Who it is for
MGAs, carriers and wholesalers: organizations that appoint agencies and need to know, continuously and without asking anyone, whether those agencies and their producers are licensed and appointed for the business being placed. Your credential is issued to one Turris organization and reaches/v1/* and /v2/upstream/*. On /v2/downstream/* it returns 403 with errorType invalid_organization_category.
What it answers
The agencies you appoint
Every agency associated with you, invited or added directly, each as its own association record with its own producer codes, documents and business rules.
Their producers
The agents attached to those agencies, by NPN, with license and authority detail.
Licenses and appointments
State licenses and lines of authority for both agencies and agents, synced from NIPR, plus appointment records and regulatory actions.
Compliance verdicts
Not just the raw license rows: the evaluated answer against your own product requirements, per state and per line.
E&O and Cyber
Policy documents you hold on each agency, with extracted metadata and a compliance verdict against your coverage minimums.
Policies and transactions
Policy records you ingest, their transactions, and surplus-lines filings.
What it will not do
Read your own licenses as if you were an agency
Read your own licenses as if you were an agency
This surface answers questions about the agencies below you. If your organization also needs its own licensing view, that is the agency surface and it needs its own credential from an agency organization.
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 another carrier's data
Reach another carrier's data
Every resource is scoped to your organization. An association you do not own is not visible, and market contacts you did not publish are never exposed.
Page most list responses
Page most list responses
Carrier lists return the complete array of matching records. The one exception is
GET /v2/upstream/policies/{policyId}/transactions, which is paginated with a default limit of 50 and a maximum of 100. Read the full set there or you will silently reconcile against the first page.Which version to build on
v2 is the recommendation for anything new. It is not a rewrite: request bodies, query parameters and response shapes are identical to v1. /v2/upstream carries 48 of v1’s 55 operations, and the seven it does not are the four auth and heartbeat paths, which moved to the unsegmented /v2/auth/* and /v2/heartbeat, plus the three deprecated dangerously- endpoints, each of which names its successor. v2 adds no upstream operation that v1 lacks.
If you already run on
v1, see migrating from v1 to v2. Nothing forces the move, and new capability lands on v2.
Make your first call
1
Get credentials
Settings → API in the carrier application, in the environment you intend to integrate against. Sandbox first. Ask support@turrisfi.com if that section is not in your navigation.
2
Exchange them for a token
3
List your associated agencies
downstreamEntityAssociationId, and this is where those ids come from.Vocabulary, before you read the reference
This surface uses carrier vocabulary throughout, and two of its words mean the opposite of what an agency would expect:
So a group named “Agencies You Appoint” and a path reading
/downstream-entity-associations are the same thing, and “Get Downstream Entity Licenses” returns an agency’s licenses, not yours. The full mapping to agency vocabulary is on one page if you ever need to reconcile the two.
Entitlement
Each area of this API needs the same product feature as the matching screen in the carrier 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.
Entitlement is checked on every request, not only when the credential is created, and it covers v1 as well as v2. The full endpoint-to-feature table is in the getting-started guide.