Signature Signer

Server

Endpoints for managing signers on a signature request.

Add an individual signer

POST

https://api.skribble.com/v2

/signature-requests/{SR_ID}/signatures

To add an individual signer, use the same parameters as when creating a SignatureRequest. The process is the same. By using account_email, you can add a signer who has a Skribble account. By using signer_identity_data, you can invite a No-Account-Signer to the SignatureRequest with the ID {{SR_ID}}.

💡 Good to know

We recommend this approach of combining signer_idendity_data and account_email if you are unsure whether the user has a Skribble account. The benefit is that an existing Skribble user will afterwards find the SignatureRequest in the To sign section of their account on my.skribble.com.

Conversely, if you invite them using only signer_identity_data, the document will not appear in their Skribble account, even if they have an existing Skribble account. Instead, they will have to access the document using the specific link provided in their signature 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

SignatureRecipient

account_email

string · email

Optional signer account email address.

sequence

number · int32

Optional signer sequence.

Default: -1

notify

boolean

Whether to send a notification to this signer.

Default: true

language

SignatureLanguage · enum

Determines in which language e-mails are sent to the user, if the user has not set their language preference yet.

Enum values:

Default: en

SignerIdentityData

Optional (no-account) signer identity information.

VisualSignature

Visual signature placement information.

Add an individual signer › Responses

SignatureResponse

id

string · uuid

title

string

message

string

document_id

string · uuid

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 · enum

Overall signing status of the document.

Possible values:

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:

OPEN

DECLINED

WITHDRAWN

SIGNED

EXPIRED

ERROR

business

string

SignatureRecipientResponse[]

cc_email_addresses

string[]

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 at create time. 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

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

Example Request Body

{
  "account_email": "single-signer@skribble.com",
  "signer_identity_data": {
    "email_address": "single-signer@skribble.com"
  }
}

json

application/json

Example Responses

{
  "id": "4f43614a-de50-bfe1-2df3-4c881fc7840e",
  "title": "Example contract",
  "message": "Please sign this document!",
  "document_id": "29eae6aa-5558-2ada-2870-d4e654c0da5c",
  "legislation": "ZERTES",
  "quality": "QES",
  "signing_url": "https://my.skribble.com/view/4f43614a-de50-bfe1-2df3-4c881fc7840e",
  "status_overall": "OPEN",
  "business": "biz-42b4c2fb9ee947778ba70bc0698c78f7",
  "signatures": [
    {
      "sid": "894a0240-e01a-2307-4376-0267c6a8d105",
      "status_code": "SIGNED",
      "account_email": "you@example.info",
      "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,
      "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",
      "visual_signature": {
        "image": {
          "content": "SGVsbG8gd29ybGQh",
          "content_type": "image/png",
          "content_size": 3160
        },
        "position": {
          "page": "0",
          "height": 70,
          "width": 150,
          "x": 350,
          "y": 240,
          "rotation": 0
        },
        "positions": [
          {
            "page": "0",
            "height": 70,
            "width": 150,
            "x": 350,
            "y": 240,
            "rotation": 0
          }
        ],
        "form_field": "Signature1",
        "text": {
          "content": "Customer Signature",
          "font_name": "Helvetica-Bold",
          "font_size": "12",
          "font_color": "#ff0000"
        }
      }
    }
  ],
  "cc_email_addresses": [],
  "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",
  "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/v2

/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 Attachment

Add an individual signer

POST

https://api.skribble.com/v2

/signature-requests/{SR_ID}/signatures

💡 Good to know

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

SignatureRecipient

account_email

string · email

Optional signer account email address.

sequence

number · int32

Optional signer sequence.

Default: -1

notify

boolean

Whether to send a notification to this signer.

Default: true

language

SignatureLanguage · enum

Determines in which language e-mails are sent to the user, if the user has not set their language preference yet.

Enum values:

Default: en

SignerIdentityData

Optional (no-account) signer identity information.

VisualSignature

Visual signature placement information.

Add an individual signer › Responses

SignatureResponse

id

string · uuid

title

string

message

string

document_id

string · uuid

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 · enum

Overall signing status of the document.

Possible values:

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:

OPEN

DECLINED

WITHDRAWN

SIGNED

EXPIRED

ERROR

business

string

SignatureRecipientResponse[]

cc_email_addresses

string[]

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

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/v2

/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