POST /v1/envelopes
{
"name": "Non disclosure agreement",
"message": "Lorem ipsum dolor sit amet.",
"shared": false,
"draft": false,
"account_id": "c64ce66b70b21c03bfd5dfa0ab14b730",
"group_id": "a5a885caee6286a54ad7bbd4ab5400e9",
"documents": [{
"id": "fcad499b03c6fc222bc66208317a18c9",
"name": "Non disclosure agreement.pdf",
"base": "iVBORw0KGgoAAAANSUhE.."
}],
"recipients": [{
"name": "Ted Annature",
"email": "ted@annature.com.au",
"mobile": "+61422000000",
"type": "signer",
"message": "Lorem ipsum dolor sit amet.",
"password": "password1",
"sms_auth": "+61422000000",
"muted": false,
"order": 1,
"redirects": {
"session_completed": "https://..",
"session_declined": "https://..",
},
"fields": [{
"id": "f901e397780d6d8de7159857c596d18b",
"type": "signature",
"anchor": "{{signature}}"
}]
}],
"metadata": {}
}
{
"id": "7e8f68e4c6df9395cd7ff48d69d7e2c1",
"name": "Non disclosure agreement",
"message": "Lorem ipsum dolor sit amet.",
"status": "sent",
"shared": false,
"created": "2019-12-17T05:30:00Z",
"sent": "2019-12-17T05:30:00Z",
"voided": null,
"declined": null,
"completed": null,
"account_id": "c64ce66b70b21c03bfd5dfa0ab14b730",
"group_id": "a5a885caee6286a54ad7bbd4ab5400e9",
"recipients": [{
"id": "255e591c2c9fe1bc99be1ec03075b402",
"name": "Ted Annature",
"email": "ted@annature.com.au",
"mobile": "+61422000000",
"type": "signer",
"status": "sent",
"message": "Lorem ipsum dolor sit amet.",
"password": false,
"sms_auth": "+61422000000",
"muted": false,
"order": 1,
"declined_reason": null,
"created": "2019-12-17T05:30:00Z",
"sent": "2019-12-17T05:30:00Z",
"declined": null,
"completed": null,
"redirects": {
"session_completed": "https://..",
"session_declined": "https://..",
}
}],
"metadata": {}
}
Envelopes
Create an envelope
POST /v1/envelopes
{
"name": "Non disclosure agreement",
"message": "Lorem ipsum dolor sit amet.",
"shared": false,
"draft": false,
"account_id": "c64ce66b70b21c03bfd5dfa0ab14b730",
"group_id": "a5a885caee6286a54ad7bbd4ab5400e9",
"documents": [{
"id": "fcad499b03c6fc222bc66208317a18c9",
"name": "Non disclosure agreement.pdf",
"base": "iVBORw0KGgoAAAANSUhE.."
}],
"recipients": [{
"name": "Ted Annature",
"email": "ted@annature.com.au",
"mobile": "+61422000000",
"type": "signer",
"message": "Lorem ipsum dolor sit amet.",
"password": "password1",
"sms_auth": "+61422000000",
"muted": false,
"order": 1,
"redirects": {
"session_completed": "https://..",
"session_declined": "https://..",
},
"fields": [{
"id": "f901e397780d6d8de7159857c596d18b",
"type": "signature",
"anchor": "{{signature}}"
}]
}],
"metadata": {}
}
{
"id": "7e8f68e4c6df9395cd7ff48d69d7e2c1",
"name": "Non disclosure agreement",
"message": "Lorem ipsum dolor sit amet.",
"status": "sent",
"shared": false,
"created": "2019-12-17T05:30:00Z",
"sent": "2019-12-17T05:30:00Z",
"voided": null,
"declined": null,
"completed": null,
"account_id": "c64ce66b70b21c03bfd5dfa0ab14b730",
"group_id": "a5a885caee6286a54ad7bbd4ab5400e9",
"recipients": [{
"id": "255e591c2c9fe1bc99be1ec03075b402",
"name": "Ted Annature",
"email": "ted@annature.com.au",
"mobile": "+61422000000",
"type": "signer",
"status": "sent",
"message": "Lorem ipsum dolor sit amet.",
"password": false,
"sms_auth": "+61422000000",
"muted": false,
"order": 1,
"declined_reason": null,
"created": "2019-12-17T05:30:00Z",
"sent": "2019-12-17T05:30:00Z",
"declined": null,
"completed": null,
"redirects": {
"session_completed": "https://..",
"session_declined": "https://..",
}
}],
"metadata": {}
}
Creates a new envelope and, by default, sends a signing email to all eligible recipients, respecting the
order and muted properties defined on each recipient. For more detail on how recipients behave, refer to the recipients section.
All envelopes must include an account_id to identify the sender. If the account is assigned to a group, the envelope will automatically inherit that group. This can be overridden by supplying a group_id directly.
Each envelope must include at least one document and one recipient with a type of signer. Every signer must have at least one field defined.
To create a draft envelope, set draft to true and include at least one document. Drafts can optionally include recipients, but recipient fields are not supported in drafts.
Drafts can be opened and completed in the Annature dashboard by visiting: https://dashboard.annature.com.au/create-envelope?envelopeId={{envelope_id}}
Field placement methods
When creating fields for a recipient, there are two supported placement strategies: anchor-based (automatic) or coordinate-based (fixed). Regardless of which method you use, any field whose bounding box would extend beyond the page bounds will be silently skipped. Ensure all fields fit entirely within the page dimensions to be rendered correctly.Anchors (automatic placement)
Anchors allow you to specify a text string, and fields will be automatically created at every location in all documents where that string appears. Anchors are a fast and flexible way to apply fields without knowing exact coordinates.- All anchor matches use the bottom-left of the matched text as the origin.
- Optional
x_offsetandy_offsetcan be supplied to fine-tune placement.
Coordinates (fixed positioning)
For precise control, coordinates can be supplied using absolutex_coordinate and y_coordinate values.
- All coordinates use 72 DPI rendering with a bottom-left origin.
- For most fields, positioning is relative to the bottom-left corner.
- For
inputfields, positioning is relative to the top-left, and height expands downward based on content.
Parameters
required
The name of the envelope. Displayed in the subject line of emails sent to recipients and when viewing the envelope.
string
The envelope message. Displayed in the body of the emails sent to recipients and in the Annature UI.
boolean
If true, the envelope is shared with other accounts in the same group as the sender.
boolean
Set to true to create a draft envelope. Signing emails will not be sent until the envelope is sent manually or via API.
string
required
The unique identifier of the sender’s account.
string
The group to assign this envelope to. If not supplied, the sender’s group will be used automatically.
array
required
A collection of base64-encoded PDF or Word documents. Word files are automatically converted to PDF.Each document can be up to 10mb in raw size. An envelope can include multiple documents, but total file size and page count limits apply. See Document limits for full details.
Show child arguments
Show child arguments
string
A user-defined identifier for the document. Must be unique per envelope.
string
Display name of the document. If omitted, one will be auto-generated.
string
required
The base64-encoded string of the PDF document.
string
required
The MIME type of the uploaded file (
application/pdf, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document).Word documents are converted to PDF automatically.array
required
A collection of recipients. At least one recipient of type
signer is required unless the envelope is a draft.Show child arguments
Show child arguments
string
required
The full name of the recipient.
string
required
The email address of the recipient.
string
The recipient’s mobile number, supplied in E.164 format. This number is used to send an SMS with a link to open the envelope.While it is technically possible to use both
mobile and sms_auth, we strongly recommend using only one. Sending both the envelope link and the OTP to the same device does not meet the requirements for two-factor authentication.string
Recipient type. Defaults to
signer.Allowed values: signer, viewer, carbon-copy.string
A custom message shown to this recipient. Overrides the envelope message.
string
A password the recipient must enter to view the envelope.
string
Enables SMS-based two-factor authentication by specifying the recipient’s mobile number, formatted in E.164.When supplied, Annature will send a one-time code (OTP) to the recipient. This code must be entered before they can access the envelope.While it is technically possible to use both
sms_auth and mobile, we strongly recommend using only one. Sending both the envelope link and the OTP to the same device does not meet the requirements for two-factor authentication.boolean
If true, Annature will not send any correspondence to this recipient — including emails, SMS messages, or automated reminders.
integer
Used to control the recipient’s position in the signing order. Recipients with lower order values must complete their actions first.
object
array
required
Fields the recipient must complete. This property is only required when:
- The recipient type is
signer, and - The envelope is not being created as a draft.
Show child arguments
Show child arguments
string
A user-defined ID for the field.
string
required
Field type:
signature, initials, witness, date, input, checkbox, or dropdown.integer
required
The 1-based page number the field should be placed on. Required when using fixed positioning; ignored if anchor is provided.
string
required
A text string used for automatic placement. Required when not using coordinates. If supplied,
page, x_coordinate, and y_coordinate will be ignored.integer
X-axis offset in pixels.
integer
Y-axis offset in pixels.
integer
required
Absolute pixel-based coordinates used for fixed positioning. Both
x_coordinate and y_coordinate are required when using fixed positioning.integer
required
Absolute pixel-based coordinates used for fixed positioning. Both
x_coordinate and y_coordinate are required when using fixed positioning.boolean
Whether this field must be completed before envelope can be completed.
boolean
Whether this field is view-only.
boolean
Whether later recipients can modify this field’s value.
string
Default value for input or dropdown fields.
boolean
Default state of a checkbox field.
integer
Field height in pixels.
integer
Field width in pixels.
array
required
integer
Font size (8–32px). Default is 10.
string
Font type. Allowed values:
courier, helvetica. Defaults to courier.string
Display format for date fields. Defaults to
DD/MM/YYYY hh:mm a.object
Set of key-value pairs attached to the envelope.
POST /v1/envelopes
{
"name": "Non disclosure agreement",
"message": "Lorem ipsum dolor sit amet.",
"shared": false,
"draft": false,
"account_id": "c64ce66b70b21c03bfd5dfa0ab14b730",
"group_id": "a5a885caee6286a54ad7bbd4ab5400e9",
"documents": [{
"id": "fcad499b03c6fc222bc66208317a18c9",
"name": "Non disclosure agreement.pdf",
"base": "iVBORw0KGgoAAAANSUhE.."
}],
"recipients": [{
"name": "Ted Annature",
"email": "ted@annature.com.au",
"mobile": "+61422000000",
"type": "signer",
"message": "Lorem ipsum dolor sit amet.",
"password": "password1",
"sms_auth": "+61422000000",
"muted": false,
"order": 1,
"redirects": {
"session_completed": "https://..",
"session_declined": "https://..",
},
"fields": [{
"id": "f901e397780d6d8de7159857c596d18b",
"type": "signature",
"anchor": "{{signature}}"
}]
}],
"metadata": {}
}
{
"id": "7e8f68e4c6df9395cd7ff48d69d7e2c1",
"name": "Non disclosure agreement",
"message": "Lorem ipsum dolor sit amet.",
"status": "sent",
"shared": false,
"created": "2019-12-17T05:30:00Z",
"sent": "2019-12-17T05:30:00Z",
"voided": null,
"declined": null,
"completed": null,
"account_id": "c64ce66b70b21c03bfd5dfa0ab14b730",
"group_id": "a5a885caee6286a54ad7bbd4ab5400e9",
"recipients": [{
"id": "255e591c2c9fe1bc99be1ec03075b402",
"name": "Ted Annature",
"email": "ted@annature.com.au",
"mobile": "+61422000000",
"type": "signer",
"status": "sent",
"message": "Lorem ipsum dolor sit amet.",
"password": false,
"sms_auth": "+61422000000",
"muted": false,
"order": 1,
"declined_reason": null,
"created": "2019-12-17T05:30:00Z",
"sent": "2019-12-17T05:30:00Z",
"declined": null,
"completed": null,
"redirects": {
"session_completed": "https://..",
"session_declined": "https://..",
}
}],
"metadata": {}
}