Skip to main content

ā€‹
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 every v1 operation except seven: 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 also carries endpoints v1 does not, because new endpoints are added to v2 only; the changelog lists each one as it lands.
This is a path change. For every endpoint both versions carry, request bodies, query parameters, response shapes and status codes are identical between v1 and v2, apart from the three additive differences in the note below. There is no field renaming, no envelope change and no new required parameters. Endpoints added since v2 shipped exist on v2 only; v1 receives bug fixes but no new endpoints.
Three endpoints differ, 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. GET /v2/upstream/surplus-lines-filings/{filingId} shows a fileDocumentId on every checklist attachment, the policy document and every completion artifact, the id to pass to Get a Download URL for a Document, which exists on v2 only; the v1 filing response does not carry it. POST /v2/upstream/file-documents additionally accepts the category Surplus Lines, which v1 rejects. For that category only, the file may be a DOC (application/msword), DOCX (application/vnd.openxmlformats-officedocument.wordprocessingml.document), JPEG (image/jpeg) or PNG (image/png) as well as a PDF (application/pdf), and downstreamEntityAssociationId must be omitted, because a Surplus Lines file belongs to a filing rather than to an agency relationship. Every other category behaves as on v1: PDF only, with downstreamEntityAssociationId required. Nothing is removed or renamed, so a client that ignores unknown fields and does not upload Surplus Lines files 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/:
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:
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: 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: Browse the full list with the version switcher at the top of the API Reference.

ā€‹
Suggested approach

  1. Point one non-critical read endpoint at /v2/upstream/ in sandbox and confirm the response matches what you already parse.
  2. Move the remaining reads. Responses are identical, so no parsing changes are needed.
  3. Move writes, replacing any dangerously- calls with their successors.
  4. 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

An endpoint both versions carry that does not behave identically between v1 and v2, other than the three additive differences described at the top of this page, is a bug on our side, not an expected difference. Email support@turrisfi.com with the endpoint and both responses.