Create Synchronous Document

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

POST

https://api.firmeasy.legal/api/v1/documents

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 vs Async?

	Sync POST /v1/documents	Async POST /v1/documents/envelopes/async
Documents per envelope	up to 5 (main + 4 attachments)	up to 100
Weight	50 MB total envelope	~100 MB per doc · 1 GB total
File source	base64, URL, DOCX or temporal key	URL only (first release)
Response	201 with complete envelope	202 with ingest_token (background assembly)
When	interactive / few documents	large batches / heavy files

---

RequestDemoResponse

Copiar

cURLNode.jsPythonPHPGo

curl -X POST https://api.firmeasy.legal/api/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

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'

Authorization

string

Access token obtained during login, with the 'Bearer' prefix.

Limits:Required

Content-Type

string

Specifies the content type of the HTTP request body. For requests that include JSON data

Limits:'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.	Mutually exclusive
document_pdf_base64	string	PDF file encoded in Base64 format.	Mutually exclusive
document_temporal_key	string(255)	Temporary key of a pre-uploaded PDF file.	Mutually exclusive
document_docx_url	url	Public URL of a DOCX file. The system will automatically convert it to PDF.	Mutually exclusive
document_docx_base64	string	DOCX file encoded in Base64 format for automatic conversion.	Mutually exclusive

document_pdf_url

url

Public URL from which the system will download the PDF file.

Limits:Mutually exclusive

document_pdf_base64

string

PDF file encoded in Base64 format.

Limits:Mutually exclusive

document_temporal_key

string(255)

Temporary key of a pre-uploaded PDF file.

Limits:Mutually exclusive

document_docx_url

url

Public URL of a DOCX file. The system will automatically convert it to PDF.

Limits:Mutually exclusive

document_docx_base64

string

DOCX file encoded in Base64 format for automatic conversion.

Limits: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)

name

string

Official document name. The system automatically normalizes it to UPPERCASE and appends the '.pdf' extension.

Limits: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'.

Limits: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.	Must be a valid UUID
template_token	uuid	Token of the pre-configured template to apply.	Must be a valid UUID
created_by	email	Email of the user who created the request.	Email format
created_through	enum	Envelope creation channel. Supported values: 'api' or 'web'.	Default: 'api'
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
send_automatic_invitations_by	enum	Invitation sending method. Values: 'email' or 'whatsapp'.	Optional
send_signed_document_by_whatsapp	bool	Sends a PDF copy of the completed document directly to the signer's WhatsApp.	Default: false
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
lang	enum	Language for the signer interface and communications. Values: 'es', 'en', 'pt'.	Default: 'es'
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

external_id

string(255)

Free external ID assigned by the integrator (pass-through) for internal control.

Limits:Optional

folder_token

uuid

Token of the destination folder where the document will be saved.

Limits:Must be a valid UUID

template_token

uuid

Token of the pre-configured template to apply.

Limits:Must be a valid UUID

created_by

email

Email of the user who created the request.

Limits:Email format

created_through

enum

Envelope creation channel. Supported values: 'api' or 'web'.

Limits:Default: 'api'

signature_deadline

ISO8601

Future deadline date and time to complete signatures (e.g. '2026-12-31T23:59:59.000Z').

Limits:Full UTC format

sender_name

string(150)

Sender name shown to signers in notifications. If omitted, the owner's name is used.

Limits:Max 150 characters

reply_to_email

email

Email address configured to receive replies from sent notifications.

Limits:Email format

disable_owner_notifications

bool

Completely disables email alerts to the envelope owner.

Limits:Default: false

disable_signer_notifications

bool

Disables automatic email alerts and flows to signers.

Limits:Default: false

send_automatic_invitations

bool

Immediately sends invitation emails or messages when creating the envelope.

Limits:Default: true

send_automatic_invitations_by

enum

Invitation sending method. Values: 'email' or 'whatsapp'.

Limits:Optional

send_signed_document_by_whatsapp

bool

Sends a PDF copy of the completed document directly to the signer's WhatsApp.

Limits:Default: false

is_signature_order_active

bool

Forces signers to strictly follow the established hierarchical order (sequential).

Limits:Default: false

is_rejection_allowed

bool

Enables the button for a signer to formally reject the document by explaining the reason.

Limits:Default: false

is_original_download_allowed

bool

Allows the signer to download the clean original PDF before stamping their signature.

Limits:Default: true

reminder_every_n_days

int

Frequency in days to send automatic pending signature reminders (range 0 to 30).

Limits:0 to disable

lang

enum

Language for the signer interface and communications. Values: 'es', 'en', 'pt'.

Limits:Default: 'es'

observers

array<string>

List of observer emails with read-only access to the document (maximum 20).

Limits:Array of emails

redirect_link

string(255)

Redirect URL that the browser will send the user to immediately after signing.

Limits:Must be a valid URL

metadata

object

Free JSON key-value storage object for custom metadata.

Limits:Pass-through

---

Attachments

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.	Mutually exclusive with base64 or key
extra_docs[].pdf_base64	string	Attachment content encoded in Base64 format.	Mutually exclusive
extra_docs[].temporal_key	string(255)	Temporary key of the pre-uploaded attachment file.	Mutually exclusive
extra_docs[].file	file (pdf)	PDF file attached directly in the request. Only available if the request is sent as `multipart/form-data`.	Mutually exclusive with url/base64/key

extra_docs[].ref_id

string

Unique and required identifier for the attachment. It is essential for associating signature coordinates later.

Limits:Required and unique

extra_docs[].name

string

Attachment file name.

Limits:Optional

extra_docs[].pdf_url

url

Public URL for direct attachment download.

Limits:Mutually exclusive with base64 or key

extra_docs[].pdf_base64

string

Attachment content encoded in Base64 format.

Limits:Mutually exclusive

extra_docs[].temporal_key

string(255)

Temporary key of the pre-uploaded attachment file.

Limits:Mutually exclusive

extra_docs[].file

file (pdf)

PDF file attached directly in the request. Only available if the request is sent as `multipart/form-data`.

Limits:Mutually exclusive with url/base64/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[].document_type	string	Type of legal identity document (e.g. 'DNI', 'CE'). Required if using advanced identity flows.	Required for high-security flows
signers[].document_number	string	Identity document number. If DNI, exactly 8 numeric digits are validated.	Required for high-security flows
signers[].standard_flow	array<string>	Primary electronic signature methods. Valid values: 'holographic_signature' (or its alias 'firma_biometrica'), 'otp_email', 'otp_sms', 'otp_whatsapp', or 'digital_certificate_local'.	See rules below
signers[].advanced_flow	array<string>	Advanced biometric validation layers. Valid values: 'selfie', 'doc_identidad' (alias 'identity_document_verification'), 'video_firma' (alias 'live_video_authentication'), 'face_recognition', 'reniec_match'.	Maximum 2 active flows

signers[].role

enum

Role of the participant within the envelope. Supported values: 'signer' (signs), 'approver' (approves without signing) or 'witness' (witness).

Limits:Default: 'signer'

signers[].document_type

string

Type of legal identity document (e.g. 'DNI', 'CE'). Required if using advanced identity flows.

Limits:Required for high-security flows

signers[].document_number

string

Identity document number. If DNI, exactly 8 numeric digits are validated.

Limits:Required for high-security flows

signers[].standard_flow

array<string>

Primary electronic signature methods. Valid values: 'holographic_signature' (or its alias 'firma_biometrica'), 'otp_email', 'otp_sms', 'otp_whatsapp', or 'digital_certificate_local'.

Limits:See rules below

signers[].advanced_flow

array<string>

Advanced biometric validation layers. Valid values: 'selfie', 'doc_identidad' (alias 'identity_document_verification'), 'video_firma' (alias 'live_video_authentication'), 'face_recognition', 'reniec_match'.

Limits: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)

Option A) 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)

document_ref

string

File label to which the signature applies. Can be 'main' (main document) or the exact 'ref_id' assigned to an attachment.

Limits:Default: 'main'

type

enum

Type of graphic mark to stamp on the page. Values: 'signature' (full signature) or 'initials' (visa/initials).

Limits:Default: 'signature'

page_number

int

Sequential page number where the box will be placed (must be greater than or equal to 1).

Limits:Required

relative_position_left

float

X-axis position calculated as a percentage (0 to 100) from the left edge of the page.

Limits: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.

Limits: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.

Limits:Mutually exclusive with top

relative_size_width

float

Width of the signature box calculated as a percentage of the total page width.

Limits:Optional (0 to 100)

relative_size_height

float

Height of the signature box calculated as a percentage of the total page height.

Limits: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
  }
]

Option B) Legacy: Absolute PDF Points (Main only)

It is configured at the signer’s root level (outside of placements). Cannot be mixed with placements or it will throw 422.

Field	Type	Notes
position_x	number	Exact X coordinate in absolute PDF points (top-left origin).
position_y	number	Exact Y coordinate in absolute PDF points.
page	int	Page number (greater than or equal to 1).

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": ["digital_certificate_local"],
      "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.

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.