API Endpoints

Referral Opportunities

The Referral Opportunities API provides a dedicated interface for creating and managing referral deals. A referral opportunity connects a seeker (who needs something) with a provider (who offers it), facilitated by a connector (who makes the introduction).

Under the hood, creating a referral opportunity atomically creates a Connection record, a ConnectionFacilitator for the connector, and a deal in the REFERRAL pipeline.

List Referral Opportunities 

GET /api/referral-opps

Retrieves a paginated list of referral opportunities with connection details.

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 Response (200)

{
  "success": true,
  "data": {
    "referralOpps": [
      {
        "id": "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"
        },
        "connection": {
          "id": "connection-uuid",
          "seeker": {
            "id": "seeker-uuid",
            "firstName": "John",
            "lastName": "Doe",
            "email": "john@acme.com",
            "company": { "id": "company-uuid", "name": "Acme Inc" }
          },
          "provider": {
            "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"
          },
          "facilitators": [],
          "createdAt": "2024-01-15T10:00:00.000Z"
        },
        "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

Atomically creates a referral opportunity: a Connection (seeker + provider), a ConnectionFacilitator for the connector, and a deal in the REFERRAL pipeline.

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"
}

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 Response (201)

{
  "success": true,
  "data": {
    "id": "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"
    },
    "connection": {
      "id": "connection-uuid",
      "seeker": { "id": "seeker-uuid", "firstName": "John", "lastName": "Doe" },
      "provider": { "id": "provider-uuid", "firstName": "Jane", "lastName": "Smith" },
      "connector": { "id": "connector-uuid", "firstName": "Bob", "lastName": "Jones" }
    },
    "createdAt": "2024-01-15T10:30:00.000Z"
  },
  "message": "Referral opportunity created successfully"
}

Error Response (409)

{
  "success": false,
  "error": "A connection between these two people already exists"
}

Get Referral Opportunity 

GET /api/referral-opps/{id}

Retrieves a specific referral opportunity with full connection details.

Path Parameters

Parameter Type Required Description
id string Yes Deal UUID (referral opp ID)

Response

Success Response (200)

Returns the same structure as a single item in the list response, with full connection details including seeker, provider, connector, and facilitators.

List Facilitators 

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

Retrieves all facilitators for a referral opportunity's connection.

Response

Success Response (200)

{
  "success": true,
  "data": {
    "facilitators": [
      {
        "id": "facilitator-uuid",
        "userId": "user-uuid",
        "role": "connector",
        "side": null,
        "createdAt": "2024-01-15T10:00:00.000Z",
        "user": {
          "id": "user-uuid",
          "firstName": "Bob",
          "lastName": "Jones",
          "email": "bob@introzy.com"
        }
      },
      {
        "id": "facilitator-uuid-2",
        "userId": "user-uuid-2",
        "role": "referral_source",
        "side": "seeker",
        "createdAt": "2024-01-16T09:00:00.000Z",
        "user": {
          "id": "user-uuid-2",
          "firstName": "Alice",
          "lastName": "Brown",
          "email": "alice@network.com"
        }
      }
    ]
  }
}

Add Facilitator 

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

Adds a facilitator to a referral opportunity's connection.

Request Body 

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

Parameters

Parameter Type Required Description
userId string Yes UUID of the user to add as facilitator
role string Yes Role: connector, facilitator, or referral_source
side string No Which side: seeker or provider

Response

Success Response (201)

{
  "success": true,
  "data": {
    "id": "facilitator-uuid",
    "userId": "user-uuid",
    "role": "referral_source",
    "side": "seeker",
    "createdAt": "2024-01-16T09:00:00.000Z",
    "user": {
      "id": "user-uuid",
      "firstName": "Alice",
      "lastName": "Brown",
      "email": "alice@network.com"
    }
  },
  "message": "Facilitator added successfully"
}

Error Response (409)

{
  "success": false,
  "error": "This user is already a facilitator on this connection"
}

Remove Facilitator 

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

Removes a facilitator from a referral opportunity's connection.

Path Parameters

Parameter Type Required Description
id string Yes Deal UUID
facilitatorId string Yes Facilitator UUID

Response

Success Response (200)

{
  "success": true,
  "data": {
    "deleted": true
  },
  "message": "Facilitator removed successfully"
}

Facilitator Roles

Role Description
connector The person who made the introduction
facilitator Someone helping facilitate the deal
referral_source The person who referred the seeker or provider

Example Usage 

# List all referral opportunities
curl -X GET "https://beta-api.introzy.com/api/referral-opps" \
  -H "Authorization: Bearer introzy_your_api_key"

# Create a referral opportunity
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
  }'

# Create with explicit connector (not the API caller)
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"
  }'

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

# Add a referral source
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"
  }'

# Remove a facilitator
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

  • Pipelines — Manage deals in the REFERRAL pipeline via generic pipeline endpoints
  • Notes — Add notes to referral deals via GET/POST /api/pipelines/referral/deals/{dealId}/notes
Previous
Pipelines
Next
Notes

Introzy API Documentation