Create an envelope

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_offset and y_offset can be supplied to fine-tune placement.

Coordinates (fixed positioning)

For precise control, coordinates can be supplied using absolute x_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 input fields, positioning is relative to the top-left, and height expands downward based on content.

Parameters

name

required

The name of the envelope. Displayed in the subject line of emails sent to recipients and when viewing the envelope.

message

string

The envelope message. Displayed in the body of the emails sent to recipients and in the Annature UI.

shared

boolean

If true, the envelope is shared with other accounts in the same group as the sender.

draft

boolean

Set to true to create a draft envelope. Signing emails will not be sent until the envelope is sent manually or via API.

account_id

string

required

The unique identifier of the sender’s account.

group_id

string

The group to assign this envelope to. If not supplied, the sender’s group will be used automatically.

documents

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

string

A user-defined identifier for the document. Must be unique per envelope.

name

string

Display name of the document. If omitted, one will be auto-generated.

base

string

required

The base64-encoded string of the PDF document.

type

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.

recipients

array

required

A collection of recipients. At least one recipient of type signer is required unless the envelope is a draft.

Show child arguments

name

string

required

The full name of the recipient.

string

required

The email address of the recipient.

mobile

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.

type

string

Recipient type. Defaults to signer.Allowed values: signer, viewer, carbon-copy.

message

string

A custom message shown to this recipient. Overrides the envelope message.

password

string

A password the recipient must enter to view the envelope.

sms_auth

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.

muted

boolean

If true, Annature will not send any correspondence to this recipient — including emails, SMS messages, or automated reminders.

order

integer

Used to control the recipient’s position in the signing order. Recipients with lower order values must complete their actions first.

redirects

object

Redirect URLs for post-session navigation.

Show child arguments

session_completed

string

Redirect after recipient completes the envelope.

session_declined

string

Redirect after recipient declines the envelope.

fields

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.

Fields are not supported for recipients who are not signers, or when the envelope is created as a draft.

Show child arguments

string

A user-defined ID for the field.

type

string

required

Field type: signature, initials, witness, date, input, checkbox, or dropdown.

page

integer

required

The 1-based page number the field should be placed on. Required when using fixed positioning; ignored if anchor is provided.

anchor

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.

x_offset

integer

X-axis offset in pixels.

y_offset

integer

Y-axis offset in pixels.

x_coordinate

integer

required

Absolute pixel-based coordinates used for fixed positioning. Both x_coordinate and y_coordinate are required when using fixed positioning.

y_coordinate

integer

required

Absolute pixel-based coordinates used for fixed positioning. Both x_coordinate and y_coordinate are required when using fixed positioning.

required

boolean

Whether this field must be completed before envelope can be completed.

read_only

boolean

Whether this field is view-only.

collaborative

boolean

Whether later recipients can modify this field’s value.

value

string

Default value for input or dropdown fields.

checked

boolean

Default state of a checkbox field.

height

integer

Field height in pixels.

width

integer

Field width in pixels.

options

array

required

Dropdown options (required for dropdown type).

Show child arguments

value

string

required

The stored value of the dropdown option.

option

string

required

The display text for the dropdown option.

font_size

integer

Font size (8–32px). Default is 10.

font_type

string

Font type. Allowed values: courier, helvetica. Defaults to courier.

date_format

string

Display format for date fields. Defaults to DD/MM/YYYY hh:mm a.

metadata

object

Set of key-value pairs attached to the envelope.

POST /v1/envelopes

{
  "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": {}
}

API Documentation

Endpoints

Resources

Create an envelope

Field placement methods

Anchors (automatic placement)

Coordinates (fixed positioning)

Parameters

API Documentation

Endpoints

Resources

​Field placement methods

​Anchors (automatic placement)

​Coordinates (fixed positioning)

​Parameters

Field placement methods

Anchors (automatic placement)

Coordinates (fixed positioning)

Parameters