> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turrisfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Carrier & MGA API

> Who this API is for, what it answers, and what it will not do

This is the carrier side of the Turris API. If you are an agency or brokerage reading your own record, you want [The Agency API](/guides/agency-api) instead, and a credential works on exactly one of the two.

## 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

<CardGroup cols={2}>
  <Card title="The agencies you appoint" icon="building" href="/api-reference/v2/downstream-entity-associations/list-associations">
    Every agency associated with you, invited or added directly, each as its own association record with its own producer codes, documents and business rules.
  </Card>

  <Card title="Their producers" icon="user" href="/api-reference/v2/agents/list-agents">
    The agents attached to those agencies, by NPN, with license and authority detail.
  </Card>

  <Card title="Licenses and appointments" icon="id-card" href="/api-reference/v2/licenses/agent-licenses">
    State licenses and lines of authority for both agencies and agents, synced from NIPR, plus appointment records and regulatory actions.
  </Card>

  <Card title="Compliance verdicts" icon="circle-check" href="/api-reference/v2/compliance-status/agent-compliance">
    Not just the raw license rows: the evaluated answer against your own product requirements, per state and per line.
  </Card>

  <Card title="E&O and Cyber" icon="shield-check" href="/api-reference/v2/eo-cyber-compliance/get-policy-compliance">
    Policy documents you hold on each agency, with extracted metadata and a compliance verdict against your coverage minimums.
  </Card>

  <Card title="Policies and transactions" icon="file-lines" href="/api-reference/v2/policies/list-policies">
    Policy records you ingest, their transactions, and surplus-lines filings.
  </Card>
</CardGroup>

Two areas exist only on this surface: **[webhooks](/guides/webhooks)**, so you are told when an agency's standing changes instead of polling for it, and **[agency onboarding](/api-reference/v2/downstream-entity-associations/invite)**, the invite and add operations that create the relationship in the first place.

## What it will not do

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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](/api-reference/v2/surplus-lines-filings/get-filing) returns `downloadUrl` and `viewUrl` on its completion artifact.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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.

|                                     | `v1`                   | `v2`                  |
| ----------------------------------- | ---------------------- | --------------------- |
| Path shape                          | `/v1/agents`           | `/v2/upstream/agents` |
| Status                              | Stable, no sunset date | Stable, recommended   |
| Deprecated `dangerously-` endpoints | Present, 3 of them     | Absent                |

If you already run on `v1`, see [migrating from v1 to v2](/guides/migration-v1-to-v2). Nothing forces the move, and new capability lands on `v2`.

## Make your first call

<Steps>
  <Step title="Get credentials">
    **Settings → API** in the carrier application, in the environment you intend to integrate against. Sandbox first. Ask [support@turrisfi.com](mailto:support@turrisfi.com) if that section is not in your navigation.
  </Step>

  <Step title="Exchange them for a token">
    ```bash theme={null}
    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" }'
    ```

    Tokens last 60 minutes. **Cache them.** The token endpoint allows 4 requests per window, so a client that fetches a fresh token per call starts failing almost immediately.
  </Step>

  <Step title="List your associated agencies">
    ```bash theme={null}
    curl "https://public.api.sandbox.turrisfi.com/v2/upstream/downstream-entity-associations" \
      -H "Authorization: Bearer <your-jwt-token>"
    ```

    Start here. Most other endpoints take a `downstreamEntityAssociationId`, and this is where those ids come from.
  </Step>
</Steps>

[Getting Started for Carriers & MGAs](/guides/getting-started) covers credentials, environments and per-area entitlement in full. [Entity & Resource Definitions](/guides/entity-definitions) covers the data model behind these endpoints.

## 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:

| Word here                         | Means                                                                            |
| --------------------------------- | -------------------------------------------------------------------------------- |
| **Upstream entity**               | You                                                                              |
| **Downstream entity**             | An agency you appoint                                                            |
| **Downstream entity association** | Your relationship with one agency, identified by `downstreamEntityAssociationId` |
| **Agent**                         | A producer at an agency you appoint                                              |

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](/which-api-is-mine#the-same-records-two-vocabularies) 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** with `errorType` `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](/guides/getting-started#what-your-credentials-can-reach) is in the getting-started guide.


## Related topics

- [Getting Started for Carriers & MGAs](/guides/getting-started.md)
- [Agency Created](/guides/webhooks/downstream-entity-created.md)
- [Agency Deleted](/guides/webhooks/downstream-entity-deleted.md)