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

# Get a Download URL for a State Template File

> Mint short-lived links to download or view one blank form

Returns two short-lived presigned links for one blank form listed by [Get State Requirements](https://docs.turrisfi.com/api-reference/v2/downstream/surplus-lines-states/get-requirements.md): `downloadUrl` saves the file under its `fileName`, and `viewUrl` opens it in a browser. Both stop working at `expiresAt`, one hour after the call. Fetch a fresh pair when you need one rather than storing the links.

Pass the state's code and the file's `id` from the requirements response as `templateFileId`.

## Files you cannot download

A file on an item Turris keeps internal, a file no longer on the state's requirements, a file id from another state and an unknown id all return the same **404**.

## Limits

Like every read on the Agency API, this endpoint allows **120 requests per 60 seconds per organization**. Past that it returns **429** with a `Retry-After` header. See [Rate Limiting](https://docs.turrisfi.com/guides/rate-limiting.md).

## Error Scenarios

### Bad Request (400)

Returned when `stateCode` is not a US state or territory code, or `templateFileId` is not a valid MongoDB ObjectId.

### File Not Found (404)

Returned when Turris keeps no requirements for the state, or the file is internal, no longer listed or unknown.

### Unauthorized (401)

Missing or invalid authentication token. See [Authentication](https://docs.turrisfi.com/authentication.md).

### Forbidden (403)

Your organization is not entitled to the API, or does not have the Surplus-Lines Filing feature.

### Too Many Requests (429)

Returned when the limit above is exceeded.


## OpenAPI

````yaml openapi/v2.json GET /v2/downstream/surplus-lines-states/{stateCode}/template-files/{templateFileId}/download-url
openapi: 3.0.0
info:
  title: Turris Public API
  description: API for managing insurance compliance data
  version: 2.0.0
  contact: {}
servers:
  - url: https://public.api.live.turrisfi.com
    description: Production
  - url: https://public.api.sandbox.turrisfi.com
    description: Sandbox
security:
  - bearer: []
  - restricted-access-token: []
tags:
  - name: auth
    description: Shared. Serves either organization category, so no persona applies.
    x-organization-category: null
  - name: downstream/actions-required
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/appointments
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/carriers
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/compliance-configs
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/contacts
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/corporate-registrations
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/documents
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/entities
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/license-overview
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/license-requests
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/licenses
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/markets
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/producers
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/surplus-lines-filings
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/surplus-lines-states
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: heartbeat
    description: Shared. Serves either organization category, so no persona applies.
    x-organization-category: null
  - name: upstream/agents
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/agents-license-compliance
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/appointment-requests
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/carriers
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/compliance-data-subscriptions
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/contacts
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/contract-container-templates
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/diligent-effort-requests
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/downstream-entity-associations
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/file-documents
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/market-contacts
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/npn-lookup
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/policies
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/products
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/surplus-lines-filings
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/surplus-lines-states
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/termination-requests
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/webhooks
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
paths:
  /v2/downstream/surplus-lines-states/{stateCode}/template-files/{templateFileId}/download-url:
    get:
      tags:
        - downstream/surplus-lines-states
      summary: Get a download URL for a state template file
      description: >-
        Returns short-lived presigned URLs for one blank form listed by Get
        State Requirements: downloadUrl saves it under its file name, viewUrl
        opens it in a browser. Both expire at expiresAt, one hour after the
        call. A file Turris keeps internal, one no longer on the state's
        requirements, and an unknown id all return the same 404.
      operationId: DownstreamSurplusLinesStatesController_getTemplateFileDownloadUrl_v2
      parameters:
        - name: stateCode
          required: true
          in: path
          description: US state or territory code
          schema:
            example: TX
            type: string
            enum:
              - AL
              - AK
              - AZ
              - AR
              - CA
              - CO
              - CT
              - DE
              - FL
              - GA
              - HI
              - ID
              - IL
              - IN
              - IA
              - KS
              - KY
              - LA
              - ME
              - MD
              - MA
              - MI
              - MN
              - MS
              - MO
              - MT
              - NE
              - NV
              - NH
              - NJ
              - NM
              - NY
              - NC
              - ND
              - OH
              - OK
              - OR
              - PA
              - RI
              - SC
              - SD
              - TN
              - TX
              - UT
              - VT
              - VA
              - WA
              - WV
              - WI
              - WY
              - GU
              - PR
              - VI
              - DC
        - name: templateFileId
          required: true
          in: path
          description: >-
            Identifier of a template file, as returned in templateFiles[].id by
            Get State Requirements
          schema:
            example: 6650a1b2c3d4e5f6a7b8c9d2
            type: string
      responses:
        '200':
          description: Presigned download and view URLs
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/FileDocumentDownloadUrlResponse'
                  requestId:
                    type: string
                    description: Unique request identifier
                    example: dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8
                  timestamp:
                    type: string
                    description: Response timestamp
                    example: '2025-11-12T20:49:03.293Z'
                required:
                  - data
                  - requestId
                  - timestamp
        '400':
          description: Invalid stateCode or templateFileId
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '401':
          description: Invalid or missing auth token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '403':
          description: >-
            Your organization is not entitled to the public API, or does not
            have the Surplus-Lines Filing feature. Also returned with
            `errorType` `invalid_organization_category` when your credential's
            organization category does not match the one this endpoint serves;
            `details` names the expected and actual category. This endpoint can
            return 403 for other reasons too, so branch on `errorType`; the
            Error Handling guide lists them.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '404':
          description: >-
            No requirements for this state, or the file is internal, no longer
            listed, or unknown
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '429':
          description: >-
            Rate limit exceeded. Like every read on the Agency API, this
            endpoint allows 120 requests per 60 seconds per organization. Wait
            the number of seconds in the Retry-After header, then retry. Also
            returned when this credential passes the API-wide limit of 1000
            requests per 10 seconds, counted across every endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
          headers:
            Retry-After:
              description: >-
                Seconds to wait before retrying. Sent when a rate limit refused
                the request.
              schema:
                type: integer
components:
  schemas:
    FileDocumentDownloadUrlResponse:
      type: object
      properties:
        downloadUrl:
          type: string
          description: >-
            Presigned URL that downloads the file under fileName. Valid until
            expiresAt.
          example: https://files.example.com/d?X-Amz-Signature=abc
        viewUrl:
          type: string
          description: >-
            Presigned URL that opens the file inline in a browser. Valid until
            expiresAt.
          example: https://files.example.com/v?X-Amz-Signature=def
        fileName:
          type: string
          description: Name the download is saved under
          example: policy.pdf
        contentType:
          type: string
          description: MIME type of the file
          example: application/pdf
        expiresAt:
          type: string
          description: When both URLs stop working, as an ISO 8601 instant
          example: '2026-09-29T13:00:00.000Z'
      required:
        - downloadUrl
        - viewUrl
        - fileName
        - contentType
        - expiresAt
    ErrorResponseDto:
      type: object
      properties:
        statusCode:
          type: number
          description: HTTP status code
        requestId:
          type: string
          description: Unique request identifier for debugging
        errorType:
          type: string
          description: >-
            Machine-readable error classification. Branch on this rather than on
            `errorMessage`, which is prose and may change. Authentication
            failures returned by our identity provider are forwarded verbatim,
            so a 401 can carry a code outside this list; treat an unrecognised
            value as a generic failure of its HTTP status.
          enum:
            - conflict
            - contact_not_authorized
            - contract_already_signed
            - document_exceeds_page_limit
            - downstream_entity_member_exists
            - duplicate_external_id_error
            - duplicate_member_email
            - duplicate_producer_code_error
            - forbidden
            - gateway_timeout
            - inactive_email
            - internal_server_error
            - invalid_email
            - invalid_email_for_invites
            - invalid_organization_category
            - invalid_organization_slug
            - invalid_phone_number
            - invalid_token
            - invite_limit_reached
            - jwt_invalid
            - m2m_client_not_found
            - not_found
            - online_signing_in_progress
            - organization_already_exists
            - organization_slug_already_used
            - payment_required
            - producer_agreement_required
            - product_feature_subscription_required
            - service_unavailable
            - session_authorization_error
            - some_custom_error_string
            - throttled
            - too_many_requests
            - unauthorized
            - unauthorized_client
            - unexpected_400_stytch_error
            - unexpected_403_stytch_error
            - unexpected_404_stytch_error
            - unexpected_error
            - unexpected_stytch_error
            - unprocessable_entity
            - validation_error
          example: validation_error
        errorMessage:
          description: Array of error messages
          type: array
          items:
            type: string
        timestamp:
          type: string
          description: ISO timestamp when the error occurred
        details:
          type: object
          description: Additional error context
      required:
        - statusCode
        - requestId
        - errorType
        - errorMessage
        - timestamp
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
    restricted-access-token:
      type: apiKey
      in: header
      name: x-restricted-access-token
      description: >-
        Alternative authentication: Restricted access token (if not using Bearer
        token)

````

## Related topics

- [Get a Download URL for a State Template File](https://docs.turrisfi.com/api-reference/v2/surplus-lines-states/get-template-file-download-url.md)
- [Get State Requirements](https://docs.turrisfi.com/api-reference/v2/downstream/surplus-lines-states/get-requirements.md)
- [Changelog](https://docs.turrisfi.com/changelog.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.