List Contacts

List contacts

curl --request GET \
  --url https://public.api.live.turrisfi.com/v2/upstream/contacts

const options = {method: 'GET'};

fetch('https://public.api.live.turrisfi.com/v2/upstream/contacts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": [
    {
      "contactId": "6627f2b5c2e0a51b8c0d4e7c",
      "firstName": "Jon",
      "lastName": "Doe",
      "email": "example@test.com",
      "isDeliverable": true,
      "associations": [
        {
          "downstreamEntityId": "6610b3d2c2e0a51b8c0d1f02",
          "businessRoles": [
            "Finance Manager"
          ],
          "isPrimary": true,
          "downstreamEntityAssociationId": "6627f1a9c2e0a51b8c0d4e3a"
        }
      ]
    }
  ],
  "requestId": "dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8",
  "timestamp": "2025-11-12T20:49:03.293Z"
}

{
  "statusCode": 123,
  "requestId": "<string>",
  "errorType": "validation_error",
  "errorMessage": [
    "<string>"
  ],
  "timestamp": "<string>",
  "details": {}
}

{
  "statusCode": 123,
  "requestId": "<string>",
  "errorType": "validation_error",
  "errorMessage": [
    "<string>"
  ],
  "timestamp": "<string>",
  "details": {}
}

GET

upstream

contacts

List contacts

curl --request GET \
  --url https://public.api.live.turrisfi.com/v2/upstream/contacts

const options = {method: 'GET'};

fetch('https://public.api.live.turrisfi.com/v2/upstream/contacts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": [
    {
      "contactId": "6627f2b5c2e0a51b8c0d4e7c",
      "firstName": "Jon",
      "lastName": "Doe",
      "email": "example@test.com",
      "isDeliverable": true,
      "associations": [
        {
          "downstreamEntityId": "6610b3d2c2e0a51b8c0d1f02",
          "businessRoles": [
            "Finance Manager"
          ],
          "isPrimary": true,
          "downstreamEntityAssociationId": "6627f1a9c2e0a51b8c0d4e3a"
        }
      ]
    }
  ],
  "requestId": "dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8",
  "timestamp": "2025-11-12T20:49:03.293Z"
}

{
  "statusCode": 123,
  "requestId": "<string>",
  "errorType": "validation_error",
  "errorMessage": [
    "<string>"
  ],
  "timestamp": "<string>",
  "details": {}
}

{
  "statusCode": 123,
  "requestId": "<string>",
  "errorType": "validation_error",
  "errorMessage": [
    "<string>"
  ],
  "timestamp": "<string>",
  "details": {}
}

Returns the agency contacts you can see across your downstream entity associations, grouped one entry per agency. Each entry includes the agency, the business roles the contact holds there (for example Finance Manager or Account Manager), and whether they are a primary contact. A single person can appear once with multiple associations when you work with them at more than one agency. Results include both agency-wide default contacts (defined once by the agency and shared with every market they work with) and market-specific contacts (added for a single relationship).

This endpoint is read-only and returns only contacts at agencies your organization is associated with. It never exposes another carrier’s market-specific contacts.

Query Parameters

All parameters are optional and can be combined.

Parameter	Type	Required	Description
`downstreamEntityAssociationId`	string (ObjectId)	No	Scope results to a single agency relationship. This is the downstream entity association (UDA) id, the same `downstreamEntityAssociationId` returned by `GET /v2/upstream/agents` and on each association below.
`businessRole`	string (enum)	No	Return only contacts who hold this business role at one of your agencies. Must be one of the business roles below (URL-encode the space, e.g. `Finance%20Manager`).

Business Roles

businessRole must be one of these exact values:

Value	Typical use
`Compliance Officer`	Compliance and licensing point of contact
`Principal Owner`	Agency principal / owner
`Account Manager`	Day-to-day account relationship
`Finance Manager`	Finance / commissions / payables contact
`Support Staff`	General support
`Contract Signatory`	Authorized to sign producer agreements
`Accounts Payable`	Accounts payable / billing

Filtering Examples

# All contacts across every agency you are associated with
GET /v2/upstream/contacts

# Contacts at one specific agency relationship
GET /v2/upstream/contacts?downstreamEntityAssociationId=6627f1a9c2e0a51b8c0d4e3a

# Every finance manager across all of your agencies
GET /v2/upstream/contacts?businessRole=Finance%20Manager

# The finance manager at one specific agency (filters combined)
GET /v2/upstream/contacts?downstreamEntityAssociationId=6627f1a9c2e0a51b8c0d4e3a&businessRole=Finance%20Manager

When a businessRole filter is supplied, each returned contact is narrowed to only the agencies where they hold that role.

Response Shape

All successful responses are wrapped in the standard response envelope. See Request/Response Conventions.

{
  "statusCode": 200,
  "data": [
    {
      "contactId": "6627f2b5c2e0a51b8c0d4e7c",
      "firstName": "Jon",
      "lastName": "Doe",
      "email": "example@test.com",
      "isDeliverable": true,
      "associations": [
        {
          "downstreamEntityAssociationId": "6627f1a9c2e0a51b8c0d4e3a",
          "downstreamEntityId": "6610b3d2c2e0a51b8c0d1f02",
          "businessRoles": ["Finance Manager", "Compliance Officer"],
          "isPrimary": true
        },
        {
          "downstreamEntityId": "6610b3d2c2e0a51b8c0d1f99",
          "businessRoles": ["Account Manager"],
          "isPrimary": false
        }
      ]
    }
  ],
  "timestamp": "2026-06-30T12:00:00.000Z"
}

The first association is market-specific (it carries a downstreamEntityAssociationId). The second is agency-wide: it has no downstreamEntityAssociationId because it is not tied to a single market relationship.

Response Fields

Contact

Field	Type	Description
`contactId`	string	Unique contact identifier. Pass this to `GET /v2/upstream/contacts/{contactId}`.
`firstName`	string	Contact first name
`lastName`	string	Contact last name
`email`	string	Contact email address
`isDeliverable`	boolean	Whether the email has been verified as deliverable
`associations`	array	One entry per agency you can see this contact at (see below)

Association

Field	Type	Description
`downstreamEntityAssociationId`	string?	The agency relationship (UDA) id. Present for market-specific relationships; omitted for agency-wide contacts.
`downstreamEntityId`	string	The downstream entity (agency) id. Always present, and the key this entry is grouped by.
`businessRoles`	string[]	The business roles the contact holds at this agency (union of all roles visible to you there).
`isPrimary`	boolean	Whether the contact is a primary contact for this agency relationship.

Query Parameters

downstreamEntityAssociationId

string

Scope results to a single agency relationship. This is the downstream entity association (UDA) id, the same downstreamEntityAssociationId returned by the List Agents endpoint and on each association in the response.

Example:

"6627f1a9c2e0a51b8c0d4e3a"

businessRole

enum<string>

Return only contacts who hold this business role at one of your agencies.

Available options:

Compliance Officer,

Principal Owner,

Account Manager,

Finance Manager,

Support Staff,

Contract Signatory,

Accounts Payable,

Policy Maintenance

Example:

"Finance Manager"

Response

List of contacts

data

object[]

required

Show child attributes

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"

Start Here

Shared Endpoints

Products

Agencies You Appoint

Contract Container Templates

Agents

Contacts

Market Contacts

Licenses

Appointments

Compliance Data Subscriptions

Compliance Status

File Documents

Policy Ingestion

Policy Transactions

Surplus Lines Filings

Webhooks

E&O/Cyber Compliance

Regulatory Actions

Tools

Query Parameters

Business Roles

Filtering Examples

Response Shape

Response Fields

Contact

Association

Query Parameters

Response

​Query Parameters

​Business Roles

​Filtering Examples

​Response Shape

​Response Fields

​Contact

​Association

Query Parameters

Response

Query Parameters

Business Roles

Filtering Examples

Response Shape

Response Fields

Contact

Association