Skip to main content
This is the operational walkthrough for the agency surface: entitlement, credentials, the token exchange, and your first calls. If you arrived here first, read The Agency API alongside it: that page covers what the surface answers, what it will not do, and how credential scope works. If you are a carrier reading about the agencies you appoint, you want Getting Started for Carriers & MGAs instead. The two surfaces are separate and a credential works on exactly one of them.

​
1. Check your organization is entitled

Agency API access is a product feature. If Settings → API is not in your Turris navigation, your organization does not have it yet; contact support@turrisfi.com. Each area of the API needs the same product feature as the matching screen in the agency application. 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. A 403 on one area never affects the others.

​
2. Mint a credential

1

Log into the Turris agency application

Use the environment you intend to integrate against. Sandbox first.
2

Go to Settings → API

Create an OAuth (machine-to-machine) client.
3

Store the client id and secret

The secret is stored hashed and cannot be retrieved again. If you lose it, delete the client and create another.
An API Client is the recommended agency credential, and this guide uses it. Agencies can also mint a Restricted Access Token from the same settings page: a single long-lived secret, fenced by an exact-match IP allowlist, for callers that cannot perform the token exchange below. It reaches the same endpoints but never expires, so prefer the API Client wherever you have a backend.

​
3. Exchange it for a token

Tokens are valid for 60 minutes. Cache them. The token endpoint allows 4 requests per window (5 minutes in production, 60 seconds elsewhere), so a client that fetches a fresh token per API call will start failing almost immediately.

​
4. Read your entities first

Start here rather than anywhere else: most other endpoints accept a downstreamEntityId, and this is where those ids come from.

​
5. Understand what your credential can see

Your credential sees its own organization plus everything beneath it, and never anything above it. Minted at your top company, it reaches the top company and every branch. Minted at a branch, it reaches that branch alone: not the parent, not sibling branches. The Agency API explains why this is narrower than what the web application shows a branch user, and why you should mint at the top company if your integration covers the whole group.

​
Narrowing to one entity

Every list accepts downstreamEntityId except three:
The exceptions are the market sub-lists: /v2/downstream/markets/{upstreamDownstreamAssociationId}/documents, /entity-contacts and /market-contacts take only the association id plus page and limit. An id outside your scope returns 404, not 403. Treat a 404 on an id you believe is yours as a sign the credential was minted lower in the tree than you thought.

​
Where to go next

The Agency API maps what the surface answers, the limits worth knowing before you build (no webhooks, no download URL for a compliance document, no view into a carrier’s own data), and the production checklist for pagination, idempotency and rate limiting. Since there are no agency webhooks, the polling loop that replaces them starts at Actions Required and the licensing summaries.

Related topics

IntroductionThe Agency APIAuthentication