You can make HTTP GET, POST or PUT Requests. Requests are passed to the API by using JSON objects to the API endpoints with the appropriate parameters. The documentation for each API call will contain more detail on the parameters accepted by the call.

All responses are sent JSON-encoded. The specific responses (successful ones) are described in the documentation section for each method. See https://en.wikipedia.org/wiki/Json for more information on JSON.

All input strings should be UTF-8 encoded, our response is always encoded conforming to the Content-Type HTTP header, which for JSON responses is charset=utf-8. Optional JSON properties should be omitted from the request when not used. Do not provide null values. For backward compatibility reasons we do include null values in the v1 responses, but we won't in the v2 responses.

Some of our endpoints return both the status of the transaction and signer activities. Further details about the statuses and activities can be found here.

All endpoints:


All models:

GET: /api/transaction/{transactionId}

Description

Returns current transaction details.

Please do not use any GET method for active polling, but use our postback service for this end.

Parameters

Name Location Required Description
transactionId path true ID of the transaction

Most common responses

200 Details of the transaction #/definitions/Transaction
401 Not authorized to access the specified transaction
410 The transaction details are no longer available and as a result the returned JSON only contains partial historical data. This happens when we cleaned the transaction for example due to reaching an end status (any status above 30), or the expiration dates have expired.

Example

Request: 
curl \
  -H "Authorization: APIKey {usertoken here}" \
  -H "Application: APPKey {appkey here}" \
  https://api.signhost.com/api/transaction/b2a9aca4-cd5e-4a21-b7f7-c08a9f2b2d57
Response:

This method returns a transaction.

{
  "Id": "67b9e140-b0f6-4c36-9b35-977041968185",
  "Status": 20,
  "Files": {
    "Contract.pdf": {
      "Links": [
        {
          "Rel": "file",
          "Type": "application/pdf",
          "Link": "https://api.signhost.com/api/transaction/67b9e140-b0f6-4c36-9b35-977041968185/file/Contract.pdf"
        }
      ],
      "DisplayName": "ArbeidsContract 2016"
    },
    "Algemenevoorwaarden": {
      "Links": [
        {
          "Rel": "file",
          "Type": "application/pdf",
          "Link": "https://api.signhost.com/api/transaction/67b9e140-b0f6-4c36-9b35-977041968185/file/Algemenevoorwaarden"
        }
      ],
      "DisplayName": "Algemene voorwaarden"
    }
  },
  "Seal": true,
  "Signers": [
    {
      "Id": "e0b39ec0-e0c6-45d9-bf0d-ae8cafbe2f48",
      "Expires": null,
      "Email": "user@example.com",
      "Mobile": "+31612345678",
      "Iban": null,
      "BSN": null,
      "RequireScribbleName": false,
      "RequireScribble": true,
      "RequireEmailVerification": true,
      "RequireSmsVerification": true,
      "RequireDigidVerification": false,
      "RequireSurfnetVerification": false,
      "SendSignRequest": true,
      "SendSignConfirmation": null,
      "SignRequestMessage": "Hello, could you please sign this document? Best regards, John Doe",
      "DaysToRemind": 15,
      "Language": "en-US",
      "ScribbleName": "John Doe",
      "ScribbleNameFixed": false,
      "Reference": "Client #123",
      "ReturnUrl": "http://signhost.com",
      "Activities": [
        {
          "Id": "91709d15-df2e-48a1-ac90-276f0360ce08",
          "Code": 103,
          "Activity": "Opened",
          "CreatedDateTime": "2016-06-15T23:33:04.1965465+02:00"
        },
        {
          "Id": "04adfda3-dd35-4f4d-af34-d2a08a4434f6",
          "Code": 203,
          "Activity": "Signed",
          "CreatedDateTime": "2016-06-15T23:38:04.1965465+02:00"
        }
      ],
      "RejectReason": null,
      "SignUrl": "http://ui.signhost.com/sign/d959e67b-acf8-4a49-8811-9b62f0b450af",
      "SignedDateTime": null,
      "RejectDateTime": null,
      "CreatedDateTime": "2016-06-15T23:33:04.1965465+02:00",
      "ModifiedDateTime": "2016-06-15T23:33:04.1965465+02:00",
      "Context": null
    }
  ],
  "Receivers": [
    {
      "Id": "df52316c-6671-4f39-9b9e-b524cc36ef93",
      "Name": "John Doe",
      "Email": "user@example.com",
      "Language": "en-US",
      "Message": "Hello, please find enclosed the digital signed document. Best regards, John Doe",
      "Reference": null,
      "Activities": null,
      "CreatedDateTime": "2016-06-15T23:33:04.1965465+02:00",
      "ModifiedDateTime": "2016-06-15T23:33:04.1965465+02:00",
      "Context": null
    }
  ],
  "Reference": "Contract #123",
  "PostbackUrl": "http://example.com/postback.php",
  "SignRequestMode": 2,
  "DaysToExpire": 30,
  "SendEmailNotifications": true,
  "CreatedDateTime": "2016-06-15T23:33:04.1965465+02:00",
  "ModifiedDateTime": "2016-06-15T23:33:04.1965465+02:00",
  "CanceledDateTime": null,
  "Context": null
}

DELETE: /api/transaction/{transactionId}

Description

Delete a transaction by a transaction id. When a transaction is not in an end-state (such as fully signed) the transaction will be cancelled and cleaned. A cancelled transaction can be told to send an e-mail notification to the awaiting signers that the transaction was cancelled. The status of the transaction will be set to cancelled.

When a transaction is in an end-state the transaction the transaction will be cleaned. The status of the transaction will remain the same but we will clean any uploaded documents and sensitive data as soon as possible.

Parameters

Name Location Required Description
transactionId path true ID of the transaction
body body false Cancellation details

Request Body

Name Type Default Description
SendNotifications boolean false Send e-mail notifications to the awaiting signers, when SendSignRequest has been set to true during the transaction creation.
Reason string The reason of cancellation.

Most common responses

200 The transaction is succesfully deleted
400 The transaction could not be deleted. #/definitions/ErrorModel

Example

Request: 
curl \
  -H "Authorization: APIKey {usertoken here}" \
  -H "Application: APPKey {appkey here}" \
  -H "Content-Type: application/json" \
  -d '{
    "SendNotifications": true,
    "Reason": "This document is out-dated"
    }'
  -X DELETE
  https://api.signhost.com/api/transaction/b2a9aca4-cd5e-4a21-b7f7-c08a9f2b2d57
Response:

This method returns the cancelled transaction.

{
  "Id": "67b9e140-b0f6-4c36-9b35-977041968185",
  "Status": 20,
  "Seal": true,
  "Signers": [
    {
      "Id": "e0b39ec0-e0c6-45d9-bf0d-ae8cafbe2f48",
      "Expires": null,
      "Email": "user@example.com",
      "Mobile": "+31612345678",
      "Iban": null,
      "BSN": null,
      "RequireScribbleName": false,
      "RequireScribble": true,
      "RequireEmailVerification": true,
      "RequireSmsVerification": true,
      "RequireIdealVerification": false,
      "RequireDigidVerification": false,
      "RequireSurfnetVerification": false,
      "SendSignRequest": true,
      "SendSignConfirmation": null,
      "SignRequestMessage": "Hello, could you please sign this document? Best regards, John Doe",
      "DaysToRemind": 15,
      "Language": "en-US",
      "ScribbleName": "John Doe",
      "ScribbleNameFixed": false,
      "Reference": "Client #123",
      "ReturnUrl": "http://signhost.com",
      "Activities": [
        {
          "Id": "91709d15-df2e-48a1-ac90-276f0360ce08",
          "Code": 103,
          "Activity": "Opened",
          "CreatedDateTime": "2016-06-15T23:33:04.1965465+02:00"
        },
        {
          "Id": "04adfda3-dd35-4f4d-af34-d2a08a4434f6",
          "Code": 203,
          "Activity": "Signed",
          "CreatedDateTime": "2016-06-15T23:38:04.1965465+02:00"
        }
      ],
      "RejectReason": null,
      "SignUrl": "http://ui.signhost.com/sign/d959e67b-acf8-4a49-8811-9b62f0b450af",
      "SignedDateTime": null,
      "RejectDateTime": null,
      "CreatedDateTime": "2016-06-15T23:33:04.1965465+02:00",
      "ModifiedDateTime": "2016-06-15T23:33:04.1965465+02:00",
      "Context": null
    }
  ],
  "Receivers": [
    {
      "Id": "df52316c-6671-4f39-9b9e-b524cc36ef93",
      "Name": "John Doe",
      "Email": "user@example.com",
      "Language": "en-US",
      "Message": "Hello, please find enclosed the digital signed document. Best regards, John Doe",
      "Reference": null,
      "Activities": null,
      "CreatedDateTime": "2016-06-15T23:33:04.1965465+02:00",
      "ModifiedDateTime": "2016-06-15T23:33:04.1965465+02:00",
      "Context": null
    }
  ],
  "Reference": "Contract #123",
  "PostbackUrl": "http://example.com/postback.php",
  "SignRequestMode": 2,
  "DaysToExpire": 30,
  "SendEmailNotifications": true,
  "CreatedDateTime": "2016-06-15T23:33:04.1965465+02:00",
  "ModifiedDateTime": "2016-06-15T23:33:04.1965465+02:00",
  "CanceledDateTime": "2016-06-15T23:34:15+02:00",
  "CancelationReason": "This document is out-dated",
  "Context": null
}

GET: /api/transaction/{transactionId}/file/{fileId}/

Description

Returns the (signed) document(s).

Parameters

Name Location Required Description
transactionId path true ID of the description
fileId path true A unique identifier provided by you for the file.

Most common responses

200 The contents of the file is returned in the body.

Example

Request: 
curl \
  -H "Authorization: APIKey {usertoken here}" \
  -H "Application: APPKey {appkey here}" \
  https://api.signhost.com/api/transaction/b2a9aca4-cd5e-4a21-b7f7-c08a9f2b2d57/file/Contract.pdf

GET: /api/file/receipt/{transactionId}

Description

Returns the receipt when the transaction is successfully signed (Status=30)

Parameters

Name Location Required Description
transactionId path true ID of the description

Most common responses

200 (signed) document(s)

Example

Request: 
curl \
  -H "Authorization: APIKey {usertoken here}" \
  -H "Application: APPKey {appkey here}" \
  https://api.signhost.com/api/file/receipt/b2a9aca4-cd5e-4a21-b7f7-c08a9f2b2d57

POST: /api/transaction

Description

Creates a new transaction

Parameters

Name Location Required Description
transaction body true Transaction to be added #/definitions/Transaction

Request Body

Name Type Default Description

Most common responses

200 Details of the created transaction. #/definitions/Transaction
401 Not authorized to create a transaction.

Example

Request: 
curl \
  -H "Authorization: APIKey {usertoken here}" \
  -H "Application: APPKey {appkey here}" \
-H "Content-Type: application/json" \
-d '{
  "Signers": [
    {
      "Email": "user@example.com",
      "SendSignRequest": true,
      "SignRequestMessage": "Hello, could you please sign this document? Best regards, John Doe",
      "DaysToRemind": 15,
      "Verifications": [
        {
          "Type": "iDeal"
        },
        {
          "Type": "Consent"
        }
      ]
    },
    {
      "Email": "anotheruser@example.com",
      "SendSignRequest": true,
      "SignRequestMessage": "Hello, could you please sign this document? Best regards, John Doe",
      "DaysToRemind": 15,
      "Verifications": [
        {
          "Type": "Consent"
        }
      ]
    }
    ],
    "SendEmailNotifications": true
    }'
    https://api.signhost.com/api/transaction/
Response:

This method returns the newly created transaction. The default values for the second signer have been stripped away. 

{
  "Id": "67b9e140-b0f6-4c36-9b35-977041968185",
  "Status": 20,
  "Seal": true,
  "Signers": [
    {
      "Id": "e0b39ec0-e0c6-45d9-bf0d-ae8cafbe2f48",
      "Expires": null,
      "Email": "user@example.com",
      "Mobile": null,
      "Iban": null,
      "BSN": null,
      "RequireScribbleName": false,
      "RequireScribble": false,
      "RequireEmailVerification": false,
      "RequireSmsVerification": false,
      "RequireDigidVerification": false,
      "RequireSurfnetVerification": false,
      "Verifications": [
        {
          "Type": "iDeal"
		},
		{
			"Type": "Consent"
		}
      ],
      "SendSignRequest": true,
      "SendSignConfirmation": null,
      "SignRequestMessage": "Hello, could you please sign this document? Best regards, John Doe",
      "DaysToRemind": 15,
      "Language": "en-US",
      "ScribbleName": null,
      "ScribbleNameFixed": false,
      "Reference": "Client #123",
      "ReturnUrl": "http://signhost.com",
      "Activities": [],
      "RejectReason": null,
      "SignUrl": "http://ui.signhost.com/sign/d959e67b-acf8-4a49-8811-9b62f0b450af",
      "SignedDateTime": null,
      "RejectDateTime": null,
      "CreatedDateTime": "2016-06-15T23:33:04.1965465+02:00",
      "ModifiedDateTime": "2016-06-15T23:33:04.1965465+02:00",
      "Context": null
    },
    {
      "Id": "b9d0f613-985d-4a5a-8e79-a83f7b5d6b55",
      "Email": "anotheruser@example.com",
      "Mobile": null,
      "RequireScribble": false,
      "RequireSmsVerification": false,
      "SendSignRequest": true,
      "SignRequestMessage": "Hello, could you please sign this document? Best regards, John Doe",
      "DaysToRemind": 15,
      "ScribbleName": null,
	  "ScribbleNameFixed": false,
	  "Verifications": [
		  {
			  "Type": "Consent"
		  }
	  ]
    }
  ],
  "Receivers": [
    {
      "Id": "df52316c-6671-4f39-9b9e-b524cc36ef93",
      "Name": "John Doe",
      "Email": "user@example.com",
      "Language": "en-US",
      "Message": "Hello, please find enclosed the digital signed document. Best regards, John Doe",
      "Reference": null,
      "Activities": null,
      "CreatedDateTime": "2016-06-15T23:33:04.1965465+02:00",
      "ModifiedDateTime": "2016-06-15T23:33:04.1965465+02:00",
      "Context": null
    }
  ],
  "Reference": "Contract #123",
  "PostbackUrl": "http://example.com/postback.php",
  "SignRequestMode": 2,
  "DaysToExpire": 30,
  "SendEmailNotifications": true,
  "CreatedDateTime": "2016-06-15T23:33:04.1965465+02:00",
  "ModifiedDateTime": "2016-06-15T23:33:04.1965465+02:00",
  "CanceledDateTime": null,
  "Context": null
}

PUT: /api/transaction/{transactionId}/file/{fileId}

Description

Add a file to the transaction or overwrite an existing file with the same {fileId}. The file parameter can either be the PDF document or JSON metadata. If your file requires metadata, the JSON metadata MUST be supplied first. Only PDF documents with Content-Type ‘application/pdf’ are accepted. Related posts How to create a transaction with api generated fields, howto create a transaction with fillable pdf fields.

File digest header

When uploading a file, it is possible to send a digest header along with the HTTP request. This header should contain a base64-encoded SHA checksum of the uploaded file. For more information on digest headers, refer to RFC 3230 for format instructions and RFC 5843 for the supported algorithms.

Supported Algorithms

Currently, only SHA-256 and SHA-512 are accepted as hash algorithms. While RFC 3230 originally included MD5 and SHA-1, these weaker algorithms are no longer supported for security reasons. Using SHA-256 or SHA-512 ensures compliance with modern security standards.

For example: Digest: SHA-256=HtHRpLOZBEMnTpQS6Zn12veC4uhjtMwamfVAwmPQPmE=

Parameters

Name Location Required Description
transactionId path true ID of an existing -- not yet started -- transaction
fileId path true A unique identifier provided by you for the file.
file body true File or file metadata. When the Content-Type is 'application/pdf' we expect the body to contain a valid PDF document which is to be signed by one or more signers. If you provide 'application/json' as a Content-Type we expect the body to contain a file meta data json. #/definitions/FileMetaData

Request Body

Name Type Default Description

Most common responses

201 File succesfully created and added to the transaction
204 Existing file replaced within the specified transaction
202 File meta data accepted, waiting for actual file content
409 Conflict while trying to overwrite the file. You have used the same fileId again which causes us to overwrite the file (which is a valid action). However the same fileId was provided in a too short time interval making it unclear which version was meant to be the latest version.

Example

Request: 
curl \
  -H "Authorization: APIKey {usertoken here}" \
  -H "Application: APPKey {appkey here}" \
  -H "Content-Type: application/pdf" \
  -H "Digest: SHA-256=HtHRpLOZBEMnTpQS6Zn12veC4uhjtMwamfVAwmPQPmE=" \
-XPUT \
  -T Contract.pdf \
https://api.signhost.com/api/transaction/b2a9aca4-cd5e-4a21-b7f7-c08a9f2b2d57/file/Contract.pdf

PUT: /api/transaction/{transactionId}/start

Description

Starts a transaction with the same {transactionId}

Parameters

Name Location Required Description
transactionId path true ID of an existing -- not yet started -- transaction

Most common responses

204 The transaction is started.
400 The transaction could not be started. Most probably causes are that the created transactions contains errors causing the transaction to be in Failed status. #/definitions/ErrorModel

Example

Request: 
curl \
  -H "Authorization: APIKey {usertoken here}" \
  -H "Application: APPKey {appkey here}" \
  https://api.signhost.com/api/transaction/b2a9aca4-cd5e-4a21-b7f7-c08a9f2b2d57/start

Models

These contain the type definitions as used by our API. We do our best to keep our API backwards compatible as long as you use documented features only. Only use the types and properties documented. Don't use undocument properties you see in the returned JSON as they may be obsoleted properties and/or contain invalid data. The sample data provided is purely fictional.

Transaction

Name Type Default Description
Id readonly string

The id of the transaction. Currently this property is read only but this may change in the future.

Files readonly object map of type #/definitions/FileEntry

A map of files attached to this transaction.

Language string (enum)
  • de-DE
  • en-US
  • es-ES
  • fr-FR
  • it-IT
  • pl-PL
  • nl-NL

The language of the sender notifications and the receipt, only de-DE, en-US, es-ES, fr-FR, it-IT, pl-PL and nl-NL are allowed.

Seal boolean false

Seal the document before sending to the signers.

Signers array of type

The signer information.

Id string

The id of the signer, must be unique within a transaction. If you don’t provide an id we will generate one for you.

Email required string

The e-mail address of the signer

IntroText string

An intro text to show to the user during the sign proces. This will be shown on the first screen to the signer and supports limitted markdown markup.

The following markup is supported:

  • # Headings
  • *Emphasis* / _Emphasis_
  • **Stong** / __Strong__
  • 1. Ordered and - Unordered lists
Authentications array of type #/definitions/Authentication

List of authentications that the signer has to authenticate with. The order in which the authentications are provided determine in which order the signer will have to perform the specified method.

Authentications must be performed before the document(s) can be viewed. When the authentication SecureDownload is configured, the download url for a signer is authenticated with the same method as the signing url. The download url is returned in the response, and (optionally) emailed to the signer..

You must explicitly specify the API-version when using this feature. This is done with the header: ‘Accept: application/vnd.signhost.v1+json’.

Verifications array of type #/definitions/Verification

List of verifications that the signer has to verify with. The order in which the verifications are provided determine in which order the signer will have to perform the specified method.

Verifications must be performed before the document(s) can be signed.

You must use one of the following verifications as the last method:

  • Consent
  • itsme sign*
  • PhoneNumber
  • Scribble
  • SigningCertificate*
  • CSC Qualified*

* These verifications can not be used in any other position than the last.

SendSignRequest boolean true

Send a sign invitation to the signer his e-mail address.

SignUrl readonly string

A unique URL per signer that provides the signing flow for the signer. Available / valid if SendSignRequest is set to false.

ShowUrl readonly string

A unique URL per signer that provides the secure download flow for the signer. Available / valid if any of the authentications SecureDownload field is set to true.

ReceiptUrl readonly string

A unique URL per signer that provides the secure receipt download flow for the signer. Available / valid if any of the authentications SecureDownload field is set to true.

SignRequestSubject string

The subject of the sign request email in plain text. Maximum of 64 characters allowed. Omitting this parameter will enable the default subject.

SignRequestMessage string

The message of the sign request in plain text. Newlines can be created by including a \n in the json, HTML is not allowed. Required if SendSignRequest is true

SendSignConfirmation boolean

Send the sign confirmation to the signer his e-mail address. Default value is the value of SendSignRequest

Language string (enum)
  • de-DE
  • en-US
  • es-ES
  • fr-FR
  • it-IT
  • pl-PL
  • nl-NL
nl-NL

The language of the receiving user, only de-DE, en-US, es-ES, fr-FR, it-IT, pl-PL and nl-NL are allowed.

ScribbleName string

The name of the signer, this will be pre filled in the scribble form.

DaysToRemind integer 7

Amount of days before reminding the signers. -1 to disable reminders. Ignored if SendSignRequest is set to false. By default your organisation’s setting will be used.

Expires string date-time

When set the signer is no longer allowed to sign the transaction after this date.

Reference string

The reference of the signer.

RejectReason readonly string

The rejection reason that was given by the signer when the transaction was rejected.

ReturnUrl string https://signhost.com

The url to redirect the user to after signing, rejecting or cancelling.

Context object

Any valid json object which we will return back to you when doing a GET on the transaction or when we send a postback.

Activities readonly array of type

List of activities attached to this signer. Activities are added by signhost when a signer event occured.

Id string
Code integer (enum)
  • 101
  • 102
  • 103
  • 104
  • 105
  • 201
  • 202
  • 203
  • 301
  • 302
  • 303
  • 401
  • 402
  • 403
  • 101 - Invitation sent
  • 102 - Received
  • 103 - Opened
  • 104 - Reminder sent
  • 105 - Document opened, Info property contains the file id of the opened document.
  • 201 - Cancelled
  • 202 - Rejected
  • 203 - Signed
  • 301 - Signed document sent
  • 302 - Signed document opended
  • 303 - Signed document downloaded
  • 401 - Receipt sent
  • 402 - Receipt opened
  • 403 - Receipt downloaded
Info string

May contain additional information belonging to this activity

CreatedDateTime string date-time
Receivers array of type
Name required string

The name of the receiver.

Email required string

The e-mail address of the reveiver.

Language string nl-NL

The language of the receiver, only de-DE, en-US, es-ES, fr-FR, it-IT and nl-NL are allowed.

Subject string

The subject of the receiver email in plain text. Maximum of 64 characters allowed. Omitting this parameter will enable the default subject.

Message required string

The email message towards the receiver in plain text. Newlines can be created by including a \n in the json, HTML is not allowed.

Reference string

The reference of the receiver.

Context object

Any valid json object which we will return back to you when doing a GET on the transaction or when we send a postback.

Reference string

The reference of the transaction. For example “1234”

PostbackUrl string

The absolute url to postback the status updates. For example https://example.com/postback.php

SignRequestMode integer int32 2

Set to 1 for sending at once, to 2 for sequential. Ignored if SendSignRequest is set to false.

DaysToExpire integer int32 60

Amount of days before expiration. Max 90 days.

SendEmailNotifications boolean true

Send e-mail notifications to the sender.

Status integer int32 (enum)
  • 5
  • 10
  • 20
  • 30
  • 40
  • 50
  • 60
  • 70

Current transaction status.

  • 5 - Waiting for document
  • 10 - Waiting for signer
  • 20 - In progress
  • 30 - Signed (end state)
  • 40 - Rejected (end state)
  • 50 - Expired (end state)
  • 60 - Cancelled (end state)
  • 70 - Failed (end state)
CancelationReason string

The original cancellation reason given during a DELETE call.

Context object

Any valid json object which we will return back to you when doing a GET on the transaction or when we send a postback.

Authentication

Name Type Default Description
Type required string (enum)
  • DigiD
  • PhoneNumber

Type of the authentication object. The Type property must be the first property in the json!

The order in which the authentications are provided determine in which order the signer will have to perform the specified method.

DigiD Authentication

Inherits properties from #/definitions/Authentication

Adds a DigiD step to the authentication process.

Name Type Default Description
Bsn string

The provided value must match the BSN of the credentials returned by DigiD. The BSN is required to match an ‘11-proef’.

Betrouwbaarheidsniveau readonly string (enum)
  • Basis
  • Midden
  • Substantieel
  • Hoog

The level of confidence with which the identity of the signer has been determined. For further information, please refer to Logius.

SecureDownload boolean false

Optional. Authentication method to be used to download the signed document(s).

A DigiD authentication response may have the following content:

{
    "Type": "DigiD",
    "Bsn": "910078476"
}

PhoneNumber Authentication

Inherits properties from #/definitions/Authentication
Name Type Default Description
Number string

The mobile phone number of the signer. Must conform to E.164, the international public telecommunication numbering plan, which requires the country calling code (e.g. +31).

SecureDownload boolean false

Optional. Authentication method to be used to download the signed document(s).

A phone number authentication response may have the following content:

{
  "Type": "PhoneNumber",
  "Number": "+31123456789"
}

Verification

Name Type Default Description
Type required string (enum)
  • Consent
  • DigiD
  • eHerkenning
  • eIDAS Login
  • iDeal
  • iDIN
  • itsme Identification
  • PhoneNumber
  • Scribble
  • itsme sign
  • SigningCertificate
  • SURFnet
  • CSC Qualified
  • OpenID Providers
  • Onfido

Type of the verification object. The Type property must be the first property in the json!

The order in which the verifications are provided determine in which order the signer will have to perform the specified method. You must use one of the following verifications as the last method:

  • Consent
  • itsme sign*
  • PhoneNumber
  • Scribble
  • SigningCertificate*
  • CSC Qualified*

* These verifications can not be used in any other position than the last.

Consent

Inherits properties from #/definitions/Verification

Adds a consent step to the signing process.

Name Type Default Description

A consent verification response may have the following content:

{
  "Type": "Consent"
}

DigiD

Inherits properties from #/definitions/Verification

Adds a DigiD step to the signing process.

Name Type Default Description
Bsn string

When provided, the provided value must match the BSN of the credentials returned by DigiD. The BSN is required to match an ‘11-proef’.

Betrouwbaarheidsniveau readonly string (enum)
  • Basis
  • Midden
  • Substantieel
  • Hoog

The level of confidence with which the identity of the signer has been determined. For further information, please refer to Logius.

A DigiD verification response may have the following content:

{
    "Type": "DigiD",
    "Bsn": "910078476"
}

eHerkenning

Inherits properties from #/definitions/Verification
Name Type Default Description
Uid readonly string
EntityConcernIdKvkNr string

When provided, the provided value must match the KvK number returned by eHerkenning.

eIDAS Login

Inherits properties from #/definitions/Verification
Name Type Default Description
Uid readonly string

The unique identifier returned by eIDAS Login.

Level readonly string

The Level of Assurance.

FirstName readonly string

The first name of the signer as returned by eIDAS Login.

LastName readonly string

The last name of the signer as returned by eIDAS Login.

DateOfBirth readonly string date

The date of birth of the signer as returned by eIDAS Login.

Attributes readonly map of string

Contains all available eIDAS Login attributes. These attributes may change, therefore we cannot guarantee the availability of any of these attributes.

An eIDAS Login verification response may have the following content:

{
    "Type": "eIDAS Login",
    "Uid": "ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789",
    "Level": "High",
    "FirstName": "John",
    "LastName": "van der Doe",
    "DateOfBirth": "1970-01-01",
    "Attributes": {
      "urn:etoegang:1.9:attribute:DateOfBirth": "1970-01-01",
      "urn:etoegang:1.9:attribute:FirstName": "John",
      "urn:etoegang:1.9:attribute:Initials": "J.",
      "urn:etoegang:1.9:attribute:FamilyName": "Doe",
      "urn:etoegang:1.9:attribute:FamilyNameInfix": "van der"
    }
}

iDeal

Inherits properties from #/definitions/Verification
Name Type Default Description
Iban string

The IBAN of the signer. When provided during the creation of the transaction this IBAN is verified during the verification flow to make sure these and the actual IBAN number match.

AccountHolderName readonly string
AccountHolderCity readonly string

An iDeal verification response may have the following content:

{
    "Type": "iDeal",
    "Iban": "NL01ABNA0123456789",
    "AccountHolderName": "DOE J",
    "AccountHolderCity": ""
}

iDIN

Inherits properties from #/definitions/Verification
Name Type Default Description
AccountHolderName readonly string

Name of the idin consumer / signer. Currently we don’t support supplying a value in this property to ensure the expected account holder name matches. This could change in the future.

AccountHolderAddress1 readonly string
AccountHolderAddress2 readonly string
AccountHolderDateOfBirth readonly string date

Date of birth of idin consumer / signer

Attributes readonly map of string

Contains all available iDIN attributes. These attributes may change, therefore we cannot guarantee the availability of any of these attributes.

An iDIN verification response may have the following content:

{
  "Type": "iDIN",
  "AccountHolderName": "John Doe",
  "AccountHolderDateOfBirth": "2001-12-31",
  "AccountHolderAddress1": "Straatlaan 123 AB",
  "AccountHolderAddress2": "AMSTERDAM 1234AB",
  "Attributes": {
      "urn:nl:bvn:bankid:1.0:consumer.bin": "xxxxx",
      "urn:nl:bvn:bankid:1.0:bankid.deliveredserviceid": "12345",
      "urn:nl:bvn:bankid:1.0:consumer.housenosuf": "AB",
      "urn:nl:bvn:bankid:1.0:consumer.postalcode": "1234AB",
      "urn:nl:bvn:bankid:1.0:consumer.houseno": "123",
      "urn:nl:bvn:bankid:1.0:consumer.initials": "JN",
      "urn:nl:bvn:bankid:1.0:consumer.street": "Straatlaan",
      "urn:nl:bvn:bankid:1.0:consumer.dateofbirth": "19800124",
      "urn:nl:bvn:bankid:1.0:consumer.legallastname": "Doe",
      "urn:nl:bvn:bankid:1.0:consumer.country": "NL",
      "urn:nl:bvn:bankid:1.0:consumer.city": "AMSTERDAM",
      "urn:nl:bvn:bankid:1.0:consumer.preferredlastname": "Doe",
      "urn:nl:bvn:bankid:1.0:consumer.addressextra": "#",
      "urn:nl:bvn:bankid:1.0:consumer.gender": "1",
      "urn:nl:bvn:bankid:1.0:consumer.partnerlastname": "Roe",
      "urn:nl:bvn:bankid:1.0:consumer.legallastnameprefix": "van der",
      "urn:nl:bvn:bankid:1.0:consumer.preferredlastnameprefix": "van der"
  }
}

itsme Identification

Inherits properties from #/definitions/Verification
Name Type Default Description
PhoneNumber string

The mobile phone number of the signer. Must be conform E.164, the international public telecommunication numbering plan, which requires the country calling code (Only the Belgian country calling code is supported: +32).

Attributes readonly map of string

Contains all available itsme Identification attributes. These attributes may change, therefore we cannot guarantee the availability of any of these attributes.

An itsme Identification verification response may have the following content:

{
    "Type": "itsme Identification",
    "PhoneNumber": "+32012345678"
    "Attributes": {
      "country": "BE",
      "email": "j.doe@example.nl",
      "email_verified": "False",
      "name": "John Doe",
      "phone_number_verified": "True",
      "gender": "male",
      "given_name": "John",
      "phone_number": "+32 012345678",
      "locale": "nl",
      "family_name": "Doe",
      "birthdate": "1935-07-31",
      "street_address": "viable  street",
      "locality": "Brussels",
      "postal_code": "1256"
    }
}

itsme sign

Inherits properties from #/definitions/Verification
Name Type Default Description
Issuer readonly string
Subject readonly string
Thumbprint readonly string

An itsme sign verification response may have the following content:

{
  "Type": "itsme sign",
  "Issuer": "CN=John Doe QC POC SELFSIGNED, C=NL, S=Noord-Holland, L=Haarlem, E=example@example.org, OU=IT, O=Evidos B.V.",
  "Subject": "CN=John Doe QC POC SELFSIGNED, C=NL, S=Noord-Holland, L=Haarlem, E=example@example.org, OU=IT, O=Evidos B.V.",
  "Thumbprint": "2B31AD44D93BE1FAED6B18A23ADF1BDD4DA0ECE8"
}

IPAddress

Inherits properties from #/definitions/Verification
Name Type Default Description
IPAddress readonly string

An IP Address verification response may have the following content:

{
  "Type": "IPAddress",
  "IPAddress": "198.51.100.42"
}

PhoneNumber

Inherits properties from #/definitions/Verification
Name Type Default Description
Number string

The mobile phone number of the signer. Must conform to E.164, the international public telecommunication numbering plan, which requires the country calling code (e.g. +31).

A phone number verification response may have the following content:

{
  "Type": "PhoneNumber",
  "Number": "+31123456789"
}

Scribble

Inherits properties from #/definitions/Verification
Name Type Default Description
RequireHandsignature boolean false

When set the signer is required to draw a hand signature, either via computer mouse, trackpad, or touchscreen.

ScribbleNameFixed boolean false

When set the signer will not be able to change its scribble name. When not set the signer can correct or provide a scribble name.

ScribbleName string

The name of the signer, this will be pre filled in the scribble form. Required if ScribbleNameFixed is set.

A scribble verification response may have the following content:

{
  "Type": "Scribble",
  "RequireHandsignature": true,
  "ScribbleName": "John Doe"
}

SigningCertificate

Inherits properties from #/definitions/Verification

A signing certificate allows a signer to sign a document with its own certificate, among others with a qualified certificate.

Name Type Default Description
Issuer readonly string
Subject readonly string
Thumbprint readonly string

A signing certificate verification response may have the following content:

{
  "Type": "SigningCertificate",
  "Issuer": "CN=John Doe QC POC SELFSIGNED, C=NL, S=Noord-Holland, L=Haarlem, E=example@example.org, OU=IT, O=Evidos B.V.",
  "Subject": "CN=John Doe QC POC SELFSIGNED, C=NL, S=Noord-Holland, L=Haarlem, E=example@example.org, OU=IT, O=Evidos B.V.",
  "Thumbprint": "2B31AD44D93BE1FAED6B18A23ADF1BDD4DA0ECE8"
}

SURFnet

Inherits properties from #/definitions/Verification
Name Type Default Description
Uid readonly string
Attributes readonly map of string

Contains all available SURFnet attributes. These attributes may change, therefore we cannot guarantee the availability of any of these attributes.

CSC Qualified

Inherits properties from #/definitions/Verification
Name Type Default Description
Issuer readonly string
Subject readonly string
Thumbprint readonly string

A CSC Qualified verification response may have the following content:

{
  "Type": "CSC Qualified",
  "Provider": "ZealiD Qualified",
  "Issuer": "CN=ZealiD Issuing CA 2020, O=ZealiD AB, OID.2.5.4.97=SE5569724288,E=support@zealid.com, STREET=Box 3437, Stockholm, PostalCode=11156, C=SE",
  "Subject": "CN=John Alexander Doe PASNL-NP11D0011 G=John Alexander, SN=Doe, C=NL,SERIALNUMBER=PASNL-NP1D0011",
  "Thumbprint": "2B31AD44D93BE1FAED6B18A23ADF1BDD4DA0ECE8"
}

Please be advised, the serial number might differ from one country to another. For example, in the Netherlands, personal number (BSN) can not be used for privacy reasons and is substituted by document number such as passport number, but in other countries this poses no problem.

Onfido

Inherits properties from #/definitions/Verification

Adds an Onfido verification step to the signing process.

Name Type Default Description
WorkflowId string (UUID)

(OPTIONAL) When a value is provided, it should match a configured workflow for the organization. If no value is provided, the default Onfido workflow will be used.

An Onfido verification response may have the following content:

{
    "Type": "Onfido",
    "WorkflowId": "dba0c424-023c-4454-b0ce-72ce625b08c0"
}

OpenID Providers

Inherits properties from #/definitions/Verification

Adds an OpenID verification step to the signing process.

Name Type Default Description
ProviderName string

(OPTIONAL) When value is provided, it should match the configured one for the organization. If the value does not match then the full list of the organization providers will be given for the end-user to select during the verification step.

A OpenID verification response may have the following content:

{
    "Type": "OpenID Providers",
    "ProviderName": "Entrust IDaaS"
}

FileEntry

Name Type Default Description
Links array of type #/definitions/Link
DisplayName string

The name of the document that was displayed to the user while signing the documents.

FileMetaData

Name Type Default Description
DisplayOrder integer

With what order number we’ll display the file to the signer

DisplayName string

With what name we’ll display the file to the signer

SetParaph bool

Places a copy of the signer’s scribble image on the bottom right of every page where no signature is present. Note: due to the nature of advanced or qualified digital signatures, paraphs are merely a cosmetic addition.

Signers object map of type

Map of array of formsets. Each key should be a valid signer id.

FormSets array of type

List of formset keys to be assigned to this signer.

FormSets object map of type

Map of one or more form set definitions. The key of the map will be the formset name. The value will be the formset definition

<,> object map of type

Map of pdf field definitions. The key of the map will be the field name. The following characters are allowed as a key / field name: a-z A-Z 0-9 _.

The value will be the definition of the field.

Type string (enum)
  • Seal
  • Signature
  • Check
  • SingleLine

Field type to create.

  • Seal is not yet implemented, this will specify the properties of a seal.
  • Signature, specifies a signature field
  • Check, specifies a checkbox. You’ll have to set the value property
  • SingleLine, specifies a single line textbox
Location object

Specify where the field should be placed within the document.

Search string

The text to search in the pdf document to use as the position for the field. For example {{Signer1}}.

Occurence integer

When using text search, only match this matched occurence.

Top integer

Offset from the top of the search text or the page

Right integer

Offset from the right of the search or the page

Bottom integer

Offset from the bottom of the search or the page

Left integer

Offset from the left of the search or the page

Width integer

The width of the field, can’t be used when both Left and Right are specified. For signature and seal fields we suggest a width of 140.

Height integer

The height of the field, can’t be used when both Bottom and Top are specified. For signature and seal fields we suggest a height of 70.

PageNumber integer

On which page the field should be placed.

Simple example which performs a scan for the {{Signer1}} mustache tag and creates a Signature fields named SignatureOne on the found location(s).

  {
    "DisplayName": "Your personal contract",
    "SetParaph": true,
    "Signers": {
      "SomeSignerId": {
        "FormSets": [ "FirstFormset" ]
      }
    },
    "FormSets": {
      "FirstFormset": {
        "SignatureOne": {
          "Type": "Signature",
          "Location": {
            "Search": "{{Signer1}}",
            "Width": 140,
            "Height": 70
          }
        }
      }
    }
}

ErrorModel

Name Type Default Description
Message string

Message describing the error in the request.