---
title: "Add a Document to a Signature Request"
method: POST
path: "/signature_requests/{signatureRequestId}/documents"
tags: ["Document"]
---

# Add a Document to a Signature Request

`POST /signature_requests/{signatureRequestId}/documents`

Add a Document to a given Signature Request.

**Limits:** a maximum of 50 Documents can be added per Signature Request.

Related guide: [Document](https://developers.youtrust.com/docs/document-1)

**ℹ️ This endpoint accepts two request body formats — pick the one that matches your use case:**
- 📁 `multipart/form-data` — upload a binary file (`PDF`, `DOCX`, `JPEG`, `JPG`, `PNG`).
- 📝 `application/json` — reference an existing Electronic Seal Document by ID.

**🔓 Endpoint access**
- Environments: `production`, `sandbox`
- API key scopes: `organization`, `workspace`
- Plans: `plus`, `pro`, `scale`
- Add-ons (for production access): _none_

## Path parameters

- `signatureRequestId` string, uuid, required — The unique identifier for a resource.

## Request body

- CreateDocumentFromJson
  - `electronic_seal_document_id` string, uuid, required — Id of the Electronic Seal Document. The Electronic Seal must be done to use its Electronic Seal Document.
  - `name` string, nullable
  - `nature` 'attachment' | 'signable_document', required
  - `insert_after_id` string, uuid, nullable — Insert just after the position of the specified Document id.
  - `parse_anchors` boolean, nullable — If true, the system will parse the document exclusively for Signature-type Smart Anchors and automatically generate the required fields.
  - `excluded_approvers` string[] — List of Approver IDs who cannot see this Document. When omitted, all Approvers can see it (default). Only available when the document_visibility feature is enabled on the organization.
  - `excluded_signers` string[] — List of Signer IDs who cannot see this Document. When omitted, all Signers can see it (default). Requires the document_visibility feature to be enabled on the organization.

## Response `201`

Created

- Document — Document to attach to a Signature Request
  - `id` string, uuid, required
  - `filename` string, required
  - `nature` 'attachment' | 'signable_document', required
  - `content_type` string, required
  - `sha256` string, required — Sha256 checksum
  - `is_protected` boolean, required
  - `is_signed` boolean, required
  - `created_at` string, date-time, required
  - `total_pages` integer, nullable, required — Number of pages for signable document
  - `is_locked` boolean, required — If protected by password and not yet unlocked
  - `initials` DocumentInitials, nullable, required
    - `alignment` 'left' | 'center' | 'right', required — Alignment of the initials on the document’s pages.
    - `y` integer, required — Y-axis position of the initials on the first page of the document.
    - `per_page` DocumentInitialsPerPageInner[], required
      - `page` integer, required — Page number.
      - `y` integer, required — Y-axis position of the initials on the page.
  - `total_anchors` integer, required — Number of parsed anchors from the document.
  - `excluded_approvers` string[], required — List of Approver IDs who cannot see this Document.
  - `excluded_signers` string[], required — List of Signer IDs who cannot see this Document.

## Other responses

- `400` — Bad request
- `401` — Access unauthorized
- `403` — Access forbidden
- `404` — Resource not found
- `405` — This method is not allowed
- `415` — UnsupportedMediaType
- `429` — Too Many Requests, please try again later.
- `500` — Internal Server Error

---

[API](https://skmtc.net/yousign/apis/public-api-v3.md) · [All operations](https://skmtc.net/yousign/apis/public-api-v3/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/yousign/public-api-v3/revisions/8d258c0b45d6/schema)