Quick Start

This guide shows the basic SignumEra API flow from authentication through launching a signing ceremony.

1. Obtain an OAuth Access Token

curl -X POST \
  "https://api.signumera.com/oauth/token" \
  -H "Accept: application/json" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Save the returned access_token.

2. Upload the PDF

curl -X POST \
  "https://api.signumera.com/api/v1/uploads" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/pdf" \
  -H "X-Filename: agreement.pdf" \
  --data-binary "@agreement.pdf"

The response contains the temporary upload_id.

{
    "upload_id": "upl_EXAMPLE",
    "filename": "agreement.pdf",
    "sha256": "DOCUMENT_SHA256",
    "size_bytes": 245760,
    "expires_in_hours": 24
}

3. Create the Signing Request

Supply a unique Idempotency-Key for each new signing request.

curl -X POST \
  "https://api.signumera.com/api/v1/signing-requests" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: contract-2026-001" \
  -d '{
    "external_reference": "contract-2026-001",
    "transaction_type": "agreement",

    "document": {
        "upload_id": "upl_EXAMPLE"
    },

    "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"
  }'

Response

{
    "id": "REQUEST_ID",
    "external_reference": "contract-2026-001",
    "transaction_type": "agreement",
    "submission_status": "accepted",
    "idempotent_replay": false
}

4. Prepare the Signing Request

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

Response

{
    "id": "REQUEST_ID",
    "status": "prepared",
    "document": {
        "revision": 1,
        "sha256": "DOCUMENT_SHA256"
    }
}

5. Create a Widget Session

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

Response

{
    "id": "REQUEST_ID",
    "widget_url": "https://...",
    "expires_in_seconds": 900
}

Open the returned widget_url to launch the SignumEra signing experience.

6. Monitor Status

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

Continue checking status until the signing request reaches its final state.

{
    "id": "REQUEST_ID",
    "submission_status": "accepted",
    "status": "completed",

    "document": {
        "status": "finalized"
    },

    "evidence": {
        "ready": true
    },

    "prepared_at": "2026-10-03T14:30:00Z",
    "opened_at": "2026-10-03T14:31:00Z",
    "finalized_at": "2026-10-03T14:42:00Z"
}

Required OAuth Scopes