> ## Documentation Index
> Fetch the complete documentation index at: https://docs.annature.com.au/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](api-reference/recipients/recipient-object) 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](api-reference/documents/document-object) and one [recipient](api-reference/recipients/recipient-object) with a type of `signer`. Every signer must have at least one [field](api-reference/fields/field-object) 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

<ParamField path="name" required>
  The name of the envelope. Displayed in the subject line of emails sent to recipients and when viewing the envelope.
</ParamField>

<ParamField path="message" type="string">
  The envelope message. Displayed in the body of the emails sent to recipients and in the Annature UI.
</ParamField>

<ParamField path="shared" type="boolean">
  If true, the envelope is shared with other accounts in the same group as the sender.
</ParamField>

<ParamField path="draft" type="boolean">
  Set to true to create a draft envelope. Signing emails will not be sent until the envelope is sent manually or via API.
</ParamField>

<ParamField path="account_id" type="string" required>
  The unique identifier of the sender’s account.
</ParamField>

<ParamField path="group_id" type="string">
  The group to assign this envelope to. If not supplied, the sender’s group will be used automatically.
</ParamField>

<ParamField path="documents" type="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](/api-reference/documents/document-object#document-limits) for full details.

  <Expandable title="child arguments">
    <ResponseField name="id" type="string">
      A user-defined identifier for the document. Must be unique per envelope.
    </ResponseField>

    <ResponseField name="name" type="string">
      Display name of the document. If omitted, one will be auto-generated.
    </ResponseField>

    <ResponseField name="base" type="string" required>
      The base64-encoded string of the PDF document.
    </ResponseField>

    <ResponseField name="type" 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.
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField path="recipients" type="array" required>
  A collection of recipients. At least one recipient of type `signer` is required unless the envelope is a draft.

  <Expandable title="child arguments">
    <ResponseField name="name" type="string" required>
      The full name of the recipient.
    </ResponseField>

    <ResponseField name="email" type="string" required>
      The email address of the recipient.
    </ResponseField>

    <ResponseField name="mobile" type="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.
    </ResponseField>

    <ResponseField name="type" type="string">
      Recipient type. Defaults to `signer`.

      Allowed values: `signer`, `viewer`, `carbon-copy`.
    </ResponseField>

    <ResponseField name="message" type="string">
      A custom message shown to this recipient. Overrides the envelope message.
    </ResponseField>

    <ResponseField name="password" type="string">
      A password the recipient must enter to view the envelope.
    </ResponseField>

    <ResponseField name="sms_auth" type="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.
    </ResponseField>

    <ResponseField name="muted" type="boolean">
      If true, Annature will not send any correspondence to this recipient — including emails, SMS messages, or automated reminders.
    </ResponseField>

    <ResponseField name="order" type="integer">
      Used to control the recipient's position in the signing order. Recipients with lower order values must complete their actions first.
    </ResponseField>

    <ResponseField name="redirects" type="object">
      Redirect URLs for post-session navigation.

      <Expandable title="child arguments">
        <ResponseField name="session_completed" type="string">
          Redirect after recipient completes the envelope.
        </ResponseField>

        <ResponseField name="session_declined" type="string">
          Redirect after recipient declines the envelope.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ParamField path="fields" type="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.

      <Expandable title="child arguments">
        <ResponseField name="id" type="string">
          A user-defined ID for the field.
        </ResponseField>

        <ResponseField name="type" type="string" required>
          Field type: `signature`, `initials`, `witness`, `date`, `input`, `checkbox`, or `dropdown`.
        </ResponseField>

        <ResponseField name="page" type="integer" required>
          The 1-based page number the field should be placed on. Required when using fixed positioning; ignored if anchor is provided.
        </ResponseField>

        <ResponseField name="anchor" type="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.
        </ResponseField>

        <ResponseField name="x_offset" type="integer">
          X-axis offset in pixels.
        </ResponseField>

        <ResponseField name="y_offset" type="integer">
          Y-axis offset in pixels.
        </ResponseField>

        <ResponseField name="x_coordinate" type="integer" required>
          Absolute pixel-based coordinates used for fixed positioning. Both `x_coordinate` and `y_coordinate` are required when using fixed positioning.
        </ResponseField>

        <ResponseField name="y_coordinate" type="integer" required>
          Absolute pixel-based coordinates used for fixed positioning. Both `x_coordinate` and `y_coordinate` are required when using fixed positioning.
        </ResponseField>

        <ResponseField name="required" type="boolean">
          Whether this field must be completed before envelope can be completed.
        </ResponseField>

        <ResponseField name="read_only" type="boolean">
          Whether this field is view-only.
        </ResponseField>

        <ResponseField name="collaborative" type="boolean">
          Whether later recipients can modify this field's value.
        </ResponseField>

        <ResponseField name="value" type="string">
          Default value for input or dropdown fields.
        </ResponseField>

        <ResponseField name="checked" type="boolean">
          Default state of a checkbox field.
        </ResponseField>

        <ResponseField name="height" type="integer">
          Field height in pixels.
        </ResponseField>

        <ResponseField name="width" type="integer">
          Field width in pixels.
        </ResponseField>

        <ResponseField name="options" type="array" required>
          Dropdown options (required for `dropdown` type).

          <Expandable title="child arguments">
            <ResponseField name="value" type="string" required>
              The stored value of the dropdown option.
            </ResponseField>

            <ResponseField name="option" type="string" required>
              The display text for the dropdown option.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="font_size" type="integer">
          Font size (8–32px). Default is 10.
        </ResponseField>

        <ResponseField name="font_type" type="string">
          Font type. Allowed values: `courier`, `helvetica`. Defaults to `courier`.
        </ResponseField>

        <ResponseField name="date_format" type="string">
          Display format for date fields. Defaults to `DD/MM/YYYY hh:mm a`.
        </ResponseField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="metadata" type="object">
  Set of key-value pairs attached to the envelope.
</ParamField>

<RequestExample>
  ```bash Endpoint theme={null}
  POST /v1/envelopes
  ```

  ```bash Body theme={null}
  {
    "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": {}
  }
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "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": {}
  }
  ```
</ResponseExample>