Skip to main content
API docs by Redocly

Signicat Sign API v2 (1.2.1)

Download OpenAPI specification:Download

Introduction

The Signicat Sign API v2 is a REST API using European identity providers for creating electronic signatures on contracts, declarations, forms and other documents.

This REST API uses the OAuth 2.0 protocol for authorisation. All request and response bodies are formatted in JSON.

Get started

Before you can start making requests to this API, you need to learn how to connect to it. To do this, see the Connect to Signicat APIs Quick start guide.

Audit logs

Use the Signicat Audit logs service to see documented evidence of the sequence of activities that have affected a system.

  • Access it: Signicat Dashboard > Settings > Audit logs
  • For information generic to all Signicat audit logs, see the general Audit logs documentation.

Errors

When you make an API call to Signicat and an error occurs, you will receive a response message with an error code.

  • For errors generic to all Signicat APIs, see the general Error codes documentation.
  • For errors specific to this service, see the Sign API v2 Error codes documentation.

Events (callback)

Use the Signicat Events service to automatically receive information about when something happens in one of our services into your system.

  • Access it: Go to Signicat Dashboard > Settings > Events
  • For information generic to all Signicat events, see the general Events documentation.

Note: This is often referred to as callback.

Documents

Upload a new document

Uploads the document as a binary stream; MIME type is defined by the Content-Type header. The response will be the resulting document reference.

Authorizations:
bearerAuth
header Parameters
Content-Type
required
string

Content type header

Request Body schema:
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "mimeType": "application/pdf",
  • "documentId": "d1234567-89ab-cdef-0123-456789abcdef",
  • "createdAt": "2023-04-12T10:30:00Z",
  • "documentHash": {
    }
}

Retrieve a single document

Returns the binary contents of the stored document.

Authorizations:
bearerAuth
path Parameters
documentId
required
string <uuid>

The unique ID of the document.

Responses

Response samples

Content type
application/problem+json
{}

Permanently delete a single document and its metadata

Deletes the document and all associated metadata permanently.

Authorizations:
bearerAuth
path Parameters
documentId
required
string <uuid>

The unique ID of the document.

Responses

Response samples

Content type
application/problem+json
{
  • "status": 500,
  • "type": "https://developer.signicat.com/errors?code=internal_server_error",
  • "title": "Internal server error",
  • "code": "internal_server_error",
  • "traceId": "ffb75ca1385ecb0a362ff9cd029d23de",
  • "invalidParams": [
    ],
  • "detail": "An internal server error happened."
}

Store optional descriptive data about a stored document

Updates the optional metadata fields (filename, title, description) for a stored document.

Authorizations:
bearerAuth
path Parameters
documentId
required
string <uuid>

The unique ID of the document.

Request Body schema: application/json
required
filename
string <= 255 characters

A name to use if the document is to be stored as a file. Optional metadata about the stored document which the customer can supply.

description
string <= 1000 characters

A description of the document for display purposes. Optional metadata about the stored document which the customer can supply.

title
string <= 255 characters

A title of the document for display purposes. Optional metadata about the stored document which the customer can supply.

Responses

Request samples

Content type
application/json
{
  • "filename": "invoice_001.pdf",
  • "description": "Invoice for order #001",
  • "title": "Invoice #001"
}

Response samples

Content type
application/json
{
  • "mimeType": "application/pdf",
  • "documentId": "d1234567-89ab-cdef-0123-456789abcdef",
  • "createdAt": "2023-04-12T10:30:00Z",
  • "documentHash": {
    },
  • "filename": "invoice_001.pdf",
  • "description": "Invoice for order #001",
  • "title": "Invoice #001"
}

Retrieve all information stored about a single document

Returns all available information about a document except for the document itself.

Authorizations:
bearerAuth
path Parameters
documentId
required
string <uuid>

The unique ID of the document.

Responses

Response samples

Content type
application/json
{
  • "mimeType": "application/pdf",
  • "documentId": "d1234567-89ab-cdef-0123-456789abcdef",
  • "createdAt": "2023-04-12T10:30:00Z",
  • "documentHash": {
    },
  • "filename": "invoice_001.pdf",
  • "description": "Invoice for order #001",
  • "title": "Invoice #001"
}

Document collections

Create a new document collection

Creates new document collection. A document collection is a logical grouping of documents that will be signed together.

Authorizations:
bearerAuth
Request Body schema: application/json
required
required
Array of objects (DocumentReference) [ 1 .. 100 ] items
packageTo
Array of strings (PackageType) <= 5 items
Items Value: "PADES_CONTAINER"

A list of formats the collection should be packaged to when all sessions connected to it are signed.

Responses

Request samples

Content type
application/json
{
  • "documents": [
    ],
  • "packageTo": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "f05d0dce-a7af-432b-b6b8-e455ab7c0858",
  • "documents": [
    ],
  • "packageTo": [
    ],
  • "output": {
    }
}

Retrieve a document collection

Returns the document collection with the given ID.

Authorizations:
bearerAuth
path Parameters
documentCollectionId
required
string <uuid>

The unique ID of the document collection.

Responses

Response samples

Content type
application/json
{
  • "id": "f05d0dce-a7af-432b-b6b8-e455ab7c0858",
  • "documents": [
    ],
  • "packageTo": [
    ],
  • "output": {
    }
}

Delete a document collection

Deletes the document collection with the given ID.

Authorizations:
bearerAuth
path Parameters
documentCollectionId
required
string <uuid>

The unique ID of the document collection.

Responses

Response samples

Content type
application/problem+json
{}

Signing sessions

Create a new signing session

Creates a new signing session.

Authorizations:
bearerAuth
Request Body schema: application/json
required
Array ([ 1 .. 100 ] items)
signatureUrlTTL
integer [ 5 .. 525600 ]
Deprecated

Deprecated! Use signatureUrlTimeToLive instead. Time-to-live for the signature URL in minutes

signatureUrlTimeToLive
string

Time-to-live for the signature URL. Must be an ISO 8601 duration and a maximum of 45 days.

title
required
string <= 255 characters

Signing session title shown in the signing interface if configured.

signText
string <= 2048 characters

Text displayed when starting the signing process. The signer must explicitly consent to this text before signing.

dueDate
string <date-time>

The deadline for signing the document(s). Can be a maximum of 45 days into the future from the current date.

required
Array of objects (SessionDocument) [ 1 .. 100 ] items
externalReference
string or null <= 1024 characters

Custom identifier for linking the signing session to your internal process. Passed back in redirect URLs.

required
Array of objects (SigningSetup) = 1 items

The user interaction setups for this signing session describing which IDPs are available for the end-user.

subsequentTo
Array of strings <uuid> <= 50 items [ items <uuid > ]

IDs of signing sessions that must be signed before this one.

packageTo
Array of strings (PackageType) <= 5 items
Items Value: "PADES_CONTAINER"

A list of formats the signing session should be packaged to when signed.

object (Signer)

The intended signer of the signing Session.

object (ArchiveSettings)

Defines what objects should be added to archive. To use this functionality you must contact Signicat Support.

object (PreAuthentication)

Sets up authentication of the signer before presenting documents.

object (Ui)

Defines UI settings for the signing session.

object (IntentionText)

A text indicating the end-user's intention when signing a document. Applicable when using flow PKISIGNING

object (RedirectSettings)

Defines URLs for redirects.

Array of objects (NotificationMessage)
usageTags
Array of strings <= 25 items [ items <= 50 characters ]

A list of tags to emit with events for the sign sessions

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve a paginated list of signing sessions

Returns a paginated list of signing sessions, with optional controls for offset, limit and sort.

Authorizations:
bearerAuth
query Parameters
offset
integer [ 0 .. 100000 ]
Default: 0

Number of rows to skip before returning results.

limit
integer [ 1 .. 1000 ]
Default: 100

Maximum number of rows to return.

sort
Array of strings

Sorting field. Default value is -createdAt. E.g., +dueDate

createdDateFrom
string
Example: createdDateFrom=2024-01-01T00:00:00Z

Filter signing sessions created on or after this date and time

createdDateTo
string
Example: createdDateTo=2024-12-31T23:59:59Z

Filter signing sessions created on or before this date and time

state
Array of strings
Example: state=READY&state=BLOCKED

Search field for state. Multiple values allowed. E.g., BLOCKED, READY. See also SessionState enum for possible values.

dueDateFrom
string
Example: dueDateFrom=2024-06-01T00:00:00Z

Filter signing sessions with due date on or after this date and time

dueDateTo
string
Example: dueDateTo=2024-06-30T23:59:59Z

Filter signing sessions with due date on or before this date and time

sessionTitleLike
string
Example: sessionTitleLike=Contract

Filter signing sessions by title using partial text matching (case-insensitive)

Responses

Response samples

Content type
application/json
{
  • "limit": 100,
  • "offset": 0,
  • "count": 100,
  • "total": 1000,
  • "data": [
    ]
}

Retrieve a signing session

Returns the signing session with the given ID.

Authorizations:
bearerAuth
path Parameters
sessionId
required
string <uuid>

The unique ID of the session.

Responses

Response samples

Content type
application/json
{
  • "id": "f05d0dce-a7af-432b-b6b8-e455ab7c0852",
  • "signatureUrl": "https://signtest-account.sandbox.signicat.com/sign/?sessionId=8ce3dac2-74b3-429c-adf7-fe6d277186d0",
  • "signatureUrlTTL": 5,
  • "signatureUrlTimeToLive": "PT1M30S",
  • "signatureUrlExpiresAt": "2026-01-15T14:05:00Z",
  • "title": "Rental agreement",
  • "signText": "Please sign this document",
  • "dueDate": "2025-04-01T17:32:28Z",
  • "documents": [
    ],
  • "lifecycle": {
    },
  • "output": {
    },
  • "externalReference": "string",
  • "signingSetup": [
    ],
  • "subsequentTo": [
    ],
  • "packageTo": [
    ],
  • "signer": {
    },
  • "archive": {
    },
  • "preAuthentication": {
    },
  • "ui": {
    },
  • "intentionText": {
    },
  • "redirectSettings": {},
  • "notifications": [
    ],
  • "usageTags": [
    ]
}

Delete a signing session

Deletes the signing session with the given ID.

Authorizations:
bearerAuth
path Parameters
sessionId
required
string <uuid>

The unique ID of the session.

Responses

Response samples

Content type
application/problem+json
{}

Update an existing signing session

Updates an existing signing session.

Authorizations:
bearerAuth
path Parameters
sessionId
required
string

The unique ID of the session.

Request Body schema: application/json
required
dueDate
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "dueDate": "2025-12-31T23:59:59Z"
}

Response samples

Content type
application/problem+json
{
  • "status": 500,
  • "type": "https://developer.signicat.com/errors?code=internal_server_error",
  • "title": "Internal server error",
  • "code": "internal_server_error",
  • "traceId": "ffb75ca1385ecb0a362ff9cd029d23de",
  • "invalidParams": [
    ],
  • "detail": "An internal server error happened."
}

Merchant signing

Sign document(s) with merchant certificate

Enables business to business (B2B) signing with a merchant certificate from a specified vendor.

Authorizations:
bearerAuth
Request Body schema: application/json
required
vendor
required
string (VendorEnum)
Value: "NBID"
required
Array of objects (ToBeSignedDocument) [ 1 .. 20 ] items

Responses

Request samples

Content type
application/json
{
  • "vendor": "NBID",
  • "toBeSignedDocuments": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]