Skip to main content
API docs by Redocly

Signicat Signature API (v1)

Download OpenAPI specification:Download

Sign contracts, declarations, forms and other documents using digital signatures.

Attachments

Create attachment

Adds an attachments to the specified document. You can choose between different ways to make the user accept the attachment. The attachment will be deleted together with the main document when the signature job is completed or has expired

path Parameters
documentId
required
string <uuid>
Request Body schema:
fileName
required
string [ 0 .. 200 ] characters

Filename with file extension. We only support PDF for attachments, set convertToPdf to true if you have a convertible file type.

title
required
string [ 0 .. 300 ] characters

The title of the attachment which will be presented to the user.

data
required
string non-empty

Base64-encoded attachment (UTF-8-encoded)

convertToPdf
boolean

Determines if the attachment should be converted to PDF. See our documentation for supported file types.

signers
Array of strings or null <uuid>

An optional list of signers that should be able to see / sign the attachment.

description
string or null

An optional description of the attachment.

type
string (AttachmentType)
Enum: "show_accept" "read_accept" "sign"

Responses

Request samples

Content type
{
  • "fileName": "Attachment1.pdf",
  • "title": "Attachment 1 - Type description",
  • "data": "Base 64 encoded pdf",
  • "convertToPdf": false,
  • "description": "This attachment describes bla bla bla...",
  • "type": "show_accept"
}

Response samples

Content type
{
  • "id": "0c73c1d1-ffea-4d23-a00c-f79606e989ed",
  • "fileName": "Attachment1.pdf",
  • "title": "Attachment 1 - Type description",
  • "data": "Base 64 encoded pdf",
  • "convertToPdf": false,
  • "description": "This attachment describes bla bla bla...",
  • "type": "show_accept"
}

List attachments

Returns a list of all attachments for the specified document.

path Parameters
documentId
required
string <uuid>

Responses

Response samples

Content type
[
  • {
    },
  • {
    }
]

Retrieve attachment

Retrieves the details of a single attachment.

path Parameters
documentId
required
string <uuid>
attachmentId
required
string <uuid>

Responses

Response samples

Content type
{
  • "id": "3cc34e9c-1161-4a78-bc19-b11538efa1d9",
  • "fileName": "Attachment1.pdf",
  • "title": "Attachment 1 - Type description",
  • "data": "Base 64 encoded pdf",
  • "convertToPdf": false,
  • "description": "This attachment describes bla bla bla...",
  • "type": "show_accept"
}

Update attachment

Updates the specified attachment (Will only take affect if no one has signed the document yet)

path Parameters
documentId
required
string <uuid>
attachmentId
required
string <uuid>
Request Body schema:
type
string (AttachmentType)
Enum: "show_accept" "read_accept" "sign"
fileName
string or null [ 0 .. 200 ] characters

Filename with file extension. We only support PDF for attachments, set convertToPdf to true if you have a convertible file type.

title
string or null [ 0 .. 300 ] characters

The title of the attachment which will be presented to the user.

data
string or null

Base64-encoded attachment (UTF-8-encoded)

convertToPdf
boolean

Determines if the attachment should be converted to PDF. See our documentation for supported file types.

signers
Array of strings or null <uuid>

An optional list of signers that should be able to see / sign the attachment.

description
string or null

An optional description of the attachment.

Responses

Request samples

Content type
{
  • "type": "show_accept",
  • "fileName": "Attachment1.pdf",
  • "title": "Attachment 1 - Type description",
  • "data": "Base 64 encoded pdf",
  • "convertToPdf": false,
  • "description": "This attachment describes bla bla bla..."
}

Response samples

Content type
{
  • "id": "a9977125-0d6b-4dff-b9cc-0047125d7bc3",
  • "fileName": "Attachment1.pdf",
  • "title": "Attachment 1 - Type description",
  • "data": "Base 64 encoded pdf",
  • "convertToPdf": false,
  • "description": "This attachment describes bla bla bla...",
  • "type": "show_accept"
}

Delete attachment

Deletes the specified attachment (Will only take affect if no one has signed the document yet)

path Parameters
documentId
required
string <uuid>
attachmentId
required
string <uuid>

Responses

Documents

Create document

Creates a new document. In the response you will receive a document ID to retrieve info about the document at a later time. You also receive a URL and unique identifier per signer.

Request Body schema:
title
required
string [ 0 .. 300 ] characters
required
Array of objects (SignerRequest)

List of signers for the document.

object (DataToSign)

The data that will be signed.

required
object (ContactDetails)

The company's contact information.

externalId
required
string [ 4 .. 255 ] characters
description
string or null

The description of the document job.

object (Notification)

Settings for custom notification texts as well as additional email addresses to receive the signed document under finalReceipt. Remark: Also requires you to setup notifications for each signer you want to notify.

object (Advanced)

Optional settings for advanced configuration.

Responses

Request samples

Content type
{
  • "title": "Test document",
  • "signers": [
    ],
  • "dataToSign": {
    },
  • "contactDetails": {},
  • "externalId": "ae7b9ca7-3839-4e0d-a070-9f14bffbbf55",
  • "description": "This is an important document",
  • "advanced": {
    }
}

Response samples

Content type
{
  • "documentId": "94865b6f-2aa9-436d-8b3c-a85e00efd034",
  • "signers": [
    ],
  • "title": "Test document",
  • "description": "This is an important document",
  • "externalId": "ae7b9ca7-3839-4e0d-a070-9f14bffbbf55",
  • "dataToSign": {
    },
  • "contactDetails": {},
  • "advanced": {
    }
}

Retrieve document

Retrieves details of a single document.

path Parameters
documentId
required
string <uuid>

Responses

Response samples

Content type
{
  • "documentId": "94865b6f-2aa9-436d-8b3c-a85e00efd034",
  • "signers": [
    ],
  • "title": "Test document",
  • "description": "This is an important document",
  • "externalId": "ae7b9ca7-3839-4e0d-a070-9f14bffbbf55",
  • "dataToSign": {
    },
  • "contactDetails": {},
  • "advanced": {
    }
}

Update document

Include the properties/fields you want to update in your request

path Parameters
documentId
required
string <uuid>
Request Body schema:
title
string or null
description
string or null
object (Notification)

Settings for custom notification texts as well as additional email addresses to receive the signed document under finalReceipt. Remark: Also requires you to setup notifications for each signer you want to notify.

object (ContactDetails)

The company's contact information.

object (Advanced)

Optional settings for advanced configuration.

Responses

Request samples

Content type
{
  • "title": "Updated title",
  • "description": "This is an updated description",
  • "contactDetails": {},
  • "advanced": {
    }
}

Response samples

Content type
{
  • "documentId": "94865b6f-2aa9-436d-8b3c-a85e00efd034",
  • "signers": [
    ],
  • "title": "Updated title",
  • "description": "This is an updated description",
  • "externalId": "ae7b9ca7-3839-4e0d-a070-9f14bffbbf55",
  • "dataToSign": {
    },
  • "contactDetails": {},
  • "advanced": {
    }
}

Cancel document

Cancel a document, after a document is canceled it cannot be signed. The signer will be presented the reason if they click the sign-url

path Parameters
documentId
required
string <uuid>
query Parameters
reason
required
string

Responses

Retrieve document status

Get the status of a document

path Parameters
documentId
required
string <uuid>

Responses

Response samples

Content type
{
  • "documentStatus": "signed",
  • "completedPackages": [
    ],
  • "attachmentPackages": { }
}

Retrieve document summary

Get information about a document

path Parameters
documentId
required
string <uuid>

Responses

Response samples

Content type
{
  • "documentId": "c1d06fd5-140d-4264-ad07-fe5e9386b5bf",
  • "accountId": "d6153599-cc87-4aef-b8aa-373e60168e2e",
  • "title": "House contract",
  • "description": "Sample avenue 42",
  • "lastUpdated": "2024-09-11T21:05:52Z",
  • "deadline": "2024-09-17T08:05:52Z",
  • "status": {
    },
  • "externalId": "ipoqj9r8232j54rmno2i3lmfrå2q034frlk",
  • "documentSignatures": [
    ],
  • "requiredSignatures": 2,
  • "currentSignatures": 1,
  • "tags": [
    ],
  • "attachments": [
    ],
  • "signers": [
    ],
  • "created": "2024-09-11T21:05:52Z"
}

List document summaries

Queries your documents using the provided parameters.

query Parameters
externalId
string

Documents external id

signerId
string <uuid>

Signer Id

externalSignerId
string

External signer Id

fromDate
string <date-time>

Documents created from date (ticks)

toDate
string <date-time>

Documents created to date (ticks)

lastUpdated
string <date-time>

Documents updated after this date (ticks)

signedDate
string <date-time>

Documents signed after this date (ticks)

nameOfSigner
string

Name of signer

title
string
status
string (DocumentStatus)
Enum: "unsigned" "waiting_for_attachments" "partialsigned" "signed" "canceled" "expired"

Document status

tags
string

Document tags

offset
integer <int32>
Default: 0

Used for paging (will be automatically set in response links)

limit
integer <int32>
Default: 100

Set how many results you want per page (max/default 100)

Responses

Response samples

Content type
{
  • "offset": 0,
  • "limit": 2,
  • "size": 45,
  • "links": {},
  • "data": [
    ]
}

Files

Retrieve file

Retrieves the signed document file.

path Parameters
documentId
required
string <uuid>
query Parameters
fileFormat
string (FileFormat)
Enum: "unsigned" "native" "standard_packaging" "pades" "xades"
originalFileName
boolean
Default: false

Set this to true if you want us to name the file with the original filename

Responses

Retrieve file for signer

Retrieves the signed document file for the specified signer.

path Parameters
documentId
required
string <uuid>
signerId
required
string <uuid>

The signers Id

query Parameters
fileFormat
string (SignerFileFormat)
Enum: "native" "packaged"

Responses

Retrieve attachment file

Retrieves the attachment file.

path Parameters
documentId
required
string <uuid>
attachmentId
required
string <uuid>
query Parameters
fileFormat
string (FileFormat)
Enum: "unsigned" "native" "standard_packaging" "pades" "xades"
originalFileName
boolean
Default: false

Set this to true if you want us to name the file with the original filename

Responses

Retrieve attachment for signer

Retrieves the attachment file for the specified signer.

path Parameters
documentId
required
string <uuid>
attachmentId
required
string <uuid>
signerId
required
string <uuid>

The signers Id

query Parameters
fileFormat
string (SignerFileFormat)
Enum: "native" "packaged"

Responses

Jwt

Validate redirect JWT

Request Body schema:
jwt
required
string non-empty

Responses

Request samples

Content type
{
  • "jwt": "string"
}

Response samples

Content type
{
  • "valid": true,
  • "expires": "2024-09-19T08:05:52Z",
  • "payload": {
    }
}

MerchantSign

Create merchant signature

Request Body schema:
dataToSign
required
string non-empty
xslt
string or null
dataFormat
required
string (MerchantDataFormat)
Enum: "xml" "txt"
dataEncodingFormat
string (MerchantEncodingFormat)
Enum: "UTF8" "ISOLATIN"
externalReference
required
string [ 1 .. 255 ] characters
signingFormat
string (MerchantSigningFormat)
Enum: "use_provider_setting" "no_bankid_seid_sdo"
departmentId
string or null <= 110 characters

Responses

Request samples

Content type
{
  • "dataToSign": "RGV0dGUgZXIgZW4gdGVrc3Qgc29tIGthbiBzaWduZXJlcw==",
  • "dataFormat": "txt",
  • "externalReference": "Some reference",
  • "signingFormat": "no_bankid_seid_sdo"
}

Response samples

Content type
{
  • "signedData": "Base 64 encoded signed data",
  • "signingFormat": "no_bankid_seid_sdo",
  • "signCertificateBase64String": "Base 64 encoded certificate used to sign data",
  • "transactionId": "be6b0d54-0cf2-41a2-a56d-78718aa01bb3"
}

Notifications

List notifications

Returns a list of all notifications that has been sent / attempted sent for a document

path Parameters
documentId
required
string <uuid>

Responses

Response samples

Content type
[
  • {
    },
  • {
    }
]

Send reminders

If you want to send out reminders to all/some of the signers manually you can do it here.

path Parameters
documentId
required
string <uuid>
Request Body schema:
notificationSetting
required
string (NotificationSetting)
Enum: "off" "sendSms" "sendEmail" "sendBoth"
object or null

Optional: Define the signers that should receive this reminder (if not signed). Dictionary with signer id as key, you can ovveride the signer email/phone as value

Responses

Request samples

Content type
{
  • "notificationSetting": "sendEmail",
  • "signers": {
    }
}

Response samples

Content type
{
  • "notificationSetting": "sendEmail",
  • "signers": {
    }
}

SignatureMethods

List signature-methods

Returns a list of all the supported signature-methods

query Parameters
mechanism
string (Mechanisms)
Enum: "pkisignature" "identification" "handwritten" "handwritten_with_identification"

The result may vary with different signature mechanisms. Defaults to pkisignature

fileType
string (ListSignMethodsFileType)
Enum: "pdf" "txt" "xml"

FileType that will be signed, some signature methods have different file support. Defaults to pdf

language
string (Language)
Enum: "EN" "NO" "DA" "SV" "FI" "NL" "DE"

The language to use for name and description. Defaults to EN (english)

signableAttachments
boolean
Default: false

Signing multiple documents? Some signature-methods may lack this functionality

redirectMode
string (RedirectMode)
Enum: "donot_redirect" "redirect" "iframe_with_webmessaging" "iframe_with_redirect" "iframe_with_redirect_and_webmessaging"

Some signature methods do not allow iframing

Responses

List signature-methods for account

Returns a list of all the signature-methods available for the requester's account.

query Parameters
mechanism
string (Mechanisms)
Enum: "pkisignature" "identification" "handwritten" "handwritten_with_identification"

The result may vary with different signature mechanisms. Defaults to pkisignature

fileType
string (ListSignMethodsFileType)
Enum: "pdf" "txt" "xml"

FileType that will be signed, some signature methods have different file support. Defaults to pdf

language
string (Language)
Enum: "EN" "NO" "DA" "SV" "FI" "NL" "DE"

The language to use for name and description. Defaults to EN (english)

signableAttachments
boolean
Default: false

Signing multiple documents? Some signature-methods may lack this functionality

redirectMode
string (RedirectMode)
Enum: "donot_redirect" "redirect" "iframe_with_webmessaging" "iframe_with_redirect" "iframe_with_redirect_and_webmessaging"

Some signature methods do not allow iframing

Responses

Signers

Retrieve signer

Retrieves the details of a single signer.

path Parameters
documentId
required
string <uuid>
signerId
required
string <uuid>

Responses

Response samples

Content type
{}

Delete signer

path Parameters
documentId
required
string <uuid>
signerId
required
string <uuid>

Responses

Update signer

path Parameters
documentId
required
string <uuid>
signerId
required
string <uuid>
Request Body schema:
externalSignerId
string or null [ 4 .. 255 ] characters

Your reference for the signer.

object (RedirectSettings)

Settings for redirect.

object (SignatureType)

Settings for the allowed signature methods.

object (SignerInfo)

Information about the signer.

object (Authentication)

Authentication settings for the signer.

object (ExtraInfoSignerRequest)

Settings for extra information to collect about the signer.

object (AddonSignerRequest)
object (UIResponse)
object (Notifications)

Email/SMS notification settings for the signer.

tags
Array of strings or null

Coming soon.

order
integer <int32>

Optional order of signing for the signer.

required
boolean

Determines if the signer is required to sign the document before other signers. Any other signers will not be allowed to sign before all required signers have signed the document.

signUrlExpires
string or null <date-time>

The time at which the signature URL expires (ISO 8601). Specify this if you want a limited time-to-live for the URL. Defaults to the lifetime of the document.

Responses

Request samples

Content type
{
  • "signerInfo": {
    },
  • "order": 0,
  • "required": false,
  • "signUrlExpires": "2024-09-15T08:05:52Z"
}

Response samples

Content type
{
  • "signerInfo": {
    },
  • "order": 0,
  • "required": false,
  • "signUrlExpires": "2024-09-15T08:05:52Z"
}

List signers

path Parameters
documentId
required
string <uuid>

Responses

Response samples

Content type
[]

Create signer

path Parameters
documentId
required
string <uuid>
Request Body schema:
externalSignerId
required
string [ 4 .. 255 ] characters

Your reference for the signer.

required
object (RedirectSettings)

Settings for redirect.

required
object (SignatureType)

Settings for the allowed signature methods.

object (SignerInfo)

Information about the signer.

object (Authentication)

Authentication settings for the signer.

object (ExtraInfoSignerRequest)

Settings for extra information to collect about the signer.

object (AddonSignerRequest)
object (UI)

UI settings for the signature process.

object (Notifications)

Email/SMS notification settings for the signer.

tags
Array of strings or null

Coming soon.

order
integer <int32>

Optional order of signing for the signer.

required
boolean

Determines if the signer is required to sign the document before other signers. Any other signers will not be allowed to sign before all required signers have signed the document.

signUrlExpires
string or null <date-time>

The time at which the signature URL expires (ISO 8601). Specify this if you want a limited time-to-live for the URL. Defaults to the lifetime of the document.

getSocialSecurityNumber
boolean

Get social security number for this signer only (The global variable advanced.getSocialSecurityNumber will ovveride this when sat to true). Requires eid with permission to retrieve social security number

verifySocialSecurityNumber
boolean or null

Get and verify social security number for this signer, if there is a mismatch the signature will fail. Requirements: 1) signerInfo.SocialSecurityNumber must be prefilled, 2) eID with permission to retrieve social security number. If the eID does not return a social security number this property will be ignored.

Responses

Request samples

Content type
{
  • "externalSignerId": "uoiahsd321982983jhrmnec2wsadm32",
  • "redirectSettings": {
    },
  • "signatureType": {
    },
  • "ui": {
    },
  • "order": 0,
  • "required": false,
  • "getSocialSecurityNumber": false
}

Response samples

Content type
{}

Delete signature

path Parameters
documentId
required
string <uuid>
signerId
required
string <uuid>

Responses

Themes

List themes

This endpoint lists all the color themes you can use in our sign application

Responses

Response samples

Content type
[
  • "Default"
]

List spinners

This endpoint lists all the spinners you can use in our sign application

Responses

Response samples

Content type
[
  • "Document"
]

Validate

Validate nbid SDO

Validates the signatures in a SEID-SDO, to validate the SDO we use the validation component from BankID Norway. In this endpoint you can also include the data from the original document to validate that they matches the SDO data, the same goes for the signatures TO USE THIS IN PRODUCTION, PLEASE CONTACT SIGNICAT SUPPORT

Request Body schema:
sdoData
string or null
externalReference
string or null
dataToValidate
string or null
Array of objects or null (Signer)

Responses

Request samples

Content type
{
  • "sdoData": "string",
  • "externalReference": "string",
  • "dataToValidate": "string",
  • "signersToValidate": [
    ]
}

Response samples

Content type
{
  • "requestId": "string",
  • "valid": true,
  • "seal": {
    },
  • "signers": [
    ],
  • "summary": "string",
  • "validationError": {
    },
  • "auditId": "03af6f11-6465-492e-a028-03a0a495d7f0"
}

Parse and validate nbid sdo

This endpoint validates and parses signature data from a SEID-SDO, to validate/parse the SDO we use the validation component from BankID Norway. This endpoint parses the SDO to readable data and provides you with information about the signatures and document. TO USE THIS IN PRODUCTION, PLEASE CONTACT SIGNICAT SUPPORT

Request Body schema:
sdoData
string or null
externalReference
string or null
fetchSSN
boolean or null

Responses

Request samples

Content type
{
  • "sdoData": "string",
  • "externalReference": "string",
  • "fetchSSN": true
}

Response samples

Content type
{
  • "requestId": "string",
  • "auditId": "03af6f11-6465-492e-a028-03a0a495d7f0",
  • "signersValid": true,
  • "seal": {
    },
  • "signers": [
    ],
  • "summary": "string",
  • "validationError": {
    },
  • "signedData": "string"
}

Parse SDO to XML

Parse Nbid SEID-SDO to xml validation format. Returns 400 if SDO is not valid

Request Body schema:
sdoData
string or null

Base 64 encoded SDO (Signed document)

externalReference
string or null

Your reference to the parse session

Responses

Request samples

Content type
{
  • "sdoData": "string",
  • "externalReference": "string"
}

Response samples

Content type
{
  • "responseType": "string",
  • "responseId": "string",
  • "results": [
    ]
}