Skip to main content
POST
/
v1
/
downstream-entity-associations
/
invite
cURL
curl --request POST \
  --url https://public.api.live.turrisfi.com/v1/downstream-entity-associations/invite \
  --header 'Content-Type: application/json' \
  --data '
{
  "useInviteUrl": false,
  "isNpnRequired": true,
  "downstreamEntityName": "ABC Insurance Agency",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "category": "agency",
  "producerCode": "PROD-001",
  "externalId": "EXT-12345",
  "contractContainerTemplateId": "507f1f77bcf86cd799439011",
  "producerAgreementId": "<string>",
  "parentProducerCode": "PARENT-001",
  "customFields": {
    "customField1": "value1",
    "customField2": 123
  },
  "customFieldValues": {
    "commission_rate": 10,
    "effective_date": "2026-06-01"
  }
}
'
{
  "data": {
    "url": "<string>"
  },
  "requestId": "dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8",
  "timestamp": "2025-11-12T20:49:03.293Z"
}
Sends an email invitation to a downstream entity to join your network. The invited entity will receive instructions to complete their onboarding.

​
Selecting a contract template

If you want a contract template assigned at invite time, pass its ID as contractContainerTemplateId. Obtain valid IDs by calling List Contract Container Templates and using the top-level _id of any item with status: "active". If you want the contract template chosen later by your team during pre-contract review, omit contractContainerTemplateId and set onboardingSettings.isPreContractReviewStepUsed to true. Sending both will return 400.
The producerAgreementId field is deprecated. It is still accepted for backward compatibility with existing integrations: legacy producer-agreement IDs are internally resolved to the matching ContractContainer template. New integrations should use contractContainerTemplateId from the List Contract Container Templates endpoint.

Headers

​
idempotency-key
string

UUID to ensure idempotent request processing

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
x-idempotency-key
string

Alternative UUID header for idempotent request processing

Example:

"550e8400-e29b-41d4-a716-446655440000"

Body

application/json
​
useInviteUrl
boolean
required

If true, returns an invite URL instead of sending an email

Example:

false

​
isNpnRequired
boolean
required

Whether NPN is required for this downstream entity

Example:

true

​
downstreamEntityName
string
required

Name of the downstream entity

Example:

"ABC Insurance Agency"

​
firstName
string
required

First name of the primary contact

Example:

"John"

​
lastName
string
required

Last name of the primary contact

Example:

"Doe"

​
email
string
required

Email address of the primary contact

Example:

"john.doe@example.com"

​
category
enum<string>
required

Category of the downstream entity

Available options:
agency,
agency network,
wholesale brokerage,
third party administrator
Example:

"agency"

​
producerCode
string

Producer code for this downstream entity

Example:

"PROD-001"

​
externalId
string

External identifier for integration purposes

Example:

"EXT-12345"

​
contractContainerTemplateId
string

ContractContainer template ID to associate with this invitation. Obtain via GET /v1/contract-container-templates. Preferred over the legacy producerAgreementId field.

Example:

"507f1f77bcf86cd799439011"

​
producerAgreementId
string
deprecated

Deprecated: use contractContainerTemplateId instead. Legacy producer-agreement file-document ID. Still accepted for backward compatibility; the ID is internally resolved to the matching ContractContainer template.

​
onboardingSettings
object

Onboarding settings to customize the onboarding flow

​
parentProducerCode
string

Producer code of the parent entity (for branch relationships)

Example:

"PARENT-001"

​
customFields
object

Custom fields for additional data

Example:
{
  "customField1": "value1",
  "customField2": 123
}
​
customFieldValues
object

Values to populate the contract template custom fields. Keyed by fieldName. Required when the selected contractContainerTemplateId has customFields defined; the values are validated against type / required / min / max.

Example:
{
  "commission_rate": 10,
  "effective_date": "2026-06-01"
}

Response

Downstream entity invitation sent

​
data
object
required
​
requestId
string
required

Unique request identifier

Example:

"dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8"

​
timestamp
string
required

Response timestamp

Example:

"2025-11-12T20:49:03.293Z"