Integration Guide

Guide to implementing an electronic signature flow using the Legaldoc.io v2 API: create a document (envelope), add recipients and fields, distribute it, and get the signed result. This flow applies to any type of signature. If your use case requires verifying the signer’s identity against a certification authority, see the Advanced Electronic Signature chapter.

---

Integration Flow

1. Createthe envelope
2. Addsignature fields
3. Distributeand sign
4. Checkthe status
5. Downloadthe result

---

1. Create the envelope and recipients

POST /envelope/create

An envelope is the API’s central object: it represents the document (or set of documents) you’re getting signed, along with its recipients, fields, and current status. The whole signing flow revolves around an envelope — it’s created once, and every other call (adding fields, distributing, checking status, downloading) acts on the id this creation returns.

{
  "type": "DOCUMENT",
  "recipients": [
    {
      "name": "Recipient name",
      "email": "recipient@example.com",
      "role": "SIGNER",
      "signingOrder": 1
    }
  ]
}

role accepts SIGNER, VIEWER, APPROVER, CC, or ASSISTANT, depending on that recipient’s participation in the document. signingOrder is optional for simple signing — if you don’t set it, recipients can sign in any order.

See the full spec for this endpoint in the API Reference.

---

2. Add signature fields

POST /envelope/field/create-many

Each recipient needs at least one field to be able to sign. Besides SIGNATURE, the API supports text, date, checkbox, radio, dropdown fields and more — see the API Reference for details on each type.

Where to place the field on the PDF

There are two ways to tell Legaldoc where a field goes, and they’re mutually exclusive:

Method	Fields	When to use it
Placeholder (recommended)	placeholder, optionally width, height	Whenever you can insert an anchor text in the PDF.
Coordinates	page, positionX, positionY, width, height (as percentages)	Only when you don’t control the PDF’s content.

With a placeholder, you give Legaldoc an anchor text to search for in the PDF:

{
  "recipientId": 456,
  "type": "SIGNATURE",
  "placeholder": "{{SIGNER_SIGNATURE}}",
  "width": 30,
  "height": 8
}

Legaldoc searches for that text in the document, places the field at its exact position, and covers the original text with a white rectangle before saving. You don’t need to calculate which page it falls on or measure coordinates, and if the document’s length changes between generations —a template with variable-length paragraphs, for example— the field still gets placed correctly without you touching anything.

If the placeholder doesn’t appear in the PDF, field creation fails immediately with a clear error (Placeholder "..." not found in PDF), before the document is distributed and before any recipient exists.

With coordinates, instead, you directly specify the page and the position as a percentage of the page’s width/height. Use them only when you can’t insert an anchor text in the PDF —for example, a scanned document or one from a third party.

Coordinates: validate the page before distributing

Legaldoc doesn’t validate that the page exists when the field is created — if you specify page: 4 on a 3-page document, the creation call doesn’t fail. The error only shows up later (the exact moment depends on the flow — see the detail in the Advanced Electronic Signature chapter), potentially with the recipient already interacting with the document. Validate the page count yourself before creating fields by coordinates.

If you use a placeholder, put it on its own line of text, without paragraph justification or extra letter/word spacing: if the engine generating your PDF splits it into several text fragments, Legaldoc won’t recognize it as a single string.

See the full spec for this endpoint in the API Reference.

---

3. Prepare the document

Before creating the envelope, decide on the final content of your PDF. The document doesn’t allow design changes once signing has started: no pages, watermarks, stamps, or any other visual element can be added after the first signature.

This isn’t a Legaldoc limitation: it’s a property of how digital signatures work over PDF. A signature cryptographically covers the bytes of the document at the moment it’s applied; any change afterward —even if it doesn’t touch the signed content— makes readers like Adobe Acrobat report the signature as invalid or the document as modified.

What to do

Make sure your PDF is in its final version —with all layout, page numbering, and content you want the signer to see— before creating it in Legaldoc. Legaldoc applies its own legal watermark and verification code before any signature exists, so that part doesn’t require anything from you.

---

4. Distribute and the signing experience

POST /envelope/distribute

Once distributed, redirect your user to the signing URL returned by the API (recipients[].signingUrl). Your responsibility ends at redirecting the user, and picks back up when the user returns to your application (via the redirectUrl you configured) or when you receive the notification that the document changed status.

See the full spec for this endpoint in the API Reference.

---

5. Knowing when it’s done

Use webhooks to find out about status changes without having to poll actively. The relevant events are DOCUMENT_COMPLETED and DOCUMENT_REJECTED.

If you prefer or need to confirm the status synchronously, check:

GET /envelope/{envelopeId}

and inspect the status field:

Status	Meaning
PENDING	Signatures are still pending or the process is in progress.
COMPLETED	All recipients completed. The document is available.
REJECTED	A recipient rejected signing. See section 7.

See the full spec for this endpoint in the API Reference.

---

6. Download the signed document

GET /envelope/item/{envelopeItemId}/download?version=signed

The returned PDF includes the applied signatures and the process’s audit trail.

See the full spec for this endpoint in the API Reference.

---

7. Rejection

A recipient can reject the document instead of signing it. When that happens, the envelope moves to REJECTED status and you receive the DOCUMENT_REJECTED event via webhook. The document remains available reflecting the rejection and its reason.

---

8. Third-party verification

Every document generated by Legaldoc includes a QR code and an alphanumeric verification code visible on the document. Anyone who receives a copy of the document —inside or outside your application— can scan the code or visit the public verification page to confirm its authenticity, without needing access to your system or Legaldoc’s. You don’t need to build anything to enable this: it’s included in the document from its creation.

---

9. Advanced Electronic Signature

If your use case needs to certify the signer’s identity —for example, contracts that require reinforced legal validity— use Advanced Electronic Signature (FEA). On top of the flow you just saw, FEA adds: the signer’s national ID, sequential signing order, and additional evidence (certificate and audit log) as independent downloads.

See the full chapter: Advanced Electronic Signature.

---

10. Endpoint summary

Action	Endpoint
Create envelope	POST /envelope/create
Add signature fields	POST /envelope/field/create-many
Distribute	POST /envelope/distribute
Check status	GET /envelope/{envelopeId}
Download signed document	GET /envelope/item/{envelopeItemId}/download?version=signed

Other v2 API resources

This guide covers the minimal creation-and-signing flow. The v2 API also exposes other resources — see the API Reference for the full detail of each:

Resource	What it’s for
Envelope (list, get-many, use, update, delete, cancel, duplicate, redistribute)	Managing the full envelope lifecycle beyond create/distribute/check: listing, cancelling, duplicating, resending, etc.
Envelope Recipients (get, create-many, update-many, delete, reject-on-behalf-of)	Managing recipients after the envelope is created, including rejecting on a recipient’s behalf.
Envelope Fields (get, update-many, delete)	Managing individual fields beyond the initial bulk creation.
Envelope Items (create-many, update-many, delete)	Managing the documents/files within an envelope.
Envelope Attachments	Attachments associated with an envelope, independent of the documents to be signed.
Folder	Organizing envelopes into folders.
Embedding (presign tokens)	Generating and verifying signing tokens to embed the signing experience in your own application, instead of redirecting to signingUrl.

---

Common errors

Situation	Common cause
Distribution fails with a validation error	A required field is missing, or a recipient has no signature field assigned.
Field creation fails with Placeholder "..." not found in PDF	The anchor text doesn’t exist verbatim in the PDF, or it got split into several fragments by the generation engine (justification, letter spacing).
Downloading the document returns an error	The envelope isn’t in COMPLETED status yet.