openapi: 3.0.3
info:
  title: DocSpring Authentication Submission Batches 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: Submission Batches
paths:
  /submissions/batches:
    post:
      operationId: batchGeneratePdfs
      summary: Generate multiple PDFs
      tags:
      - Submission Batches
      responses:
        '201':
          description: submissions created
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - success
                    - error
                  error:
                    type: string
                  errors:
                    type: array
                    items:
                      type: string
                  submission_batch:
                    $ref: '#/components/schemas/submission_batch'
                  submissions:
                    type: array
                    items:
                      type: object
                      properties:
                        status:
                          type: string
                          enum:
                          - success
                          - error
                          - valid_but_not_saved
                        errors:
                          type: array
                          items:
                            type: string
                        submission:
                          $ref: '#/components/schemas/submission_preview'
                      additionalProperties: false
                      required:
                      - status
                required:
                - status
                - submission_batch
                - submissions
                additionalProperties: false
              example:
                status: success
                submission_batch:
                  id: sbb_1234567890abcdef01
                  state: pending
                  metadata:
                    job_id: 54321
                  processed_at: null
                  total_count: 2
                  pending_count: 2
                  error_count: 0
                  completion_percentage: 0
                submissions:
                - status: success
                  submission:
                    batch_id: sbb_1234567890abcdef01
                    data_requests: []
                    editable: null
                    error_message: null
                    expired: false
                    expires_at: null
                    id: sub_1234567890abcdef01
                    json_schema_errors: []
                    metadata:
                      submission_number: 1
                    password: null
                    processed_at: null
                    state: pending
                    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: []
                - status: success
                  submission:
                    batch_id: sbb_1234567890abcdef01
                    data_requests: []
                    editable: null
                    error_message: null
                    expired: false
                    expires_at: null
                    id: sub_1234567890abcdef02
                    json_schema_errors: []
                    metadata:
                      submission_number: 2
                    password: null
                    processed_at: null
                    state: pending
                    template_id: tpl_1234567890abcdef01
                    template_type: pdf
                    template_version: null
                    test: true
                    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: []
        '200':
          description: some PDFs with invalid data
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - success
                    - error
                  error:
                    type: string
                  errors:
                    type: array
                    items:
                      type: string
                  submission_batch:
                    $ref: '#/components/schemas/submission_batch'
                  submissions:
                    type: array
                    items:
                      type: object
                      properties:
                        status:
                          type: string
                          enum:
                          - success
                          - error
                          - valid_but_not_saved
                        errors:
                          type: array
                          items:
                            type: string
                        submission:
                          $ref: '#/components/schemas/submission_preview'
                      additionalProperties: false
                      required:
                      - status
                required:
                - status
                - submission_batch
                - submissions
                additionalProperties: false
              example:
                status: error
                submission_batch:
                  id: sbb_1234567890abcdef01
                  state: error
                  metadata:
                    job_id: 54321
                  processed_at: null
                  total_count: 2
                  pending_count: 0
                  error_count: 1
                  completion_percentage: 100
                submissions:
                - status: valid_but_not_saved
                  errors: []
                - status: error
                  submission:
                    batch_id: sbb_1234567890abcdef01
                    data_requests: []
                    editable: null
                    error_message: null
                    expired: false
                    expires_at: null
                    id: sub_1234567890abcdef02
                    json_schema_errors:
                    - The object did not contain a required property of 'first_name'
                    metadata:
                      submission_number: 2
                    password: null
                    processed_at: null
                    state: invalid_data
                    template_id: tpl_1234567890abcdef01
                    template_type: pdf
                    template_version: null
                    test: true
                    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 'first_name'
        '401':
          description: authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
              example:
                status: error
                error: Invalid API token secret
        '422':
          description: array of arrays
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_or_multiple_errors_response'
              example:
                status: error
                error: 'You can only generate up to 50 PDFs per batch request. You requested: 51'
                errors:
                - 'The property ''#/submissions/0'' of type array did not match the following type: object'
        '400':
          description: invalid JSON
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
              example:
                status: error
                error: 'There was a problem with the JSON you submitted: unexpected character at line 1, column 25 in ''{ "first_name": "John", last_name: "Smith" }'
      description: 'Generates up to 50 PDFs in a single request. Each submission can use a different template

        and data. Supports both synchronous (wait for all PDFs) and asynchronous processing. More

        efficient than individual requests when creating multiple PDFs.


        See also:

        - [Batch and Combine PDFs](https://docspring.com/docs/api-guide/generate-pdfs/batch-generate-pdfs/) - Generate and merge PDFs in one request

        '
      externalDocs:
        url: https://docspring.com/docs/api-guide/generate-pdfs/batch-generate-pdfs/
        description: Learn more about generating multiple PDFs in batches
      parameters:
      - name: wait
        in: query
        type: boolean
        default: true
        required: false
        description: 'Wait for submission batch to be processed before returning. Set to false to return immediately. Default: true (on sync.* subdomain)'
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                metadata:
                  type: object
                submissions:
                  items:
                    additionalProperties: false
                    properties:
                      css:
                        type: string
                      data:
                        type: object
                      html:
                        type: string
                      metadata:
                        type: object
                      template_id:
                        type:
                        - string
                        - 'null'
                      template_version:
                        type:
                        - string
                        - 'null'
                      test:
                        type: boolean
                    title: submission_data_batch_request
                    type: object
                  type: array
                template_id:
                  type:
                  - string
                  - 'null'
                template_version:
                  type:
                  - string
                  - 'null'
                test:
                  type: boolean
              required:
              - submissions
              title: submission_batch_data
              type: object
              example:
                metadata:
                  job_id: 54321
                test: true
                template_id: null
                template_version: null
                submissions:
                - test: false
                  template_id: tpl_1234567890abcdef01
                  template_version: draft
                  data:
                    first_name: Johnny
                    last_name: Smith
                  metadata:
                    submission_number: 1
                - template_id: tpl_1234567890abcdef01
                  template_version: latest
                  data:
                    first_name: Jane
                    last_name: Doe
                  metadata:
                    submission_number: 2
        required: true
      security:
      - basicAuth: []
  /submissions/batches/{submission_batch_id}:
    get:
      operationId: getSubmissionBatch
      summary: Check the status of a submission batch job
      tags:
      - Submission Batches
      responses:
        '200':
          description: processed submission batch found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/submission_batch_with_submissions'
              example:
                id: sbb_1234567890abcdef01
                state: error
                metadata:
                  qux: abc
                processed_at: null
                total_count: 10
                pending_count: 1
                error_count: 2
                completion_percentage: 90
                submissions:
                - batch_id: sbb_1234567890abcdef01
                  data_requests: []
                  editable: false
                  error_message: null
                  expired: false
                  expires_at: null
                  id: sub_1234567890abcdef01
                  json_schema_errors: []
                  metadata: {}
                  password: null
                  processed_at: null
                  state: processed
                  template_id: tpl_1234567890abcdef01
                  template_type: pdf
                  template_version: null
                  test: false
                  truncated_text: {}
                  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: []
                - batch_id: sbb_1234567890abcdef01
                  data_requests: []
                  editable: false
                  error_message: null
                  expired: false
                  expires_at: null
                  id: sub_1234567890abcdef02
                  json_schema_errors: []
                  metadata: {}
                  password: null
                  processed_at: null
                  state: processed
                  template_id: tpl_1234567890abcdef01
                  template_type: pdf
                  template_version: null
                  test: false
                  truncated_text: {}
                  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: []
        '404':
          description: submission batch not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
              example:
                status: error
                error: Submission batch 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 status and results of a batch PDF generation job. Returns processing state,

        completion statistics, and optionally includes all individual submission details. Use this

        to poll for completion when using asynchronous batch processing.

        '
      parameters:
      - name: submission_batch_id
        in: path
        type: string
        required: true
        x-example: sbb_1234567890abcdef01
      - name: include_submissions
        in: query
        type: boolean
        x-example: true
      security:
      - basicAuth: []
components:
  schemas:
    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
    error_or_multiple_errors_response:
      type: object
      title: error_or_multiple_errors_response
      properties:
        status:
          type: string
          enum:
          - error
        error:
          type: string
          description: Single error message (when only one error occurred)
        errors:
          type: array
          items:
            type: string
          description: Array of error messages (when multiple validation errors occurred)
      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
    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_batch_with_submissions:
      title: submission_preview
      type: object
      properties:
        id:
          type: string
          nullable: true
        state:
          type: string
          enum:
          - pending
          - processed
          - error
        metadata:
          type: object
        processed_at:
          type: string
          nullable: true
        total_count:
          type: integer
        pending_count:
          type: integer
        error_count:
          type: integer
        completion_percentage:
          type: number
        submissions:
          type: array
          items:
            $ref: '#/components/schemas/submission_preview'
      required:
      - completion_percentage
      - error_count
      - id
      - metadata
      - pending_count
      - processed_at
      - state
      - total_count
      additionalProperties: false
    submission_batch:
      title: submission_batch
      type: object
      properties:
        id:
          type: string
          nullable: true
        state:
          type: string
          enum:
          - pending
          - processed
          - error
        metadata:
          type: object
        processed_at:
          type: string
          nullable: true
        total_count:
          type: integer
        pending_count:
          type: integer
        error_count:
          type: integer
        completion_percentage:
          type: number
      required:
      - completion_percentage
      - error_count
      - id
      - metadata
      - pending_count
      - processed_at
      - state
      - total_count
      additionalProperties: false
  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