Files and envelopes

An envelope is one send: one or more PDFs, the people who sign them, and the fields each person fills in. It is also the unit you pay for, once, when it is sent (sending is coming next; a draft costs nothing).

Upload a file

Four ways, all POST /v1/files unless noted:

How	Body	Limit
Multipart	-F file=@agreement.pdf	25 MB
From a URL	{"url": "https://…"}	25 MB
Inline	{"base64": "…", "name": "agreement.pdf"}	10 MB
Presigned	POST /v1/files/presign with {"name": "agreement.pdf", "bytes": 1921746}, PUT the bytes to upload_url with the returned headers, then POST /v1/files/{id}/complete	25 MB

A direct upload, and a presigned one once complete succeeds, answers with the file’s id, page_count, page_sizes in points, and sha256 of exactly the bytes you sent. Only PDF is accepted for now; anything else is 422 invalid_file. A file not attached to an envelope is removed after 30 days.

You can also skip the upload and put {"url": …} or {"base64": …, "name": …} straight into an envelope’s files list.

Where fields go

Each field is a box on one page of one file:

• Origin: the top-left corner of the page as a viewer shows it (after any rotation).
• x, y: the top-left corner of the box. width, height: positive.
• Unit: declared per field with unit. Sealpost always answers in points and keeps your original numbers in source.

unit	One unit is	Typical source
pt (default)	1 point (1/72 inch)	Most editors, PDF tools
px72	1 pixel of a 72 dpi render (same as pt)	Coordinates measured in “pixels” by older signing tools
px96	1 CSS pixel (0.75 pt)	A browser editor measuring on screen
percent	1% of the page width (x, width) or height (y, height)	Responsive editors

Coordinates are checked against the file’s real page sizes. A box that leaves its page, or names a page the file does not have, is 422 invalid_field_geometry, naming the field and the page size.

Field types

signature, initials, date_signed, text, checkbox, radio, dropdown, attachment, image, note.

recipient is the index of the signer in recipients (required except for note). file is the index into files and defaults to the first file.

Create an envelope

POST /v1/envelopes: title and files are required; add recipients and fields to say who signs where. Useful options:

• flexible_signing: true lets each signer place their own signature instead of fixed fields.
• sequential: true makes routing_order on recipients count, so signers go one after another.
• metadata: up to 20 string values (keys of letters, digits, _, ., -, up to 40 characters; values up to 500), returned unchanged.
• client_reference: your own id for the envelope.

The envelope is created as a draft. See the Quickstart for a complete example and the API reference for every property.