Signature Signer

Server

Endpoints for managing signers on a signature request.

Add an individual signer

POST

https://api.skribble.com/v3

/signature-requests/{SR_ID}/signatures

Adds an individual signer to the SignatureRequest with the ID SR_ID. Use account_email to invite a signer with an existing Skribble account, or signer_identity_data to invite a No-Account-Signer (NAS).

Good to know We recommend combining signer_identity_data and account_email when you are unsure whether the user has a Skribble account. If a matching account exists, the user will find the SignatureRequest in the To sign section of their account on my.skribble.com.

If you invite them using only signer_identity_data, the document will not appear in their Skribble account even if one exists — they will need to access it via the link in their invitation email.

Add an individual signer › path Parameters

SR_ID

string · uuid · required

Unique ID received when creating the Signature Request object

Add an individual signer › Request Body

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object
	type = object · requires: signer_group_id

Properties for User Signer:

sequence

number · int32

Optional signer sequence.

Default: -1

notify

boolean

Whether to send a notification to this signer.

Default: true

SignatureDocument[]

Visual signatures to place on the document.

account_email

string · email

Optional signer account email address.

SignerIdentityData

Optional (no-account) signer identity information.

Add an individual signer › Responses

SignatureResponse_v3

id

string · uuid

title

string

message

string

DocumentInSignatureResponse[]

legislation

SignatureLegislation · enum

Legislation under which the signatures are created. Required when quality is QES or AES_MINIMAL.

Legislation	Description
ZERTES	QES according to Swiss law. This is the default.
EIDAS	QES according to EU law.

Enum values:

ZERTES

EIDAS

quality

SignatureQuality · enum

Minimal quality of the signatures for this signature request.

Quality	Description
QES	Every signer must use QES. This is the default quality. Requires a `legislation` parameter.
AES	Signers will use AES if available, otherwise fall back to QES.
AES_MINIMAL	Signers will use QES if available, otherwise AES. At least AES is guaranteed. Requires a `legislation` parameter.
SES	Every signer uses SES.
DEMO	Every signer uses a DEMO signature with no legal binding. API demo users (`api_demo_example_*`) get this quality by default.
PART11	Signers use a signature compliant with 21 CFR Part 11 regulations.

Enum values:

SES

AES

AES_MINIMAL

QES

DEMO

PART11

signing_url

string · uri

The URL for the SignatureRequest owner to view and manage the request in the Skribble web application. This URL is not intended for signers — each signer has their own dedicated signing_url within the signatures array.

status_overall

SignatureStatusOverall_v3 · enum

Overall signing status of the document.

Possible values:

DRAFT The signature request has not yet been placed.
OPEN At least one user has not signed or declined their signature yet.
DECLINED At least one user declined to sign. The signature request failed.
WITHDRAWN The owner has withdrawn the signature request.
SIGNED All users signed the document. The signature request was successfully completed.
EXPIRED The owner-set expires_at date has passed before all signers signed. Terminal status.
ERROR A technical error occurred. The signature request cannot be completed.

Enum values:

DRAFT

OPEN

DECLINED

WITHDRAWN

SIGNED

EXPIRED

ERROR

business_id

string

SignatureRecipientResponse_v3[]

origin

string

SignatureObserverResponse[]

auto_delete_at

string · date

Server-managed date on which this signature request and its related documents are automatically deleted in line with the owning business's retention policy. Not directly settable by API clients. May be absent or null when no retention policy applies.

expires_at

string · date

Owner-set expiry date for this signature request. When this date passes, the request transitions to status_overall=EXPIRED. Set via expires_at on create/update; clear via DELETE /signature-requests/{SR_ID}/expires-at. Absent or null when no owner-set expiry has been configured.

SignatureAttachment[]

attach_on_success

string[]

When a SignatureRequest has been signed by all signers, all signers and all observers are notified by email. Skribble provides the option to attach two types of attachments automatically to this email:

the signed document and
the signature protocol.

This can be configured via the business settings, which can be used to define that these documents should generally be attached for all SignatureRequests created by business members.

Alternatively it is possible to define the attachments on demand per SignatureRequest by using this field.

Enum values:

SIGNED_DOCUMENT

SIGNATURE_PROTOCOL

custom

string

Custom field for storing application-specific data related to this signature request.

owner

string

read_access

string[]

Users or API keys with read access to this signature request.

write_access

string[]

Users or API keys with write access to this signature request.

created_at

string · date-time

updated_at

string · date-time

initiated_at

string · date-time

callback_success_url

string · uri

Callback URL called on overall success. See the request schema for supported placeholders and retry behaviour.

callback_error_url

string · uri

Callback URL called when a signer declines or the request is withdrawn. See the request schema for supported placeholders and retry behaviour.

callback_update_url

string · uri

Callback URL called on any update (e.g. one signer signed). See the request schema for supported placeholders and retry behaviour.

callback_start_sign_url

string · uri

Callback URL called when a signer starts the signature process (only for xQES). See the request schema for supported placeholders and retry behaviour.

callback_ident_pending_url

string · uri

Callback URL called when the identification of a signer requires manual review. See the request schema for supported placeholders and retry behaviour.

callback_ident_error_url

string · uri

Callback URL called when the identification of a signer ends in an error. See the request schema for supported placeholders and retry behaviour.

POST/signature-requests/{SR_ID}/signatures

curl https://api.skribble.com/v3/signature-requests/:SR_ID/signatures \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "account_email": "single-signer@skribble.com",
  "signer_identity_data": {
    "email_address": "single-signer@skribble.com"
  },
  "document_signatures": [
    {
      "document_id": "3648f61d-4194-455c-a0bc-1c438d2cd11b"
    }
  ]
}'

Example Request Body

{
  "account_email": "single-signer@skribble.com",
  "signer_identity_data": {
    "email_address": "single-signer@skribble.com"
  },
  "document_signatures": [
    {
      "document_id": "3648f61d-4194-455c-a0bc-1c438d2cd11b"
    }
  ]
}

json

application/json

Example Responses

{
  "id": "4f43614a-de50-bfe1-2df3-4c881fc7840e",
  "title": "Example contract",
  "message": "Please sign this document!",
  "documents": [
    {
      "id": "f1e2d3c4-7b8a-4e6f-9d3b-123456789abc",
      "name": "Filename1.pdf",
      "version_id": "a84f5085-67e5-e106-71c7-69b3d4b7c632"
    }
  ],
  "legislation": "ZERTES",
  "quality": "QES",
  "signing_url": "https://my.skribble.com/view/4f43614a-de50-bfe1-2df3-4c881fc7840e",
  "status_overall": "OPEN",
  "business_id": "biz-42b4c2fb9ee947778ba70bc0698c78f7",
  "signatures": [
    {
      "sid": "894a0240-e01a-2307-4376-0267c6a8d105",
      "account_email": "you@example.info",
      "document_signatures": [
        {
          "document_id": "f1e2d3c4-7b8a-4e6f-9d3b-123456789abc",
          "visual_signature": {
            "positions": [
              {
                "page": "0",
                "height": 70,
                "width": 150,
                "x": 350,
                "y": 240,
                "rotation": 0
              }
            ],
            "image": {
              "content": "SGVsbG8gd29ybGQh",
              "content_type": "image/png",
              "content_size": 3160
            },
            "position": {},
            "form_field": {}
          }
        }
      ],
      "signer_identity_data": {
        "email_address": "nas@example.com",
        "first_name": "John",
        "last_name": "Doe",
        "mobile_number": "41791234567",
        "language": "en",
        "identity_reference": "Internal-ID-012345",
        "identification_require_evidence": true,
        "provider": "swisscom_ra_app",
        "evidence_id": "700580648"
      },
      "sequence": -1,
      "status_code": "SIGNED",
      "notify": true,
      "signing_url": "https://my.skribble.com/view/4f43614a-de50-bfe1-2df3-4c881fc7840e/cd16bd0802d146fd94ff736d7d7bf551",
      "decline_message": "decline_message",
      "signed_at": "2025-10-09T12:15:30.000Z",
      "signed_legislation": "ZERTES",
      "signed_quality": "QES",
      "last_viewed_at": "2025-10-09T12:10:00.000Z",
      "language": "en",
      "invited_by": "api_demo_example"
    }
  ],
  "origin": "API",
  "observers": [],
  "auto_delete_at": "2026-04-21",
  "expires_at": "2026-12-31",
  "attachments": [],
  "attach_on_success": [
    "SIGNED_DOCUMENT",
    "SIGNATURE_PROTOCOL"
  ],
  "custom": "MyCustomvalue1,MyVal2",
  "owner": "api_demo_example",
  "read_access": [
    "persononetosign@external.net",
    "api_demo_example",
    "you@example.info",
    "persontwotosign@external.net"
  ],
  "write_access": [
    "api_demo_example"
  ],
  "created_at": "2025-10-08T17:37:03.569Z",
  "updated_at": "2025-10-08T17:37:03.569Z",
  "initiated_at": "2025-10-08T17:37:03.569Z",
  "callback_success_url": "https://mybiz.com/call/success",
  "callback_error_url": "https://mybiz.com/call/error",
  "callback_update_url": "https://mybiz.com/call/update",
  "callback_start_sign_url": "https://mybiz.com/call/start-sign",
  "callback_ident_pending_url": "https://mybiz.com/call/ident-pending",
  "callback_ident_error_url": "https://mybiz.com/call/ident-error"
}

json

application/json

Remove an individual signer

DELETE

https://api.skribble.com/v3

/signature-requests/{SR_ID}/signatures/{SID}

Removes an individual signer from the SignatureRequest. Provide the SignatureRequest ID SR_ID and the Signature ID SID of the signer to remove.

Remove an individual signer › path Parameters

SR_ID

string · uuid · required

Unique ID received when creating the Signature Request object

SID

string · uuid · required

Unique ID of the signer

Remove an individual signer › Responses

No data returned

Signature Signature Observer

Add an individual signer

POST

https://api.skribble.com/v3

/signature-requests/{SR_ID}/signatures

Good to know We recommend combining signer_identity_data and account_email when you are unsure whether the user has a Skribble account. If a matching account exists, the user will find the SignatureRequest in the To sign section of their account on my.skribble.com.

If you invite them using only signer_identity_data, the document will not appear in their Skribble account even if one exists — they will need to access it via the link in their invitation email.

Add an individual signer › path Parameters

SR_ID

string · uuid · required

Unique ID received when creating the Signature Request object

Add an individual signer › Request Body

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object
	type = object · requires: signer_group_id

Properties for User Signer:

sequence

number · int32

Optional signer sequence.

Default: -1

notify

boolean

Whether to send a notification to this signer.

Default: true

SignatureDocument[]

Visual signatures to place on the document.

account_email

string · email

Optional signer account email address.

SignerIdentityData

Optional (no-account) signer identity information.

Add an individual signer › Responses

SignatureResponse_v3

id

string · uuid

title

string

message

string

DocumentInSignatureResponse[]

legislation

SignatureLegislation · enum

Legislation under which the signatures are created. Required when quality is QES or AES_MINIMAL.

Legislation	Description
ZERTES	QES according to Swiss law. This is the default.
EIDAS	QES according to EU law.

Enum values:

ZERTES

EIDAS

quality

SignatureQuality · enum

Minimal quality of the signatures for this signature request.

Quality	Description
QES	Every signer must use QES. This is the default quality. Requires a `legislation` parameter.
AES	Signers will use AES if available, otherwise fall back to QES.
AES_MINIMAL	Signers will use QES if available, otherwise AES. At least AES is guaranteed. Requires a `legislation` parameter.
SES	Every signer uses SES.
DEMO	Every signer uses a DEMO signature with no legal binding. API demo users (`api_demo_example_*`) get this quality by default.
PART11	Signers use a signature compliant with 21 CFR Part 11 regulations.

Enum values:

SES

AES

AES_MINIMAL

QES

DEMO

PART11

signing_url

string · uri

status_overall

SignatureStatusOverall_v3 · enum

Overall signing status of the document.

Possible values:

DRAFT The signature request has not yet been placed.
OPEN At least one user has not signed or declined their signature yet.
DECLINED At least one user declined to sign. The signature request failed.
WITHDRAWN The owner has withdrawn the signature request.
SIGNED All users signed the document. The signature request was successfully completed.
EXPIRED The owner-set expires_at date has passed before all signers signed. Terminal status.
ERROR A technical error occurred. The signature request cannot be completed.

Enum values:

DRAFT

OPEN

DECLINED

WITHDRAWN

SIGNED

EXPIRED

ERROR

business_id

string

SignatureRecipientResponse_v3[]

origin

string

SignatureObserverResponse[]

auto_delete_at

string · date

expires_at

string · date

SignatureAttachment[]

attach_on_success

string[]

the signed document and
the signature protocol.

This can be configured via the business settings, which can be used to define that these documents should generally be attached for all SignatureRequests created by business members.

Alternatively it is possible to define the attachments on demand per SignatureRequest by using this field.

Enum values:

SIGNED_DOCUMENT

SIGNATURE_PROTOCOL

custom

string

Custom field for storing application-specific data related to this signature request.

owner

string

read_access

string[]

Users or API keys with read access to this signature request.

write_access

string[]

Users or API keys with write access to this signature request.

created_at

string · date-time

updated_at

string · date-time

initiated_at

string · date-time

callback_success_url

string · uri

Callback URL called on overall success. See the request schema for supported placeholders and retry behaviour.

callback_error_url

string · uri

Callback URL called when a signer declines or the request is withdrawn. See the request schema for supported placeholders and retry behaviour.

callback_update_url

string · uri

Callback URL called on any update (e.g. one signer signed). See the request schema for supported placeholders and retry behaviour.

callback_start_sign_url

string · uri

Callback URL called when a signer starts the signature process (only for xQES). See the request schema for supported placeholders and retry behaviour.

callback_ident_pending_url

string · uri

Callback URL called when the identification of a signer requires manual review. See the request schema for supported placeholders and retry behaviour.

callback_ident_error_url

string · uri

Callback URL called when the identification of a signer ends in an error. See the request schema for supported placeholders and retry behaviour.

Remove an individual signer

DELETE

https://api.skribble.com/v3

/signature-requests/{SR_ID}/signatures/{SID}

Removes an individual signer from the SignatureRequest. Provide the SignatureRequest ID SR_ID and the Signature ID SID of the signer to remove.

Remove an individual signer › path Parameters

SR_ID

string · uuid · required

Unique ID received when creating the Signature Request object

SID

string · uuid · required

Unique ID of the signer

Remove an individual signer › Responses

No data returned