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.

Body

required

application/json

providerId
Type: stringFormat: uuid
required

Person ID of the provider (the solution provider)
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
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.
productId
Type: stringFormat: uuid

Product associated with the referral

Responses

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

post/api/referral-opps

curl https://beta-api.introzy.com/api/referral-opps \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "seekerId": "",
  "providerId": "",
  "connectorId": "",
  "name": "Acme Inc → Beta Solutions LLC",
  "description": "",
  "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,
    "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-05-20T14:22:03.090Z",
    "updatedAt": "2026-05-20T14:22:03.090Z"
  },
  "message": "Referral opportunity created successfully"
}

Referral opportunity created