List Market Contacts

List market contacts

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

const options = {method: 'GET'};

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

{
  "data": [
    {
      "contactId": "6627f2b5c2e0a51b8c0d4e7c",
      "displayName": "Jon Doe",
      "contactType": "person",
      "associations": [
        {
          "roles": [
            "underwriter"
          ],
          "customRoles": [
            {
              "id": "6627f1a9c2e0a51b8c0d4e3a",
              "name": "National Accounts"
            }
          ],
          "downstreamEntityAssociationId": "6627f1a9c2e0a51b8c0d4e3a"
        }
      ],
      "firstName": "Jon",
      "lastName": "Doe",
      "label": "Underwriting Desk",
      "email": "example@test.com",
      "phone": "+1-212-555-0142"
    }
  ],
  "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

market-contacts

List market contacts

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

const options = {method: 'GET'};

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

{
  "data": [
    {
      "contactId": "6627f2b5c2e0a51b8c0d4e7c",
      "displayName": "Jon Doe",
      "contactType": "person",
      "associations": [
        {
          "roles": [
            "underwriter"
          ],
          "customRoles": [
            {
              "id": "6627f1a9c2e0a51b8c0d4e3a",
              "name": "National Accounts"
            }
          ],
          "downstreamEntityAssociationId": "6627f1a9c2e0a51b8c0d4e3a"
        }
      ],
      "firstName": "Jon",
      "lastName": "Doe",
      "label": "Underwriting Desk",
      "email": "example@test.com",
      "phone": "+1-212-555-0142"
    }
  ],
  "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 market contacts your organization has published to its agency relationships, grouped one entry per contact. The relationships a contact is assigned to are grouped under associations, each carrying the built-in and carrier-defined roles the contact holds there. These are your own outward-facing people, the underwriters, territory managers, and shared mailboxes an agency should reach out to. That makes this the mirror image of GET /v2/upstream/contacts, which returns the agency’s contacts as seen by you. A single contact appears once with multiple associations when they are published to more than one relationship.

This endpoint is read-only and returns only contacts your organization owns. Another carrier’s market contacts are never returned, and neither are their custom role definitions.

Carrier-wide vs relationship-specific

Each associations entry is one of two kinds, distinguished only by whether downstreamEntityAssociationId is present:

Kind	`downstreamEntityAssociationId`	Meaning
Relationship-specific	Present	The contact is published to that one agency relationship.
Carrier-wide	Omitted	The contact applies to every one of your agency relationships.

A contact can hold different roles in each, so a carrier-wide general assignment and a relationship-specific underwriter assignment appear as two separate entries on the same contact.

Query Parameters

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.

When you supply downstreamEntityAssociationId, the response contains contacts assigned to that relationship plus your carrier-wide contacts, since the latter apply to it too. Relationship-specific assignments for your other relationships are filtered out of each contact’s associations. An id that does not belong to your organization returns an empty array, not an error. Ownership is enforced in the lookup, so an unknown or foreign id simply matches nothing.

Built-in Roles

roles values are drawn from this fixed set:

Value	Typical use
`territory manager`	Territory or regional relationship owner
`underwriter`	Underwriting contact for the relationship
`credentialing`	Appointment and credentialing contact
`account manager`	Day-to-day account relationship
`claims`	Claims contact
`general`	General or catch-all contact

Carrier-defined roles beyond this set are returned separately in customRoles, each with its id and display name.

Examples

# Every market contact you have published, across all relationships
GET /v2/upstream/market-contacts

# Contacts an agency would see for one specific relationship,
# including your carrier-wide contacts
GET /v2/upstream/market-contacts?downstreamEntityAssociationId=6627f1a9c2e0a51b8c0d4e3a

Response Shape

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

{
  "data": [
    {
      "contactId": "6627f2b5c2e0a51b8c0d4e7c",
      "displayName": "Jon Doe",
      "contactType": "person",
      "firstName": "Jon",
      "lastName": "Doe",
      "email": "example@test.com",
      "phone": "+1-212-555-0142",
      "associations": [
        {
          "downstreamEntityAssociationId": "6627f1a9c2e0a51b8c0d4e3a",
          "roles": ["underwriter"],
          "customRoles": [
            { "id": "6627f1a9c2e0a51b8c0d4e3a", "name": "National Accounts" }
          ]
        },
        {
          "roles": ["general"],
          "customRoles": []
        }
      ]
    },
    {
      "contactId": "6627f2b5c2e0a51b8c0d4e8d",
      "displayName": "Underwriting Desk",
      "contactType": "mailbox",
      "label": "Underwriting Desk",
      "email": "underwriting@example-carrier.com",
      "associations": [
        {
          "roles": ["underwriter", "general"],
          "customRoles": []
        }
      ]
    }
  ],
  "requestId": "dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8",
  "timestamp": "2026-08-05T12:00:00.000Z"
}

The first contact’s opening association is relationship-specific; its second has no downstreamEntityAssociationId and is therefore carrier-wide. The second contact is a shared mailbox published carrier-wide.

Response Fields

Market Contact

Field	Type	Description
`contactId`	string	Unique market contact identifier.
`displayName`	string	Ready-to-render name. Resolution order: the linked member’s live full name, then the stored first and last name, then `label`, then `email`.
`contactType`	string (enum)	`person` for a named individual, `mailbox` for a shared inbox.
`firstName`	string?	Person contacts only.
`lastName`	string?	Person contacts only.
`label`	string?	Mailbox contacts only.
`email`	string?	Contact email address.
`phone`	string?	Contact phone number.
`associations`	array	One entry per assignment visible to you (see below).

Prefer displayName for rendering. For a person linked to a user in your organization it tracks that user’s current name, so it stays correct after a rename, whereas firstName and lastName may hold the values captured when the contact was created.

Association

Field	Type	Description
`downstreamEntityAssociationId`	string?	The agency relationship (UDA) id. Present for a relationship-specific assignment; omitted for a carrier-wide one.
`roles`	string[]	Built-in roles held in this assignment. See Built-in Roles. May be empty when only custom roles are assigned.
`customRoles`	object[]	Carrier-defined roles held in this assignment, each `{ id, name }`. Empty when none are assigned.

A custom role whose definition has since been deleted is omitted from customRoles rather than returned with a null name, so treat this array as the current set of resolvable roles.

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. When supplied, returns contacts assigned to that relationship plus your carrier-wide contacts.

Example:

"6627f1a9c2e0a51b8c0d4e3a"

Response

List of published market 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

Carrier-wide vs relationship-specific

Query Parameters

Built-in Roles

Examples

Response Shape

Response Fields

Market Contact

Association

Query Parameters

Response

​Carrier-wide vs relationship-specific

​Query Parameters

​Built-in Roles

​Examples

​Response Shape

​Response Fields

​Market Contact

​Association

Query Parameters

Response

Carrier-wide vs relationship-specific

Query Parameters

Built-in Roles

Examples

Response Shape

Response Fields

Market Contact

Association