Skip to main content
POST
Add a contact
Adds a contact to one of your agency relationships, the downstreamEntityAssociationId that GET /v2/upstream/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.

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

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. This endpoint allows 10 requests per 60 seconds per organization. See Rate limiting.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

idempotency-key
string

UUID to ensure idempotent request processing

Example:

"550e8400-e29b-41d4-a716-446655440000"

x-idempotency-key
string

Alternative UUID header for idempotent request processing

Example:

"550e8400-e29b-41d4-a716-446655440000"

Body

application/json
downstreamEntityAssociationId
string
required

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
string
required

Given name. Stored only when this email is new to Turris; an address Turris already knows keeps its stored name.

Example:

"Jon"

lastName
string
required

Surname. Stored only when this email is new to Turris; an address Turris already knows keeps its stored name.

Example:

"Doe"

email
string
required

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
string

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
enum<string>[]

Business roles this contact holds on this agency relationship.

Available options:
Compliance Officer,
Principal Owner,
Account Manager,
Finance Manager,
Support Staff,
Contract Signatory,
Accounts Payable,
Policy Maintenance
Example:
isPrimary
boolean

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
boolean

Set to false to add a Contract Signatory without the onboarding email Turris sends them. Defaults to true.

Example:

true

Response

The contact, as Get Contact returns it

data
object
required
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"