openapi: 3.0.3
info:
  title: DocSpring Authentication PDF Submissions API
  description: Use DocSpring's API to programmatically fill out PDF forms, convert HTML to PDFs, merge PDFs, or request legally binding e-signatures.
  version: v1
  contact:
    url: https://docspring.com/docs/
  license:
    name: Proprietary
servers:
- url: https://sync.api.docspring.com/api/v1
  description: DocSpring API
security:
- basicAuth: []
tags:
- name: PDF Submissions
paths:
  /templates/{template_id}/submissions:
    post:
      operationId: generatePdf
      summary: Generate a PDF
      tags:
      - PDF Submissions
      responses:
        '201':
          description: submission created
          content:
            application/json:
              schema:
                type: object
                title: create_submission_response
                properties:
                  status:
                    type: string
                    enum:
                    - success
                    - error
                  submission:
                    $ref: '#/components/schemas/submission_preview'
                  errors:
                    type: array
                    items:
                      type: string
                required:
                - status
                - submission
                additionalProperties: false
              example:
                status: success
                submission:
                  batch_id: null
                  data_requests:
                  - id: drq_1234567890abcdef01
                    email: jsmith@example.com
                    name: null
                    order: 0
                    sort_order: 0
                    fields: null
                    metadata: {}
                    state: pending
                    viewed_at: null
                    completed_at: null
                    data: null
                    auth_type: email_link
                    auth_second_factor_type: none
                    auth_provider: null
                    auth_session_started_at: null
                    auth_session_id_hash: null
                    auth_user_id_hash: null
                    auth_username_hash: null
                    auth_phone_number_hash: null
                    ip_address: null
                    user_agent: null
                  editable: null
                  error_message: null
                  expired: false
                  expires_at: null
                  id: sub_1234567890abcdef01
                  json_schema_errors: []
                  metadata:
                    foo: 123
                    bar: baz
                  password: null
                  processed_at: null
                  state: waiting_for_data_requests
                  template_id: tpl_1234567890abcdef02
                  template_type: pdf
                  template_version: null
                  test: false
                  truncated_text: {}
                  pdf_hash: null
                  download_url: null
                  permanent_download_url: null
                  preview_download_url: null
                  preview_generated_at: null
                  audit_trail_download_url: null
                  actions: []
        '422':
          description: invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/submission_422_response'
                type: object
                title: create_submission_response
                properties:
                  status:
                    type: string
                    enum:
                    - success
                    - error
                  submission:
                    $ref: '#/definitions/submission_preview'
                  errors:
                    type: array
                    items:
                      type: string
                required:
                - status
                - submission
                additionalProperties: false
              example:
                status: error
                error: 'Invalid field_overrides. Fields do not exist for this template: ''non_existent'''
                submission:
                  batch_id: null
                  data_requests: []
                  editable: null
                  error_message: null
                  expired: false
                  expires_at: null
                  id: sub_1234567890abcdef01
                  json_schema_errors:
                  - The object did not contain a required property of 'last_name'
                  metadata:
                    foo: 123
                    bar: baz
                  password: null
                  processed_at: null
                  state: invalid_data
                  template_id: tpl_1234567890abcdef01
                  template_type: pdf
                  template_version: null
                  test: false
                  truncated_text: {}
                  pdf_hash: null
                  download_url: null
                  permanent_download_url: null
                  preview_download_url: null
                  preview_generated_at: null
                  audit_trail_download_url: null
                  actions: []
                errors:
                - The object did not contain a required property of 'last_name'
        '401':
          description: authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
              example:
                status: error
                error: Invalid API token secret
      description: 'Creates a PDF submission by filling in a template with data. Supports both synchronous (default) and

        asynchronous processing. Set `wait: false` to return immediately.


        See also:

        - [Customize the PDF Title and Filename](https://docspring.com/docs/api-guide/generate-pdfs/customize-pdf-title-and-filename/) - Set custom metadata

        - [Handling Truncated Text](https://docspring.com/docs/api-guide/generate-pdfs/handle-truncated-text/) - Handle text that doesn''t fit in fields

        '
      externalDocs:
        url: https://docspring.com/docs/api-guide/generate-pdfs/generate-pdfs-via-api/
        description: Complete guide to generating PDFs with DocSpring
      parameters:
      - name: template_id
        in: path
        type: string
        required: true
        x-example: tpl_1234567890abcdef01
      - name: wait
        in: query
        type: boolean
        default: true
        required: false
        description: 'Wait for submission to be processed before returning. Set to false to return immediately. Default: true (on sync.* subdomain)'
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  title: submission_data
                  type: object
                data_requests:
                  items:
                    properties:
                      auth_phone_number_hash:
                        type:
                        - string
                        - 'null'
                      auth_provider:
                        type:
                        - string
                        - 'null'
                      auth_second_factor_type:
                        enum:
                        - none
                        - phone_number
                        - totp
                        - mobile_push
                        - security_key
                        - fingerprint
                        type: string
                      auth_session_id_hash:
                        type:
                        - string
                        - 'null'
                      auth_session_started_at:
                        type:
                        - string
                        - 'null'
                      auth_type:
                        enum:
                        - none
                        - password
                        - oauth
                        - email_link
                        - phone_number
                        - ldap
                        - saml
                        type: string
                      auth_user_id_hash:
                        type:
                        - string
                        - 'null'
                      auth_username_hash:
                        type:
                        - string
                        - 'null'
                      email:
                        type:
                        - string
                        - 'null'
                      fields:
                        items:
                          type:
                          - string
                          - 'null'
                        type: array
                      metadata:
                        type: object
                      name:
                        type:
                        - string
                        - 'null'
                      order:
                        type: integer
                      skipped:
                        type:
                        - boolean
                        - 'null'
                    title: create_submission_data_request_data
                    type:
                    - object
                    - 'null'
                  type: array
                editable:
                  type: boolean
                expires_in:
                  type: integer
                field_overrides:
                  title: submission_field_overrides
                  type: object
                metadata:
                  title: submission_metadata
                  type: object
                password:
                  type: string
                test:
                  type: boolean
                version:
                  type: string
              required:
              - data
              title: create_pdf_submission_data
              type: object
              example:
                version: draft
                data:
                  first_name: John
                  last_name: Smith
                  phone_number: '+11234567890'
                metadata:
                  foo: 123
                  bar: baz
                expires_in: 300
        required: true
      security:
      - basicAuth: []
    get:
      operationId: listTemplateSubmissions
      summary: List all submissions for a given template
      tags:
      - PDF Submissions
      responses:
        '200':
          description: listing submissions
          content:
            application/json:
              schema:
                title: list_submissions_response
                type: object
                properties:
                  submissions:
                    type: array
                    items:
                      $ref: '#/components/schemas/submission'
                  limit:
                    type: integer
                  next_cursor:
                    type: string
                    nullable: true
                required:
                - submissions
                - limit
                - next_cursor
                additionalProperties: false
              example:
                submissions:
                - batch_id: null
                  data_requests: []
                  editable: false
                  error_message: null
                  expired: false
                  expires_at: '2020-10-27T13:00:00Z'
                  id: sub_1234567890abcdef11
                  json_schema_errors: []
                  metadata:
                    qux: abc
                    user_id: 42
                  password: null
                  processed_at: '2020-05-14T02:00:00Z'
                  state: processed
                  template_id: tpl_1234567890abcdef02
                  template_type: pdf
                  template_version: null
                  test: false
                  truncated_text:
                    first_name:
                    - F. Scott Fitzgerald
                  pdf_hash: bbc369dd471442006963e3244a1b43610e066165c09770978221f91bd7ace8f5
                  download_url: https://example.com/submissions/submission.pdf
                  permanent_download_url: https://app.docspring.com/submissions/sub_1234567890abcdef11/download
                  preview_download_url: null
                  preview_generated_at: null
                  audit_trail_download_url: null
                  actions: []
                  source: api
                  referrer: null
                  data:
                    first_name: John C. D. Rom Laserdisk F. Scott Fitzgerald
                    last_name: Smith
                    phone_number: '+11234567890'
                - batch_id: null
                  data_requests: []
                  editable: false
                  error_message: null
                  expired: false
                  expires_at: '2020-10-27T13:00:00Z'
                  id: sub_1234567890abcdef12
                  json_schema_errors: []
                  metadata:
                    qux: abc
                    user_id: 42
                  password: null
                  processed_at: '2020-05-14T02:00:00Z'
                  state: processed
                  template_id: tpl_1234567890abcdef02
                  template_type: pdf
                  template_version: null
                  test: false
                  truncated_text:
                    first_name:
                    - F. Scott Fitzgerald
                  pdf_hash: bbc369dd471442006963e3244a1b43610e066165c09770978221f91bd7ace8f5
                  download_url: https://example.com/submissions/submission.pdf
                  permanent_download_url: https://app.docspring.com/submissions/sub_1234567890abcdef12/download
                  preview_download_url: null
                  preview_generated_at: null
                  audit_trail_download_url: null
                  actions: []
                  source: api
                  referrer: null
                  data:
                    first_name: John C. D. Rom Laserdisk F. Scott Fitzgerald
                    last_name: Smith
                    phone_number: '+11234567890'
                - batch_id: null
                  data_requests: []
                  editable: false
                  error_message: null
                  expired: false
                  expires_at: '2020-10-27T13:00:00Z'
                  id: sub_1234567890abcdef13
                  json_schema_errors: []
                  metadata:
                    qux: abc
                    user_id: 42
                  password: null
                  processed_at: '2020-05-14T02:00:00Z'
                  state: processed
                  template_id: tpl_1234567890abcdef02
                  template_type: pdf
                  template_version: null
                  test: false
                  truncated_text:
                    first_name:
                    - F. Scott Fitzgerald
                  pdf_hash: bbc369dd471442006963e3244a1b43610e066165c09770978221f91bd7ace8f5
                  download_url: https://example.com/submissions/submission.pdf
                  permanent_download_url: https://app.docspring.com/submissions/sub_1234567890abcdef13/download
                  preview_download_url: null
                  preview_generated_at: null
                  audit_trail_download_url: null
                  actions: []
                  source: api
                  referrer: null
                  data:
                    first_name: John C. D. Rom Laserdisk F. Scott Fitzgerald
                    last_name: Smith
                    phone_number: '+11234567890'
                - batch_id: null
                  data_requests: []
                  editable: false
                  error_message: null
                  expired: false
                  expires_at: '2020-10-27T13:00:00Z'
                  id: sub_1234567890abcdef14
                  json_schema_errors: []
                  metadata:
                    qux: abc
                    user_id: 42
                  password: null
                  processed_at: '2020-05-14T02:00:00Z'
                  state: processed
                  template_id: tpl_1234567890abcdef02
                  template_type: pdf
                  template_version: null
                  test: false
                  truncated_text:
                    first_name:
                    - F. Scott Fitzgerald
                  pdf_hash: bbc369dd471442006963e3244a1b43610e066165c09770978221f91bd7ace8f5
                  download_url: https://example.com/submissions/submission.pdf
                  permanent_download_url: https://app.docspring.com/submissions/sub_1234567890abcdef14/download
                  preview_download_url: null
                  preview_generated_at: null
                  audit_trail_download_url: null
                  actions: []
                  source: api
                  referrer: null
                  data:
                    first_name: John C. D. Rom Laserdisk F. Scott Fitzgerald
                    last_name: Smith
                    phone_number: '+11234567890'
                next_cursor: sub_1234567890abcdef14
                limit: 50
        '404':
          description: invalid template id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
      description: 'Returns a paginated list of all submissions for a specific template. Can be filtered by

        date range, submission type (test/live), and optionally include submission data. Supports

        cursor-based pagination for efficient retrieval of large result sets.

        '
      parameters:
      - name: template_id
        in: path
        type: string
        required: true
        x-example: tpl_1234567890abcdef02
      - name: cursor
        in: query
        type: string
        required: false
      - name: limit
        in: query
        type: integer
        required: false
      - name: created_after
        in: query
        type: string
        required: false
      - name: created_before
        in: query
        type: string
        required: false
      - name: type
        in: query
        type: string
        required: false
      - name: include_data
        in: query
        type: boolean
        x-example: true
      security:
      - basicAuth: []
  /submissions/{submission_id}:
    get:
      operationId: getSubmission
      summary: Check the status of a PDF
      tags:
      - PDF Submissions
      responses:
        '200':
          description: processed submission found with data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/submission'
              example:
                batch_id: null
                data_requests: []
                editable: false
                error_message: null
                expired: false
                expires_at: '2018-10-27T13:00:00Z'
                id: sub_1234567890abcdef01
                json_schema_errors: []
                metadata:
                  qux: abc
                  user_id: 42
                password: null
                processed_at: '2020-05-14T02:00:00Z'
                state: processed
                template_id: tpl_1234567890abcdef01
                template_type: pdf
                template_version: null
                test: true
                truncated_text:
                  first_name:
                  - F. Scott Fitzgerald
                pdf_hash: bbc369dd471442006963e3244a1b43610e066165c09770978221f91bd7ace8f5
                download_url: https://example.com/submissions/submission.pdf
                permanent_download_url: https://app.docspring.com/submissions/sub_1234567890abcdef01/download
                preview_download_url: null
                preview_generated_at: null
                audit_trail_download_url: null
                actions:
                - id: sba_1234567890abcdef01
                  integration_id: aci_1234567890abcdef01
                  state: processed
                  action_type: aws_s3_upload
                  action_category: file_upload
                  result_data:
                    s3_key: templates/tpl_eGc5CmFbPnCCmerqsx/sub_gzYpKDYFqEHxzca4kK.pdf
                    s3_url: https://docspring-s3-example.s3.amazonaws.com/templates/tpl_eGc5CmFbPnCCmerqsx/sub_gzYpKDYFqEHxzca4kK.pdf
                    s3_bucket: docspring-s3-example
                    s3_region: us-east-1
                  error_message: null
                source: api
                referrer: null
                data:
                  first_name: John C. D. Rom Laserdisk F. Scott Fitzgerald
                  last_name: Smith
                  phone_number: '+11234567890'
        '404':
          description: submission not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
              example:
                status: error
                error: Submission not found.
        '401':
          description: authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
              example:
                status: error
                error: 'Missing Basic Auth: Please provide an API token via Basic Auth. See: https://docspring.com/docs/api-guide/authentication/'
      description: 'Retrieves the details and status of a PDF submission. Returns processing state, download

        URL (if processed), metadata, submission data (optional), and information about any

        integrated actions. Use this to poll for completion when using asynchronous processing.

        '
      parameters:
      - name: submission_id
        in: path
        type: string
        required: true
        x-example: sub_1234567890abcdef01
      - name: include_data
        in: query
        type: boolean
        x-example: true
      security:
      - basicAuth: []
    delete:
      operationId: expireSubmission
      summary: Expire a PDF submission
      tags:
      - PDF Submissions
      responses:
        '200':
          description: submission was expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/submission_preview'
              example:
                batch_id: null
                data_requests: []
                editable: false
                error_message: null
                expired: true
                expires_at: '2018-10-20T13:00:00Z'
                id: sub_1234567890abcdef01
                json_schema_errors: []
                metadata:
                  qux: abc
                  user_id: 42
                password: null
                processed_at: '2020-05-14T02:00:00Z'
                state: processed
                template_id: tpl_1234567890abcdef01
                template_type: pdf
                template_version: null
                test: true
                truncated_text:
                  first_name:
                  - F. Scott Fitzgerald
                pdf_hash: bbc369dd471442006963e3244a1b43610e066165c09770978221f91bd7ace8f5
                download_url: null
                permanent_download_url: null
                preview_download_url: null
                preview_generated_at: null
                audit_trail_download_url: null
                actions:
                - id: sba_1234567890abcdef01
                  integration_id: aci_1234567890abcdef01
                  state: processed
                  action_type: aws_s3_upload
                  action_category: file_upload
                  result_data:
                    s3_key: templates/tpl_eGc5CmFbPnCCmerqsx/sub_gzYpKDYFqEHxzca4kK.pdf
                    s3_url: https://docspring-s3-example.s3.amazonaws.com/templates/tpl_eGc5CmFbPnCCmerqsx/sub_gzYpKDYFqEHxzca4kK.pdf
                    s3_bucket: docspring-s3-example
                    s3_region: us-east-1
                  error_message: null
        '404':
          description: submission not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
              example:
                status: error
                error: Submission not found.
        '401':
          description: authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
              example:
                status: error
                error: Invalid API token secret
        '403':
          description: test API token used
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
              example:
                status: error
                error: You must use a live API token to expire a submission.
      description: 'Expiring a PDF submission deletes the PDF and removes the data from our database.

        This is useful for invalidating sensitive documents after they''ve been downloaded.

        You can also [configure a data retention policy for your submissions](https://docspring.com/docs/template-editor/settings/#expire-submissions)

        so that they automatically expire.

        '
      parameters:
      - name: submission_id
        in: path
        type: string
        required: true
        x-example: sub_1234567890abcdef01
      security:
      - basicAuth: []
  /submissions/{submission_id}/generate_preview:
    post:
      operationId: generatePreview
      summary: Generate a preview PDF for partially completed data requests
      tags:
      - PDF Submissions
      responses:
        '200':
          description: preview was successfully requested
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/success_error_response'
              example:
                status: success
        '404':
          description: submission not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
              example:
                status: error
                error: Submission not found.
        '422':
          description: error requesting preview
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/success_error_response'
              example:
                status: error
                error: Preview PDF cannot be generated when all data requests have been completed.
      description: 'Generates a preview PDF for a submission with partially completed data requests. Useful

        for showing users what the final document will look like before all signatures or data

        have been collected. The preview includes any data collected so far.

        '
      parameters:
      - name: submission_id
        in: path
        type: string
        required: true
        x-example: sub_1234567890abcdef01
      security:
      - basicAuth: []
  /submissions:
    get:
      operationId: listSubmissions
      summary: List all submissions
      tags:
      - PDF Submissions
      responses:
        '200':
          description: listing submissions
          content:
            application/json:
              schema:
                title: list_submissions_response
                type: object
                properties:
                  submissions:
                    type: array
                    items:
                      $ref: '#/components/schemas/submission'
                  limit:
                    type: integer
                  next_cursor:
                    type: string
                    nullable: true
                required:
                - submissions
                - limit
                - next_cursor
                additionalProperties: false
              example:
                submissions:
                - batch_id: null
                  data_requests: []
                  editable: false
                  error_message: null
                  expired: false
                  expires_at: '2020-10-27T13:00:00Z'
                  id: sub_1234567890abcdef01
                  json_schema_errors: []
                  metadata:
                    qux: abc
                    user_id: 42
                  password: null
                  processed_at: '2020-05-14T02:00:00Z'
                  state: processed
                  template_id: tpl_1234567890abcdef01
                  template_type: pdf
                  template_version: null
                  test: true
                  truncated_text:
                    first_name:
                    - F. Scott Fitzgerald
                  pdf_hash: bbc369dd471442006963e3244a1b43610e066165c09770978221f91bd7ace8f5
                  download_url: https://example.com/submissions/submission.pdf
                  permanent_download_url: https://app.docspring.com/submissions/sub_1234567890abcdef01/download
                  preview_download_url: null
                  preview_generated_at: null
                  audit_trail_download_url: null
                  actions: []
                  source: api
                  referrer: null
                  data:
                    first_name: John C. D. Rom Laserdisk F. Scott Fitzgerald
                    last_name: Smith
                    phone_number: '+11234567890'
                - batch_id: null
                  data_requests: []
                  editable: false
                  error_message: null
                  expired: false
                  expires_at: '2020-10-27T13:00:00Z'
                  id: sub_1234567890abcdef02
                  json_schema_errors: []
                  metadata:
                    qux: abc
                    user_id: 42
                  password: null
                  processed_at: '2020-05-14T02:00:00Z'
                  state: processed
                  template_id: tpl_1234567890abcdef01
                  template_type: pdf
                  template_version: null
                  test: true
                  truncated_text:
                    first_name:
                    - F. Scott Fitzgerald
                  pdf_hash: bbc369dd471442006963e3244a1b43610e066165c09770978221f91bd7ace8f5
                  download_url: https://example.com/submissions/submission.pdf
                  permanent_download_url: https://app.docspring.com/submissions/sub_1234567890abcdef02/download
                  preview_download_url: null
                  preview_generated_at: null
                  audit_trail_download_url: null
                  actions: []
                  source: api
                  referrer: null
                  data:
                    first_name: John C. D. Rom Laserdisk F. Scott Fitzgerald
                    last_name: Smith
                    phone_number: '+11234567890'
                - batch_id: null
                  data_requests: []
                  editable: false
                  error_message: null
                  expired: false
                  expires_at: '2020-10-27T13:00:00Z'
                  id: sub_1234567890abcdef03
                  json_schema_errors: []
                  metadata:
                    qux: abc
                    user_id: 42
                  password: null
                  processed_at: '2020-05-14T02:00:00Z'
                  state: processed
                  template_id: tpl_1234567890abcdef01
                  template_type: pdf
                  template_version: null
                  test: true
                  truncated_text:
                    first_name:
                    - F. Scott Fitzgerald
                  pdf_hash: bbc369dd471442006963e3244a1b43610e066165c09770978221f91bd7ace8f5
                  download_url: https://example.com/submissions/submission.pdf
                  permanent_download_url: https://app.docspring.com/submissions/sub_1234567890abcdef03/download
                  preview_download_url: null
                  preview_generated_at: null
                  audit_trail_download_url: null
                  actions: []
                  source: api
                  referrer: null
                  data:
                    first_name: John C. D. Rom Laserdisk F. Scott Fitzgerald
                    last_name: Smith
                    phone_number: '+11234567890'
                next_cursor: sub_1234567890abcdef03
                limit: 3
        '422':
          description: invalid type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
              example:
                status: error
                error: 'Invalid submission type: ''foo'''
        '401':
          description: authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
              example:
                status: error
                error: 'Missing Basic Auth: Please provide an API token via Basic Auth. See: https://docspring.com/docs/api-guide/authentication/'
      description: 'Returns a paginated list of all PDF submissions across all templates in your account.

        Can be filtered by date range and submission type (test/live). Supports cursor-based

        pagination and optionally includes submission data for each result.

        '
      parameters:
      - name: cursor
        in: query
        type: string
        required: false
        x-example: sub_1234567890abcdef12
      - name: limit
        in: query
        type: integer
        required: false
        x-example: 3
      - name: created_after
        in: query
        type: string
        required: false
        x-example: '2019-01-01T09:00:00-05:00'
      - name: created_before
        in: query
        type: string
        required: false
        x-example: 2020-01-01T09:00:00.000+0200
      - name: type
        in: query
        type: string
        required: false
        x-example: test
      - name: include_data
        in: query
        type: boolean
        x-example: true
      security:
      - basicAuth: []
components:
  schemas:
    success_error_response:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
          - error
        error:
          type: string
      required:
      - status
      additionalProperties: false
      title: success_error_response
    submission_data_request:
      title: submission_data_request
      type: object
      properties:
        id:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
        order:
          type: integer
          nullable: true
        sort_order:
          type: integer
        fields:
          type: array
          items:
            type: string
          nullable: true
        metadata:
          type: object
          nullable: true
        state:
          type: string
          enum:
          - pending
          - completed
        viewed_at:
          type: string
          nullable: true
        completed_at:
          type: string
          nullable: true
        data:
          type: object
          nullable: true
        auth_type:
          type: string
          enum:
          - none
          - password
          - oauth
          - email_link
          - phone_number
          - ldap
          - saml
        auth_second_factor_type:
          type: string
          enum:
          - none
          - phone_number
          - totp
          - mobile_push
          - security_key
          - fingerprint
        auth_provider:
          type: string
          nullable: true
        auth_session_started_at:
          type: string
          nullable: true
        auth_session_id_hash:
          type: string
          nullable: true
        auth_user_id_hash:
          type: string
          nullable: true
        auth_username_hash:
          type: string
          nullable: true
        auth_phone_number_hash:
          type: string
          nullable: true
        ip_address:
          type: string
          nullable: true
        user_agent:
          type: string
          nullable: true
      required:
      - auth_phone_number_hash
      - auth_provider
      - auth_second_factor_type
      - auth_session_id_hash
      - auth_session_started_at
      - auth_type
      - auth_user_id_hash
      - auth_username_hash
      - completed_at
      - data
      - email
      - fields
      - id
      - ip_address
      - metadata
      - name
      - order
      - sort_order
      - state
      - user_agent
      - viewed_at
      additionalProperties: false
    submission_preview:
      title: submission_preview
      type: object
      properties:
        batch_id:
          type: string
          nullable: true
        data_requests:
          type: array
          items:
            $ref: '#/components/schemas/submission_data_request'
        editable:
          type: boolean
          nullable: true
        error_message:
          type: string
          nullable: true
        expired:
          type: boolean
        expires_at:
          type: string
          nullable: true
        id:
          type: string
          nullable: true
        json_schema_errors:
          type: array
          items:
            type: string
          nullable: true
        metadata:
          type: object
        password:
          type: string
          nullable: true
        processed_at:
          type: string
          nullable: true
        state:
          type: string
          enum:
          - pending
          - processed
          - invalid_data
          - error
          - image_download_failed
          - image_processing_failed
          - waiting_for_data_requests
          - syntax_error
          - account_suspended
          - license_revoked
          - accidental
        template_id:
          type: string
          nullable: true
        template_type:
          type: string
          enum:
          - pdf
          - html
        template_version:
          type: string
          nullable: true
        test:
          type: boolean
        truncated_text:
          type: object
          nullable: true
        pdf_hash:
          type: string
          nullable: true
        download_url:
          type: string
          nullable: true
        permanent_download_url:
          type: string
          nullable: true
        preview_download_url:
          type: string
          nullable: true
        preview_generated_at:
          type: string
          nullable: true
        audit_trail_download_url:
          type: string
          nullable: true
        actions:
          type: array
          items:
            $ref: '#/components/schemas/submission_action'
      required:
      - actions
      - audit_trail_download_url
      - batch_id
      - data_requests
      - download_url
      - editable
      - error_message
      - expired
      - expires_at
      - id
      - json_schema_errors
      - metadata
      - password
      - pdf_hash
      - permanent_download_url
      - preview_download_url
      - preview_generated_at
      - processed_at
      - state
      - template_id
      - template_type
      - template_version
      - test
      - truncated_text
      additionalProperties: false
    submission:
      title: submission
      type: object
      properties:
        batch_id:
          type: string
          nullable: true
        data_requests:
          type: array
          items:
            $ref: '#/components/schemas/submission_data_request'
        editable:
          type: boolean
          nullable: true
        error_message:
          type: string
          nullable: true
        expired:
          type: boolean
        expires_at:
          type: string
          nullable: true
        id:
          type: string
          nullable: true
        json_schema_errors:
          type: array
          items:
            type: string
          nullable: true
        metadata:
          type: object
        password:
          type: string
          nullable: true
        processed_at:
          type: string
          nullable: true
        state:
          type: string
          enum:
          - pending
          - processed
          - invalid_data
          - error
          - image_download_failed
          - image_processing_failed
          - waiting_for_data_requests
          - syntax_error
          - account_suspended
          - license_revoked
          - accidental
        template_id:
          type: string
          nullable: true
        template_type:
          type: string
          enum:
          - pdf
          - html
        template_version:
          type: string
          nullable: true
        test:
          type: boolean
        truncated_text:
          type: object
          nullable: true
        pdf_hash:
          type: string
          nullable: true
        download_url:
          type: string
          nullable: true
        permanent_download_url:
          type: string
          nullable: true
        preview_download_url:
          type: string
          nullable: true
        preview_generated_at:
          type: string
          nullable: true
        audit_trail_download_url:
          type: string
          nullable: true
        actions:
          type: array
          items:
            $ref: '#/components/schemas/submission_action'
        source:
          type: string
          enum:
          - api
          - web
          - reprocess
          - webhook
        referrer:
          type: string
          nullable: true
        data:
          type: object
          nullable: true
      required:
      - actions
      - audit_trail_download_url
      - batch_id
      - data
      - data_requests
      - download_url
      - editable
      - error_message
      - expired
      - expires_at
      - id
      - json_schema_errors
      - metadata
      - password
      - pdf_hash
      - permanent_download_url
      - preview_download_url
      - preview_generated_at
      - processed_at
      - referrer
      - source
      - state
      - template_id
      - template_type
      - template_version
      - test
      - truncated_text
      additionalProperties: false
    submission_action:
      title: submission_action
      type: object
      properties:
        id:
          type: string
          nullable: true
        integration_id:
          type: string
          nullable: true
        state:
          type: string
          enum:
          - pending
          - processed
          - failed
          - error
        action_type:
          type: string
          enum:
          - webhook
          - slack_webhook
          - email
          - aws_s3_upload
        action_category:
          type: string
          enum:
          - notification
          - file_upload
        result_data:
          type: object
        error_message:
          type: string
          nullable: true
      required:
      - action_category
      - action_type
      - error_message
      - id
      - integration_id
      - result_data
      - state
      additionalProperties: false
    submission_422_response:
      type: object
      title: submission_422_response
      properties:
        status:
          type: string
          enum:
          - error
        error:
          type: string
          description: Single error message (for non-validation errors)
        submission:
          $ref: '#/components/schemas/submission_preview'
          description: The submission object with validation errors (for validation errors)
        errors:
          type: array
          items:
            type: string
          description: Array of validation error messages (when submission data is invalid)
      required:
      - status
      additionalProperties: false
    error_response:
      type: object
      properties:
        status:
          type: string
          enum:
          - error
        error:
          type: string
      required:
      - status
      - error
      additionalProperties: false
      title: error_response
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: 'Username: API Token ID, Password: API Token Secret'
externalDocs:
  url: https://docspring.com/docs/
  description: DocSpring API Documentation