API Endpoints

Referral Opportunities

The Referral Opportunities API creates and manages referral deals as PipelineDealObject rows in the REFERRAL pipeline, with PipelineDealFacilitator records (connector, referral sources, etc.).

Responses are deal-first: the public id for the hub deal is pipelineDealId, equal to id. seeker, provider, connector, and facilitators are returned on the deal object. There is no nested connection object on these Express API (api.introzy.com) responses.

To preview fees or convert a referral hub to a finance deal, use Pipeline deals (referral hub) (GET / POST /api/pipeline-deals/{dealId}/…).

List Referral Opportunities 

GET /api/referral-opps

Returns a paginated list of referral opportunities. Omit pipelineId to use the organization’s default Referral Opportunities pipeline. Pass pipelineId (from GET /api/pipelines) to list a named REFERRAL instance such as SPH Pipeline.

Query Parameters

Parameter Type Required Description
limit integer No Number of results to return (1–100, default: 50)
offset integer No Number of results to skip (default: 0)
pipelineId string No Named REFERRAL pipeline UUID. Invalid UUID or non-REFERRAL instance → 400. Unknown, other-org, or hidden → 404.

Response

Success (200) — standard envelope with success, data, meta.

{
  "success": true,
  "data": {
    "referralOpps": [
      {
        "id": "deal-uuid",
        "pipelineDealId": "deal-uuid",
        "name": "Acme needs cloud migration help",
        "description": "Acme is looking for a cloud migration partner",
        "leadOrigin": "Partner website",
        "expectedValue": 50000,
        "currency": "USD",
        "stage": {
          "id": "stage-uuid",
          "label": "Introduction",
          "color": "#3B82F6"
        },
        "owner": {
          "id": "user-uuid",
          "firstName": "Sales",
          "lastName": "Rep",
          "email": "sales@example.com"
        },
        "seeker": {
          "type": "USER",
          "id": "seeker-uuid",
          "firstName": "John",
          "lastName": "Doe",
          "email": "john@acme.com",
          "company": { "id": "company-uuid", "name": "Acme Inc" }
        },
        "provider": {
          "type": "USER",
          "id": "provider-uuid",
          "firstName": "Jane",
          "lastName": "Smith",
          "email": "jane@cloudco.com",
          "company": { "id": "company-uuid-2", "name": "CloudCo" }
        },
        "connector": {
          "id": "connector-uuid",
          "firstName": "Bob",
          "lastName": "Jones",
          "email": "bob@introzy.com",
          "company": null
        },
        "facilitators": [],
        "createdAt": "2024-01-15T10:00:00.000Z",
        "updatedAt": "2024-01-20T15:30:00.000Z"
      }
    ],
    "total": 12,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

Create Referral Opportunity 

POST /api/referral-opps

Creates a referral pipeline deal and facilitator rows. connectorId defaults to the authenticated user.

The provider is a person by default. Set providerType to COMPANY to make a company the provider. This works even when the company has no people, for example a solution provider you have just created with POST /api/companies. (API v3.2.0)

Set leadOrigin to record where the lead came from. It appears as Lead Origin on the referral. (API v3.3.0)

Request Body 

{
  "seekerId": "seeker-person-uuid",
  "providerId": "provider-person-uuid",
  "connectorId": "connector-user-uuid",
  "name": "Acme needs cloud migration help",
  "description": "Acme is looking for a cloud migration partner",
  "leadOrigin": "Partner website",
  "expectedValue": 50000,
  "currency": "USD",
  "productId": "product-uuid"
}

Parameters

Parameter Type Required Description
seekerId string Yes UUID of the person seeking a solution
providerId string Yes UUID of the person, or company when providerType is COMPANY, providing a solution
providerType string No USER (default) or COMPANY
connectorId string No UUID of the connector (defaults to authenticated user)
name string No Deal name (auto-generated as seeker company → provider company if omitted)
description string No Deal description
leadOrigin string No Where the lead came from (max 1000 chars; empty is stored as null)
expectedValue number No Expected deal value
currency string No Currency code (default: USD)
productId string No Associated product UUID

The provider must belong to your organization. An unknown provider returns 404, and a provider from another organization returns 403.

Company provider 

{
  "seekerId": "seeker-person-uuid",
  "providerId": "provider-company-uuid",
  "providerType": "COMPANY",
  "description": "Acme asked to be connected with CloudCo"
}

The response returns the company as the provider:

"provider": { "type": "COMPANY", "id": "provider-company-uuid", "name": "CloudCo" }

Response

Success (201)

{
  "success": true,
  "data": {
    "id": "deal-uuid",
    "pipelineDealId": "deal-uuid",
    "name": "Acme needs cloud migration help",
    "description": "Acme is looking for a cloud migration partner",
    "leadOrigin": "Partner website",
    "expectedValue": 50000,
    "currency": "USD",
    "stage": { "id": "stage-uuid", "label": "Introduction", "color": "#3B82F6" },
    "owner": {
      "id": "user-uuid",
      "firstName": "Sales",
      "lastName": "Rep",
      "email": "sales@example.com"
    },
    "seeker": {
      "type": "USER",
      "id": "seeker-uuid",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@acme.com",
      "company": { "id": "company-uuid", "name": "Acme Inc" }
    },
    "provider": {
      "type": "USER",
      "id": "provider-uuid",
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "jane@cloudco.com",
      "company": { "id": "company-uuid-2", "name": "CloudCo" }
    },
    "connector": {
      "id": "connector-uuid",
      "firstName": "Bob",
      "lastName": "Jones",
      "email": "bob@introzy.com",
      "company": null
    },
    "facilitators": [],
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  },
  "message": "Referral opportunity created successfully"
}

Conflict (409): a referral already exists for this seeker, provider and product set:

{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "A referral opportunity already exists between this seeker and provider"
  },
  "meta": { "requestId": "…", "timestamp": "…" }
}

Get Referral Opportunity 

GET /api/referral-opps/{id}

Path Parameters

Parameter Type Required Description
id string Yes Referral pipeline deal UUID (id)

Returns the same deal-first shape as a single list item.

List Facilitators 

GET /api/referral-opps/{id}/facilitators

Returns PipelineDealFacilitator rows for the deal.

Response 

{
  "success": true,
  "data": {
    "facilitators": [
      {
        "id": "facilitator-uuid",
        "userId": "user-uuid",
        "companyId": null,
        "role": "connector",
        "side": null,
        "createdAt": "2024-01-15T10:00:00.000Z",
        "user": {
          "id": "user-uuid",
          "firstName": "Bob",
          "lastName": "Jones",
          "email": "bob@introzy.com"
        },
        "company": null
      }
    ]
  }
}

Add Facilitator 

POST /api/referral-opps/{id}/facilitators

Adds a facilitator to the referral pipeline deal. Send exactly one of userId or companyId. The connector role must use a user, not a company.

Request Body 

{
  "userId": "user-uuid",
  "role": "referral_source",
  "side": "seeker"
}

Or with a company facilitator:

{
  "companyId": "company-uuid",
  "role": "facilitator",
  "side": "provider"
}

Parameters

Parameter Type Required Description
userId string One of User to add (mutually exclusive with companyId)
companyId string One of Company to add (mutually exclusive with userId)
role string Yes connector, facilitator, or referral_source
side string No seeker or provider

Conflict (409) if that user or company is already a facilitator on this deal.

Remove Facilitator 

DELETE /api/referral-opps/{id}/facilitators/{facilitatorId}

Path Parameters

Parameter Type Required Description
id string Yes Referral deal UUID
facilitatorId string Yes Facilitator row UUID

Facilitator Roles

Role Description
connector The person who made the introduction
facilitator Someone helping facilitate the deal
referral_source Referral-source participant on seeker/provider side

Example Usage 

curl -X GET "https://api.introzy.com/api/referral-opps" \
  -H "Authorization: Bearer introzy_your_api_key"

curl -X GET "https://api.introzy.com/api/referral-opps?pipelineId=sph-pipeline-uuid" \
  -H "Authorization: Bearer introzy_your_api_key"

curl -X POST "https://api.introzy.com/api/referral-opps" \
  -H "Authorization: Bearer introzy_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"seekerId":"seeker-uuid","providerId":"provider-uuid","name":"Cloud migration partnership","expectedValue":50000}'

curl -X POST "https://api.introzy.com/api/referral-opps" \
  -H "Authorization: Bearer introzy_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"seekerId":"seeker-uuid","providerId":"provider-uuid","connectorId":"other-user-uuid","name":"Cloud migration partnership"}'

curl -X POST "https://api.introzy.com/api/referral-opps" \
  -H "Authorization: Bearer introzy_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"seekerId":"seeker-uuid","providerId":"company-uuid","providerType":"COMPANY"}'

curl -X GET "https://api.introzy.com/api/referral-opps/deal-uuid/facilitators" \
  -H "Authorization: Bearer introzy_your_api_key"

curl -X POST "https://api.introzy.com/api/referral-opps/deal-uuid/facilitators" \
  -H "Authorization: Bearer introzy_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"userId":"user-uuid","role":"referral_source","side":"seeker"}'

curl -X DELETE "https://api.introzy.com/api/referral-opps/deal-uuid/facilitators/facilitator-uuid" \
  -H "Authorization: Bearer introzy_your_api_key"

Related Endpoints

  • Pipeline deals (referral hub) — GET / POST /api/pipeline-deals/{dealId}/fee-preview and /convert
  • Pipelines — generic pipeline and deal endpoints
  • Notes — notes on deals via GET/POST /api/pipelines/referral/deals/{dealId}/notes
Previous
Pipeline deals (referral hub)
Next
Notes
Introzy API Documentation