Create Document Async

POST

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

Create Document Async

Unlike the synchronous method, this endpoint accepts massive batches in a single call and responds immediately with a 202 Accepted status and an ingest_token. The envelope is assembled in the background by downloading files in parallel.

curl -X POST https://api.firmeasy.legal/api/v1/documents/envelopes/async \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "name": "Service Agreement",
  "documents": [{
    "ref_id": "main",
    "source_type": "url",
    "file_format": "pdf",
    "role": "sign",
    "source_payload": { "url": "https://files.example.com/contract.pdf" }
  }],
  "signers": [{
    "name": "John Doe",
    "email": "[email protected]",
    "country_code": "+51",
    "phone": "900000001"
  }]
}'

Sin ejecutar·latencia ~ 412 ms

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

Async Ingestion Limits

Limit	Value
Maximum documents per envelope	100
Maximum weight per document	~100 MB
Maximum total envelope weight	1 GB
Supported source (V1)	URL Only

Optional Header (Idempotency)

To avoid duplicates in case of network failures, you can send an idempotency key. If you retry the same call, the server will return the same cached response (30-minute TTL).

Parameter	Type	Description	Limits
`Idempotency-Key`	uuid	Unique identifier generated by the client. If the original ingestion is still in progress and you retry, it will return code 409.	HTTP Header

Idempotency-Key

uuid

Unique identifier generated by the client. If the original ingestion is still in progress and you retry, it will return code 409.

Limits:HTTP Header

Request Body

Parameter	Type	Description	Limits
`name`	string	Envelope name (normalized to UPPERCASE with .pdf appended).	Required
`documents`	array	List of 1 to 100 documents. The first element (position 0) will always be considered the main document.	Required
`documents[].ref_id`	string	Unique identifier. For the main document it is optional (defaults to 'main'). For attachments it is required and must be unique.	Required for attachments
`documents[].source_type`	enum	File source type.	Only supports 'url'
`documents[].file_format`	enum	File format.	Only supports 'pdf'
`documents[].role`	enum	Role of the file within the envelope.	Only supports 'sign'
`documents[].source_payload.url`	url	Public URL from which the document will be downloaded.	Max: 2048 characters
`callback_url`	url	One-shot webhook that will be invoked when ingestion finishes (success or failure).	Max: 2048 characters
`callback_secret`	string	Secret key. If sent, the webhook payload will be signed via HMAC-SHA256 in the X-Firmeasy-Signature-SHA256 header.	Optional
`external_id`	string(255)	Free external ID assigned by the integrator (pass-through). Copied to the resulting document.	Optional
`metadata`	object	Free JSON key-value storage object for custom metadata. Copied to the resulting document.	Pass-through

name

string

Envelope name (normalized to UPPERCASE with .pdf appended).

Limits:Required

documents

array

List of 1 to 100 documents. The first element (position 0) will always be considered the main document.

Limits:Required

documents[].ref_id

string

Unique identifier. For the main document it is optional (defaults to 'main'). For attachments it is required and must be unique.

Limits:Required for attachments

documents[].source_type

enum

File source type.

Limits:Only supports 'url'

documents[].file_format

enum

File format.

Limits:Only supports 'pdf'

documents[].role

enum

Role of the file within the envelope.

Limits:Only supports 'sign'

documents[].source_payload.url

url

Public URL from which the document will be downloaded.

Limits:Max: 2048 characters

callback_url

url

One-shot webhook that will be invoked when ingestion finishes (success or failure).

Limits:Max: 2048 characters

callback_secret

string

Secret key. If sent, the webhook payload will be signed via HMAC-SHA256 in the X-Firmeasy-Signature-SHA256 header.

Limits:Optional

external_id

string(255)

Free external ID assigned by the integrator (pass-through). Copied to the resulting document.

Limits:Optional

metadata

object

Free JSON key-value storage object for custom metadata. Copied to the resulting document.

Limits:Pass-through

Envelope configuration (optional)

The async endpoint accepts the same configuration fields as the Sync endpoint:

Parameter	Type	Description	Limits
`folder_token`	uuid	Token of the destination folder where the document will be saved.	Must be a valid UUID
`lang`	enum	Language for the signer interface and communications. Values: 'es', 'en', 'pt'.	Default: 'es'
`signature_deadline`	ISO8601	Future deadline date and time to complete signatures (e.g. '2026-12-31T23:59:59.000Z').	Full UTC format
`is_signature_order_active`	bool	Forces signers to strictly follow the established order (sequential).	Default: false
`is_rejection_allowed`	bool	Enables the button for a signer to formally reject the document.	Default: false
`is_original_download_allowed`	bool	Allows the signer to download the clean original PDF before signing.	Default: true
`disable_owner_notifications`	bool	Disables email alerts to the envelope owner.	Default: false
`disable_signer_notifications`	bool	Disables automatic alerts to signers.	Default: false
`send_automatic_invitations`	bool	Sends invitations 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 completed document copy via WhatsApp.	Default: false
`reminder_every_n_days`	int	Frequency in days for automatic reminders (0 to 30).	0 to disable
`observers`	array<string>	List of observer emails with read-only access (max 20).	Array of emails
`redirect_link`	string(255)	Post-signature redirect URL.	Must be a valid URL
`created_by`	email	Email of the user who created the request.	Email format
`sender_name`	string(150)	Sender name shown to signers. If omitted, the owner's name is used.	Max 150 characters
`reply_to_email`	email	Address to receive replies from sent notifications.	Email format

folder_token

uuid

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

Limits:Must be a valid UUID

lang

enum

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

Limits:Default: 'es'

signature_deadline

ISO8601

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

Limits:Full UTC format

is_signature_order_active

bool

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

Limits:Default: false

is_rejection_allowed

bool

Enables the button for a signer to formally reject the document.

Limits:Default: false

is_original_download_allowed

bool

Allows the signer to download the clean original PDF before signing.

Limits:Default: true

disable_owner_notifications

bool

Disables email alerts to the envelope owner.

Limits:Default: false

disable_signer_notifications

bool

Disables automatic alerts to signers.

Limits:Default: false

send_automatic_invitations

bool

Sends invitations 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 completed document copy via WhatsApp.

Limits:Default: false

reminder_every_n_days

int

Frequency in days for automatic reminders (0 to 30).

Limits:0 to disable

observers

array<string>

List of observer emails with read-only access (max 20).

Limits:Array of emails

redirect_link

string(255)

Post-signature redirect URL.

Limits:Must be a valid URL

created_by

Email of the user who created the request.

Limits:Email format

sender_name

string(150)

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

Limits:Max 150 characters

reply_to_email

Address to receive replies from sent notifications.

Limits:Email format

Ingestion Response

If the request is valid, the system immediately responds with an ingestion token. The estimated time is calculated as min(1800, 10 + n·5) seconds, where n is the number of documents.

{
  "ingest_token": "01234567-89ab-cdef-0123-456789abcdef",
  "status": "ingesting",
  "documents_total": 2,
  "credits_cost": 2,
  "status_url": "[https://api.firmeasy.legal/api/v1/documents/envelopes/01234567-89ab-cdef-0123-456789abcdef/status](https://api.firmeasy.legal/api/v1/documents/envelopes/01234567-89ab-cdef-0123-456789abcdef/status)",
  "estimated_processing_time_seconds": 20
}

Nombre	Type	Description
`ingest_token`	string	Unique ingestion identifier. Save it to check the status or cancel the process.
`status`	string	Initial ingestion status. Returned value: 'ingesting'.
`documents_total`	integer	Total number of documents received for processing in this batch.
`credits_cost`	integer	Credits that will be deducted upon successful completion. If ingestion fails, no charge is made.
`status_url`	string	URL to check the envelope assembly progress in real time.
`estimated_processing_time_seconds`	integer	Estimated time in seconds to complete the ingestion.

ingest_token

string

Unique ingestion identifier. Save it to check the status or cancel the process.

status

string

Initial ingestion status. Returned value: 'ingesting'.

documents_total

integer

Total number of documents received for processing in this batch.

credits_cost

integer

Credits that will be deducted upon successful completion. If ingestion fails, no charge is made.

status_url

string

URL to check the envelope assembly progress in real time.

estimated_processing_time_seconds

integer

Estimated time in seconds to complete the ingestion.

Billing note: 1 credit per document is charged only upon successful completion of the assembly. If ingestion fails, no credits are deducted. If the organization balance is firmas_disponibles < -500, the operation is rejected with code 402.

Check Ingestion Status

Allows you to verify the progress of the envelope assembly. When it reaches the ready status, the system will return the definitive document_token.

See the dedicated page for full detail: Ingestion Status.

Endpoint: GET /v1/documents/envelopes/{{ingest_token}}/status

Possible statuses: ingesting → assembling → ready (success) | failed | cancelled.

Additional error codes: 402 if the organization has insufficient balance (firmas_disponibles < -500).

Cancel Ingestion in Progress

If the document is still in progress, you can send the order to abort it.

See the dedicated page for full detail: Cancel Ingestion.

Endpoint: POST /v1/documents/envelopes/{{ingest_token}}/cancel

It will respond with code 200 if cancelled successfully. If the envelope is already in a terminal state (ready, failed, or cancelled), it will return a 409 error.

Document Object (Final Response / Webhooks)

Once the document is processed, the system consolidates the complete envelope. This is the structure you will get when querying the document via the API (or through creation Webhooks).

{
  "external_id": "ERP-123",
  "token": "abcdef01-2345-6789-abcd-ef0123456789",
  "name": "CONTRATO_LOTE_MASIVO.pdf",
  "folder": { "token": "uuid", "name": "Carpeta" },
  "status": "pending",
  "lang": "es",
  "size": 245100,
  "original_file": "https://.../files/...?intent=view&signature=...",
  "signed_file": null,
  "original_download_file": "https://.../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": 2,
  "extra_docs": [
    {
      "token": "anexo-token",
      "name": "Anexo 1 - Tarifario 2026.pdf",
      "original_file": "https://.../?intent=view&...",
      "signed_file": null,
      "original_download_file": "https://.../?intent=download&...",
      "signed_download_file": null,
      "uploaded_by": { "email": "[email protected]" }
    }
  ],
  "signers": [
    {
      "external_id": null,
      "token": "signer-api-id",
      "status": "pending",
      "rejection_reason": null,
      "order": 1,
      "name": "Jane Doe",
      "email": "[email protected]",
      "phone": "900000001",
      "country_code": "+51",
      "document_type": "dni",
      "document_number": "900000003",
      "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 for future queries and operations.
`external_id`	string	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. Initial value: 'pending'.
`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. Null while the envelope is not fully signed.
`signatures_made`	integer	Number of signatures stamped so far. Starts at 0.
`extra_docs_count`	integer	Number of attached documents included in the envelope.
`extra_docs`	array	List of attachments with their tokens and download URLs. URLs expire in 60 minutes.
`signers`	array	List of registered signers with their individual token, status, signature link, and flow configuration.
`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 for future queries and operations.

external_id

string

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. Initial value: 'pending'.

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. Null while the envelope is not fully signed.

signatures_made

integer

Number of signatures stamped so far. Starts at 0.

extra_docs_count

integer

Number of attached documents included in the envelope.

extra_docs

array

List of attachments with their tokens and download URLs. URLs expire in 60 minutes.

signers

array

List of registered signers with their individual token, status, signature link, and flow configuration.

created_at

datetime

Exact date and time of envelope creation in UTC ISO 8601 format.