Who it is for
Agencies and brokerages: organizations that hold licenses and place business, and need their own compliance record as data rather than as a screen. Your own entities and branches, your own producers, your own licenses and appointments, and the markets you place through. Your credential is issued to one Turris organization and reaches/v2/downstream/*. On /v2/upstream/*, and on every persona-scoped /v1/* route, it returns 403 with errorType invalid_organization_category.
Four routes are the exception, on both versions.
POST /v{1,2}/auth/jwt, GET /v{1,2}/auth/test-oauth, GET /v{1,2}/auth/test-restricted-access-token and GET /v{1,2}/heartbeat carry no persona and serve any credential, because the token itself identifies the organization. So the v1 token endpoint works for you; everything you would then call with that token does not. Prefer the v2 paths regardless, since only GET /v2/auth/test-oauth reports orgCategory.This surface is
v2 only. v1 predates the persona model and serves carriers exclusively, so there is no v1 agency surface and there will not be one. Nothing is missing from your surface as a result: v2 is where it was born.What it answers
Your organization
Your legal entities and branches, the producers attached to them, and your contacts. Call
entities first: most other endpoints take a downstreamEntityId and this is where those ids come from.Licenses and appointments
State licenses and lines of authority for both your entities and your producers, plus appointment records, all synced from NIPR.
What needs attention today
The one endpoint to poll on a schedule. Expiring and expired licenses across your whole organization, in one list.
Licensing overview
The aggregates behind the dashboard: counts and coverage per entity and per producer, rather than raw license rows.
Your markets
The carriers, MGAs and wholesalers you place business with, their contacts, and the documents shared on each relationship.
Corporate registrations
State registration filings and the standing facts behind them.
Documents
Compliance policies, their status per entity, and uploads.
Renewal work in flight
The license requests Turris is running on your behalf, and the groups they belong to.
The one thing to understand before you build
Your credential sees its own organization plus everything beneath it, and never anything above it.Minted at your top company
You see the top company and every branch. This is what most integrations want.
Minted at a branch
You see that branch and nothing else. Not the parent, not sibling branches, even though a person signed into that branch in the web application can see them.
What it will not do
Send you webhooks
Send you webhooks
Webhooks are a carrier feature. The events fire about an agency a carrier appoints, and only a carrier credential can subscribe. There is no
/v2/downstream/webhooks and no agency equivalent.Poll Actions Required and the licensing summaries on a schedule instead. Tell us if a subscription would be more useful.Return a document download URL
Return a document download URL
Document endpoints return metadata and version history. No presigned URL is returned and there is no document endpoint that mints one, on either surface.The one exception is a completed surplus-lines filing: Get a Filing returns
downloadUrl and viewUrl on its completion artifact.Reach anything above you in the tree
Reach anything above you in the tree
Not your parent company, not sibling branches, and never another agency. See credential scope above.
Show you a carrier's own compliance data
Show you a carrier's own compliance data
A market record tells you about your relationship with that carrier, its contacts and the documents shared on it. It is not a window into the carrier’s organization.
Accept downstreamEntityId on three market sub-lists
Accept downstreamEntityId on three market sub-lists
Almost every list narrows by
downstreamEntityId. The three exceptions are the market sub-lists, /markets/{upstreamDownstreamAssociationId}/documents, /entity-contacts and /market-contacts, which take only the association id plus page and limit.Make your first call
1
Get credentials
Settings → API in the agency application, in the environment you intend to integrate against. Sandbox first. If that section is not in your navigation, your organization is not entitled yet; contact support@turrisfi.com.
2
Exchange them for a token
3
Read your entities
downstreamEntityId values in this response are what the rest of the surface takes.Vocabulary, before you read the reference
Most of this surface speaks your language. Three names are worth knowing because they are not the words you would guess:
The full mapping between the two surfaces’ vocabularies is on one page if you ever compare notes with a carrier.
Entitlement
Each area of this API needs the same product feature as the matching screen in the agency application. API access 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 witherrorType product_feature_subscription_required and a message naming the feature to ask for.
A 403 on one area never affects the others: the rest of your integration keeps working. The full endpoint-to-feature table is in the getting-started guide.
Before you go to production
Every list is paginated
Every list is paginated
items, total, page, limit, totalPages. Default 50, maximum 100. See Pagination.Send an idempotency key on every write
Send an idempotency key on every write
All seven
POST operations on this surface accept an Idempotency-Key header and replay the original response for an hour. Without one, a retried request runs twice. See Idempotency.Rate limits are per organization
Rate limits are per organization
120 reads and 30 writes per minute, counted per endpoint and per organization rather than per IP address. See Rate Limiting.
Branch on errorType, not on message text
Branch on errorType, not on message text
Messages are prose and may be reworded. The codes are a published enum. See Error Handling.