Ceremonies

After a signing request has been accepted, the ceremony API allows your application to add participants, prepare the document, and create a SignumEra widget session.

Ceremony operations require the ceremony.create OAuth scope.

Typical Ceremony Flow

  1. Create the signing request.
  2. Add any additional participants.
  3. Prepare the signing request.
  4. Create a widget session.
  5. Open the returned widget URL.
  6. Monitor the signing request for completion.

Add a Participant

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

Required Scope

ceremony.create

Request

{
    "participant_type": "signer",
    "is_internal": false,
    "role": "Signer",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "signing_order": 2
}
Field Required Description
participant_type Yes signer or observer.
is_internal No Boolean. Defaults to false.
role Yes Maximum 100 characters.
name Yes Maximum 255 characters.
email Yes Valid email address.
signing_order No Integer greater than or equal to 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": "Jane Smith",
    "email": "jane@example.com",
    "signing_order": 2
  }'

201 Response

{
    "id": "REQUEST_ID",
    "participant": {
        "participant_id": "PARTICIPANT_ID",
        "participant_type": "signer",
        "is_internal": false,
        "role": "Signer",
        "name": "Jane Smith",
        "email": "jane@example.com",
        "signing_order": 2
    }
}

Prepare the Ceremony

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

Required Scope

ceremony.create

Preparation finalizes the document state required to launch the ceremony.

This endpoint does not require a JSON request body.

Example

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

Success Response

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

The returned SHA-256 value identifies the prepared document content used by the ceremony.

Create a Widget Session

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

Required Scope

ceremony.create

After preparation, create a widget session to launch the SignumEra signing interface.

This endpoint does not require a JSON request body.

Example

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

Success Response

{
    "id": "REQUEST_ID",
    "widget_url": "https://...",
    "expires_in_seconds": 900
}
Widget URLs are temporary. Your application should use the value of expires_in_seconds rather than assuming a fixed lifetime.

Monitor the Ceremony

Use the signing-request status endpoint to monitor the ceremony:

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

The response can include: 

{
    "submission_status": "accepted",
    "status": "in_progress",
    "document": {
        "status": "prepared"
    },
    "evidence": {
        "ready": false
    },
    "prepared_at": "2026-10-03T14:30:00Z",
    "opened_at": "2026-10-03T14:31:00Z",
    "finalized_at": null
}

Ceremony Errors

HTTP Code Description
404 signing_request_not_found The signing request does not exist or is not available to the current application.
409 signing_request_not_ready The signing request has not reached the state required for the operation.
403 participant_forbidden The client cannot modify this signing request.
409 participant_conflict The participant conflicts with the ceremony state or signing sequence.
422 invalid_participant_request The participant request is invalid.
403 prepare_forbidden The client cannot prepare this signing request.
409 prepare_conflict The signing request cannot be prepared in its current state.
422 invalid_prepare_request The preparation request is invalid.
403 widget_session_forbidden The client is not authorized to launch this signing request.
409 widget_session_conflict A widget session cannot be created in the current signing state.
422 invalid_widget_session_request The widget launch request is invalid.
503 upstream_unavailable The SignumEra signing service is temporarily unavailable.