> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turrisfi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List Market Contacts
> List the market contacts you have published to your agency relationships
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`](/api-reference/v2/contacts/list-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`](/api-reference/v2/agents/list-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
```bash theme={null}
# 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](/guides/request-response).
```json theme={null}
{
"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](#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.
## OpenAPI
````yaml openapi/v2.json GET /v2/upstream/market-contacts
openapi: 3.0.0
info:
title: Turris Public API
description: API for managing insurance compliance data
version: 2.0.0
contact: {}
servers:
- url: https://public.api.live.turrisfi.com
description: Production
- url: https://public.api.sandbox.turrisfi.com
description: Sandbox
security: []
tags: []
paths:
/v2/upstream/market-contacts:
get:
tags:
- upstream/market-contacts
summary: List market contacts
description: >-
Returns the market contacts you (the carrier) have published to your
agency relationships. Each contact appears once; the relationships they
are assigned to are grouped under `associations`, each carrying the
built-in and custom roles held there. A carrier-wide contact appears
with an association entry that has no downstreamEntityAssociationId (it
applies to every one of your relationships). Filter with
downstreamEntityAssociationId to scope to a single agency relationship
(its assigned contacts plus your carrier-wide contacts).
operationId: MarketContactsFeatureV2Controller_getMarketContacts_v2
parameters:
- name: downstreamEntityAssociationId
required: false
in: query
description: >-
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.
schema:
example: 6627f1a9c2e0a51b8c0d4e3a
type: string
responses:
'200':
description: List of published market contacts
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/MarketContactResponse'
requestId:
type: string
description: Unique request identifier
example: dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8
timestamp:
type: string
description: Response timestamp
example: '2025-11-12T20:49:03.293Z'
required:
- data
- requestId
- timestamp
'400':
description: Invalid query parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseDto'
'401':
description: Invalid or missing auth token
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseDto'
components:
schemas:
MarketContactResponse:
type: object
properties:
contactId:
type: string
description: Unique identifier of the market contact
example: 6627f2b5c2e0a51b8c0d4e7c
displayName:
type: string
description: >-
Human-readable name for the contact. For a person: their full name
(resolved live from the linked member when available), falling back
to email. For a mailbox: its label, falling back to email.
example: Jon Doe
contactType:
type: string
description: Whether this contact is a named person or a shared mailbox
enum:
- person
- mailbox
example: person
firstName:
type: string
description: Contact first name (person contacts only)
example: Jon
lastName:
type: string
description: Contact last name (person contacts only)
example: Doe
label:
type: string
description: Display label (mailbox contacts only)
example: Underwriting Desk
email:
type: string
description: Contact email address
example: example@test.com
phone:
type: string
description: Contact phone number
example: +1-212-555-0142
associations:
description: >-
The agency relationships this contact is published to. A
carrier-wide assignment appears as an entry with no
downstreamEntityAssociationId.
type: array
items:
$ref: '#/components/schemas/MarketContactAssociationResponse'
required:
- contactId
- displayName
- contactType
- associations
ErrorResponseDto:
type: object
properties:
statusCode:
type: number
description: HTTP status code
requestId:
type: string
description: Unique request identifier for debugging
errorType:
type: string
description: >-
Machine-readable error classification. Branch on this rather than on
`errorMessage`, which is prose and may change. Authentication
failures returned by our identity provider are forwarded verbatim,
so a 401 can carry a code outside this list; treat an unrecognised
value as a generic failure of its HTTP status.
enum:
- conflict
- contact_not_authorized
- document_exceeds_page_limit
- downstream_entity_member_exists
- duplicate_external_id_error
- duplicate_member_email
- duplicate_producer_code_error
- forbidden
- gateway_timeout
- inactive_email
- internal_server_error
- invalid_email
- invalid_email_for_invites
- invalid_organization_category
- invalid_organization_slug
- invalid_phone_number
- invalid_token
- invite_limit_reached
- jwt_invalid
- m2m_client_not_found
- not_found
- organization_already_exists
- organization_slug_already_used
- payment_required
- producer_agreement_required
- product_feature_subscription_required
- service_unavailable
- session_authorization_error
- some_custom_error_string
- throttled
- too_many_requests
- unauthorized
- unauthorized_client
- unexpected_400_stytch_error
- unexpected_403_stytch_error
- unexpected_404_stytch_error
- unexpected_error
- unexpected_stytch_error
- unprocessable_entity
- validation_error
example: validation_error
errorMessage:
description: Array of error messages
type: array
items:
type: string
timestamp:
type: string
description: ISO timestamp when the error occurred
details:
type: object
description: Additional error context
required:
- statusCode
- requestId
- errorType
- errorMessage
- timestamp
MarketContactAssociationResponse:
type: object
properties:
downstreamEntityAssociationId:
type: string
description: >-
The market relationship (downstream entity association / UDA) id
this contact is assigned to. Omitted for a carrier-wide assignment
that applies to every one of your agency relationships.
example: 6627f1a9c2e0a51b8c0d4e3a
roles:
type: array
description: Built-in market contact roles this contact holds in this assignment
example:
- underwriter
items:
type: string
enum:
- territory manager
- underwriter
- credentialing
- account manager
- claims
- general
customRoles:
description: Carrier-defined custom roles this contact holds in this assignment
type: array
items:
$ref: '#/components/schemas/MarketContactCustomRoleResponse'
required:
- roles
- customRoles
MarketContactCustomRoleResponse:
type: object
properties:
id:
type: string
description: The custom role definition id
example: 6627f1a9c2e0a51b8c0d4e3a
name:
type: string
description: The carrier-defined display name for the custom role
example: National Accounts
required:
- id
- name
````
## Related topics
- [Changelog](/changelog.md)
- [List a Market's Contacts](/api-reference/v2/downstream/markets/market-contacts.md)
- [List Markets](/api-reference/v2/downstream/markets/list-markets.md)