Signature Handling

Server

Download schema

Endpoints for handling signature requests and callbacks.

List and find Signature Requests

GET

https://api.skribble.com/v3

/signature-requests

Returns all SignatureRequest objects that the current user has sufficient access rights to.

Filter

You can optionally filter results using one or more of the optional parameters.

Filters search for an exact match of the corresponding field value. This means the filter is case-sensitive and will not match partial values. For example, account_email=john.doe@skribble.com will only match a SignatureRequest where the account_email field is exactly john.doe@skribble.com and will not match another.john.doe@skribble.com.

Exception: The search parameter searches for document titles that contain the search term.

Pagination

The result set can be controlled using the optional pagination parameters page_number and page_size, which helps prevent excessively large result sets.

List and find Signature Requests › query Parameters

account_email

string · email

Filter on the field signatures[].account_email

search

string

Filter on the field title to search for documents containing the serach term.

signature_status

SignatureStatusCode_v3 · enum

Filter on the field signatures[].status_code with one of the valid Signature states

The state of a signature.

Possible values:

DRAFT The signature request has not yet been placed.
OPEN Waiting for the user to sign a signature.
WAITING The signer is waiting for a preceding signer in the sequence to complete.
DECLINED The user declined to sign.
WITHDRAWN The owner has withdrawn the signature request.
SIGNED The user signed the document.
ERROR A technical error occurred.

Enum values:

DRAFT

OPEN

WAITING

DECLINED

WITHDRAWN

SIGNED

ERROR

status_overall

SignatureStatusOverall_v3 · enum

Filter on the field status_overall with one of the valid Signature states

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

page_number

number · min: 1

Page number for pagination. By default pagination is disabled.

page_size

number · min: 0

Page size for pagination.

Default: 50

List and find Signature Requests › Responses

SignatureResponse_v3[]

List of Signature Requests.

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.

GET/signature-requests

curl https://api.skribble.com/v3/signature-requests \
  --header 'Authorization: Bearer <token>'

Example Responses

[
  {
    "id": "4f43614a-de50-bfe1-2df3-4c881fc7840e",
    "title": "Sample document",
    "message": "Please sign this document.",
    "documents": [
      {
        "id": "a84f5085-67e5-e106-71c7-69b3d4b7c632",
        "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-5a2aea44ddea4f0531ebcdcbcedf873c",
    "signatures": [
      {
        "sid": "e5ab7fba-e815-0f65-f437-7c78953a0b7d",
        "account_email": "you@example.info",
        "document_signatures": [
          {
            "document_id": "a84f5085-67e5-e106-71c7-69b3d4b7c632",
            "visual_signature": null
          }
        ],
        "sequence": -1,
        "status_code": "OPEN",
        "notify": true,
        "invited_by": "api_demo_example"
      }
    ],
    "origin": "API",
    "observers": [],
    "attachments": [],
    "owner": "api_demo_example",
    "read_access": [
      "you@example.info",
      "api_demo_example"
    ],
    "write_access": [
      "api_demo_example"
    ],
    "created_at": "2025-10-15T07:47:01.223Z",
    "updated_at": "2025-10-15T07:47:01.223Z"
  },
  {
    "id": "8c73215f-bf33-d8a9-90e5-1a5cd0b9273a",
    "title": "Employment Contract",
    "message": "Please review and sign your employment contract.",
    "documents": [
      {
        "id": "a84f5085-67e5-e106-71c7-69b3d4b7c632",
        "name": "Filename1.pdf",
        "version_id": "a84f5085-67e5-e106-71c7-69b3d4b7c632"
      }
    ],
    "legislation": "EIDAS",
    "quality": "AES",
    "signing_url": "https://my.skribble.com/view/8c73215f-bf33-d8a9-90e5-1a5cd0b9273a",
    "status_overall": "OPEN",
    "business_id": "biz-87c4d39afc6d471da7bcbf4f2e8ef931",
    "signatures": [
      {
        "sid": "5ad9f2c1-6a81-42af-9a6a-7c5adcb54e23",
        "account_email": "alice@example.com",
        "document_signatures": [
          {
            "document_id": "a84f5085-67e5-e106-71c7-69b3d4b7c632",
            "visual_signature": {
              "positions": [
                {
                  "x": 120,
                  "y": 490,
                  "width": 150,
                  "height": 70,
                  "page": "2",
                  "rotation": 0
                }
              ]
            }
          }
        ],
        "sequence": 1,
        "status_code": "SIGNED",
        "notify": true,
        "invited_by": "api_demo_example"
      },
      {
        "sid": "19de3b41-9d65-4cb7-90ff-239b7a0eac12",
        "account_email": "hr@examplecorp.com",
        "document_signatures": [
          {
            "document_id": "a84f5085-67e5-e106-71c7-69b3d4b7c632",
            "visual_signature": {
              "positions": [
                {
                  "x": 130,
                  "y": 420,
                  "width": 155,
                  "height": 72,
                  "page": "2",
                  "rotation": 0
                }
              ]
            }
          }
        ],
        "sequence": 2,
        "status_code": "OPEN",
        "notify": true,
        "invited_by": "api_demo_example"
      }
    ],
    "origin": "API",
    "observers": [
      {
        "id": "ob_789",
        "type": "USER",
        "user_info": {
          "email": "legal@examplecorp.com"
        },
        "invited_at": "2025-10-15T08:15:22.115Z",
        "invited_by": "api_demo_example"
      }
    ],
    "owner": "api_demo_example",
    "read_access": [
      "alice@example.com",
      "hr@examplecorp.com",
      "legal@examplecorp.com",
      "api_demo_example"
    ],
    "write_access": [
      "api_demo_example"
    ],
    "created_at": "2025-10-15T08:15:22.115Z",
    "updated_at": "2025-10-15T08:15:22.115Z"
  }
]

json

application/json

Update a Signature Request

PUT

https://api.skribble.com/v3

/signature-requests

Updates an existing SignatureRequest. We recommend creating the SignatureRequest with all necessary information upfront and using this endpoint only when changes are required.

The following fields can be updated: title, message, legislation, quality, signatures, callback_success_url, callback_error_url, callback_update_url, custom, attach_on_success, read_access, and write_access.

Observers are managed separately via the dedicated /observers endpoints.

Updating signers

To add or remove signers, provide the complete desired state of the signatures array:

To add a signer, include the new entry alongside all existing signers.
To remove a signer, omit their entry from the array.

Alternatively, use the dedicated /signatures endpoints to add or remove individual signers without having to send the full list.

Important: When updating via this endpoint, any signer not present in the signatures array will be removed. Changes to signers can only be made as long as none of the signers have already completed their signature.

Update a Signature Request › Request Body

UpdateSignatureRequest

id

string · uuid · required

Unique ID of the signature request.

title

string

Title of the signature request.

message

string

Message sent to the other participants along with this signature request.

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

callback_success_url

string · uri

Callback-URL which is called on overall success.

callback_error_url

string · uri

Callback-URL which is called in case of an error.

callback_update_url

string · uri

Callback-URL which is called in case of an update.

callback_start_sign_url

string · uri

Callback-URL which is called when a signer starts the signature process (only for xQES).

callback_ident_pending_url

string · uri

Callback-URL which is called when the identification of a signer requires manual review.

callback_ident_error_url

string · uri

Callback-URL which is called when the identification of a signer ends in an error.

expires_at

string · date

Early access. This field is available to opted-in businesses only. To request access, contact support@skribble.com.

Setting expires_at requires the signature-request expiry feature to be enabled for the business. If it is not, the request fails with 403 Forbidden (problem type feature-not-enabled).

Owner-set expiry date for this signature request (ISO 8601 date, e.g. 2026-12-31).

When set, the SignatureRequest transitions to status_overall=EXPIRED at the end of the given day if it has not been completed. EXPIRED is a terminal status.

To clear an existing expiry date, call DELETE /signature-requests/{SR_ID}/expires-at.

Constraints

Must be today or later.
Must be at most 6 months in the future.
If the owning business has a retention policy configured, expires_at must be at most one day before the configured retention deletion date.
Mutable on status_overall=DRAFT only. Updating on a non-DRAFT request returns 400 Bad Request.

Update a Signature Request › 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.

PUT/signature-requests

curl https://api.skribble.com/v3/signature-requests \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "id": "4f43614a-de50-bfe1-2df3-4c881fc7840e",
  "title": "Example contract",
  "message": "Please sign this document!"
}'

Example Request Body

{
  "id": "4f43614a-de50-bfe1-2df3-4c881fc7840e",
  "title": "Example contract",
  "message": "Please sign this document!"
}

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

List Signature Requests by bulk

POST

https://api.skribble.com/v3

/signature-requests/bulk

Retrieves multiple SignatureRequest objects in a single call.

Provide a JSON array of SignatureRequest IDs in the request body to specify which records to fetch. The response includes only the SignatureRequests that were successfully found. IDs that do not match any existing record are silently ignored.

List Signature Requests by bulk › Request Body

string[]

List Signature Requests by bulk › Responses

SignatureResponse[]

List of found SignatureRequests. IDs not matching any existing record are silently ignored and absent from the response.

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

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[]

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

curl https://api.skribble.com/v3/signature-requests/bulk \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '[
  "abababab-a777-e8e8-e8e8-121212121212",
  "bbddbbdd-7788-7ee7-a22a-bfbfbfbfbfbf",
  "cccccccc-1111-2222-3333-444444444444",
  "dddddddd-dead-beef-cafe-999999999999",
  "eeeeeeee-aaaa-bbbb-cccc-dddddddddddd",
  "ffffaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "abababab-1234-5678-9abc-defdefdefdef",
  "12341234-aaaa-bbbb-cccc-123412341234",
  "99999999-8888-7777-6666-555555555555",
  "abcdabcd-abcd-abcd-abcd-abcdabcdabcd"
]'

Example Request Body

[
  "abababab-a777-e8e8-e8e8-121212121212",
  "bbddbbdd-7788-7ee7-a22a-bfbfbfbfbfbf",
  "cccccccc-1111-2222-3333-444444444444",
  "dddddddd-dead-beef-cafe-999999999999",
  "eeeeeeee-aaaa-bbbb-cccc-dddddddddddd",
  "ffffaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "abababab-1234-5678-9abc-defdefdefdef",
  "12341234-aaaa-bbbb-cccc-123412341234",
  "99999999-8888-7777-6666-555555555555",
  "abcdabcd-abcd-abcd-abcd-abcdabcdabcd"
]

json

application/json

Example Responses

[
  {
    "id": "abababab-a777-e8e8-e8e8-121212121212",
    "title": "First example contract",
    "document_id": "1ff0cf91-6b54-f3bd-bffb-8fcd5e799764",
    "legislation": "ZERTES",
    "quality": "QES",
    "signing_url": "https://my.skribble.com/view/abababab-a777-e8e8-e8e8-121212121212",
    "status_overall": "OPEN",
    "business": "biz-5a2aea44ddea4f0531ebcdcbcedf873c",
    "signatures": [
      {
        "sid": "e5ab7fba-e815-0f65-f437-7c78953a0b7d",
        "account_email": "you@example.info",
        "sequence": -1,
        "status_code": "OPEN",
        "notify": true
      }
    ],
    "cc_email_addresses": [],
    "attachments": [],
    "owner": "api_demo_example",
    "read_access": [
      "you@example.info",
      "api_demo_example"
    ],
    "write_access": [
      "api_demo_example"
    ],
    "created_at": "2025-10-15T07:47:01.223Z",
    "updated_at": "2025-10-15T07:47:01.223Z"
  },
  {
    "id": "bbddbbdd-7788-7ee7-a22a-bfbfbfbfbfbf",
    "title": "Second example contract",
    "document_id": "2aa9b2e7-3c21-4d7a-bf9c-6a1f6f5fcb98",
    "legislation": "ZERTES",
    "quality": "QES",
    "signing_url": "https://my.skribble.com/view/bbddbbdd-7788-7ee7-a22a-bfbfbfbfbfbf",
    "status_overall": "SIGNED",
    "business": "biz-5a2aea44ddea4f0531ebcdcbcedf873c",
    "signatures": [
      {
        "sid": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "account_email": "colleague@example.info",
        "sequence": -1,
        "status_code": "SIGNED",
        "notify": true
      }
    ],
    "cc_email_addresses": [],
    "attachments": [],
    "owner": "api_demo_example",
    "read_access": [
      "colleague@example.info",
      "api_demo_example"
    ],
    "write_access": [
      "api_demo_example"
    ],
    "created_at": "2025-10-14T09:00:00.000Z",
    "updated_at": "2025-10-14T11:30:00.000Z"
  }
]

json

application/json

Get a Signature Request

GET

https://api.skribble.com/v3

/signature-requests/{SR_ID}

Fetches a SignatureRequest by its ID.

Get a Signature Request › path Parameters

SR_ID

string · uuid · required

Unique ID received when creating the Signature Request object

Get a Signature Request › 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.

GET/signature-requests/{SR_ID}

curl https://api.skribble.com/v3/signature-requests/:SR_ID \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "id": "4f43614a-de50-bfe1-2df3-4c881fc7840e",
  "title": "Sample document",
  "message": "Please sign this document.",
  "documents": [
    {
      "id": "a84f5085-67e5-e106-71c7-69b3d4b7c632",
      "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-5a2aea44ddea4f0531ebcdcbcedf873c",
  "signatures": [
    {
      "sid": "e5ab7fba-e815-0f65-f437-7c78953a0b7d",
      "account_email": "you@example.info",
      "document_signatures": [
        {
          "document_id": "a84f5085-67e5-e106-71c7-69b3d4b7c632",
          "visual_signature": null
        }
      ],
      "sequence": -1,
      "status_code": "OPEN",
      "notify": true,
      "invited_by": "api_demo_example"
    }
  ],
  "origin": "API",
  "observers": [],
  "attachments": [],
  "owner": "api_demo_example",
  "read_access": [
    "you@example.info",
    "api_demo_example"
  ],
  "write_access": [
    "api_demo_example"
  ],
  "created_at": "2025-10-15T07:47:01.223Z",
  "updated_at": "2025-10-15T07:47:01.223Z"
}

json

application/json

Remind Open Signers of a Signature Request

POST

https://api.skribble.com/v3

/signature-requests/{SR_ID}/remind

In addition to the automatic signature reminders, manual reminders can also be initiated via the Skribble web application and also via the API.

This allows for greater flexibility in managing signature requests, ensuring that important documents are signed promptly. By using both automatic and manual reminders, you can tailor your approach to suit the specific needs of your users or customers.

Limits

There is an hourly limit on the number of signature reminders that can be sent. This limit ensures that reminders are used responsibly and prevents excessive notifications. Generally, this restriction should not affect you if you use this feature appropriately. By adhering to this limit, you can effectively manage your signature requests without overwhelming your users or customers with frequent reminders.

Remind Open Signers of a Signature Request › path Parameters

SR_ID

string · uuid · required

Unique ID received when creating the Signature Request object

Remind Open Signers of a Signature Request › Responses

No data returned

Clear the expiry date of a Signature Request

DELETE

https://api.skribble.com/v3

/signature-requests/{SR_ID}/expires-at

Early access. This endpoint is available to opted-in businesses only. To request access, contact support@skribble.com.

Clearing the expiry requires the signature-request expiry feature to be enabled for the business. If it is not, the request fails with 403 Forbidden (problem type feature-not-enabled).

Clears the owner-set expires_at date from a SignatureRequest in status_overall=DRAFT.

After this call the SignatureRequest no longer has an owner-set expiry. The auto_delete_at retention date (if any) is unaffected.

Constraints

Only allowed while status_overall=DRAFT. Calling this on a non-DRAFT request returns 400 Bad Request.
Requires the same write access as updating the SignatureRequest.

Clear the expiry date of a Signature Request › path Parameters

SR_ID

string · uuid · required

Unique ID received when creating the Signature Request object

Clear the expiry date of a Signature Request › Responses

Expiry date cleared.

No data returned

Get Signature Request Report

GET

https://api.skribble.com/v3

/signature-requests/{SR_ID}/report

Provides the signature report for a specific signature request.

By default, the report is returned as a human-readable, digitally signed PDF document. Optionally, the report format can be changed using the type query parameter (e.g. JSON or HTML).

The report contains all relevant information about the signature process, including signatories, timestamps, and verification details. It serves as legally valid proof of the completed signing process and can be stored or shared for auditing, compliance, or record-keeping purposes.

Get Signature Request Report › path Parameters

SR_ID

string · uuid · required

Unique ID received when creating the Signature Request object

Get Signature Request Report › query Parameters

type

string · enum

Format of the Report.

Enum values:

PDF

JSON

HTML

Default: PDF

Get Signature Request Report › Responses

string · binary

Get callback details for a signature request

GET

https://api.skribble.com/v3

/signature-requests/{SR_ID}/callbacks

Returns detailed information about the callbacks associated with a SignatureRequest. Use this endpoint to confirm whether a callback has been executed or to identify errors that occurred during the callback process.

Result

If no callbacks have been triggered yet, the response will be an empty array. Otherwise, it contains an array of callback objects that have already been executed.

Get callback details for a signature request › path Parameters

SR_ID

string · uuid · required

Unique ID received when creating the Signature Request object

Get callback details for a signature request › Responses

object[]

signature_request_id

string · uuid

Signature request's unique ID on Skribble.

type

CallbackType_v3 · enum

The type of this callback.

Possible values:

SUCCESS Is triggered when the document has been successfully signed by all parties involved.
UPDATE Is triggered on changes on the SignatureRequest object like when one person of all involved parties has signed.
INITIATE Is triggered when the signature request is initiated via the endpoint.
ERROR Is triggered when a person declines the signature or when the SignatureRequest is withdrawn.
START_SIGN Is triggered when a person starts the signature process (only for xQES).
IDENT_PENDING Is triggered when the identification of a person within a signature process requires manual review.
IDENT_ERROR Is triggered when the identification of a person within a signature process ended in an error.

Enum values:

SUCCESS

UPDATE

ERROR

START_SIGN

INITIATE

IDENT_PENDING

IDENT_ERROR

state

CallbackState · enum

The state of the callback.

Possible values:

OPEN The callback request will be executed in the next execution cycle.
COMPLETED The callback request was executed successfully. The API received an HTTP 2xx success code in response.
RESIGNATED The callback request has been attempted attempts times but was unsuccessful. The API did not receive a valid HTTP 2xx response.

Enum values:

OPEN

COMPLETED

RESIGNATED

url

string · uri

The called URL of this callback.

attempts

integer · int32

The attempts this callback was carried out.

messages

string[]

Error messages in case that the callback failed.

created_at

string · date-time

The time at which the object was created.

updated_at

string · date-time

The time at which the object was last changed.

Signature Attachment Seal