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 (beta-api) 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.

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)

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",
        "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.

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",
  "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 providing a solution
connectorId string No UUID of the connector (defaults to authenticated user)
name string No Deal name (auto-generated if omitted)
description string No Deal description
expectedValue number No Expected deal value
currency string No Currency code (default: USD)
productId string No Associated product UUID

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",
    "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) — duplicate seeker/provider (and optional product) pair:

{
  "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://beta-api.introzy.com/api/referral-opps" \
  -H "Authorization: Bearer introzy_your_api_key"

curl -X POST "https://beta-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://beta-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 GET "https://beta-api.introzy.com/api/referral-opps/deal-uuid/facilitators" \
  -H "Authorization: Bearer introzy_your_api_key"

curl -X POST "https://beta-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://beta-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