Signing Requests

Signing requests represent transactions submitted to the SignumEra signing service.

A signing request identifies the source document, recipients, signing sequence, ceremony configuration and required evidence level.

Creating a signing request requires the signing.create OAuth scope and a unique Idempotency-Key header.

Create a Signing Request

POST /api/v1/signing-requests

Required Scope

signing.create

Headers

Header Required Description
Authorization Yes OAuth Bearer access token.
Idempotency-Key Yes Unique identifier for this request. Maximum 255 characters.
Accept Recommended application/json
Content-Type Yes application/json

Request Fields

Field Required Description
external_reference Yes Your application's reference for the transaction. Maximum 191 characters.
transaction_type Yes Transaction classification. Maximum 100 characters.
document.upload_id Yes Identifier returned by the SignumEra upload API.
recipients Yes Array containing between 1 and 100 recipients.
recipients[].participant_type No signer or observer.
recipients[].is_internal No Boolean indicating an internal participant.
recipients[].role Yes Participant role. Maximum 100 characters.
recipients[].name Yes Participant name.
recipients[].email Yes Valid participant email address.
recipients[].signing_order No Integer starting at 1.
signing.enforce_order No Boolean controlling whether signing order is enforced.
signing.owner.must_sign No Boolean indicating whether the owner participates as a signer.
signing.owner.signing_order No Owner signing order. Minimum value 1.
ceremony.mode Yes Ceremony mode. Maximum 64 characters.
ceremony.meeting_provider Yes Meeting provider identifier. Maximum 64 characters.
evidence_level Yes Evidence level identifier. Maximum 64 characters.
locale No Locale identifier. Maximum 35 characters.

Example Request

curl -X POST \
  "https://api.signumera.com/api/v1/signing-requests" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY" \
  -d '{
    "external_reference": "contract-2026-001",
    "transaction_type": "agreement",
    "document": {
        "upload_id": "YOUR_UPLOAD_ID"
    },
    "recipients": [
        {
            "participant_type": "signer",
            "is_internal": false,
            "role": "Signer",
            "name": "Jane Smith",
            "email": "jane@example.com",
            "signing_order": 1
        }
    ],
    "signing": {
        "enforce_order": true,
        "owner": {
            "must_sign": false
        }
    },
    "ceremony": {
        "mode": "YOUR_CEREMONY_MODE",
        "meeting_provider": "YOUR_MEETING_PROVIDER"
    },
    "evidence_level": "YOUR_EVIDENCE_LEVEL",
    "locale": "en-CA"
  }'

Idempotency

The Idempotency-Key prevents accidental duplicate creation when an application retries a request.

Repeating the same request with the same key may return the existing signing request. Reusing the key with a different payload returns HTTP 409 Conflict. 

{
    "error": {
        "code": "idempotency_key_reused",
        "message": "This Idempotency-Key was already used with a different request payload."
    }
}

Get Signing Request Status

GET /api/v1/signing-requests/{id}

Required Scope

signing.read

Example

curl \
  "https://api.signumera.com/api/v1/signing-requests/REQUEST_ID" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

{
    "id": "REQUEST_ID",
    "external_reference": "contract-2026-001",
    "transaction_type": "agreement",
    "submission_status": "accepted",
    "status": "unknown",
    "document": {
        "status": null
    },
    "evidence": {
        "ready": false
    },
    "created_at": "2026-10-03T14:00:00Z",
    "updated_at": "2026-10-03T14:00:00Z",
    "prepared_at": null,
    "opened_at": null,
    "finalized_at": null
}

Status data is retrieved from the SignumEra signing service. If the signing service cannot be reached, the API returns HTTP 503.

Add a Participant

POST /api/v1/signing-requests/{id}/participants

Required Scope

ceremony.create

Additional participants may be added after the signing request has been accepted and while the current ceremony state permits modification.

Request Fields

Field Required Description
participant_type Yes signer or observer.
is_internal No Defaults to false.
role Yes Participant role.
name Yes Participant name.
email Yes Valid email address.
signing_order No Integer starting at 1.

Example

curl -X POST \
  "https://api.signumera.com/api/v1/signing-requests/REQUEST_ID/participants" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "participant_type": "signer",
    "is_internal": false,
    "role": "Signer",
    "name": "John Smith",
    "email": "john@example.com",
    "signing_order": 2
  }'

Prepare the Signing Request

POST /api/v1/signing-requests/{id}/prepare

Required Scope

ceremony.create

Prepares the signing request and document for the signing ceremony.

Create a Widget Session

POST /api/v1/signing-requests/{id}/widget-session

Required Scope

ceremony.create

Creates a session used to launch the SignumEra signing experience for an accepted signing request.

Cancel a Signing Request

POST /api/v1/signing-requests/{id}/cancel

Required Scope

signing.cancel

Cancels a signing request when its current signing state still permits cancellation.

Common Errors

HTTP Code Description
422 invalid_idempotency_key Missing or invalid Idempotency-Key.
409 idempotency_key_reused The key was already used with a different payload.
404 signing_request_not_found The requested signing request was not found.
409 signing_request_not_ready The signing request is not in the required state.
403 participant_forbidden The client cannot modify the signing request.
409 participant_conflict Ceremony state or signing sequence prevents the participant from being added.
503 upstream_unavailable The SignumEra signing service is temporarily unavailable.