Migrating from v1 to v2

This page is for carriers and MGAs with an existing /v1/* integration. There was never a v1 agency surface, so an agency has nothing to migrate: start at Getting Started for Agencies. /v2/upstream carries 48 of v1’s 55 operations. The seven it does not are the four auth and heartbeat paths, which moved to the unsegmented /v2/auth/* and /v2/heartbeat, and the three deprecated dangerously- endpoints listed below, each of which names its successor. v2 adds no upstream operation that v1 lacks.

This is a path change. Request bodies, query parameters, response shapes and status codes are identical between v1 and v2. There is no field renaming, no envelope change and no new required parameters.

One endpoint differs, additively. GET /v2/auth/test-oauth returns an extra orgCategory field naming the kind of organization your credential belongs to; the v1 response does not. Nothing is removed or renamed, so a client that ignores unknown fields needs no change.

You do not have to migrate. v1 is stable, fully supported and has no sunset date. Migrate when you want the endpoints that will only be added to v2.

1. Change the path prefix

Replace /v1/ with /v2/upstream/:

# Before
curl "https://public.api.live.turrisfi.com/v1/agents" \
  -H "Authorization: Bearer YOUR_TOKEN"

# After
curl "https://public.api.live.turrisfi.com/v2/upstream/agents" \
  -H "Authorization: Bearer YOUR_TOKEN"

For most integrations this is a one-line change to a base URL constant. upstream identifies the kind of organization your credentials belong to. See versioning for the full persona model and why it was introduced.

2. Authentication is unchanged

Your existing client ID and secret work as-is. No new credentials, no re-issuing tokens. The token endpoint moves to /v2/auth/jwt and takes no persona segment, because the token itself identifies your organization:

curl -X POST "https://public.api.live.turrisfi.com/v2/auth/jwt" \
  -H "Content-Type: application/json" \
  -d '{"clientId": "YOUR_CLIENT_ID", "clientSecret": "YOUR_CLIENT_SECRET"}'

GET /v2/heartbeat is likewise persona-neutral. Tokens are interchangeable between versions. A token minted at /v1/auth/jwt is accepted by /v2/upstream/*, so you can migrate endpoint by endpoint rather than all at once.

3. Three endpoints are not in v2

These were deprecated in v1 and are absent from v2. Each has a direct replacement with an identical request and response:

Not in v2	Use instead
`POST /v1/downstream-entity-associations/dangerously-invite`	`POST /v2/upstream/downstream-entity-associations/invite`
`POST /v1/downstream-entity-associations/dangerously-add`	`POST /v2/upstream/downstream-entity-associations/add`
`GET /v1/downstream-entity-associations/licenses/dangerously-surplus-lines`	`GET /v2/upstream/downstream-entity-associations/licenses/surplus-lines`

If you call any of these on v1 today you will receive Deprecation, Sunset and Link response headers. They remain available on v1 until the sunset date of 1 January 2027.

Switching from a dangerously- endpoint to its replacement is a rename only. The request body and the response are the same, so it is safe to make this change on v1 before you migrate to v2, and we recommend doing so.

4. Everything else maps one to one

Every other v1 endpoint exists on v2 at the same path with the new prefix. Some examples:

v1	v2
`GET /v1/agents/{agentId}/licenses`	`GET /v2/upstream/agents/{agentId}/licenses`
`GET /v1/downstream-entity-associations`	`GET /v2/upstream/downstream-entity-associations`
`POST /v1/policies`	`POST /v2/upstream/policies`
`GET /v1/webhooks`	`GET /v2/upstream/webhooks`

Browse the full list with the version switcher at the top of the API Reference.

Suggested approach

Point one non-critical read endpoint at /v2/upstream/ in sandbox and confirm the response matches what you already parse.
Move the remaining reads. Responses are identical, so no parsing changes are needed.
Move writes, replacing any dangerously- calls with their successors.
Update your token endpoint to /v2/auth/jwt.

Because tokens work across versions and the shapes match, a partial migration is a valid resting state. There is no deadline.

Getting help

Something not behaving identically between v1 and v2 is a bug on our side, not an expected difference. Email support@turrisfi.com with the endpoint and both responses.

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

Migrating from v1 to v2

Migrating from v1 to v2

1. Change the path prefix

2. Authentication is unchanged

3. Three endpoints are not in v2

4. Everything else maps one to one

Suggested approach

Getting help

​Migrating from v1 to v2

​1. Change the path prefix

​2. Authentication is unchanged

​3. Three endpoints are not in v2

​4. Everything else maps one to one

​Suggested approach

​Getting help

Migrating from v1 to v2

1. Change the path prefix

2. Authentication is unchanged

3. Three endpoints are not in v2

4. Everything else maps one to one

Suggested approach

Getting help