> ## 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/file-documents/list-documents) returns that is not deleted, and for the files on your surplus-lines filings that you can see in the filing response. The default list includes deleted documents, except Surplus Lines files, which are never listed once deleted, and asking for a deleted document returns **404**. 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/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 your organization sees: the copy held on your relationship with the agency, otherwise the latest version. Pass `versionId` (an S3 version id from the document's version history) to pick a specific one.

If a compliance document has more than one relationship with your organization, the call returns **400** until you say which one with `upstreamDownstreamAssociationId`. The parameter is ignored for categories that have no per-relationship copies.

## Limits

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` is not a valid MongoDB ObjectId, or the document has more than one relationship with your organization and `upstreamDownstreamAssociationId` is missing.

### Document Not Found (404)

Returned when the document does not exist, is not yours, has been deleted, sits on a checklist item Turris keeps internal, 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/upstream/file-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/upstream/file-documents/{fileDocumentId}/download-url:
    get:
      tags:
        - upstream/file-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 that is not deleted (the default list includes deleted
        documents, which return 404 here), and for the files on your
        surplus-lines filings that you can see in the filing response. For a
        compliance document you get the version your organization sees: your
        relationship copy, else the latest version. 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: FileDocumentFeatureV2Controller_getDownloadUrl_v2
      parameters:
        - name: fileDocumentId
          required: true
          in: path
          description: Unique identifier of the file 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 you see.
          schema:
            example: Xo2f9mK1Qv.3a7b
            type: string
        - name: upstreamDownstreamAssociationId
          required: false
          in: query
          description: >-
            The downstream entity association whose copy to download. Needed
            only when a compliance document has more than one relationship with
            your organization; ignored for other categories.
          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 id, or the document has more than one relationship with your
            organization and upstreamDownstreamAssociationId is missing
          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: >-
            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, not yours, deleted (List Documents can still
            return it), on a checklist item Turris keeps internal, or versionId
            is not one of its versions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '429':
          description: >-
            Rate limit exceeded. Your organization may make 120 requests per 60
            seconds to this endpoint. 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/downstream/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.