Pipeline deals (referral hub)

Endpoints under /api/pipeline-deals support referral pipeline deals (hub records in the REFERRAL pipeline) when converting to finance deals: fee preview and conversion.

They use the same authentication as other protected API routes (API key or Clerk JWT in the Authorization: Bearer … header).

The dealId path parameter is the referral pipeline deal id — the same value returned as id and pipelineDealId from Referral Opportunities.

Fee preview

GET /api/pipeline-deals/{dealId}/fee-preview

Returns fee plans and chain estimates for converting the hub deal to a finance deal.

Response shape: the HTTP body is the preview object directly (not wrapped in { "success", "data" }).

Example (not converted)

{
  "isConverted": false,
  "organizationId": "org-uuid",
  "dealValue": 50000,
  "expectedValue": 50000,
  "feePlans": [],
  "estimatedChainCount": 2,
  "facilitatorCount": 1,
  "connectorUserId": "user-uuid",
  "facilitators": []
}

feePlans and related fields are populated from product, connector, and facilitator fee configuration. See the OpenAPI schema PipelineDealFeePreview for the full shape.

Example (already converted)

{
  "isConverted": true,
  "message": "Pipeline deal has already been converted",
  "feePlans": [],
  "dealValue": null,
  "expectedValue": null
}

Convert to finance deal

POST /api/pipeline-deals/{dealId}/convert

Creates a finance Deal, fee chains, and related records.

Response shape: the HTTP body is the result object directly (not wrapped in { "success", "data" }).

Request body (optional)

Field	Type	Description
`dealName`	string	Finance deal name
`dealDescription`	string	Finance deal description
`triggerFeeCalculation`	boolean	Default `true`
`amountStructure`	string	`ONE_TIME`, `MONTHLY`, `ANNUAL`, or `CUSTOM`
`periodStart`	string	Period start (when using period-based structure)
`periodEnd`	string	Period end

Example response (`201`)

{
  "deal": {
    "id": "finance-deal-uuid",
    "name": "Acme → CloudCo",
    "amount": 50000,
    "status": "ACTIVE"
  },
  "chains": [
    {
      "id": "chain-uuid",
      "connectorId": "product-uuid",
      "connectorType": "PRODUCT",
      "feePlanCount": 1
    }
  ],
  "feeEvents": []
}

Errors

404 — Hub deal not found.
400 — Invalid state, e.g. already converted, missing seeker/provider for conversion, or deal missing organization.
401 — Missing or invalid authentication.

Structured error bodies use the same { "success": false, "error": { "code", "message" }, "meta" } shape as other authenticated API routes.

Referral Opportunities — create and list hub deals (pipelineDealId).
Pipelines — generic pipeline and deal CRUD.

Pipelines

Referral Opportunities