> ## 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 Contacts
> List agency contacts and their business roles across your associations
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 /v1/agents`](/api-reference/v1/agents/list-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](#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
```bash theme={null}
# All contacts across every agency you are associated with
GET /v1/contacts
# Contacts at one specific agency relationship
GET /v1/contacts?downstreamEntityAssociationId=6627f1a9c2e0a51b8c0d4e3a
# Every finance manager across all of your agencies
GET /v1/contacts?businessRole=Finance%20Manager
# The finance manager at one specific agency (filters combined)
GET /v1/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](/guides/request-response).
```json theme={null}
{
"statusCode": 200,
"data": [
{
"contactId": "6627f2b5c2e0a51b8c0d4e7c",
"firstName": "Dana",
"lastName": "Lee",
"email": "dana.lee@acme-insurance.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 /v1/contacts/{contactId}`](/api-reference/v1/contacts/get-contact). |
| `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. |
## OpenAPI
````yaml openapi/v1.json GET /v1/contacts
openapi: 3.0.0
info:
title: Turris Public API
description: API for managing insurance compliance data
version: 1.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:
/v1/contacts:
get:
tags:
- contacts
summary: List contacts
description: >-
Returns the agency contacts you can see across your downstream entity
associations. Each contact appears once; the agencies you can see them
at are grouped under `associations` (each carrying the business roles
held there and whether they are a primary contact). Includes both
agency-wide default contacts and market-specific contacts. Filter with
downstreamEntityAssociationId (a single agency relationship),
businessRole, or both.
operationId: ContactFeatureController_getContacts_v1
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 GET /v1/agents and on each
association in the response.
schema:
example: 6627f1a9c2e0a51b8c0d4e3a
type: string
- name: businessRole
required: false
in: query
description: >-
Return only contacts who hold this business role at one of your
agencies.
schema:
example: Finance Manager
type: string
enum:
- Compliance Officer
- Principal Owner
- Account Manager
- Finance Manager
- Support Staff
- Contract Signatory
- Accounts Payable
responses:
'200':
description: List of contacts
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ContactResponse'
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:
ContactResponse:
type: object
properties:
contactId:
type: string
description: Unique identifier of the contact
example: 6627f2b5c2e0a51b8c0d4e7c
firstName:
type: string
description: Contact first name
example: Dana
lastName:
type: string
description: Contact last name
example: Lee
email:
type: string
description: Contact email address
example: dana.lee@acme-insurance.com
isDeliverable:
type: boolean
description: Whether the contact email is deliverable
example: true
associations:
description: Agencies where you can see this contact
type: array
items:
$ref: '#/components/schemas/ContactAssociationResponse'
required:
- contactId
- firstName
- lastName
- email
- isDeliverable
- 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: Error type classification
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
ContactAssociationResponse:
type: object
properties:
downstreamEntityAssociationId:
type: string
description: >-
The market relationship (downstream entity association / UDA) id,
when a market-specific scope exists
example: 6627f1a9c2e0a51b8c0d4e3a
downstreamEntityId:
type: string
description: The downstream entity (agency) id
example: 6610b3d2c2e0a51b8c0d1f02
businessRoles:
type: array
description: >-
Business roles this contact holds at this agency (union of their
visible scopes there)
example:
- Finance Manager
items:
type: string
enum:
- Compliance Officer
- Principal Owner
- Account Manager
- Finance Manager
- Support Staff
- Contract Signatory
- Accounts Payable
isPrimary:
type: boolean
description: >-
Whether this contact is a primary contact for this agency
relationship
example: true
required:
- downstreamEntityId
- businessRoles
- isPrimary
````