Create a referral opportunity

Creates a referral opportunity as a REFERRAL pipeline deal (PipelineDealObject) with PipelineDealFacilitator rows (connector and auto-added referral sources where applicable).

The durable public identifier for the hub deal is pipelineDealId (same as id in responses). The connector defaults to the authenticated user unless connectorId is provided.

The provider is a person by default. Set providerType to COMPANY to use a company as the provider, including a company with no people (since v3.2.0).

Set leadOrigin to record where the lead came from (since v3.3.0).

Body

required

application/json

providerId
Type: stringFormat: uuid
required

ID of the provider (the solution provider). A person ID by default, or a company ID when providerType is COMPANY.
seekerId
Type: stringFormat: uuid
required

Person ID of the seeker (the one looking for a solution)
connectorId
Type: stringFormat: uuid

Person ID of the connector. Defaults to the authenticated user if omitted.
currency
Type: string
min length:
3
max length:
3
description
Type: string
max length:
1000

Note or justification for the referral
expectedValue
Type: number
min:
0

Expected deal value
leadOrigin
Type: string
max length:
1000

Free text describing where the lead came from, shown as Lead Origin on the referral. Trimmed; an empty value is stored as null. Added in v3.3.0.
name
Type: string
max length:
200

Deal name. Auto-generated as seeker company → provider company (employer names) if omitted; falls back to person names when company is unavailable. With providerType: COMPANY, the provider company name is used.
productId
Type: stringFormat: uuid

Product associated with the referral
providerType
Type: "USER" or "COMPANY"enum

Entity type of providerId. COMPANY makes the company the provider and skips the seeker/provider same-person check. Added in v3.2.0.

Responses

application/json
application/json
application/json
application/json
application/json
application/json

post/api/referral-opps

curl https://api.introzy.com/api/referral-opps \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "seekerId": "",
  "providerId": "",
  "providerType": "USER",
  "connectorId": "",
  "name": "Acme Inc → Beta Solutions LLC",
  "description": "",
  "leadOrigin": "SSA-V2",
  "expectedValue": 50000,
  "currency": "USD",
  "productId": ""
}'

Show Schema

{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "pipelineDealId": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Alice Seeker → Bob Provider",
    "description": null,
    "leadOrigin": null,
    "expectedValue": null,
    "currency": "USD",
    "stage": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "label": "Lead",
      "color": "#3B82F6",
      "description": "string",
      "sortOrder": 1
    },
    "owner": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "firstName": "string",
      "lastName": "string",
      "email": "string"
    },
    "seeker": {
      "type": "USER",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "firstName": null,
      "lastName": null,
      "email": null,
      "name": null,
      "company": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "string"
      }
    },
    "provider": {
      "type": "USER",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "firstName": null,
      "lastName": null,
      "email": null,
      "name": null,
      "company": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "string"
      }
    },
    "connector": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "firstName": null,
      "lastName": null,
      "email": null,
      "company": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "string"
      }
    },
    "facilitators": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "userId": null,
        "companyId": null,
        "role": "connector",
        "side": "seeker",
        "user": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "firstName": "string",
          "lastName": "string",
          "email": "string"
        },
        "company": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "string"
        }
      }
    ],
    "createdAt": "2026-10-28T00:33:51.464Z",
    "updatedAt": "2026-10-28T00:33:51.464Z"
  },
  "message": "Referral opportunity created successfully"
}

Referral opportunity created

List referral opportunities

Get a referral opportunity