Create Session From Template

Create a new signing session from a template. This endpoint allows you to generate a session based on a template and specify recipients.

Endpoint

POST https://api.airsign.com.au/api/v1/SessionFromTemplate

Headers

Name	Value	Required	Description
Content-Type	application/json	Yes	Specifies the format of the request body
Authorization	Bearer {access_token}	Yes	Bearer token obtained from authentication

Request Body

Parameter	Type	Required	Description
templateId	string	Yes	The ID of the template to use, must be active
name	string	No	Name of the session (1-50 characters). Defaults to the template name
sendImmediately	boolean	No	Whether to send invitations immediately or leave in draft. Defaults to `false`
recipients	array	No	List of recipient objects (`name`, `email`, `exclude`, `signingOrder`). Overrides the template recipients by index - pass an empty object `{}` to leave a position on its template defaults. Must not exceed the number of recipients defined in the template
variableValues	object	No	Key-value map of template variable values. Text variables accept strings, image variables accept file IDs, and table variables accept objects with `headers` (string[]) and `data` (string[][]). Required variables must be provided
tagIds	string[]	No	Array of tag UUIDs to associate with the session

Session Settings

The following optional parameters allow you to override session settings. If not provided, values are inherited from the template. Some settings require specific plan features — using a setting without the required plan will return a 403 error.

Parameter	Type	Description	Plan Required
expiryDays	number	Number of days before the session expires (1-730). Null means no expiry	Session Expiry
reminderEnabled	boolean	Whether to send automatic reminders to recipients	Session Expiry
reminderFrequency	string	Reminder frequency: `daily`, `weekly`, `monthly`, or `quarterly`	Session Expiry
senderProfileId	string	ID of a verified sender profile to use for this session	Sender Profiles
overrideCompletionEmailRecipients	string	Who receives the completion email: `all`, `sender_only`, `sender_and_cc`, or `none`	Advanced Completion Email
overrideAttachPdf	boolean	Whether to attach the signed PDF to the completion email	Advanced Completion Email
overrideAttachCertificate	boolean	Whether to attach the signing certificate to the completion email	Advanced Completion Email
overrideCreateCombinedDoc	boolean	Whether to create a combined PDF (all signed documents followed by the Certificate of Completion) when the session completes	-
overrideAttachCombinedDoc	boolean	Whether to attach the combined PDF to the completion email (requires overrideCreateCombinedDoc)	Advanced Completion Email
overrideCustomCompletionMessage	string	Custom message to include in the completion email (max 50,000 characters)	Advanced Completion Email
overrideDownloadLinkExpiryDays	number	Number of days before the download link in the completion email expires (1-365)	Advanced Completion Email

Signing Order

Recipients inherit the signing order defined on the template. The order is a routing level, not a strict rank: recipients sharing a level are notified at the same time, and a higher level is only notified once every recipient at all lower levels has completed. Recipients without an order are treated as level 0 (the first batch).

To change the order for a single session, pass signingOrder (integer, 0-100) on the recipient override at that position. Omitted positions keep the template order.

{
  "templateId": "{uuid}",
  "sendImmediately": true,
  "recipients": [
    { "name": "First Signer", "email": "[email protected]", "signingOrder": 1 },
    { "name": "Second Signer", "email": "[email protected]", "signingOrder": 2 }
  ]
}

Optional Recipients

A template recipient can be marked optional in the template editor. Optional recipients behave as follows when creating a session:

With sendImmediately: true, an optional recipient left without its required contact detail (email, or mobile for SMS recipients) is dropped from the session, along with its signing fields and any coupled witness or nominated recipients.
To drop an optional recipient that has contact details pre-set in the template, pass { "exclude": true } at its position in the recipients array. Explicit exclusion also works for drafts.
Passing exclude on a recipient the template does not mark optional returns a 400 with error code RECIPIENT_NOT_OPTIONAL.
If dropping or excluding recipients would leave the session with none, the request fails with a 400 and error code NO_RECIPIENTS_REMAIN.

Example - the template has three recipients where the second and third are optional; the second is excluded explicitly and the third is filled in:

{
  "templateId": "{uuid}",
  "sendImmediately": true,
  "recipients": [
    { "name": "First Signer", "email": "[email protected]" },
    { "exclude": true },
    { "name": "Second Director", "email": "[email protected]" }
  ]
}

Example (application/json):

{
  "templateId": "2bc7fc6a-2b90-44f4-9889-d8f7673f5f4f",
  "name": "api test multirecipient",
  "sendImmediately": true,
  "recipients": [
    {
      "name": "test1",
      "email": "{valid_email}"
    }
  ],
  "variableValues": {
    "client_name": "Jane Smith",
    "contract_date": "2025-01-15"
  },
  "tagIds": ["tag-uuid-1"],
  "expiryDays": 30,
  "reminderEnabled": true,
  "reminderFrequency": "weekly"
}

Example Request

curl --location 'https://api.airsign.com.au/api/v1/SessionFromTemplate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
    "templateId": "{uuid}",
    "name": "api test multirecipient",
    "sendImmediately": true,
    "recipients": [{
        "name": "test1",
        "email": "{valid_email}"
    }],
    "variableValues": {
        "client_name": "Jane Smith"
    },
    "expiryDays": 30,
    "reminderEnabled": true,
    "reminderFrequency": "weekly"
}'

Response

Status: 200 OK

{
    "name": "Api Test",
    "sessionId": "{uuid}",
    "status": "pending",
    "selfSignOnly": false,
    "expiryDays": 30,
    "expiryDate": "2025-08-01 16:19:36",
    "reminderEnabled": true,
    "reminderFrequency": "weekly",
    "senderProfileId": null,
    "overrideCompletionEmailRecipients": null,
    "overrideAttachPdf": null,
    "overrideAttachCertificate": null,
    "overrideCreateCombinedDoc": null,
    "overrideAttachCombinedDoc": null,
    "overrideCustomCompletionMessage": null,
    "createdAt": "2025-07-02 16:19:36",
    "completedDate": null,
    "updatedAt": "2025-07-02 16:19:36",
    "files": [
        {
            "fileId": "{uuid}",
            "fileName": "{file_name}.pdf",
            "fileType": "application/octet-stream",
            "namespace": "templateDocuments",
            "zones": [
                {
                    "id": "{uuid}",
                    "name": "signingZone3315",
                    "type": "signingZone",
                    "label": "Sign",
                    "page": 1,
                    "recipientId": "default",
                    "x": 29.17,
                    "y": 38.01,
                    "w": 100,
                    "h": 50
                }
            ],
            "sessionId": "{uuid}",
            "importedZones": true
        }
    ],
    "recipients": [
        {
            "recipientId": "default",
            "status": "pending",
            "name": "test1",
            "email": "{valid_email}"
        }
    ],
    "tagIds": []
}

Error Responses

Status	Description
`400`	Invalid request body, template not active, recipients mismatch, missing required variables, `exclude` on a non-optional recipient (`RECIPIENT_NOT_OPTIONAL`), or no recipients remaining after exclusions (`NO_RECIPIENTS_REMAIN`)
`401`	Missing or invalid authentication token
`403`	Your plan does not include the required feature for the provided session settings
`404`	Template not found