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

> Mint short-lived links to download or view one document

Returns two short-lived presigned links for one document: `downloadUrl` saves the file under its original name, 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.

It works for every document [List Documents](/api-reference/v2/downstream/documents/list-documents) returns, and for the files on your surplus-lines filings that you can see in the filing response. Files on checklist items Turris keeps internal are never served: they return **404**, the same response as an id that does not exist.

For a file on a filing, pass the `fileDocumentId` the [filing response](/api-reference/v2/downstream/surplus-lines-filings/get-filing) shows on that file: every checklist attachment, the policy document and every completion artifact carries one. That is also how you fetch a file someone else put on the filing, such as a document Turris attached. An attachment's `_id` identifies the attachment record, not the document, and returns **404** here.

## Which version you get

For a compliance document you get the version [List Documents](/api-reference/v2/downstream/documents/list-documents) shows. To get the copy one carrier holds instead, the one [List a Market's Documents](/api-reference/v2/downstream/markets/market-documents) shows for your own compliance documents, pass that market's id as `upstreamDownstreamAssociationId`. Files the carrier shared into a relationship (`isSharedByCarrier: true` in that list) are not downloadable here and return **404**. Pass `versionId` (an S3 version id from the document's version history) to pick a specific version. The market id is ignored for categories that have no per-market copies.

## Limits

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

## Error Scenarios

### Bad Request (400)

Returned when `fileDocumentId` or a query parameter is not valid.

### Document Not Found (404)

Returned when the document does not exist or is not in your organization, sits on a checklist item Turris keeps internal, the market is not yours, or `versionId` is not one of its versions.

### Too Many Requests (429)

Returned when the rate limit above is exceeded.

### Unauthorized (401)

Missing or invalid authentication token. See [Authentication](/authentication).


## OpenAPI

````yaml openapi/v2.json GET /v2/downstream/documents/{fileDocumentId}/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/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: 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/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/webhooks
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
paths:
  /v2/downstream/documents/{fileDocumentId}/download-url:
    get:
      tags:
        - downstream/documents
      summary: Get a download URL for a document
      description: >-
        Returns short-lived presigned URLs for one document: downloadUrl saves
        it under its original name, viewUrl opens it in a browser. Both expire
        at expiresAt, one hour after the call. Works for every document List
        Documents returns and for the files on your surplus-lines filings that
        you can see in the filing response. A compliance document returns the
        version List Documents shows, or the copy a market holds when you pass
        that market id. Files on checklist items Turris keeps internal return
        404. For a surplus-lines filing file, pass the fileDocumentId shown on
        that file in the filing response (on a checklist item attachment, the
        policy document or a completion artifact). An attachment _id identifies
        the attachment record, not the file, and returns 404 here. Template
        files on checklist items are not documents: use their own downloadUrl.
      operationId: DocumentsController_getDownloadUrl_v2
      parameters:
        - name: fileDocumentId
          required: true
          in: path
          description: Unique identifier of the document
          schema:
            example: 66a1b2c3d4e5f6a7b8c9d0e3
            type: string
        - name: versionId
          required: false
          in: query
          description: >-
            S3 version id of the version to download, from the document version
            history. Defaults to the latest version.
          schema:
            example: Xo2f9mK1Qv.3a7b
            type: string
        - name: upstreamDownstreamAssociationId
          required: false
          in: query
          description: >-
            A market id from List Markets. Downloads the copy that market holds,
            the one List a Market Documents shows, instead of the version List
            Documents shows. Ignored for categories without per-market copies.
          schema:
            example: 507f1f77bcf86cd799439011
            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 document id or query parameters
          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. 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: >-
            Document not found or not in your organization, on a checklist item
            Turris keeps internal, the market is not yours, or versionId is not
            one of its versions
          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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
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
            - 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
            - 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 Document](/api-reference/v2/file-documents/get-download-url.md)
- [List Documents](/api-reference/v2/downstream/documents/list-documents.md)
- [Get a Surplus-Lines Filing](/api-reference/v2/downstream/surplus-lines-filings/get-filing.md)


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