Create Session

Create a signing session from scratch - no template or PDF required. Documents are written in the block document format; AirSign handles layout and signature field placement. By default the session is created as a draft and the response includes a draftUrl that opens the session in the AirSign editor for review before sending. Set sendImmediately: true to skip review and email the signing invitations straight away. Previously uploaded PDFs (see Upload File) can be attached as additional reference documents.

Endpoint

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

Headers

Name	Value	Required	Description
Content-Type	application/json	Yes	Specifies the format of the request body
Authorization	Bearer {access_token}	Yes	Bearer token with the `write:sessions` scope

Request Body

Parameter	Type	Required	Description
name	string	Yes	Session name (1-50 characters)
files	array	Yes	1-10 file entries. Each is either `{ "type": "blocks", "document": {...} }` (a block document) or `{ "type": "uploadedPdf", "fileId": "...", "fileName": "..." }` (a previously uploaded PDF, see Uploaded PDF entries). Any mix works: block documents carry `field` / `fieldRow` / `signatureBlock` blocks; uploaded PDFs get their own form fields imported plus any `fields` you add. Every signer should end up with a signature field somewhere - the response's `warnings` tell you if not
recipients	array	Yes	1-20 recipients, each with `key`, `name`, `email` and optional `signingOrder`. Keys are referenced by `signatureBlock` blocks in the documents
sendImmediately	boolean	No	Whether to email signing invitations now or leave the session in draft for review. Defaults to `false`
expiryDays	number	No	Days before the session expires (1-730). Requires the Session Expiry plan feature
reminderEnabled	boolean	No	Whether to send automatic reminders. Requires the Session Expiry plan feature
reminderFrequency	string	No	`daily`, `weekly`, `monthly`, or `quarterly`. Requires the Session Expiry plan feature

Uploaded PDF Entries

An uploadedPdf entry references a file from Upload File. The PDF's own form fields (text boxes, checkboxes, radio buttons, dropdowns, empty signature fields) are imported as AirSign fields, and fields the PDF lacks - typically the signature - are placed with fields, anchored to text printed in the PDF or by page coordinates. Both can be combined.

Field	Type	Description
fileId	string	Required. The uploaded file
fileName	string	Display name; defaults to the uploaded name
importFields	boolean	Import the PDF's own form fields. Default `true`
recipient	string	Recipient key who fills the imported fields. Defaults to the first recipient
importedFields	object	Per-field tweaks keyed by the PDF field name from the upload response: `{ "recipient", "required", "exclude" }`
fields	array	Fields to add (max 100) - see below

Each entry in fields takes the same fieldType, label, recipient, name, required, placeholder, options and dateFormat as block-document fields, plus three signing types: signature, dateSigned and signerName. Position it in one of two ways:

Placement	Fields	Description
By anchor	`anchor`, `placement` (right / below / above / left / over, default right), `anchorOccurrence`, `offsetX`, `offsetY`	Finds `anchor` in the PDF text (case-insensitive) and places the field relative to it - e.g. a signature `below` "Parent signature:". Fields are kept on the page
Absolute	`page`, `x`, `y`	PDF points from the top-left corner of the page (A4 is 595 x 842). Out-of-page fields are rejected
Size	`w`, `h`	Defaults match the editor toolbox: signature 100 x 50, text 200 x 15, checkbox/radio 12 x 12, initials 60 x 40
Choice groups	`optionSpacing` (default 60), `optionDirection` (row / column)	A radio or checkbox field with `options` places one box per option from the resolved position; the PDF is expected to print the captions

Field names must be unique within a file (imported names count). Validation issues - anchor-not-found, page-out-of-range, zone-out-of-bounds, duplicate-field-name, unknown-recipient - come back as DOCUMENT_VALIDATION_FAILED with the same issue list as block documents. The response includes warnings when a recipient ends up without a signature field.

Example Request

curl --location 'https://api.airsign.com.au/api/v1/Session' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
    "name": "NDA - Acme Pty Ltd",
    "sendImmediately": false,
    "files": [{
        "type": "blocks",
        "document": {
            "format": "blocks",
            "title": "Mutual NDA",
            "blocks": [
                { "type": "heading", "text": "1. Purpose" },
                { "type": "paragraph", "text": "The parties wish to exchange confidential information." },
                { "type": "spacer", "height": 24 },
                { "type": "signatureBlock", "recipient": "partyA", "label": "Party A" },
                { "type": "signatureBlock", "recipient": "partyB", "label": "Party B" }
            ]
        }
    }],
    "recipients": [
        { "key": "partyA", "name": "Ada Lovelace", "email": "{valid_email}" },
        { "key": "partyB", "name": "Charles Babbage", "email": "{valid_email_2}" }
    ]
}'

Response

Status: 200 OK. For drafts, draftUrl opens the session in the AirSign editor so the document can be verified (and tweaked) before sending - send it later with Send Session.

{
    "name": "NDA - Acme Pty Ltd",
    "sessionId": "{uuid}",
    "status": "draft",
    "selfSignOnly": false,
    "createdAt": "2026-06-12 10:15:00",
    "updatedAt": "2026-06-12 10:15:00",
    "files": [
        {
            "fileId": null,
            "fileName": "Mutual NDA.pdf",
            "zones": [ ... ],
            "sessionId": "{uuid}"
        }
    ],
    "recipients": [
        { "recipientId": "{uuid}", "status": "draft", "name": "Ada Lovelace", "email": "{valid_email}", "signingOrder": 1 },
        { "recipientId": "{uuid}", "status": "draft", "name": "Charles Babbage", "email": "{valid_email_2}", "signingOrder": 2 }
    ],
    "draftUrl": "https://app.airsign.com.au/authenticated/main/sessions/session/{uuid}",
    "sent": false
}

Error Responses

Status	Description
`400`	Invalid request body, or the document failed layout validation (`DOCUMENT_VALIDATION_FAILED` with a structured `issues` list - see the format reference)
`401`	Missing or invalid authentication token
`403`	Session limit reached for your plan (`SESSION_LIMIT_REACHED`), or a setting requires a plan feature (`PLAN_FEATURE_REQUIRED`)
`404`	A referenced uploaded file was not found (`FILE_NOT_FOUND`)