> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bindbee.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Document Download URL

> **Beta.** The Documents API is in beta and its contract may change.

Returns an expiring, signed URL from which the document file can be downloaded, along with its filename, MIME type and size. This is a separate call from Get Document By Id because the URL expires within minutes while the document metadata stays cacheable for hours, and because downloading a signed W-4 warrants its own permission and its own audit event.



## OpenAPI

````yaml get /api/hris/v1/documents/{id}/download
openapi: 3.1.0
info:
  title: Bindbee APIs
  version: 0.1.0
servers:
  - url: https://api.bindbee.dev
  - url: https://api-eu.bindbee.dev
security: []
paths:
  /api/hris/v1/documents/{id}/download:
    get:
      tags:
        - Documents
      summary: Get Document Download URL
      description: >-
        **Beta.** The Documents API is in beta and its contract may change.


        Returns an expiring, signed URL from which the document file can be
        downloaded, along with its filename, MIME type and size. This is a
        separate call from Get Document By Id because the URL expires within
        minutes while the document metadata stays cacheable for hours, and
        because downloading a signed W-4 warrants its own permission and its own
        audit event.
      operationId: get_document_download_url_api_hris_v1_documents__id__download_get
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Id
        - name: ttl_seconds
          in: query
          required: false
          schema:
            type: integer
            maximum: 3600
            minimum: 60
            description: >-
              How long the returned download URL stays valid, in seconds.
              Maximum is 3600.
            examples:
              - 300
            default: 300
            title: Ttl Seconds
          description: >-
            How long the returned download URL stays valid, in seconds. Maximum
            is 3600.
        - name: x-connector-token
          in: header
          required: true
          schema:
            type: string
            title: X-Connector-Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HrisDocumentDownload'
        '401':
          description: Missing or invalid bearer authentication credentials.
          headers:
            WWW-Authenticate:
              description: Bearer authentication challenge.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            The credentials are valid but do not permit access to this resource,
            e.g. a connector token used on a different API category or a model
            whose writes are disabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate limit exceeded.
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: >-
                Unix timestamp (seconds since epoch) at which the current
                rate-limit window resets.
              schema:
                type: integer
            Retry-After:
              description: Seconds to wait before retrying the request.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - HTTPBearer: []
components:
  schemas:
    HrisDocumentDownload:
      properties:
        url:
          anyOf:
            - type: string
              maxLength: 2083
              minLength: 1
              format: uri
            - type: 'null'
          title: Url
          description: >-
            A short-lived, signed URL from which the file can be downloaded.
            Fetch the file before `expires_at`; do not store or share the URL.
          examples:
            - https://files.bindbee.dev/documents/018b18ef...?signature=...
        expires_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Expires At
          description: >-
            The datetime at which the download URL stops working. Format:
            DateTime (ISO 8601)
          examples:
            - '2026-08-07T12:05:00Z'
        filename:
          anyOf:
            - type: string
            - type: 'null'
          title: Filename
          description: The name of the document file in the third-party system.
          examples:
            - Charlotte_Danielle_Abbott_W-4.pdf
        content_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Content Type
          description: The MIME type of the file behind the URL.
          examples:
            - application/pdf
        size_bytes:
          anyOf:
            - type: integer
            - type: 'null'
          title: Size Bytes
          description: The size of the file in bytes.
          examples:
            - 161484
      type: object
      required:
        - url
        - expires_at
        - filename
        - content_type
        - size_bytes
      title: HrisDocumentDownload
      description: >-
        An expiring link to the document file, together with the metadata a
        consumer needs in order to download and store it.
    ErrorResponse:
      type: object
      required:
        - detail
      properties:
        detail:
          type: string
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````