Create Synchronous Document

1. API
2. ›Documents
3. ›Create synchronous document

POST {{base_url}}/v1/documents

Environments

Variable {{base_url}}: Check servers in Environments.

RequestDemoResponse

Copiar

cURLNode.jsPythonPHPGo

curl -X POST {{base_url}}/v1/documents \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "name": "Service Provision Contract No. 9",
  "document_pdf_url": "https://files.example.com/contract.pdf",
  "signers": [{
    "name": "John Doe",
    "email": "[email protected]",
    "country_code": "+51",
    "phone": "900000001"
  }]
}'

Sin ejecutar·latencia ~ 412 ms

Probar en vivo

Demo pública · no guarda datos · firma con sandbox PKI

Create Synchronous Document

This endpoint allows you to register a new main document and, optionally, attachments, signers, and signature placements in a single call. It responds with 201 and the complete envelope.

Sync

	Sync POST /v1/documents
Documents per envelope	up to 5 (main + 4 attachments)
Weight	50 MB total envelope
File source	base64, URL
Response	201 with complete envelope
When	interactive / few documents

---

Authentication

The access token obtained during the login process must be sent with each request:

Parameter	Type	Description	Limits
Authorization*	string	Access token obtained during login, with the 'Bearer' prefix.	Required
Content-Type	string	Specifies the content type of the HTTP request body. For requests that include JSON data	'application/json'

---

Required Fields

Fields marked with an asterisk (*) are required and must be provided in the request. Other fields are optional.

---

Envelope Limits

| Limit | Value | |—|—|—| | Documents per envelope (main + attachments) | 5 | | TOTAL envelope weight | 50 MB | | Attachments (extra_docs) | Maximum 4 (= total − 1) | | A single document | ≤ total weight (50 MB) |

Note

The model is based on total weight: a single document can use the full 50 MB, or it can be distributed between the main document and attachments (e.g., 2×25 MB, 5×10 MB). For larger batches, use the async endpoint.

---

Main document source

You must strictly choose ONE of the following options (they are mutually exclusive; sending two will cause a 422 error):

Parameter	Type	Description	Limits
document_pdf_url	url	Public URL from which the system will download the PDF file. Recommended	Mutually exclusive
document_pdf_base64	string	PDF file encoded in Base64 format.	Mutually exclusive

---

Identity and Reference

Parameter	Type	Description	Limits
name*	string	Official document name. The system automatically normalizes it to UPPERCASE and appends the '.pdf' extension.	Required
ref_id	string	Reference for the main file. In this synchronous flow, the system ignores it by default, always mapping the main file as 'main'.	Optional (ignored)

---

Envelope Configuration

Parameter	Type	Description	Limits
external_id	string(255)	Free external ID assigned by the integrator (pass-through) for internal control.	Optional
folder_token	uuid	Token of the destination folder where the document will be saved.	Optional
signature_deadline	ISO8601	Future deadline date and time to complete signatures (e.g. '2026-12-31T23:59:59.000Z').	Full UTC format
sender_name	string(150)	Sender name shown to signers in notifications. If omitted, the owner's name is used.	Max 150 characters
reply_to_email	email	Email address configured to receive replies from sent notifications.	Email format
disable_owner_notifications	bool	Completely disables email alerts to the envelope owner.	Default: false
disable_signer_notifications	bool	Disables automatic email alerts and flows to signers.	Default: false
send_automatic_invitations	bool	Immediately sends invitation emails or messages when creating the envelope.	Default: true
is_signature_order_active	bool	Forces signers to strictly follow the established hierarchical order (sequential).	Default: false
is_rejection_allowed	bool	Enables the button for a signer to formally reject the document by explaining the reason.	Default: false
is_original_download_allowed	bool	Allows the signer to download the clean original PDF before stamping their signature.	Default: true
reminder_every_n_days	int	Frequency in days to send automatic pending signature reminders (range 0 to 30).	0 to disable
observers	array<string>	List of observer emails with read-only access to the document (maximum 20).	Array of emails
redirect_link	string(255)	Redirect URL that the browser will send the user to immediately after signing.	Must be a valid URL
metadata	object	Free JSON key-value storage object for custom metadata.	Pass-through

---

Additional Documents

Allows adding up to a maximum of 4 supplementary documents in the same call.

Parameter	Type	Description	Limits
extra_docs[].ref_id*	string	Unique and required identifier for the attachment. It is essential for associating signature coordinates later.	Required and unique
extra_docs[].name	string	Attachment file name.	Optional
extra_docs[].pdf_url	url	Public URL for direct attachment download. Recommended	Mutually exclusive with base64 or key

---

Required Fields

Fields marked with an asterisk (*) are required and must be provided in the request. Other fields are optional.

---

Signers

Defines the document actors. Minimum required fields per element: name, country_code (e.g. ‘+51’), phone and email.

Parameter	Type	Description	Limits
signers[].role	enum	Role of the participant within the envelope. Supported values: 'signer' (signs), 'approver' (approves without signing) or 'witness' (witness).	Default: 'signer'
signers[].standard_flow	array<string>	Primary electronic signature methods. Valid values: 'holographic_signature', 'otp_email', 'otp_whatsapp', or 'digital_certificate_local'.	See rules below
signers[].advanced_flow	array<string>	Advanced biometric validation layers. Valid values: 'selfie', 'doc_identidad', 'video_firma', 'face_recognition'.	Maximum 2 active flows

Critical Validation Rules (Error 422)

• Certificate Exclusivity: If you use digital_certificate_local, it cannot be combined with any other standard or advanced flow for that signer.
• High Security: face_recognition strictly require correct document_type and document_number values. Sending these identity fields without activating a high-security advanced flow will result in 422.
• Digital certificate placement limit: When using digital_certificate_local, a maximum of 1 placement per document is allowed. If you send multiple placements to the same document, the system keeps the first one.

---

Signature Placement (Mutually Exclusive Formats)

Recommended Structure: placements[] (Percentages)

It is configured within each signer’s array (signers[].placements[]). Allows positioning signatures and initials fluidly across multiple documents at once.

Parameter	Type	Description	Limits
document_ref	string	File label to which the signature applies. Can be 'main' (main document) or the exact 'ref_id' assigned to an attachment.	Default: 'main'
type	enum	Type of graphic mark to stamp on the page. Values: 'signature' (full signature) or 'initials' (visa/initials).	Default: 'signature'
page_number	int	Sequential page number where the box will be placed (must be greater than or equal to 1).	Required
relative_position_left	float	X-axis position calculated as a percentage (0 to 100) from the left edge of the page.	Required (e.g. 36.5)
relative_position_top	float	Y-axis position calculated as a percentage (0 to 100) from the top edge of the page.	Mutually exclusive with bottom
relative_position_bottom	float	Y-axis position calculated as a percentage (0 to 100) from the bottom edge of the page.	Mutually exclusive with top
relative_size_width	float	Width of the signature box calculated as a percentage of the total page width.	Optional (0 to 100)
relative_size_height	float	Height of the signature box calculated as a percentage of the total page height.	Optional (0 to 100)

Dynamic Reference Resolution

In this synchronous flow, if you send a non-existent document_ref, with a typo, or empty, the backend will not throw an error; for safety and consistency, it will apply an automatic fallback and silently place the signature on the main document (main). (Note: For digital certificate signatures, a strict limit of maximum 1 placement per file is enforced).

"placements": [
  {
    "document_ref": "main",
    "type": "signature",
    "page_number": 1,
    "relative_position_left": 36.5,
    "relative_position_top": 39.25,
    "relative_size_width": 25,
    "relative_size_height": 8
  }
]

Minimum request example (JSON Payload)

{
  "name": "Service Provision Contract No. 9",
  "document_pdf_base64": "JVBERi0xLjQKJdPr6goxIDAgb2JqCjw8L0xlbmd0aCAyIDAgUi9GaWx0ZXIvRmxhdGVEZWNvZGU+PnN0cmVhbQp4nDMwVTAwULAwMDIxUzAFAAZ3A2Y9CmVuZHN0cmVhbQplbmRvYmoKMiAwIG9iagozMAplbmRvYmoKMyAwIG9iago8PC9UeXBlL1BhZ2VzL0NvdW50IDEvS2lkc1s0IDAgUl0+PgplbmRvYmoKNDAwIFJGST0=",
  "signers": [
    {
      "name": "Jane Doe",
      "email": "[email protected]",
      "country_code": "+51",
      "phone": "900000001",
      "standard_flow": ["holographic_signature"],
      "placements": [
        {
          "document_ref": "main",
          "type": "signature",
          "page_number": 1,
          "relative_position_left": 36.5,
          "relative_position_top": 39.25,
          "relative_size_width": 25,
          "relative_size_height": 8
        }
      ]
    }
  ]
}

cert-only

If the submitted PDF already comes pre-loaded with a digital signature, the system detects the api origin and auto-corrects the signer flow to digital_certificate_local, ensuring document consistency.

---

Successful Response (201 Created)

{
  "external_id": "ERP-123",
  "token": "abcdef01-2345-6789-abcd-ef0123456789",
  "name": "Acuerdo_Comercial_2025.pdf",
  "folder": { "token": "uuid", "name": "Carpeta" },
  "status": "pending",
  "lang": "es",
  "size": 245100,
  "original_file": "[https://api.firmeasy.legal/files/...?intent=view&signature=](https://api.firmeasy.legal/files/...?intent=view&signature=)...",
  "signed_file": null,
  "original_download_file": "[https://api.firmeasy.legal/files/...?intent=download](https://api.firmeasy.legal/files/...?intent=download)&...",
  "signed_download_file": null,
  "signatures_made": 0,
  "signature_deadline": "2026-12-31T23:59:59.000Z",
  "created_by": { "email": "[email protected]" },
  "extra_docs_count": 0,
  "extra_docs": [],
  "signers": [
    {
      "external_id": null,
      "token": "signer-api-id",
      "status": "pending",
      "rejection_reason": null,
      "order": 1,
      "name": "Carl Smith",
      "email": "[email protected]",
      "phone": "900000002",
      "country_code": "+51",
      "document_type": null,
      "document_number": null,
      "role": "signer",
      "link": "[https://app.firmeasy.legal/](https://app.firmeasy.legal/)...",
      "placements": [
        {
          "document_ref": "main",
          "type": "signature",
          "page_number": 1,
          "relative_position_left": 36.5,
          "relative_position_top": 39.25,
          "relative_size_width": 25,
          "relative_size_height": 8
        }
      ],
      "standard_flow": [
        {
          "state": "pending",
          "flow_name": "Firma Holográfica",
          "flow_key": "holographic_signature"
        }
      ],
      "advanced_flow": []
    }
  ],
  "created_through": "api",
  "created_at": "2026-06-23T10:00:00.000000Z",
  "updated_at": "2026-06-23T10:00:00.000000Z"
}

Nombre	Type	Description
token	string	Unique envelope identifier generated by FirmEasy. Save it in your database for future queries and operations.
external_id	string	The same external ID sent in the original request, returned for your system's validation.
name	string	Normalized document name (in UPPERCASE with '.pdf' extension).
status	string	Current envelope status. Possible values: 'pending', 'signed', 'rejected'.
original_file	string	Signed URL to view the original PDF in the browser.
original_download_file	string	Signed URL to download the original PDF directly.
signed_file	string	URL of the signed document. Will be null while the envelope is not fully signed.
signatures_made	integer	Number of signatures stamped so far. Starts at 0.
signers	array	List of registered signers with their individual token, status, signature link, and flow configuration.
extra_docs_count	integer	Number of attached documents included in the envelope.
created_at	datetime	Exact date and time of envelope creation in UTC ISO 8601 format.

---

Possible Errors

Code	Status	Description
400	Bad Request	Invalid request (body parameters with incorrect or missing syntax).
401	Unauthorized	Not authorized (invalid, expired, or missing JWT token in headers).
422	Unprocessable Entity	Business validation error (multiple file sources, incompatible flows).
500	Server Error	Internal error on FirmEasy servers.