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

# Create Document Request

> Create a document request and send an email invitation to collect files from an external party.

Create a new document request to collect files from an external party (guest). This endpoint creates the request record and automatically sends an email invitation with a secure, time-limited upload link.

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

## Invitation Workflow

1. **Email Sent**: An automated email is sent to the recipient containing a unique link.
2. **Guest Access**: The recipient can click the link to upload documents directly to Veridox without needing an account.
3. **Automatic Association**: All uploaded files are automatically associated with a case in your organisation.

## Best Practices

1. **Clear Instructions**: Use the `email_message` field to provide context to your customers about why they are being asked to upload documents.
2. **Expiration**: Set reasonable expiration dates (e.g., 7-14 days) to maintain security while giving users enough time to gather their files.
3. **Follow-ups**: Monitor the status of requests and use the [Resend](./document-requests-resend) endpoint if a user hasn't completed their upload before expiry.


## OpenAPI

````yaml POST /document-requests/create
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/create:
    post:
      tags:
        - Document Requests
      summary: Create a new document request
      description: >-
        Creates a new document request and associated case. Sends an automated
        email to the recipient with a secure upload link. The link allows the
        guest to upload files without having an account.
      operationId: DocumentRequestsController_createDocumentRequest
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDocumentRequestDto'
      responses:
        '201':
          description: Document request created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentRequestResponseDto'
        '400':
          description: Invalid input provided (e.g. past expiry date)
          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:
    CreateDocumentRequestDto:
      type: object
      properties:
        label:
          type: string
          minLength: 1
          maxLength: 200
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-parent-additional-properties: false
        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))$
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-parent-additional-properties: false
        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,}$
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-parent-additional-properties: false
        recipient_name:
          type: string
          minLength: 1
          maxLength: 200
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-parent-additional-properties: false
        email_message:
          type: string
          minLength: 1
          maxLength: 1000
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-parent-additional-properties: false
        max_files:
          type: integer
          exclusiveMinimum: 0
          maximum: 20
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-parent-additional-properties: false
        copy:
          default: false
          type: boolean
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-parent-additional-properties: false
      required:
        - label
        - expires_at
        - recipient_email
        - max_files
    DocumentRequestResponseDto:
      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})$
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-parent-additional-properties: false
        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})$
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-parent-additional-properties: false
        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,}$
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-parent-additional-properties: false
        recipient_name:
          anyOf:
            - type: string
            - type: 'null'
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-empty-type: true
          x-nestjs_zod-parent-additional-properties: false
        label:
          type: string
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-parent-additional-properties: false
        status:
          type: string
          enum:
            - pending
            - completed
            - expired
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-parent-additional-properties: false
        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))$
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-parent-additional-properties: false
        max_files:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-parent-additional-properties: false
        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))$
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-parent-additional-properties: false
        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))$
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-parent-additional-properties: false
      required:
        - id
        - case_id
        - recipient_email
        - recipient_name
        - label
        - status
        - expires_at
        - max_files
        - created_at
        - updated_at
    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

````