Create Document Async

1. API
2. ›Documents
3. ›Create Document Async

POST {{base_url}}/v1/documents/envelopes/async

Environments

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

RequestDemoResponse

Copiar

cURLNode.jsPythonPHPGo

curl -X POST {{base_url}}/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

Probar en vivo

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

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.

---

---

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

---

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[].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

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
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

Signers

The async endpoint accepts exactly the same signers and placements structure (signers[]) as the Sync endpoint, including standard/advanced flows, percentage-based placements and legacy positions.

Strict with References

Unlike the synchronous method, the async method is strict: if in placements[].document_ref you send a reference that does not exist in your documents[] array, the API will return a 422 error instead of auto-assigning it to the main document.

---

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": "[{{base_url}}/v1/documents/envelopes/01234567-89ab-cdef-0123-456789abcdef/status]({{base_url}}/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.

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).

cert-only

If during ingestion the system detects that a PDF comes pre-signed, it auto-corrects those signers’ flow to digital_certificate_local to maintain document consistency.

New: Attachments and Counts

The object now includes extra_docs (array of attachments and their temporary links, always present in create and webhooks) and extra_docs_count (number of attachments added). Download URLs expire in 60 minutes for security.

{
  "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.