Signing - API only (v1)

Stable / GA

This is the current stable version of this step type.

Executes document signing without any user interaction

Used when you need to sign or seal documents instantly without requiring user interaction. Headless Signing is a strictly backend operation that integrates with the Sphinx credential system to issue either Advanced Electronic Signatures (AES) for natural persons or Qualified Electronic Seals (QSEAL) for legal entities. The signing process runs entirely server-side: it initiates the signing request, polls for the result, and finalizes the operation — making it ideal for automated workflows and backend-driven processes.

---

Key features

• Strictly headless: No UI, no user interaction required; executes purely server-side
• Two signing modes: Supports AES (Advanced Electronic Signature for individuals) and QSEAL (Qualified Electronic Seal for organisations)
• Sphinx credentials: Uses the same credential system as Signing (v1) for issuing signatures
• Async polling: Initiates the signing request, polls for completion, and finalizes the result in a Temporal workflow
• Automatic signature issuance: Instantly signs documents using available identity or entity data

---

Configuration

Option	Type	Required	Description
mode	string	Yes	Signing mode: AES (Advanced Electronic Signature for natural persons) or QSEAL (Qualified Electronic Seal for legal entities). Accepted values: AES, QSEAL.
config	object	Yes	Environment-specific configuration for the InstantSign provider.
config.live.shortname	string	Yes	The InstantSign provider shortname for the environment (live or staging). Provided by IDnow during onboarding. (live)
config.staging.shortname	string	Yes	The InstantSign provider shortname for the environment (live or staging). Provided by IDnow during onboarding. (staging)

Example configuration

AES — Sign documents with individual identity

{
  "mode": "AES",
  "config": {
    "live": {
      "shortname": "my-sphinx-live"
    },
    "staging": {
      "shortname": "my-sphinx-staging"
    }
  }
}

QSEAL — Seal documents with entity credential

{
  "mode": "QSEAL",
  "config": {
    "live": {
      "shortname": "my-sphinx-live"
    },
    "staging": {
      "shortname": "my-sphinx-staging"
    }
  }
}

---

---

Signing modes

AES (Advanced Electronic Signature)

Used for signing documents on behalf of natural persons. Requires verified identity information.

Input requirements:

• DocumentsToSign — The documents to be signed
• BasicIdentity — The signer's identity data (given name, family name)

Credential binding: The signature is linked to the individual's verified identity from the BasicIdentity data block.

QSEAL (Qualified Electronic Seal)

Used for sealing documents on behalf of legal entities. Does not require individual identity information — the seal is bound to the entity's credential.

Input requirements:

• DocumentsToSign — The documents to be sealed

Credential binding: The seal is bound to the organisation's entity credential, not an individual.

---

Input data blocks

Data block	Required	Description
DocumentsToSign	Yes	The documents to be signed or sealed. References uploaded documents via vault URIs.
BasicIdentity	Conditional	The signer's identity information (given name, family name). Present unless mode is QSEAL.

File size limit

Each file referenced in DocumentsToSign must not exceed 25 MB. Exceeding this limit returns HTTP 422 with error code FILE_TOO_LARGE at session creation.

---

Routes

Route	Description
success	The document was signed or sealed successfully. The SignedDocumentsPackage contains the signature process ID and vault references to the signed or sealed documents.

---

Output data blocks

Route	Data blocks produced
success	SignedDocumentsPackage

SignedDocumentsPackage — success

Field	Type	Description
signatureProcessId	string	Identifier of the signature process (transaction number) for audit and tracking.
signedDocuments.mode	string	Delivery mode: archive, items, or both.
signedDocuments.archive	object	Vault reference to the ZIP archive containing signed documents (when applicable).
signedDocuments.documents	array	Individual signed document references with their vault URIs.
signedDocuments.documents[].templateId	string	Identifier for the template used for the electronic signature.
signedDocuments.documents[].signed	object	Vault reference to the signed PDF file.
createdAt	string	ISO 8601 timestamp of when the signed documents package was created.

Example payloads

SignedDocumentsPackage — success

{
  "signatureProcessId": "txn-4a7b2c9e-f831-4d6a-b205-1e3c8d0fa912",
  "signedDocuments": {
    "mode": "both",
    "archive": {
      "$ref": "vault",
      "$id": "01900000-c4d8-7e5f-9a2b-6d3f8c1e4b07"
    },
    "documents": [
      {
        "templateId": "contract-template-v2",
        "signed": {
          "$ref": "vault",
          "$id": "01900000-d9a3-4f6c-8b1e-7a2d5c9f3e84"
        }
      }
    ]
  },
  "createdAt": "2026-02-10T14:00:01.000Z"
}

---