---
title: "Generate a PDF"
method: POST
path: "/templates/{template_id}/submissions"
tags: ["PDF Submissions"]
---

# Generate a PDF

`POST /templates/{template_id}/submissions`

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

## Path parameters

- `template_id` string, required

## Query parameters

- `wait` boolean

## Request body

- object
  - `data` object, required
  - `data_requests` object[]
    - `auth_phone_number_hash` string, nullable
    - `auth_provider` string, nullable
    - `auth_second_factor_type` 'none' | 'phone_number' | 'totp' | 'mobile_push' | 'security_key' | 'fingerprint'
    - `auth_session_id_hash` string, nullable
    - `auth_session_started_at` string, nullable
    - `auth_type` 'none' | 'password' | 'oauth' | 'email_link' | 'phone_number' | 'ldap' | 'saml'
    - `auth_user_id_hash` string, nullable
    - `auth_username_hash` string, nullable
    - `email` string, nullable
    - `fields` string[]
    - `metadata` object
    - `name` string, nullable
    - `order` integer
    - `skipped` boolean, nullable
  - `editable` boolean
  - `expires_in` integer
  - `field_overrides` object
  - `metadata` object
  - `password` string
  - `test` boolean
  - `version` string

## Response `201`

submission created

- object
  - `status` 'success' | 'error', required
  - `submission` SubmissionPreview, required
    - `batch_id` string, nullable, required
    - `data_requests` SubmissionDataRequest[], required
      - `id` string, nullable, required
      - `email` string, nullable, required
      - `name` string, nullable, required
      - `order` integer, nullable, required
      - `sort_order` integer, required
      - `fields` string[], nullable, required
      - `metadata` object, nullable, required
      - `state` 'pending' | 'completed', required
      - `viewed_at` string, nullable, required
      - `completed_at` string, nullable, required
      - `data` object, nullable, required
      - `auth_type` 'none' | 'password' | 'oauth' | 'email_link' | 'phone_number' | 'ldap' | 'saml', required
      - `auth_second_factor_type` 'none' | 'phone_number' | 'totp' | 'mobile_push' | 'security_key' | 'fingerprint', required
      - `auth_provider` string, nullable, required
      - `auth_session_started_at` string, nullable, required
      - `auth_session_id_hash` string, nullable, required
      - `auth_user_id_hash` string, nullable, required
      - `auth_username_hash` string, nullable, required
      - `auth_phone_number_hash` string, nullable, required
      - `ip_address` string, nullable, required
      - `user_agent` string, nullable, required
    - `editable` boolean, nullable, required
    - `error_message` string, nullable, required
    - `expired` boolean, required
    - `expires_at` string, nullable, required
    - `id` string, nullable, required
    - `json_schema_errors` string[], nullable, required
    - `metadata` object, required
    - `password` string, nullable, required
    - `processed_at` string, nullable, required
    - `state` 'pending' | 'processed' | 'invalid_data' | 'error' | 'image_download_failed' | 'image_processing_failed' | 'waiting_for_data_requests' | 'syntax_error' | 'account_suspended' | 'license_revoked' | 'accidental', required
    - `template_id` string, nullable, required
    - `template_type` 'pdf' | 'html', required
    - `template_version` string, nullable, required
    - `test` boolean, required
    - `truncated_text` object, nullable, required
    - `pdf_hash` string, nullable, required
    - `download_url` string, nullable, required
    - `permanent_download_url` string, nullable, required
    - `preview_download_url` string, nullable, required
    - `preview_generated_at` string, nullable, required
    - `audit_trail_download_url` string, nullable, required
    - `actions` SubmissionAction[], required
      - `id` string, nullable, required
      - `integration_id` string, nullable, required
      - `state` 'pending' | 'processed' | 'failed' | 'error', required
      - `action_type` 'webhook' | 'slack_webhook' | 'email' | 'aws_s3_upload', required
      - `action_category` 'notification' | 'file_upload', required
      - `result_data` object, required
      - `error_message` string, nullable, required
  - `errors` string[]

## Other responses

- `401` — authentication failed
- `422` — invalid request

---

[API](https://skmtc.dev/docspring/apis/docspring-api.md) · [All operations](https://skmtc.dev/docspring/apis/docspring-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/docspring/docspring-api/revisions/5726657b9432/schema)