← Back to Adapters

Signing

Document signing lifecycle — upload documents, create signing orders, poll status, and download signed documents

Signing Adapter

Provider-agnostic signing adapter API for managing the full document signing lifecycle. The adapter maps this payload to the underlying signing provider (e.g., Signicat, Scrive).

Endpoints:

  • POST /sign/upload — Upload document
  • POST /sign/order — Create signing order
  • POST /sign/status — Get signing status
  • POST /sign/document/download — Download signed document

Signing lifecycle:

  1. Upload each PDF to signing provider
  2. Create signing order with signatories and documents
  3. Signatories visit signing URLs
  4. Poll/callback for completion
  5. Download signed documents
  6. Store signed documents in file storage

1. Upload Document

POST /sign/upload — Upload a PDF to the signing provider's document store.

Called once per document that needs to be signed. The handler iterates over generatedDocuments in a document package and uploads each one.

Request: Raw PDF binary (application/pdf)

Response:

  • documentId — Provider-assigned document reference, used as documentRef when creating a signing order

2. Create Order

POST /sign/order — Create a signing order with signatories and documents.

Called once per document package during the signing sub-process, after all documents have been uploaded. The adapter maps the provider-agnostic payload to the underlying provider's format.

Request body — SigningOrder:

  • signatories (required): One per person who needs to sign
    • id: UUID (generated by handler, echoed in response)
    • nationalId: National identity number (NIN / personnummer)
    • firstName, lastName: Signatory name (optional)
    • language: NB, SV, or EN
    • authenticationMethod: NO_BANKID or SE_BANKID
  • documents (required): Documents to be signed
    • id: UUID (generated by handler)
    • documentRef: Provider reference from upload step
    • description: e.g., ACCEPTANCE_LETTER
    • action: SIGN or VIEW
  • callbackUrl (required): URL called when signing completes, typically {API_URL}/api/sign/{flowId}/callback
  • redirectUrl (required): Where to redirect signatories after signing
  • packaging (optional): How to package signed documents (e.g., PAdES). Some providers handle this internally.
  • options (optional): Title, duration in days

Response:

  • orderId — Provider-assigned order identifier
  • signatories[] — Each with id, signingUrl, and initial status

3. Get Signing Status

POST /sign/status — Retrieve the current status of a signing order or signatory.

Request body:

  • orderId (required): Signing order identifier from create order response
  • signatoryId (optional): When provided, returns status for that specific signatory. Otherwise returns the overall order status.

Response:

  • orderId — Signing order identifier
  • signatoryId — Present when queried per signatory
  • status — Current signing status
  • updatedAt — Timestamp of last status change

Possible statuses:

  • CREATED — Order/task created, signatory has not started
  • STARTED — Signatory has opened the signing URL
  • COMPLETED — Signing completed successfully
  • REJECTED — Signatory rejected the signing
  • EXPIRED — Signing order/task expired
  • CANCELLED — Order/task was cancelled

4. Download Signed Document

POST /sign/document/download — Retrieve a signed document.

Called after signing is completed. The adapter resolves how to fetch the signed document from the provider based on the orderId and documentId.

Request body:

  • orderId (required): Signing order identifier
  • documentId (required): Document identifier from the signing order documents array

Response:

  • filename — Suggested filename for the signed document
  • mimeType — MIME type (typically application/pdf)
  • content — Base64-encoded signed document

Error cases:

  • 404 — Order or document not found at the provider
  • 409 — Signing not yet completed