Getting Started for Carriers & MGAs

To begin using the Turris API, follow these steps:

1. Create an Upstream Entity Account

If you don’t already have one, you’ll need to reach out to Turris support to invite you onto the Turris platform.

You will need two separate invitations - one for the sandbox environment and another one for the live production environment.

Contact support@turrisfi.com to request access.

2. Generate API Credentials

Log into the web app

Access your Turris dashboard at the appropriate environment URL.

Navigate to API Settings

Go to Settings > API in the navigation menu.

Create your credentials

Create your API credentials of choice. We highly recommend the OAuth flow.

Store credentials securely

Store the credentials before closing the modals.

Important: Sensitive secrets and tokens are not known to Turris, are stored as hashed strings, and cannot be retrieved again at a later time. If you lose them, you will have to delete the issued credentials and create new ones.

3. Environment Setup

Choose the appropriate environment for your use case:

Use Case	Environment	Base URL
Development & Testing	Sandbox	`https://public.api.sandbox.turrisfi.com`
Production	Live	`https://public.api.live.turrisfi.com`

4. Make Your First API Call

Once you have your credentials, authenticate and make your first request:

curl -X POST "https://public.api.sandbox.turrisfi.com/v2/auth/jwt" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret"
  }'

curl -X GET "https://public.api.sandbox.turrisfi.com/v2/upstream/downstream-entity-associations" \
  -H "Authorization: Bearer <your-jwt-token>"

On v1 the same two calls are POST /v1/auth/jwt and GET /v1/downstream-entity-associations. Tokens are accepted by both versions, so you can try v2 without issuing new credentials. See migrating from v1 to v2.

What your credentials can reach

Each area of the API needs the same product feature as the matching screen in the Turris application. API access on its own opens the door; it does not grant an area your organization has not bought. If you can see a section in the app, its endpoints are available to your credential; if you cannot, they return 403 with an errorType of product_feature_subscription_required and a message naming the feature to ask for. The paths below are written without their version and persona prefix. Each one applies to both /v1/* and /v2/upstream/*.

Endpoints	Product feature
`/agents`	Agents View
`/agents/{id}/licenses`, `/agents/licenses`, `/agents/{id}/license-compliance-statuses`, `/downstream-entity-associations/{id}/licenses`, `/downstream-entity-associations/licenses`, `/downstream-entity-associations/{id}/license-compliance-statuses`	License Compliance
`/agents/{id}/appointments`, `/downstream-entity-associations/{id}/appointments`	Appointment
`/downstream-entity-associations` and its sub-resources, including `/downstream-entity-associations/{id}/policy-compliance-statuses`	Downstream Entity
`/agents/{id}/regulatory-actions`, `/downstream-entity-associations/{id}/regulatory-actions`	Regulatory Actions
`/policies` and its transactions	Policy Compliance
`/products`	Products and Compliance Settings
`/contract-container-templates`	Template Agreement Settings
`/webhooks`	Webhook Settings
`/npn-lookup`, `/file-documents`	Tools
`/surplus-lines-filings`	Surplus-Lines Filing

Three endpoint groups need only API access and no further feature: /contacts, /market-contacts and /compliance-data-subscriptions.

Entitlement is checked on every request, not only when the credential is created, and it covers v1 as well as v2. An organization that stops being a Turris customer, or has the Public API feature switched off, receives 403 rather than continuing to work until its credential is deleted.

A feature that has just been switched on can take up to a minute to take effect, because entitlement is cached briefly. Requesting a new token does not shorten that: the cache is keyed on your organization, not on the token.

Next Steps

The Carrier & MGA API

See what this API answers and what it will not do

Authentication

Learn about OAuth and Restricted Access Token authentication

Entity Definitions

Understand the core entities and their relationships

API Reference

Explore all available endpoints

Error Handling

Learn how to handle API errors

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

Getting Started for Carriers & MGAs

1. Create an Upstream Entity Account

2. Generate API Credentials

3. Environment Setup

4. Make Your First API Call

What your credentials can reach

Next Steps

The Carrier & MGA API

Authentication

Entity Definitions

API Reference

Error Handling

​1. Create an Upstream Entity Account

​2. Generate API Credentials

​3. Environment Setup

​4. Make Your First API Call

​What your credentials can reach

​Next Steps

The Carrier & MGA API

Authentication

Entity Definitions

API Reference

Error Handling

1. Create an Upstream Entity Account

2. Generate API Credentials

3. Environment Setup

4. Make Your First API Call

What your credentials can reach

Next Steps