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

# List Document Requests

> Retrieve a paginated list of all document requests belonging to you.

Retrieve a paginated list of all document requests created by your organisation. This endpoint supports filtering by status, searching by ID, and sorting options.

<Note>
  This endpoint requires the **Document Requests** feature to be enabled for your organisation. If you receive a `403` with `request.organisations.module.not-enabled`, contact your organisation admin to have it activated. [Learn more](/guides/feature-modules).
</Note>

## Features

* **Filtering**: Filter by request status (`pending`, `completed`, `expired`) or specific request ID.
* **Sorting**: Order results by creation date to find newest requests first.
* **Pagination**: Use `limit` and `offset` to manage large result sets.

## Best Practices

1. **Monitor Status**: Regularly list `pending` requests to track completion rates and identify customers who may need a follow-up.
2. **Expiration Tracking**: Identify requests approaching their `expires_at` date to ensure document collection is completed in time.
3. **Efficiency**: Use a `limit` of 100 for background reporting and 20-50 for user-facing dashboards.


## OpenAPI

````yaml GET /document-requests
openapi: 3.1.0
info:
  title: Veridox Core API
  description: Veridox Core Platform API
  version: 0.0.1
  contact: {}
servers:
  - url: https://api.uk.veridox.ai
    description: Live (UK)
  - url: https://api.ca.veridox.ai
    description: Live (CA)
security: []
tags:
  - name: Status
    description: System status and health check endpoints
  - name: Cases
    description: Case and case file management
  - name: Organisations
    description: Organisation management
  - name: Document Requests
    description: Document request management
  - name: Search
    description: Search functionality
  - name: Admin
    description: Administrative endpoints
paths:
  /document-requests:
    get:
      tags:
        - Document Requests
      summary: List document requests
      description: >-
        Returns a paginated list of document requests created by the
        authenticated user. Supports filtering by status and sorting.
      operationId: DocumentRequestsController_listDocumentRequests
      parameters:
        - name: id
          required: false
          in: query
          x-nestjs_zod-parent-additional-properties: false
          schema:
            type: string
            format: uuid
            pattern: >-
              ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$
        - name: status
          required: false
          in: query
          x-nestjs_zod-parent-additional-properties: false
          schema:
            type: string
            enum:
              - pending
              - completed
              - expired
        - name: limit
          required: false
          in: query
          x-nestjs_zod-parent-additional-properties: false
          schema:
            default: '20'
            type: string
        - name: offset
          required: false
          in: query
          x-nestjs_zod-parent-additional-properties: false
          schema:
            default: '0'
            type: string
        - name: sort_order
          required: false
          in: query
          x-nestjs_zod-parent-additional-properties: false
          schema:
            default: desc
            type: string
            enum:
              - asc
              - desc
      responses:
        '200':
          description: List of document requests retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentRequestListResponseDto'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        '401':
          description: Unauthorized (invalid or missing authentication token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        '429':
          description: Too many requests (rate limit exceeded)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
      security:
        - api-key: []
components:
  schemas:
    DocumentRequestListResponseDto:
      type: object
      properties:
        links:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
                pattern: >-
                  ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$
              case_id:
                type: string
                format: uuid
                pattern: >-
                  ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$
              recipient_email:
                type: string
                format: email
                pattern: >-
                  ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
              recipient_name:
                anyOf:
                  - type: string
                  - type: 'null'
              label:
                type: string
              status:
                type: string
                enum:
                  - pending
                  - completed
                  - expired
              expires_at:
                type: string
                format: date-time
                pattern: >-
                  ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
              max_files:
                type: integer
                minimum: -9007199254740991
                maximum: 9007199254740991
              created_at:
                type: string
                format: date-time
                pattern: >-
                  ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
              updated_at:
                type: string
                format: date-time
                pattern: >-
                  ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
            required:
              - id
              - case_id
              - recipient_email
              - recipient_name
              - label
              - status
              - expires_at
              - max_files
              - created_at
              - updated_at
            additionalProperties: false
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-parent-additional-properties: false
        total:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-parent-additional-properties: false
        limit:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-parent-additional-properties: false
        offset:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-parent-additional-properties: false
      required:
        - links
        - total
        - limit
        - offset
    ErrorDto:
      type: object
      properties:
        error_code:
          type: string
          description: Machine-readable error code for programmatic handling
          examples:
            - request.cases.file.missing-risk-score
            - request.authentication.invalid-token
            - request.forbidden
            - request.cases.case.not-found
            - request.cases.case.already-locked
        error_message:
          type: string
          description: Human-readable error message explaining what went wrong
          example: >-
            User tried to perform an invalid operation on a file without a risk
            score.
        error_details:
          type: object
          example:
            field: email_address
      required:
        - error_code
        - error_message
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: x-api-key

````