> ## 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.

# Add Contact

> Add a contact to one of your agency relationships

Adds a contact to one of your agency relationships, the `downstreamEntityAssociationId` that [`GET /v2/upstream/contacts`](https://docs.turrisfi.com/api-reference/v2/contacts/list-contacts) filters on. The contact shows on that agency's Contacts tab in Turris and in List Contacts straight away. The response has the same shape as [Get Contact](https://docs.turrisfi.com/api-reference/v2/contacts/get-contact.md).

## Email addresses are unique across Turris

Contact email is unique platform-wide, not per agency, so the address you send may belong to a contact the agency or another carrier added first. In that case this endpoint links that contact to your agency relationship instead of creating a second one. It keeps the stored `firstName`, `lastName` and `phoneNumber`, and the response shows the stored values, which can differ from what you sent.

The response lists every business role you can see the contact hold at that agency, so it can include roles from the agency's own record of the contact as well as the ones you sent.

## Primary contact

Leave `isPrimary` out and the contact becomes the relationship's primary contact only when it is the first contact on it. `isPrimary: true` on a relationship that already has a primary contact returns `409` and nothing is written. Change the primary contact in Turris, then add this contact without `isPrimary`.

## Contract signatories receive an email

A contact with the `Contract Signatory` business role is given a Turris login so they can sign, and is emailed: the contract signing request when the agency's onboarding has reached contract signing, otherwise the onboarding invitation when they are the primary contact. Send `shouldSendEmail: false` to add them without the email. Turris does not email an address it has found undeliverable.

The email goes out after the contact is saved. If it cannot be sent, the contact is still added and the response is the same, so a `201` does not confirm the email was delivered.

One case sends nothing: if the contact is already linked to the relationship but missing from its contact list, which older writes could leave behind, the request adds it back to the list and returns `201` without changing the contact, creating a login or sending an email.

## Errors

| Status | When |
| - | - |
| `400` | The body is invalid; the email is not a real mailbox (`errorType: invalid_email`); or the agency cannot receive Turris logins yet and the contact is a Contract Signatory or the primary contact |
| `404` | The `downstreamEntityAssociationId` is not one of your live agency relationships. Nothing is written |
| `409` | The contact is already on that relationship; `isPrimary` is `true` and the relationship already has a primary contact; or the contact changed while the request ran, in which case retry it |
| `429` | More than 10 requests in 60 seconds from your organization |

## Retries and limits

Send an `idempotency-key` header. A retry with the same key within an hour returns the first response. A retry without one, after the first request succeeded, returns `409` because the contact is already on the relationship. See [Idempotency](https://docs.turrisfi.com/guides/idempotency.md).

This endpoint allows 10 requests per 60 seconds per organization. See [Rate limiting](https://docs.turrisfi.com/guides/rate-limiting.md).


## OpenAPI

````yaml openapi/v2.json POST /v2/upstream/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:
  - bearer: []
  - restricted-access-token: []
tags:
  - name: auth
    description: Shared. Serves either organization category, so no persona applies.
    x-organization-category: null
  - name: downstream/actions-required
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/appointments
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/carriers
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/compliance-configs
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/contacts
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/corporate-registrations
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/documents
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/entities
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/license-overview
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/license-requests
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/licenses
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/markets
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/producers
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/surplus-lines-filings
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/surplus-lines-states
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: heartbeat
    description: Shared. Serves either organization category, so no persona applies.
    x-organization-category: null
  - name: upstream/agents
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/agents-license-compliance
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/appointment-requests
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/carriers
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/compliance-data-subscriptions
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/contacts
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/contract-container-templates
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/diligent-effort-requests
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/downstream-entity-associations
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/file-documents
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/market-contacts
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/npn-lookup
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/policies
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/products
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/surplus-lines-filings
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/surplus-lines-states
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/termination-requests
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/webhooks
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
paths:
  /v2/upstream/contacts:
    post:
      tags:
        - upstream/contacts
      summary: Add a contact
      description: >-
        Adds a contact to one of your agency relationships, the
        downstreamEntityAssociationId List Contacts filters on. Email is unique
        across Turris: an address Turris already knows is linked to your
        relationship, keeping its stored name and phone, and the response shows
        the stored values. A Contract Signatory is given a Turris login so they
        can sign. They are emailed the contract signing request when the agency
        has reached the contract-signing step, or otherwise the onboarding
        invitation when they are the primary contact; not when shouldSendEmail
        is false or the address is undeliverable. Returns the contact as Get
        Contact does.
      operationId: ContactFeatureV2Controller_createContact_v2
      parameters:
        - name: idempotency-key
          in: header
          description: UUID to ensure idempotent request processing
          required: false
          schema:
            type: string
            example: 550e8400-e29b-41d4-a716-446655440000
        - name: x-idempotency-key
          in: header
          description: Alternative UUID header for idempotent request processing
          required: false
          schema:
            type: string
            example: 550e8400-e29b-41d4-a716-446655440000
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContactDto'
      responses:
        '201':
          description: The contact, as Get Contact returns it
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ContactV2Response'
                  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 request body, an email address that is not a real mailbox
            (`errorType: invalid_email`), or an agency that cannot receive
            Turris logins yet when the contact is a Contract Signatory or the
            primary contact
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '401':
          description: Invalid or missing auth token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '403':
          description: >-
            Returned with `errorType` `invalid_organization_category` when your
            credential's organization category does not match the one this
            endpoint serves; `details` names the expected and actual category.
            This endpoint can return 403 for other reasons too, so branch on
            `errorType`; the Error Handling guide lists them.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '404':
          description: No such downstream entity association for your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '409':
          description: >-
            The contact is already on that association, isPrimary is true and
            the association already has a primary contact, or the contact
            changed while the request ran (retry it)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '429':
          description: >-
            More than 10 requests in 60 seconds from your organization. Also
            returned when this credential passes the API-wide limit of 1000
            requests per 10 seconds, counted across every endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
          headers:
            Retry-After:
              description: >-
                Seconds to wait before retrying. Sent when a rate limit refused
                the request.
              schema:
                type: integer
components:
  schemas:
    CreateContactDto:
      type: object
      properties:
        downstreamEntityAssociationId:
          type: string
          description: >-
            The agency relationship to add the contact to. This is the
            downstream entity association id, the same
            downstreamEntityAssociationId List Contacts filters on.
          example: 6627f1a9c2e0a51b8c0d4e3a
        firstName:
          type: string
          description: >-
            Given name. Stored only when this email is new to Turris; an address
            Turris already knows keeps its stored name.
          example: Jon
        lastName:
          type: string
          description: >-
            Surname. Stored only when this email is new to Turris; an address
            Turris already knows keeps its stored name.
          example: Doe
        email:
          type: string
          description: >-
            Email address. Unique across Turris and matched case-insensitively,
            so an address Turris already knows is linked to your agency
            relationship rather than duplicated.
          example: example@test.com
        phoneNumber:
          type: string
          description: >-
            The contact's direct phone number. Stored only when this email is
            new to Turris; an address Turris already knows keeps its stored
            number.
          example: +1 555 010 0199
        businessRoles:
          type: array
          description: Business roles this contact holds on this agency relationship.
          example:
            - Contract Signatory
          items:
            type: string
            enum:
              - Compliance Officer
              - Principal Owner
              - Account Manager
              - Finance Manager
              - Support Staff
              - Contract Signatory
              - Accounts Payable
              - Policy Maintenance
        isPrimary:
          type: boolean
          description: >-
            Whether this is the primary contact for the agency relationship.
            Omit it and the contact is primary only when it is the first contact
            on the relationship. true is refused with 409 when the relationship
            already has a primary contact.
          example: false
        shouldSendEmail:
          type: boolean
          description: >-
            Set to false to add a Contract Signatory without the onboarding
            email Turris sends them. Defaults to true.
          example: true
      required:
        - downstreamEntityAssociationId
        - firstName
        - lastName
        - email
    ContactV2Response:
      type: object
      properties:
        contactId:
          type: string
          description: Unique identifier of the contact
          example: 6627f2b5c2e0a51b8c0d4e7c
        firstName:
          type: string
          description: Contact first name
          example: Jon
        lastName:
          type: string
          description: Contact last name
          example: Doe
        email:
          type: string
          description: Contact email address
          example: example@test.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'
        phoneNumber:
          type: string
          description: The contact's direct phone number, when Turris holds one
          example: +1 555 010 0199
      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: >-
            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
            - contract_already_signed
            - 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
            - online_signing_in_progress
            - 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
    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
              - Policy Maintenance
        isPrimary:
          type: boolean
          description: >-
            Whether this contact is a primary contact for this agency
            relationship
          example: true
      required:
        - downstreamEntityId
        - businessRoles
        - isPrimary
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
    restricted-access-token:
      type: apiKey
      in: header
      name: x-restricted-access-token
      description: >-
        Alternative authentication: Restricted access token (if not using Bearer
        token)

````

## Related topics

- [Changelog](https://docs.turrisfi.com/changelog.md)
- [Add a Contact](https://docs.turrisfi.com/api-reference/v2/downstream/contacts/add-contact.md)
- [Support and Contact Information](https://docs.turrisfi.com/guides/support.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.