OKSign API

This information is only available in English.

History

Document history
2024-10-22	Added EmailTemplates.retrieve service to retrieve a list of email templates defined in the account
2023-11-25	Added Users.retrieve service to retrieve a list of users in the account
2023-11-18	Briefcase.create service: Added `webhookurl` as possible parameter.
2023-10-28	Added Contacts.upload service to insert or update contact(s) in the account's contacts list. Added Contacts.retrieve service to retrieve a list of account's contacts.. Added Contacts.remove service to remove contact(s) from the account's contacts list.
2023-10-21	Add Email/SMS workflow so signatures can be collected in a specific order. See Example 12: Add Email/SMS workflow
2023-07-15	Added `filename` parameter to the `Documents.signed` service response).
2023-04-15	As of now the `Audittrail.retrieve` service expects the x-oksign-docid parameter to be signed docid of the signed documen (no longer the source_docid).
2023-03-25	Restrict Text(Area) data input by using validation rules. See Example 11: Add validation rules to Text(Area) fields
2022-07-16	Add a teammember's countersignature to a document. See FormDesc.upload service example 10 Editor.create service: Added `showTeammembers` parameter
2022-06-07	Added RateLimiter documentation
2022-01-31	Notifications.upload service available allowing to (re)send email(s) and/or SMS(s) after uploading a Form Descriptor
2022-01-31	Briefcase.create, Briefcase.retrieve and Briefcase.remove services available allowing to bundle documents together so these documents can be signed together with 1 siging link by the signer(s).
2021-11-21	EmailAttachment.upload and EmailAttachment.remove services available
2021-09-21	API methods flow Added `creditsinfo` JSONArray as callbackurl/returnurl parameter so the number of credits consumed per signer can be processed.
2021-09-18	Editor.create service Added `showAnonymousSigners`, `showMeSigner`, `showSigningOptions` parameters
2021-09-04	Documents.active service available
2021-05-05	Audittrail.retrieve service available

General information

Use the

API to easily scale from simple eSignature integrations to complex enterprise applications.
The

API is exposed as REST web services.
In case of questions, contact us at support@betrust.be

REST endpoint

The REST root endpoint is located at https://oksign.be/services/rest/v1 Each service is defined with a noun and verb added to the endpoint:

https://oksign.be/services/rest/v1/{noun}/{verb}

Authentication

The API requires authentication for all its methods.
The authentication data is passed as the value of a custom HTTP header called x-oksign-authorization. The x-oksign-authorization header's value is the combination of:

Your accountnumber;
The authorization token defined in your account;
The organizational token defined in your account

Example: x-oksign-authorization = 100693;463204-5BC1F362-85AD-34A3-9DB5-DC891D20979E;marketing
The authorization token can be linked to a callbackURL, returnURL and webhookURL (all optional).
If your application cannot receive http requests, API Polling can be used to find out which documents have been signed in a defined timeframe.
Organizational tokens can be defined in your account, menu-item REST API --> API Console.

API response result

Each response contains a JSONObject describing a status and reason. The return code is always 200.
The response is a JSONObject indicating the status and the reason:

If the status is OK the reason will give more information.
If the status is FAILED the reason will give more information about the error that occured.

Example (success):

{
 "reason": "{ "https://oksign.be/sign/100693/gtOZQBecrNHpdx_z6i..."},
 "status": "OK"
}

Example (failure):

{
 "reason": ""Invalid format x-oksign-docid. Found: 'zzz'. Expected: A valid format",
 "status": "FAILED"
}

Note: The Document.retrieve and Audittrail.retrieve services return a PDF document. In case of error a 404 error is returned.
Note: If a really bad error occures a 500 - Internal Server Error is thrown.

Rate limits

FREE (non paying) accounts have a limitation of sending 20 emails using the API services. Do you need more for your API testing? Contact us at support@betrust.be

As some requests consume more resources to handle than others, different rate limits are imposed.
Different requests per second (RPS) are applicable as follows:

`Document.upload`	3 RPS
`Document.retrieve`	3 RPS
`Metadata.retrieve`	3 RPS
`Documents.signed`	1 request per 3 minutes
`Documents.active`	1 request per 3 minutes
`Webhooks.retrieve`	1 request per 3 minutes
All other endpoints	10 RPS

If a request is called too often a 429 Too Many Requests response code is returned.

Credits and account's storage size

The account's storage size is limited. You can monitor the available/maximum storage size and available credits as follows:

Using the Account's Dashboard

Using the API

Use the Credits.retrieve service (see below).

Checking the API response (header)

Credits
All services add following entry in the response header:

X-AccountCredits-Remaining : -3.158

This way the number of remaining credits can be monitored.
Some services (see table below) perform a credits balance check and return following response in case no credits are available in your account. Example:

{
 "reason": "{ Insufficient credits. Found: -3.158.Expected: A positive balance. Please buy credits in your account.}",
 "status": "FAILED"
}

Account's storage
The Document.upload service adds following entries in the response header:

X-AccountStorage-Limit :671088640
X-AccountStorage-Remaining :-12586
X-AccountStorage-Reset never

This way the available storage capacity can be monitored.
A storage check is done and if no storage is available when uploading a document following response is returned:

{
 "reason": "{ Max account size exceeded. Maximum size allowed (bytes): 671088640. Current size (bytes): 671089857.)},
 "status": "FAILED"
}

Please find below the list of which services do a credit and/or storage check:

Service	Credit check	Storage check
`Document.upload`		YES
`FormDesc.upload`
`Notifications.upload`	YES
`FormDesc.retrieve`	YES
`Document.retrieve`	YES
`Document.exists`
`Document.remove`
`Metadata.retrieve`	YES
`Documents.active`	YES
`Documents.signed (API polling)`	YES
`Webhooks.retrieve (API polling)`	YES
`Credits.retrieve`
`Audittrail.retrieve`	YES

Notes:

The account's storage size increases when credits are bought with a maximum of 360Mb.
Please remove regularly (signed) documents from your account if no longer used. No documents are automatically removed from your account.
Documents can still be uploaded even if credits are negative as not to impact the service to your customers.
Documents can still be signed even if storage has exceeded or credits are negative as not to impact the service to your customers.

API methods flow

The typical use of the web services is as follows:

Upload a document (PDF or Word) to the platform using the Document.upload service.
Upload a form descriptor (describing the form's (signature) fields) to the platform using the Formdesc.upload service.
The Formdesc.upload service returns a signing URL you can send to the signer(s).
Upload notifications (if needed) defining email(s) and/or SMS(es) to be send to the signer(s) using the Notifications.upload service. The email and/or SMS informs a signer the document or briefcase is ready for signing. A signing link is added to the email's/SMS content).
If emails or SMSs are send, the GET webhookURL - if defined - is called in case of any errors (or use the Webhooks.retrieve service as a polling mechanism to get an overview of errors).
Once a document has been signed the GET callbackURL - if defined - is used to inform your application a document has been signed (otherwise API polling can be used).
Following parameters are added to the callbackURL. Example:
```
https://your.website.com/callbackurl/?source_docid=897215-59BFAC70-6257-1260-F259-6259A18EECE0
&signed_docid=656858-6072474D-80A0-D54A-4937-4FD639BAE9B6
&fields_completed=%5B%22SIG_FIELD_1%22%2C%22SIG_FIELD_2%22%5D
&orgtoken=sales
&accountnbr=100123
&ts=2020-08-03T10%3A57%3A35%2B02%3A00
&nbrOfSigaturesRequired=2
&nbrOfSigaturesValid=2
&creditsinfo=%5B%7B%22signerid%22%3A%20%22bt_00000000-0000-0000-0000-000000000001%22%2C%22signingoption%22%3A%20%22itsme%22%2C%22credits%22%3A%203%2C%22subscription%22%3A%200%7D%5D
```
The source_docid is the docid of the document that has been uploaded before.
The signed_docid is the docid of the signed copy of the source document.
The fields_completed contains a list (JSONArray) of the completed fields (signature and other fields).
The orgtoken contains the name of the organisational token by which the document was uploaded with.
The accountnbr contains the accountnumber.
The ts defines the current timestamp.
The nbrOfSigaturesRequired defines the number of signatures boxes in the document.
The nbrOfSigaturesValid defines the number of signatures boxes completed.
The creditsinfo defines for each signer the number of credits consumed.

Notes:
- The callbackURL, returnURL and webhooksURL requests are send using a GET method.
- The creditsinfo is a JSONArray containing for each signer the signingmethod used and the number of credits consumed. The number of credits consumed is the sum of the credits and subscription values. Example:
```
 [
{
"signerid": "bt_00000000-0000-0000-0000-000000000001",
"signingoption": "itsme",
"credits": 3,
"subscription": 0
}
]
```
  The signingoptions are 'pen', 'tan', 'itsme", 'eid'. 'tan' is signing via a TAN code send via SMS.
- If the nbrOfSigaturesRequired equals nbrOfSigaturesValid then all signatures are in place and the document is completely signed.
- It is possible in future versions new parameters are added
- The parameters source_doc and signed_doc have been renamed to source_docid and signed_docid to be consistent with the naming used in the Documents signed service. The old parameters remain in the parameters list but please update your code.
- If the credits balance in your account is negative, sending of callbacks is deferred until the balance becomes positive again.
The GET returnURL - if defined - is used to redirect the browser to whatever location is requested.
Following request parameters are added to the returnURL. Example:
```
https://your.website.com/returnurl/?status=OK
&source_docid=897215-59BFAC70-6257-1260-F259-6259A18EECE0
&signed_docid=656858-6072474D-80A0-D54A-4937-4FD639BAE9B6
&fields_completed=%5B%22SIG_FIELD_1%22%2C%22SIG_FIELD_2%22%5D
&orgtoken=sales
&accountnbr=100123
&ts=2020-08-03T10%3A57%3A35%2B02%3A00
&nbrOfSigaturesRequired=2
&nbrOfSigaturesValid=2
&creditsinfo=%5B%7B%22signerid%22%3A%20%22bt_00000000-0000-0000-0000-000000000001%22%2C%22signingoption%22%3A%20%22itsme%22%2C%22credits%22%3A%203%2C%22subscription%22%3A%200%7D%5D
```
The status is OK if the document has been successfully signed, FAILED otherwise.
The source_docid is the docid of the document that has been uploaded before.
Following parameters are only added in case the document has been successfully signed:
The signed_docid is a signed copy of the source document (only if status = OK).
The fields_completed contains a list (JSONArray) of the completed fields (signature and other fields).
The orgtoken contains the name of the organisational token by which the document was uploaded with.
The accountnbr contains the accountnumber.
The ts defines the current timestamp.
The nbrOfSigaturesRequired defines the number of signatures boxes in the document.
The nbrOfSigaturesValid defines the number of signatures boxes completed.
The creditsinfo defines for each signer the number of credits consumed.

Notes:
- The creditsinfo is a JSONArray containing for each signer the signingmethod used and the number of credits consumed. The number of credits consumed is the sum of the credits and subscription values. Example:
```
 [
{
"signerid": "bt_00000000-0000-0000-0000-000000000001",
"signingoption": "itsme",
"credits": 3,
"subscription": 0
}
]
```
- If the nbrOfSigaturesRequired equals nbrOfSigaturesValid then al signatures are in place and the document is completely signed.
- It is possible in future versions new parameters are added
- The parameters source_doc and signed_doc have been renamed to source_docid and signed_docid to be consistent with the naming used in the Documents signed service. The old parameters remain in the parameters list but please update your code.
You can use the Document.retrieve and Metadata.retrieve services to get the signed copy of the document (passing the signed_docid value) and any metadata (content of completed fields, more info over the signatures placed on the document).
Use the Document.remove service to remove the (signed) document from the platform.

List of available services

Basic services:

`Document.upload`	POST Upload a document (PDF or Word) to the platform
`FormDesc.upload`	POST Upload the Form Descriptor to the platform
`Notifications.upload`	POST Upload the Notifications to the platform
`FormDesc.retrieve`	GET Retrieve the previously uploaded Form Descriptor. This allows you to detect if any FormDesc changes that were made using the Document Editor (like adding or removing fields).
`Document.retrieve`	GET Retrieve a (signed) document from the platform
`Document.exists`	GET Does a (signed) document still exists on the platform?
`Document.remove`	DELETE Remove a (signed) document from the platform
`Metadata.retrieve`	GET Retrieve the metadata from a (signed) document so all fields and signature can be automatically processed in you application.
`Documents.active`	GET Retrieve a list of all active documents (all documents visible in the Active Documents tab).
`Documents.signed (API polling)`	GET Retrieve a list of docids of signed documents in a defined timeframe.
`Webhooks.retrieve (API polling)`	GET Retrieve a list of webhooks indicating a problem with sending an email or SMS in a defined timeframe.
`Credits.retrieve`	GET Retrieve more information about your credits.
`Audittrail.retrieve`	GET Retrieve the Audit Trail Report of a (signed) document.

Additional services:

Below the list additional services which might come in handy:

Briefcase services

The Briefcase services bundles documents together so they can be signed using one signing link per signer.

`Briefcase.create`	POST Upload a JSONObject defining which documents to sign and other properties.
`Briefcase.retrieve`	GET Retrieve a previously uploaded Briefcase tokeninfo JSONObject for consultation.
`Briefcase.remove`	DELETE Remove a previously created Briefcase from the platform.

Email Attachment services

The Email Attachment services allows you to add attachment(s) to an email sent via your

account (when sending the signing link(s) to the signer(s)).

`EmailAttachment.upload`	POST Upload a file to be added as attachment to an email sent from your platform.
`EmailAttachment.remove`	DELETE Remove a previously uploaded attachment file.

EditorExpress services

The EditorExpress services allows you to invoke the

Editor in your own application so the user can modify the document. Afterwards the modified FormDescriptor can be read using the FormDesc.retrieve service.

`EditorExpress.create`	POST Upload a tokeninfo JSONObject defining which document to show in the editor.
`EditorExpress.retrieve`	GET Retrieve a previously uploaded EditorExpress tokeninfo JSONObject for consultation.
`EditorExpress.remove`	DELETE Remove a previously uploaded EditorExpress tokeninfo JSONObject from the platform.

SignExpress services

Add a 'Sign now' button in your application and use the SignExpress service to have an end-to-end flow between your application and OK!Sign.

`SignExpress.create`	POST Upload a tokeninfo JSONObject defining which documents to sign and by which signer (and other properties).
`SignExpress.retrieve`	GET Retrieve a previously uploaded SignExpress tokeninfo JSONObject for consultation.
`SignExpress.remove`	DELETE Remove a previously uploaded SignExpress tokeninfo JSONObject from the platform.

Document Upload service

URL	`https://oksign.be/services/rest/v1/document/upload`
Title	Document upload Upload a PDF or Word document that needs to be completed and/or signed.
Method	POST
Request Headers	The x-oksign-authorization header's value is the combination of: Your accountnumber; The authoriation token defined in your account; The organizational token defined in your account Example: `x-oksign-authorization = 100693;463204-5BC1F362-85AD-34A3-9DB5-DC891D20979E;marketing` The x-oksign-filename is the filename of the uploaded file. Headers only support US-ASCII characters. If you need to pass filenames with characters outside the US-ASCII range please define the filename in the `FormDesc.upload service (see Example 6: Add filename to the Form Descriptor)`. Example: `x-oksign-filename = name.pdf` The content-type header depends whether or not the body is a PDF or Word document: .pdf : `content-type = application/pdf` .doc : `content-type = application/msword` .docx: `content-type = application/vnd.openxmlformats-officedocument.wordprocessingml.document` The accept header should be application/json as a response in JSON format is returned. `accept = application/json; charset=utf-8`
Body	Put the raw PDF of Word file in the body. Example: %PDF-1.5 %µµµµ 1 0 obj <</Type/Catalog/Pages 2 0 R/Lang(nl-BE) /StructTreeRoot 59 0 R/MarkInfo<</Marked true>>>> endobj ...
Success Response	The response is a JSONObject indicating the status (OK, FAILED) and the reason is the documentID of the uploaded document. This docid is needed with other webservices. Example: { "reason": "670816-483B7F54-8591-DDF9-FA77-9042AED3E8FD", "status": "OK" }
Error Response	In case of a severe error a 500 Internal Server Error is thrown.
Notes	The maximum size of the file can be 8 MB. Uploading Word documents (.doc, docx) takes considerable more time (+/ 10 to 50 seconds depending on the size/content of the document) as the document is converted to PDF. The Conversion process is not flawless and errors in the conversion process can occur (for example: Text not strikethrough in converted document). IMPORTANT: Uploaded documents remain in your account until all signatures are in place (afterwards the uploaded document is automatically removed) or the document is removed by you. The FormDescriptor can be uploaded as a `JSONObject`. The field definitions for a document can be copied The field definitions for a document can be copied from your account using the Document Editor.

Formdesc Upload service

URL https://oksign.be/services/rest/v1/formdesc/upload

Title

FormDesc upload
The FormDescriptor defines the fields to be added to the document. The allowed fields are:

Text: A text field;
TextArea: A textarea field;
Select: A select field;
Date: A date field;
Checkbox: A checkbox field;
CanvasSIG: A Signature box field

It can also:

define notifications (email or SMS) to be send to the signer(s) informing a document is ready to be signed.
define the logo to be displayed during the signing process.
define the filename of the uploaded document.
prefill values of fields (and whether or not these values can be changed by the signer).

The FormDescriptor can be uploaded as a JSONObject. The field definitions for a document can be copied from your account using the Document Editor.
Do as follows:

Login into your account;
Select the Active documents (Actieve documenten, Documents actifs) button
Click on the wrench button of the document you want to copy the field(s) from (if needed upload a document and add the field(s) to it using the Document Editor).
The Forms Editor opens. Select the API button to copy the Form Descriptor (JSONObject):

Now add the copied JSONObject to the body of this service (example below).

Note: You can (programmatically) modify the content of this JSONObject before adding
it to this service giving you all freedom to tailer the fields when uploading other (type of) documents if needed (see the examples below).

Method POST

Request
Headers

The x-oksign-authorization header's value is the combination of:

Your accountnumber;
The authoriation token defined in your account;
The organizational token defined in your account

Example: x-oksign-authorization = 100693;463204-5BC1F362-85AD-34A3-9DB5-DC891D20979E;marketing
The x-oksign-docid is the docid you received when uploading the document Document.upload service.

x-oksign-docid = 670816-483B7F54-8591-DDF9-FA77-9042AED3E8FD

The content-type header should be application/json as the body is in JSON format:

content-type = application/json; charset=utf-8

The accept header should be application/json as a response in JSON format is returned.

accept = application/json; charset=utf-8

Body

The body is a JSONObject containing:

A reusable JSONString indicating whether multiple copies of this document could be signed (this is false for personalized documents (contracts, ordernotes; ...) .
A fields JSONArray defining the fields to use with this document.
A signersinfo JSONArray defining the properties of each signer.
A notifications JSONObject defining the properties of the email(s) or SMSs to send (optional).
A logo JSONString defining the url of the logo to be displayed during the signing process (if not defined the account logo is displayed as defined in the account's setting (See Settings --> Company data --> Company logo)
A sendtomeonly Boolean defining whether or not the signed document should be send to all signers (or only to the account's email)
A sendtomeemail defining an alternative email address to send the signed document to instead of the account's email

Below some examples you can copy/paste and modify as needed for your own situation:

Example 1: Pass a JSONObject with pagenbr, posX and posY for each field
Example 2: Pass a JSONObject with a marker parameter for each field
Example 3: Add notifications to the Form Descriptor
Example 4: Add logo to the Form Descriptor
Example 5: Add sendtomeonly to the Form Descriptor
Example 6: Add filename to the Form Descriptor
Example 7: Prefilling of fields
Example 8: Assign a document to a user
Example 9: Add sendtomeemail to the Form Descriptor
Example 10: Add (a) teammember's (user's) countersignature(s) to the Form Descriptor
Example 11: Add validation rules to Text(Area) fields
Example 12: Add email/sms workflow

Example 1: Pass a JSONObject with pagenbr, posX and posY for each field
If you know the position of each field in the document, you can define each field with its pagenbr, posX, posY parameters.

Raw
{
    "reusable": false,
    "fields": [
        {
            "inputtype": "CanvasSIG",
            "name": "SIG_FIELD_1",
            "required": true,
            "pagenbr": 0,
            "posX": 119.89,
            "posY": 712.73,
            "width": 175,
            "height": 70,
            "signerid": "bt_00000000-0000-0000-0000-000000000100",
            "signingoptions": {
                    "eid": {},
                    "pen": {},
                    "tan": {},
                    "itsme": {}
            }
        },
        {
            "inputtype": "CanvasSIG",
            "name": "SIG_FIELD_2",
            "required": true,
            "pagenbr": 0,
            "posX": 331.56,
            "posY": 712.73,
            "width": 175,
            "height": 70,
            "signerid": "bt_00000000-0000-0000-0000-000000000200",
            "signingoptions": {
                    "eid": {},
                    "pen": {},
                    "tan": {},
                    "itsme": {}
            }
        },
        {
            "inputtype": "Text",
            "name": "FIELD_1",
            "required": true,
            "pagenbr": 0,
            "posX": 152.13,
            "posY": 476.26,
            "height": 20.67083333333333,
            "width": 300.1405,
            "fontsize": "12"
        }
    ],
    "signersinfo": [
      {
        "name": "John Lennon",
        "mobile": "+32495123456",
        "actingas": "Singer / Songwriter",
        "id": "bt_00000000-0000-0000-0000-000000000100",
        "email": "john.lennon@imagine.com"
      },
      {
        "name": "",
        "mobile": "",
        "actingas": "",
        "id": "bt_00000000-0000-0000-0000-000000000200",
        "email": "yoko.ono@imagine.com"
      }
    ]
}

A signersinfo JSONArray allows you to define for each Signature box (CanvasSIG) field the signer's name, actingas (function), email and mobile number. This way the signer does not need to enter this data and you keep full control of these properties during the signing process.
The signerid (bt_00000000-0000-0000-0000-000000000100 in above example) defines which CanvasSIG field corresponds to which entry in the signersinfo JSONArray.
Notes:

If the the signer's name, actingas (function) and email are defined, the 'Personal info needed' screen is skipped and the signer can immediately view and sign the document. If the signer needs to be able to modify this data, add a readonly=false key/value pair.
```
{
  "name": "John Lennon",
  "mobile": "+32495123456",
  "actingas": "Singer / Songwriter",
  "id": "bt_00000000-0000-0000-0000-000000000100",
  "email": "john.lennon@imagine.com"
  "readonly": false,
}
```
If the email address is in the account's addressbook, this information is used to complete any empty properties.

The mobie number must be in E164 format. Some examples of E164 format below:

E.164 Format	Country Code	Country	Subscriber Number
+32495123456	32	BE	495123456
+442071838750	44	GB	2071838750
+551155256325	55	BR	1155256325

The allowed format of the signerid is (regex notation): bt_00000000-0000-0000-0000-0000000-[0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9]. So only the last 12 digits can be defined (for now).
It is encouragned (but not obliged) to calculate signerid by using the Signerid.calculate service.

Example 2: Pass a JSONObject with a marker parameter for each field
If you don't know the exact position of the (signature) field(s) (you use a report generator and cannot calculate these values for each field) you can use markers instead (see below).
Do as follows:

In your PDF/Word document mark each field position with a unique text, for example: _sb1_
Now reference this text in the marker key/value pair of the corresponding field (see below).
You no longer define the pagenbr, posX and posY parameters (as you don't know these values).
You still need to define the width and height of the field (it is adapted automatically if the values are too big to fit on the page).

Raw
{
    "reusable": false,
    "fields": [
        {
            "marker": "_sb1_",
            "inputtype": "CanvasSIG",
            "name": "SIG_FIELD_1",
            "required": true,
            "pagenbr": 0,
            "posX": 119.89,
            "posY": 712.73,
            "width": 175,
            "height": 70,
            "signerid": "bt_00000000-0000-0000-0000-000000000100",
            "signingoptions": {
                    "eid": {},
                    "pen": {},
                    "tan": {},
                    "itsme": {}
            }
        },
        {
            "marker": "_sb2_",
            "inputtype": "CanvasSIG",
            "name": "SIG_FIELD_2",
            "required": true,
            "pagenbr": 0,
            "posX": 331.56,
            "posY": 712.73,
            "width": 175,
            "height": 70,
            "signerid": "bt_00000000-0000-0000-0000-000000000200",
            "signingoptions": {
                    "eid": {},
                    "pen": {},
                    "tan": {},
                    "itsme": {}
            }
        },
        {
            "marker": "_text1_",
            "inputtype": "Text",
            "name": "FIELD_1",
            "required": true,
            "pagenbr": 0,
            "posX": 152.13,
            "posY": 476.26,
            "height": 20.67,
            "width": 300.14,
            "fontsize": "12"
        }
    ],
    "signersinfo": [
      {
        "name": "John Lennon",
        "mobile": "+32495123456",
        "actingas": "Singer / Songwriter",
        "id": "bt_00000000-0000-0000-0000-000000000100",
        "email": "john.lennon@imagine.com"
      },
      {
        "name": "",
        "mobile": "",
        "actingas": "",
        "id": "bt_00000000-0000-0000-0000-000000000200",
        "email": "yoko.ono@imagine.com"
      }
    ]
}

Remarks:
Keep the ratio between width and height of each CanvasSIG field at 3. Good dimensions are width:150 and height:50.
The marker defines the top-left position of the signature box, so keep this into account when defining the marer location on the page.

Example 3: Add notifications to the Form Descriptor
Preferably use the Notifications.upload service allowing you to (re)send email(s) and/or SMS(s) at any time after uploading the Form Descriptor.
Define a notifications JSONObject to inform signers via email and/or SMS that a document is ready to be signed.
The notifications JSONObject can contain a smtp and/or sms JSONObject defining the attributes of the email(s) or SMS(s) to send.

Raw
{
	"reusable": false,

	"notifications": {
		"smtp": {
                        "sender": "Bill Gates",
			"to": ["bt_00000000-0000-0000-0000-000000000001"],
			"cc": [],
			"subject": "Contract_TEST_14-10-2019.pdf",
			"body": "<p>Dear,<br/> click the button below to start the signing process.</p>",
			"reminder_days": 3,
			"repeat": 3,
			"language" : "fr",
			"delay": 0
		},
		"sms": {
			"to": ["bt_00000000-0000-0000-0000-000000000001"],
			"subject": "Please sign the document Contract_0025847 via link:",
			"reminder_days": 0,
			"repeat": 0,
			"delay" : 0,
			"language" : "nl"
		}
	},

	"fields": [
		{
			"signerid": "bt_00000000-0000-0000-0000-000000000001",
			"height": 82.68,
			"inputtype": "CanvasSIG",
			"name": "SIG_FIELD_1",
			"pagenbr": 4,
			"posX": 51.26,
			"posY": 390.27,
			"required": true,
			"signingoptions": {
				"eid": {},
				"pen": {},
				"tan": {},
                                "itsme": {}
			},
			"width": 204.23
		}
	],
	"signersinfo": [
		{
			"mobile": "32495XXXXXX",
			"name": "Bill Gates",
			"actingas": "Tester",
			"id": "bt_00000000-0000-0000-0000-000000000001",
			"email": "bill.gates@microsoft.xxx"
		}
	]
}

The smtp JSONObject has following parameters:

Parameter	R/O	Description
`sender`	Optional String	The name of the sender (not an email address). The recipient will see this as: Bill Gates via OK!Sign <no-reply@oksign.be>. If absent, the name is taken from the Company field defined via Settings --> Company Data --> Name and Logo. If this field is empty the sender name is defined as Your companyname.
`to`	Required JSONArray	The list of signers ids to send emails to. The id should correspond to an `id` defined in the `signersinfo` list. The email of each signer should be defined in the `signersinfo` list. To add Email workflow, consult Example 12: Add email/sms workflow
`cc`	Optional JSONArray	The list of emails that should be in Cc:. Leave empty or omit if not needed.
`replyto`	Optional String	Email address on which recipients will be able to reply back. If not defined, the replyto is the `assignto` value (if defined). Otherwise the account's email address.
`subject`	Required String	The subject of the email in regular format (not HTML).
`body`	Required String	The body of the email in HTML format.
`delay`	Optional Int	Should emails be send with a delay? The delay is measured in hours. Example: delay=3: The email(s) are send 3 hours after this request has been uploaded. If you want to send the email immediately, omit this property or set `delay=0`.
`repeat`	Optional Int	How many times the email should be repeated (send again) to the signers who have not signed the document. Define an integer value between 0 and 3. An email can be repeated maximum 3 times. Example: repeat=2: The email(s) are resend maximum 2 times. If no resend should be done, omit this property or set `repeat=0`.
`reminder_days`	Optional Int	The number of days between each repeat. Define an integer value between 0 and 10. . Example: reminder_days=2: Email(s) are send with a timespan of 2 days in between. Default value: 1. Note:If `repeat` is not defined or has the value of 0, this property has no impact.
`language`	Optional String	In which language the signing page should be shown. Accepted values: 'fr', 'nl', 'en', 'da', 'de', 'pl', 'es', 'it', 'pt'. Omit this property if the signer's browser default language should be used.

The sms JSONObject has following parameters:

Parameter	R/O	Description
`to`	Required JSONArray	The list of signers ids to send the mail to. The id should correspond to an `id` defined in the `signersinfo` list. The mobile number of each signer should be defined in the `signersinfo` list. To add SMS workflow, consult Example 12: Add email/sms workflow
`subject`	Required String	The subject of the SMS in regular TXT format (not HTML). The maximum length of the text can be 95 characters. Text if truncated if needed. A short url is automatically added to this text. Example: Please sign your contract with following link: http://www.oksign.be/999999/sign/Tg5rd3sC0
`delay`	Optional Int	Should SMSs be send with a delay? The delay is measured in hours. Example: delay=3: The SMS(s) are send 3 hours after this request has been uploaded. If you want to send the email immediately, omit this property or set `delay=0`.
`repeat`	Optional Int	How many times the SMS(s) should be repeated (send again) to the signers who have not signed the document. Define an integer value between 0 and 3. Resending can be repeated maximum 3 times. Example: repeat=2: The SMS(s) are resend maximum 2 times. If no resend should be done, omit this property or set `repeat=0`.
`reminder_days`	Optional Int	The number of days between each repeat. Define an integer value between 0 and 10. . Example: reminder_days=2: SMS(s) are send with a timespan of 2 days in between. Default value: 1. Note:If `repeat` is not defined or has the value of 0, this property has no impact.
`language`	Optional String	In which language the signing page should be shown. Accepted values: 'fr', 'nl', 'en', 'da', 'de', 'pl', 'es', 'it', 'pt'. Omit this property if the signer's browser can choose the page language.

Example 4: Add logo to the Form Descriptor
To define the logo to be displayed during the Signing process a logo key/value pair can be defined defining the URL of the logo.

Raw
{
        "logo" : "https://www.yourwebsite.com/static/images/yourlogo.png",
	"reusable": false,
	"fields": [
		{
			"signerid": "bt_00000000-0000-0000-0000-000000000001",
			"height": 82.68,
			"inputtype": "CanvasSIG",
			"name": "SIG_FIELD_1",
			"pagenbr": 4,
			"posX": 51.26,
			"posY": 390.27,
			"required": true,
			"signingoptions": {
				"eid": {},
				"pen": {},
				"tan": {},
                                "itsme": {}
			},
			"width": 204.23
		}
	],
	"signersinfo": [
		{
			"mobile": "32495XXXXXX",
			"name": "Bill Gates",
			"actingas": "Tester",
			"id": "bt_00000000-0000-0000-0000-000000000001",
			"email": "bill.gates@microsoft.xxx"
		}
	]
}

If the logo parameter is not defined, the logo is displayed as defined in your account via menu Settings --> Company Data --> Name and Logo. If the logo is not defined, the

logo is displayed.

Example 5: Add sendtomeonly to the Form Descriptor
To define whether or not the signed document should be send to all signers (or only to the account's email) the sendtomeonly key/value pair can be defined.

Raw
{
        "sendtomeonly" : true,
	"reusable": false,
	"fields": [
		{
			"signerid": "bt_00000000-0000-0000-0000-000000000001",
			"height": 82.68,
			"inputtype": "CanvasSIG",
			"name": "SIG_FIELD_1",
			"pagenbr": 4,
			"posX": 51.26,
			"posY": 390.27,
			"required": true,
			"signingoptions": {
				"eid": {},
				"pen": {},
				"tan": {},
                                "itsme": {}
			},
			"width": 204.23
		}
	],
	"signersinfo": [
		{
			"mobile": "32495XXXXXX",
			"name": "Bill Gates",
			"actingas": "Tester",
			"id": "bt_00000000-0000-0000-0000-000000000001",
			"email": "bill.gates@microsoft.xxx"
		}
	]
}

Following values are allowed:

true: Send the signed document only to the account's email.
false: Send the signed document to the account's email and also to the signers.

Notes:

By default the account's email is the email address used to open the account.
This email address can be overruled in the Send signed documents to: field via the menu Settings --> Preferences in your account.
This field can also be left empty if no email needs to be send.
See also sendtomeemail to define a differnt email address.>

Example 6: Add filename to the Form Descriptor
If the filename contains non US-ASCII characters, the x-oksign-filename header can't be used in the Document.upload service as section 3.1 of the ARPA Internet Text Messages spec states that headers are always in US-ASCII encoding. Use a filename key/value pair in the descriptor.

Raw
{
        "filename" : "Frédéric Malpertûse.pdf",
	"reusable": false,
	"fields": [
		{
			"signerid": "bt_00000000-0000-0000-0000-000000000001",
			"height": 82.68,
			"inputtype": "CanvasSIG",
			"name": "SIG_FIELD_1",
			"pagenbr": 4,
			"posX": 51.26,
			"posY": 390.27,
			"required": true,
			"signingoptions": {
				"eid": {},
				"pen": {},
				"tan": {},
                                "itsme": {}
			},
			"width": 204.23
		}
	],
	"signersinfo": [
		{
			"mobile": "32495XXXXXX",
			"name": "Bill Gates",
			"actingas": "Tester",
			"id": "bt_00000000-0000-0000-0000-000000000001",
			"email": "bill.gates@microsoft.xxx"
		}
	]
}

Example 7: Prefilling of fields
Prefill fields with data from your application so the signer can verify and/or update these fields before signing the document. Each field can be:

prefilled with a value
made 'required' so the field must be completed by the signer before the document can be completed
made 'readonly' so the field cannot be modified by the signer

Below an example for all the field types (Date, Text, Select, Checkbox) and which key/value pairs can be changed for 'fillable' fields.

Raw
{
  "reusable": false,
  "fields": [
    {
      "fontsize": "12",
      "height": 22.32,
      "inputtype": "Date",
      "name": "FIELD_1",
      "pagenbr": 0,
      "posX": 165.37,
      "posY": 200.09,
      "readonly": false, <== Signer can change field value
      "required": true, <== Signer needs to complete field
      "value": "2021-01-15", <== prefilled with a date
      "width": 95.91
    },
    {
      "fontsize": "12",
      "height": 22.32,
      "inputtype": "Text",
      "name": "FIELD_2",
      "pagenbr": 0,
      "posX": 162.06,
      "posY": 243.92,
      "readonly": false, <== Signer can change field value
      "required": true, <== Signer needs to complete field
      "value": "Bill Gates", <== prefilled with a name
      "width": 300.14
    },
    {
      "fontsize": "12",
      "height": 22.32,
      "inputtype": "Select",
      "options": [
        {
          "volvo": "Volvo"
        },
        {
          "saab": "Saab"
        },
        {
          "seat": "Seat"
        }
      ],
      "name": "FIELD_3",
      "pagenbr": 0,
      "posX": 162.06,
      "posY": 286.08,
      "readonly": false, <== Signer can change field value
      "required": true, <== Signer needs to complete field
      "value": "volvo", <== prefilled with an option value
      "width": 300.14,
      "size": 1
    },
    {
      "fontsize": "12",
      "height": 22.32,
      "inputtype": "Checkbox",
      "name": "FIELD_4",
      "pagenbr": 0,
      "posX": 163.71,
      "posY": 332.39,
      "readonly": true, <== Signer can NOT change field value
      "required": true, <== Field cannot be empty
      "value": "OK",  <== prefilled with a value (will be passed as value if checked)
      "width": 22.32
    },
    {
      "signerid": "bt_00000000-0000-0000-0000-000000000001",
      "height": 100.05,
      "inputtype": "CanvasSIG",
      "name": "SIG_FIELD_5",
      "pagenbr": 0,
      "posX": 163.71,
      "posY": 384.48,
      "readonly": false,
      "required": true,
      "signingoptions": {
        "eid": {},
        "pen": {},
        "tan": {},
        "itsme": {}
      },
      "width": 249.7
    }
  ],
  "signersinfo": [
    {
      "mobile": "",
      "name": "Signer-1",
      "actingas": "",
      "id": "bt_00000000-0000-0000-0000-000000000001",
      "email": ""
    }
  ]
}

Example 8: Assign a document to a user
A document can be assigned to a user (but is optional).
Define the email address of the user as the value of the assignto key. In the example below bill.gates@ms.com is a user defined in your

account.

Raw
{
        "assignto": "bill.gates@ms.com",
	"reusable": false,
	"fields": [
		{
			"signerid": "bt_00000000-0000-0000-0000-000000000001",
			"height": 82.68,
			"inputtype": "CanvasSIG",
			"name": "SIG_FIELD_1",
			"pagenbr": 4,
			"posX": 51.26,
			"posY": 390.27,
			"required": true,
			"signingoptions": {
				"eid": {},
				"pen": {},
				"tan": {},
				"itsme": {}
			},
			"width": 204.23
		}
	],
	"signersinfo": [
		{
			"mobile": "32495XXXXXX",
			"name": "Bill Gates",
			"actingas": "Tester",
			"id": "bt_00000000-0000-0000-0000-000000000001",
			"email": "bill.gates@microsoft.xxx"
		}
	]
}

Notes:

If no user is assigned, the document is by default assigned to the owner of the account.

Example 9: Add sendtomeemail to the Form Descriptor
By default a signed document (containing all signatures) is send to the account's email address as defined in the Send signed documents to: field via the menu Settings --> Preferences in your account.
To define an alternative email address use the sendtomeemail parameter.

Raw
{
        "sendtomeemail" : "elon.musk@ms.com",
	"reusable": false,
	"fields": [
		{
			"signerid": "bt_00000000-0000-0000-0000-000000000001",
			"height": 82.68,
			"inputtype": "CanvasSIG",
			"name": "SIG_FIELD_1",
			"pagenbr": 4,
			"posX": 51.26,
			"posY": 390.27,
			"required": true,
			"signingoptions": {
				"eid": {},
				"pen": {},
				"tan": {},
                                "itsme": {}
			},
			"width": 204.23
		}
	],
	"signersinfo": [
		{
			"mobile": "32495XXXXXX",
			"name": "Bill Gates",
			"actingas": "Tester",
			"id": "bt_00000000-0000-0000-0000-000000000001",
			"email": "bill.gates@microsoft.xxx"
		}
	]
}

Example 10: Add teammember's (user's) countersignature(s) to the Form Descriptor
In previous versions only the account's signature (with signerid bt_00000000-0000-0000-0000-000000000000) could be used to automatically countersign the document.
As of now all teammembers can be referenced to countersign a document (assuming they have defined their countersignature via the menu Settings->My data->My Signature).

Do as follows:

Login into your account;
Select REST API in the menu.
Select SignerIDs
A list appears of all teammembers (users) and their corresponding signerid.

Use the signerid and refer it in the signersinfo id field (example below).

Raw
{
	"reusable": false,
	"fields": [
		{
			"signerid": "bt_00000000-0000-0000-0000-002484214376",
			"height": 82.68,
			"inputtype": "CanvasSIG",
			"name": "SIG_FIELD_1",
			"pagenbr": 4,
			"posX": 51.26,
			"posY": 390.27,
			"required": true,
			"signingoptions": {
				"eid": {},
				"pen": {},
				"tan": {},
                                "itsme": {}
			},
			"width": 204.23
		}
	],
	"signersinfo": [
		{
			"mobile": "",
			"name": "",
			"actingas": "",
			"id": "bt_00000000-0000-0000-0000-002484214376",
			"email": ""
		}
	]
}

Notes:

The email, name, mobile and actingas parameters are automatically overwritten with the teammember values as defined in the account, so no need to define these values in the signersinfo.
If the teammember has enabled his/her countersignature no email and/or SMS are send.
Multiple teammembers (countersignatures) can be defined in the same document).

Example 11: Add validation rules to Text(Area) fields
The content of the Text(Area) fields can be checked with some predefined functions allowing to check the validity of an email address, mobile number, IBAN or Belgian NRN number.
The predefined functions are:

Function name	Description
`BT_CUSTOMERS.oksign.isValidEmail<blur>()`	Checks if the field's value is a valid email address (syntax only).
`BT_CUSTOMERS.oksign.isValidMobile<blur>()`	Checks if the field's value is a valid mobile number number (syntax only).
`BT_CUSTOMERS.oksign.isValidIBAN<blur>()`	Checks if the field's value is a valid IBAN number (syntax only).
`BT_CUSTOMERS.oksign.isValidNRN<blur>()`	Checks if the field's value is a valid Belgian National Register Number number (syntax only).

Add the function name as a value of the fnname key in the field's definition (example below).

Raw
{
	"reusable": false,
	"fields": [
		{
			"fontsize": "12",
			"height": 23.14,
			"inputtype": "Text",
			"name": "IBAN",
			"fnname": "BT_CUSTOMERS.oksign.isValidIBAN<blur>()",
			"pagenbr": 0,
			"posX": 203.29,
			"posY": 197.51,
			"readonly": false,
			"required": true,
			"value": "",
			"width": 299.98
		},
		{
			"fontsize": "12",
			"height": 23.14,
			"inputtype": "Text",
			"name": "MOBILE",
			"fnname": "BT_CUSTOMERS.oksign.isValidMobile<blur>()",
			"pagenbr": 0,
			"posX": 220.65,
			"posY": 263.62,
			"readonly": false,
			"required": true,
			"value": "",
			"width": 299.98
		},
		{
			"fontsize": "12",
			"height": 23.14,
			"inputtype": "Text",
			"name": "NRN",
			"fnname": "BT_CUSTOMERS.oksign.isValidNRN<blur>()",
			"pagenbr": 0,
			"posX": 280.15,
			"posY": 316.51,
			"readonly": false,
			"required": false,
			"value": "",
			"width": 299.98
		},
		{
			"fontsize": "12",
			"height": 23.14,
			"inputtype": "Text",
			"name": "EMAIL",
                        "fnname": "BT_CUSTOMERS.oksign.isValidEmail<blur>()",
			"pagenbr": 0,
			"posX": 254.53,
			"posY": 390.88,
			"readonly": false,
			"required": true,
			"value": "",
			"width": 299.98
		},
		{
			"signerid": "bt_00000000-0000-0000-0000-000000000001",
			"height": 99.99,
			"inputtype": "CanvasSIG",
			"name": "SIG_FIELD_1",
			"pagenbr": 1,
			"posX": 67.76,
			"posY": 328.08,
			"readonly": false,
			"required": true,
			"signingoptions": {
				"eid": {},
				"pen": {},
				"tan": {},
				"itsme": {}
			},
			"width": 250.4
		}
	],
	"signersinfo": [
		{
			"mobile": "",
			"name": "Signer-1",
			"actingas": "",
			"id": "bt_00000000-0000-0000-0000-000000000001",
			"email": ""
		}
	]
}

Notes:

Only Text(Area) fields can have a fnname key/value pair defined.
If the users enters an invalid value a message is displayed informing the user.
The document can only be signed if all fields contain valid data.

Example 12: Add Email/SMS workflow

Add a workflow JSONObject to the notifications JSONObject to define a sequence number for each recipient (signer) so signatures can be collected in a specific order (example below).
The recipient(s) with the lowest sequence number get(s) an email/sms and each time a document is signed the next email(s) are send to the signer with the next sequence number.
This assure a simple yet effective email/sms workflow.

Raw
{
	"reusable": false,
	"fields": [
		{
			"signerid": "bt_00000000-0000-0000-0000-000000000001",
			"height": 99.22,
			"inputtype": "CanvasSIG",
			"name": "SIGFIELD1",
			"pagenbr": 2,
			"posX": 86.82,
			"posY": 224.9,
			"readonly": false,
			"required": true,
			"signingoptions": {
				"eid": {},
				"pen": {},
				"tan": {},
				"itsme": {}
			},
			"width": 249.7
		},
		{
			"signerid": "bt_00000000-0000-0000-0000-000000000002",
			"height": 99.22,
			"inputtype": "CanvasSIG",
			"name": "SIGFIELD2",
			"pagenbr": 2,
			"posX": 128.99,
			"posY": 343.96,
			"readonly": false,
			"required": true,
			"signingoptions": {
				"eid": {},
				"pen": {},
				"tan": {},
				"itsme": {}
			},
			"width": 249.7
		},
		{
			"signerid": "bt_00000000-0000-0000-0000-000000000003",
			"height": 99.22,
			"inputtype": "CanvasSIG",
			"name": "SIGFIELD3",
			"pagenbr": 2,
			"posX": 196.79,
			"posY": 480.39,
			"readonly": false,
			"required": true,
			"signingoptions": {
				"eid": {},
				"pen": {},
				"tan": {},
				"itsme": {}
			},
			"width": 249.7
		}
	],
	"notifications": {
		"workflow": [
			{
				"id": "bt_00000000-0000-0000-0000-000000000001",
				"sequence": 1
			},
			{
				"id": "bt_00000000-0000-0000-0000-000000000002",
				"sequence": 2
			},
			{
				"id": "bt_00000000-0000-0000-0000-000000000003",
				"sequence": 3
			}
		],
		"smtp": {
			"sender": "Bill Gates",
			"to": [
				"bt_00000000-0000-0000-0000-000000000001",
				"bt_00000000-0000-0000-0000-000000000002",
				"bt_00000000-0000-0000-0000-000000000003"
			],
			"cc": [],
			"subject": "Contract_TEST_14-10-2019.pdf",
			"body": "Dear,
 Please sign this document.",
			"reminder_days": 1,
			"repeat": 0,
			"delay": 0,
			"language": "fr"
		},
		"sms": {
			"to": [
				"bt_00000000-0000-0000-0000-000000000001",
				"bt_00000000-0000-0000-0000-000000000002",
				"bt_00000000-0000-0000-0000-000000000003"
			],
			"subject": "Sign document Contract_14-10-2019 via link:",
			"reminder_days": 1,
			"repeat": 0,
			"delay": 0,
			"language": "nl"
		}
	},
	"signersinfo": [
		{
			"mobile": "",
			"name": "Signer-1",
			"actingas": "",
			"id": "bt_00000000-0000-0000-0000-000000000001",
			"email": ""
		},
		{
			"mobile": "",
			"name": "Signer-2",
			"actingas": "",
			"id": "bt_00000000-0000-0000-0000-000000000002",
			"email": ""
		},
		{
			"mobile": "",
			"name": "Signer-3",
			"actingas": "",
			"id": "bt_00000000-0000-0000-0000-000000000003",
			"email": ""
		}
	]
}

Notes:

The lowest sequence number allowed is 1, the highest 256.
Multiple recipients can have the same sequence number.

Success Response

The response is a JSONObject indicating the status (OK, FAILED) and the reason.
If OK the reason is a JSONArray containing a link for each signer. Each URL is typically send to someone that needs to sign the document or put as a link on a website (if you only have 1 signer).

Example (success):

{
        "status": "OK",
	"reason": [{
			"name": "Signer-1",
			"id": "bt_00000000-0000-0000-0000-000000000001",
			"url": "http://localhost:8080/oksign/sign/100751/THdtzPcxAp10p9KKlmn1-iQ63nrbHP-414Hk925snJ6CJZHwwC9sOyKt8TAU0-mTBHWye5f2mv7gn6Jn7ZzFNQ"
		},
		{
			"name": "Signer-2",
			"id": "bt_00000000-0000-0000-0000-000000000002",
			"url": "http://localhost:8080/oksign/sign/100751/THdtzPcxAp10p9KKlmn1-iQ63nrbHP-414Hk925snJ6CJZHwwC9sOyKt8TAU0-mTBHWye5f2mv7g5EzxLoP23Z"
		}
	]
	
}

Notes:

If you have multiple CanvasSIG (signatures) fields then only 1 copy of the document can be signed (reusable = false). If multiple documents need to be signed then you need to upload the document and form descriptor for each document!
If for a signer the name, actingas, email and mobile are defined the the signer will not be able to change any of these parameters.
If a signersinfo JSONArray is not present, it is generated automatically by this REST service.
A lg parameter can be added at the end of each signing URL to define the language to use during the signing process. The allowed values are nl, fr, en, da, de, pl, es, it, pt. Example:
```
https://oksign.be/sign/100292/hERAOm...?lg=nl
```
A fitinviewport parameter can be added at the end of each signing URL to fit the pages of the document in the viewport during the signing process. By default the document's pages are shown in full size during the signing process - screenshot (A). fitinviewport=true shows all pages completely in the viewport - screenshot (B).. Example:
```
https://oksign.be/sign/100292/hERAOm...?lg=nl&fitinviewport=true
```

Example (failure):

{
 "reason": "Invalid format x-oksign-docid. Found: 'zzz'. Expected: A valid format",
 "status": "FAILED"
}

Error Response In case of a severe error a 500 Internal Server Error is thrown (this should only happen in care cases).

Notes

Notes:

0.2 credits is charged for each SMS sent.

Notifications Upload service

URL https://oksign.be/services/rest/v1/notifications/upload

Title Notifications upload
Define the content of email(s) and or SMS(s) to be send to signers informing a document or briefcase is ready for signing.
Important: This service will remove any pending notifications for the referenced document or briefcase (as referenced by the passed x-oksign-docid parameter).

Method POST

Request
Headers

The x-oksign-authorization header's value is the combination of:

Your accountnumber;
The authoriation token defined in your account;
The organizational token defined in your account

Example: x-oksign-authorization = 100693;463204-5BC1F362-85AD-34A3-9DB5-DC891D20979E;marketing
The x-oksign-docid is the token you received when creating a document or Briefcase using the Document.upload or Briefcase.create service.

x-oksign-docid= 670816-483B7F54-8591-DDF9-FA77-9042AED3E8FD

The content-type header should be application/json as the body is in JSON format:

content-type = application/json; charset=utf-8

The accept header should be application/json as a response in JSON format is returned.

accept = application/json; charset=utf-8

Body

A JSONObject defining the properties of the email(s)/SMSs to send and to which signer(s).
The JSONObject has following parameters:

Raw
{
	"notifications": {
		"smtp": {
			"body": "<p>Dear,<br/> Please sign this document.</p>",
			"cc": [],
			"delay": 0,
			"language": "fr",
			"reminder_days": 1,
			"repeat": 0,
			"subject": "Bundle insurances reference AB-8475-985",
			"to": [
				"bt_00000000-0000-0000-0000-000000000001"
			]
		},
		"sms": {
			"delay": 0,
			"language": "nl",
			"reminder_days": 1,
			"repeat": 0,
			"subject": "Bundle insurances reference AB-8475-985:",
			"to": [
				"bt_00000000-0000-0000-0000-000000000001"
			]
		}
	},
	"signersinfo": [
		{
			"mobile": "32495XXXXXX",
			"name": "Bill Gates",
			"actingas": "Tester",
			"id": "bt_00000000-0000-0000-0000-000000000001",
			"email": "bill.gates@microsoft.xxx"
		}
	]
}

The passed JSNObject contains 2 top-level key/value pairs:

Parameter	R/O	Description
`notifications`	Required JSONObject	Defines the email and/or SMS properties. More info below.
`signersinfo`	Optional JSONArray	The list of signers to send notifications to. Each id should correspond to an `id` defined in the `signersinfo` JSONArray of the Form Descriptor referenced by the `x-oksign-docid` parameter. If the `x-oksign-docid` refers to a briefcase, each id corresponds to an `id` defined in the `signersinfo` JSONArray of each document in the briefcase. If this parameter is not defined, notifications are send to all signers defined in the `signersinfo` JSONArray of the document or briefcase referenced by the `x-oksign-docid` parameter. Notes: The properties defined here will replace any properties defined in the Form Descriptor(s) of the document/briefcase. If a signer is not mentioned in this parameter the properties of the signer as defined in the Form Descriptor(s) of the document or briefcase are used. If you want to limit the notifications to be send to some signers, add a signerinfo object with empty email and SMS for those signers that no email/SMS need to be send to. This way you can setup your own workflow. If a signer has already signed the document or briefcase, the signer will not receive any email(s) and/or SMSs(s). If a signerid does not exists in the Form Descriptor(s) of the document or briefcase, it is ignored. If the signer's name, actingas (function) and email are defined, the 'Personal info needed' screen is skipped during the signing process and the signer can immediately view and sign the document. If the signer needs to be able to modify this data, add a `readonly=false` key/value pair. { "name": "John Lennon", "mobile": "+32495123456", "actingas": "Singer / Songwriter", "id": "bt_00000000-0000-0000-0000-000000000100", "email": "john.lennon@imagine.com" "readonly": false, } If the `signerid` represents a teammember (OK!Sign user in your account), the email, name, mobile and actingas parameters are automatically overwritten with the teammember values as defined in the account, so no need to define these values in the signersinfo. If the teammember has enabled his/her countersignature no email and/or SMS are send. Important: If the email or mobile is empty, no notifications are send to this signer. This allows you to (re)send notifications only to some selected signers.

The notifications JSONObject contains 2 top-level key/value pairs:
The smtp JSONObject has following parameters:

Parameter	R/O	Description
`sender`	Optional String	The name of the sender (not an email address). The recipient will see this as: Bill Gates via OK!Sign <no-reply@oksign.be>. If absent, the name is taken from the Company field defined via Settings --> Company Data --> Name and Logo. If this field is empty the sender name is defined as Your companyname.
`to`	Required JSONArray	The list of signers ids to send emails to. The id should correspond to an `id` defined in the `signersinfo` list. The email of each signer should be defined in the `signersinfo` list. To add email workflow, consult Example 12: Add email/sms workflow
`cc`	Optional JSONArray	The list of emails that should be in Cc:. Leave empty or omit if not needed.
`replyto`	Optional String	Email address on which recipients will be able to reply back. If not defined, the replyto is the `assignto` value (if defined). Otherwise the account's email address.
`subject`	Required String	The subject of the email in regular format (not HTML).
`body`	Required String	The body of the email in HTML format.
`delay`	Optional Int	Should emails be send with a delay? The delay is measured in hours. Example: delay=3: The email(s) are send 3 hours after this request has been uploaded. If you want to send the email immediately, omit this property or set `delay=0`.
`repeat`	Optional Int	How many times the email should be repeated (send again) to the signers who have not signed the document. Define an integer value between 0 and 3. An email can be repeated maximum 3 times. Example: repeat=2: The email(s) are resend maximum 2 times. If no resend should be done, omit this property or set `repeat=0`.
`reminder_days`	Optional Int	The number of days between each repeat. Define an integer value between 0 and 10. . Example: reminder_days=2: Email(s) are send with a timespan of 2 days in between. Default value: 1. Note:If `repeat` is not defined or has the value of 0, this property has no impact.
`language`	Optional String	In which language the signing page should be shown. Accepted values: 'fr', 'nl', 'en', 'da', 'de', 'pl', 'es', 'it', 'pt'. Omit this property if the signer's browser default language should be used.

The sms JSONObject has following parameters:

Parameter	R/O	Description
`to`	Required JSONArray	The list of signers ids to send the mail to. The id should correspond to an `id` defined in the `signersinfo` list. The mobile number of each signer should be defined in the `signersinfo` list. To add SMS workflow, consult Example 12: Add email/sms workflow
`subject`	Required String	The subject of the SMS in regular TXT format (not HTML). The maximum length of the text can be 95 characters. Text if truncated if needed. A short url is automatically added to this text. Example: Please sign your contract with following link: http://www.oksign.be/999999/sign/Tg5rd3sC0
`delay`	Optional Int	Should SMSs be send with a delay? The delay is measured in hours. Example: delay=3: The SMS(s) are send 3 hours after this request has been uploaded. If you want to send the email immediately, omit this property or set `delay=0`.
`repeat`	Optional Int	How many times the SMS(s) should be repeated (send again) to the signers who have not signed the document. Define an integer value between 0 and 3. Resending can be repeated maximum 3 times. Example: repeat=2: The SMS(s) are resend maximum 2 times. If no resend should be done, omit this property or set `repeat=0`.
`reminder_days`	Optional Int	The number of days between each repeat. Define an integer value between 0 and 10. . Example: reminder_days=2: SMS(s) are send with a timespan of 2 days in between. Default value: 1. Note:If `repeat` is not defined or has the value of 0, this property has no impact.
`language`	Optional String	In which language the signing page should be shown. Accepted values: 'fr', 'nl', 'en', 'da', 'de', 'pl', 'es', 'it', 'pt'. Omit this property if the signer's browser can choose the page language.

Success Response

The response is a JSONObject indicating the status (OK, FAILED) and the reason (optional).

Example (success):

{
	"status": "OK"
}

Example (failure):

{
 "reason": "Invalid format x-oksign-token. Found: 'zzz'. Expected: A valid format",
 "status": "FAILED"
}

Error Response In case of a severe error a 500 Internal Server Error is thrown (this should only happen in care cases).

Notes

Formdesc Retrieve service

URL	`https://oksign.be/services/rest/v1/formdesc/retrieve`
Title	Formdesc retrieve Retrieve a document's form descriptor.
Method	GET
Request Headers	The x-oksign-authorization header's value is the combination of: Your accountnumber; The authoriation token defined in your account; The organizational token defined in your account Example: `x-oksign-authorization = 100693;463204-5BC1F362-85AD-34A3-9DB5-DC891D20979E;marketing` The x-oksign-docid is the docid you received when uploading the document `Document.upload` service. `x-oksign-docid = 670816-483B7F54-8591-DDF9-FA77-9042AED3E8FD` The accept header should be application/json as a response in JSON format is returned. `accept = application/json; charset=utf-8`
Body	The body is empty.
Success Response	The response is a JSONObject representing indicating the status (OK, FAILED) and the reason. If the status is OK the reason contains the Form Descriptor (as a JSONObject). Example (success): { "reason": { "fields": [ { "checked": false, "comment": "", "fnname": "", "fontfamily": "Courier", "fontstyle": "normal", "fontweight": "normal", "height": 70, "hidden": false, "id": "BT-202008061922-100001", "inputtype": "CanvasSIG", "letterspacing": "normal", "marker": "_sb1_", "name": "SIG_FIELD_1", "pagenbr": 3, "posX": 56.88, "posY": 460.74997, "readonly": false, "required": true, "signerid": "bt_00000000-0000-0000-0000-000000009805", "signingoptions": { "itsme": {}, "pen": {}, "tan": {} }, "textalign": "left", "width": 175 }, ], "reusable": false, "signerurls": [ { "id": "bt_00000000-0000-0000-0000-000000009805", "name": "GATES, BILL", "url": "https://your.website.com/sign/100123/OFWLU...?lg=fr" }, ] }, "status": "OK" } Example (failure): { "reason": "Invalid format x-oksign-docid. Found: 'zzz'. Expected: A valid format", "status": "FAILED" }
Error Response	In case of a severe error a 500 Internal Server Error is thrown (this should only happen in care cases).
Notes

Document Retrieve service

URL	`https://oksign.be/services/rest/v1/document/retrieve`
Title	Document retrieve Retrieve a (signed) document from the platform. IMPORTANT:The signed document remains on our platform until it is removed using the `Document.remove` service.
Method	GET
Request Headers	The x-oksign-authorization header's value is the combination of: Your accountnumber; The authoriation token defined in your account; The organizational token defined in your account Example: `x-oksign-authorization = 100693;463204-5BC1F362-85AD-34A3-9DB5-DC891D20979E;marketing` The x-oksign-docid is the docid you received when uploading the document `Document.upload` service. `x-oksign-docid = 670816-483B7F54-8591-DDF9-FA77-9042AED3E8FD` The accept header should be application/pdf as the (signed) document is returned as a PDF file. `accept = application/pdf`
Body	The body is empty.
Success Response	The response is a PDF document (bytes). Example (success): %PDF-1.5 %µµµµ 1 0 obj <</Type/Catalog/Pages 2 0 R/Lang(nl-BE) /StructTreeRoot 59 0 R/MarkInfo<</Marked true>>>> endobj ...
Error Response	A Status code 400 SC_BAD_REQUEST is thrown in case the passed documentid (x-oksign-docid) in absent or invalid. A Status code 404 SC_NOT_FOUND is thrown in case the requested document is not found on the platform. Post Request is not successful: (400) Invalid format x-oksign-docid. Found: '329259-580F2A2A-E7C6-3770-E7CE-B767701E7291xx'. Expected: A valid format Post Request is not successful: (404) No PDF document (in documents table) found for docid: 813009-187AB32B-A6DF-4298-F8A6-D9ED64DEBD86
Notes

Document Exists service

URL	`https://oksign.be/services/rest/v1/document/exists`
Title	Document exists Does a document exists on the platform?
Method	GET
Request Headers	The x-oksign-authorization header's value is the combination of: Your accountnumber; The authoriation token defined in your account; The organizational token defined in your account Example: `x-oksign-authorization = 100693;463204-5BC1F362-85AD-34A3-9DB5-DC891D20979E;marketing` The x-oksign-docid is the docid you received when uploading the document `Document.upload` service. `x-oksign-docid = 670816-483B7F54-8591-DDF9-FA77-9042AED3E8FD` The accept header should be application/json as a response in JSON format is returned. `accept = application/json; charset=utf-8`
Body	The body is empty.
Success Response	The response is a JSONObject indicating the status (OK, FAILED) and the reason. If the status is OK the filename and template (true\|false) are mentioned in the reason (as a JONObject). Example (success): { "reason": { "filename": "Haarvergoeding-15u51.pdf", "template": true }, "status": "OK" } Example (failure): { "reason": "Invalid format x-oksign-docid. Found: 'zzz'. Expected: A valid format", "status": "FAILED" }
Error Response	In case of a severe error a 500 Internal Server Error is thrown (this should only happen in care cases).
Notes

Document Remove service

If a signed document is removed immediately after having received a callback (when informing the signers via email is still ongoing on the platform) , a FAILED status is send back with the message: Too soon. Processing still ongoing. Please retry later.

URL	`https://oksign.be/services/rest/v1/document/remove`
Title	Document remove Remove a (signed) document from the platform.
Method	DELETE
Request Headers	The x-oksign-authorization header's value is the combination of: Your accountnumber; The authoriation token defined in your account; The organizational token defined in your account Example: `x-oksign-authorization = 100693;463204-5BC1F362-85AD-34A3-9DB5-DC891D20979E;marketing` The x-oksign-docid is the docid you received when uploading the document `Document.upload` service. `x-oksign-docid = 670816-483B7F54-8591-DDF9-FA77-9042AED3E8FD` The accept header should be application/json as a response in JSON format is returned. `accept = application/json; charset=utf-8`
Body	The body is empty.
Success Response	The response is a JSONObject indicating the status (OK, FAILED) and the reason (if FAILED). Example (success): {"status": "OK" } Example (failure): { "reason": "Too soon. Processing still ongoing. Please retry later", "status": "FAILED" }
Error Response	In case of a severe error a 500 Internal Server Error is thrown (this should only happen in care cases).
Notes

Metadata Retrieve service

URL	`https://oksign.be/services/rest/v1/metadata/retrieve`
Title	Metadata retrieve Retrieve the metadata of a (signed) document. The medata contains more info regarding the signature(s) and the content of the completed fields.
Method	GET
Request Headers	The x-oksign-authorization header's value is the combination of: Your accountnumber; The authoriation token defined in your account; The organizational token defined in your account Example: `x-oksign-authorization = 100693;463204-5BC1F362-85AD-34A3-9DB5-DC891D20979E;marketing` The x-oksign-docid is the docid of the signed document (signed_docid). `x-oksign-docid = 670816-483B7F54-8591-DDF9-FA77-9042AED3E8FD` The accept header should be application/json as a response in JSON format is returned. `accept = application/json; charset=utf-8`
Body	The body is empty.
Success Response	The response is a JSONObject indicating the status (OK, FAILED) and the reason. The reason contains the document's metadatason (as a JONObject). Example (success): { "reason": { "response": { "fieldslist": [], "other": { "documentURI": "Haarvergoeding-15u51.pdf", "lastmodified": "2017-11-06T12:07:14+01:00", "leaseperiod_ends": "2017-12-06T00:00:00+01:00", "nbrOfPages": 2, "refslist": [] }, "signatureslist": [] }, "responseHeader": { "fieldslistsize": 0, "othersize": 5, "signatureslistsize": 0 } }, "status": "OK" } Example (failure): { "reason": "Invalid format x-oksign-docid. Found: 'zzz'. Expected: A valid format", "status": "FAILED" }
Error Response	In case of a severe error a 500 Internal Server Error is thrown (this should only happen in care cases).
Notes

Documents active service

URL https://oksign.be/services/rest/v1/documents/active

Title Documents active
Get a list of docids and other properties of active documents.
Active documents are listed in the Active Documents tab in your account.

Method GET

Request
Headers

The x-oksign-authorization header's value is the combination of:

Your accountnumber;
The authoriation token defined in your account;
The organizational token defined in your account

Example: x-oksign-authorization = 100693;463204-5BC1F362-85AD-34A3-9DB5-DC891D20979E;marketing
The accept header should be application/json as a response in JSON format is returned.

accept = application/json; charset=utf-8

Body The body is empty.

Success Response

The response is a JSONObject indicating the status (OK, FAILED) and the reason.
If the status is OK more info can be found in the reason (as a JSONArray).
Example (success):

{
  "reason": [
    {
      "createdate": "2021-08-28T12:32:26+02:00",
      "creator": "bill.gates@ms.com",
      "docid": "751589-90FB642F-FBEA-AD61-0BEA-B5247FB09659",
      "filename": "MAKRO invulformulier - kopie (7) - Signer-1.pdf",
      "nbrOfSigaturesRequired": 1,
      "nbrOfSigaturesValid": 1,
      "orgtoken" : "opdrachtbrief" 
      "reusable" : false,
      "signed_docid": "563278-7877ACB2-507A-5B02-AB6E-CCF48C77E790",
      "status": 1,
      "viaapi": true
    },
    ...
  ],
  "status": "OK"
}

The reason contains a JSONArray of JSONObjects each describing the properties of an active document:

Parameter	Type	Description
`createdate`	String	The moment when the document was uploaded in the account (ISO8601 format).
`creator`	String	The owner/creator of the document.
`docid`	String	The document ID of the document concerned.
`filename`	String	The filename of the document concerned.
`nbrOfSigaturesRequired`	Int	The number of signatures required (as defined in the corresponding Form Descriptor).
`nbrOfSigaturesValid`	Int	The number of signatures valid (this mean placed in the document).
`orgtoken`	String	The organisational token used when uploading the document via the REST api Note: If not uploaded via the REST api this paramater is absent.
`reusable`	Boolean	Is the document a reusable document (as defined in the corresponding Form Descriptor) (true\|false)? Deprecated: Please check status parameter to know the status of a document.
`signed_docid`	String	The document ID of the signed document (if any). Notes: - If the document is not yet signed this paramater is absent. - If the document is reusable this parameter is absent.
`status`	Int	The status of the document: 1 : Active document 10 : Briefcase (more info) 11 : Active document in a briefcase 12 : Reusable document 14 : Template document
`viaapi`	Boolean	Has the document been uploaded via the REST API service (true\|false)?

Example (failure):

{
  "reason": "Unparseable date: \"2017-11-01T12:00:00+0X:00\"",
  "status": "FAILED"
}

Error Response In case of a severe error a 500 Internal Server Error is thrown (this should only happen in care cases).

Notes Do not call this request more than once every 3 minutes. If this request is called too often a 429 Too Many Requests response code is returned.

Documents signed service (via API Polling)

URL https://oksign.be/services/rest/v1/documents/signed

Title Documents signed
Get a list of docids of signed documents in a defined timeframe that have been uploaded previously via the Document.upload service.

Method GET

Request
Headers

The x-oksign-authorization header's value is the combination of:

Your accountnumber;
The authoriation token defined in your account;
The organizational token defined in your account

Example: x-oksign-authorization = 100693;463204-5BC1F362-85AD-34A3-9DB5-DC891D20979E;marketing
The x-oksign-starttime is the start time of the timeframe (ISO-8601 format).

x-oksign-starttime = 2017-11-06T12:00:00+01:00

The x-oksign-endtime is the end time of the timeframe (ISO-8601 format).

x-oksign-endtime = 2017-11-06T12:15:00+01:00

The accept header should be application/json as a response in JSON format is returned.

accept = application/json; charset=utf-8

Body The body is empty.

Success Response

The response is a JSONObject indicating the status (OK, FAILED) and the reason.
If the status is OK more info can be found in the reason (as a JSONArray).
Example (success):

{
  "reason": [
    {
            "accountnbr": 123456,
            "creditsinfo": [
                    {
                            "credits": 1,
                            "signerid": "bt_00000000-0000-0000-0000-000000000001",
                            "signingoption": "pen",
                            "subscription": 0
                    }
            ],
            "filename" : "a-filename.pdf",
            "fields_completed": ["L1-60c2"],
            "nbrOfSigaturesRequired": 1,
            "nbrOfSigaturesValid": 1,
            "orgtoken": "test-production",
            "signed_docid": "00000-6F179F99-0000-0000-0000-DEC8F816E42B",
            "signerid": "bt_00000000-0000-0000-0000-000000000001",
            "source": "SignViaLink",
            "source_docid": " 00000-BA0A5760-0000-0000-0000-FA7808BA7D8C",
            "ts": "2021-10-13T16:47:44+02:00"
    },
    {
            "accountnbr": 123456,
            "creditsinfo": [
                    {
                            "credits": 1,
                            "signerid": "bt_00000000-0000-0000-0000-000000000001",
                            "signingoption": "itsme",
                            "subscription": 4
                    }
            ],
            "filename" : "another-filename.pdf",
            "fields_completed": ["L1-60c2"],
            "nbrOfSigaturesRequired": 1,
            "nbrOfSigaturesValid": 1,
            "orgtoken": "test-production",
            "signed_docid": "999999-6F179F99-0000-0000-0000-DEC8F816E42B",
            "signerid": "bt_00000000-0000-0000-0000-000000000001",
            "source": "SignViaLink",
            "source_docid": " 999999-BA0A5760-0000-0000-0000-FA7808BA7D8C",
            "ts": "2021-10-12T16:47:44+02:00"
    }
  ],
  "status": "OK"
}

Notes:

The creditsinfo is a JSONArray containing for each signer the signingmethod used and the number of credits consumed. The number of credits consumed is the sum of the credits and subscription values. Example:

[
    {
            "signerid": "bt_00000000-0000-0000-0000-000000000001",
            "signingoption": "itsme",
            "credits": 3,
            "subscription": 0
    }
]

If the nbrOfSigaturesRequired equals nbrOfSigaturesValid then al signatures are in place and the document is completely signed.
It is possible in future versions new parameters are added

Example (failure):

{
  "reason": "Unparseable date: \"2017-11-01T12:00:00+0X:00\"",
  "status": "FAILED"
}

Error Response In case of a severe error a 500 Internal Server Error is thrown (this should only happen in care cases).

Notes

Do not call this request more than once every 3 minutes and define the x-oksign-starttime and x-oksign-endtime as moving timestamps. Example:

Time of request	x-starttime	x-endtime
09:05:00	09:00:00	09:05:00
09:10:00	09:05:00	09:10:00
09:15:00	09:10:00	09:15:00

Slide the x-oksign-starttime and x-oksign-endtime with the execution time of calling this request so the response only contains the latest information (since the previous request). Of course you can also execute this request hourly, daily, ... as per your convenience.
If this request is called too often a 429 Too Many Requests response code is returned.

Webhooks retrieve service (via API Polling)

URL https://oksign.be/services/rest/v1/webhooks/retrieve

Title Webhooks retrieve
Get a list of SMS or Email webhooks in a defined timeframe.
The webhooks are generated in case a bad event happened resulting in a error during the sending of the email or SMS.
Only error events are reported.

Method GET

Request
Headers

The x-oksign-authorization header's value is the combination of:

Your accountnumber;
The authoriation token defined in your account;
The organizational token defined in your account

Example: x-oksign-authorization = 100693;463204-5BC1F362-85AD-34A3-9DB5-DC891D20979E;marketing
The x-oksign-starttime is the start time of the timeframe (ISO-8601 format).

x-oksign-starttime = 2017-11-06T12:00:00+01:00

The x-oksign-endtime is the end time of the timeframe (ISO-8601 format).

x-oksign-endtime = 2017-11-06T12:15:00+01:00

The accept header should be application/json as a response in JSON format is returned.

accept = application/json; charset=utf-8

Body The body is empty.

Success Response

The response is a JSONObject indicating the status (OK, FAILED) and the reason.
If the status is OK the detailed webhook info can be found in the reason (as a JSONArray).
Example (success):

{
  "reason": [
    {
      "type": "smtp",
      "event": "deferred",
      "to": "stefan@gmail.xxx",
      "source_docid": "565581-335E99F3-350F-51F1-F7C1-386FE7C82E0E",
      "notificationid": "202001061348-1005A7-F312EF68-792B-D3E4-0841.smtp.int.test.oksign",
      "reason": "getaddrinfo ENOTFOUND gmail.xxx gmail.xxx:25",
      "orgtoken": "sales",
      "accountnbr": 123456,
      "ts": "2017-11-06T14:57:34+01:00"
    },
    {
      "type": "sms",
      "event": "blocked",
      "to": "3295509235",
      "source_docid": "565581-335E99F3-350F-51F1-F7C1-386FE7C82E0E",
      "notificationid": "202001061348-1005A7-F312EF68-792B-D3E4-0841.smtp.int.test.oksign",
      "reason": "Invalid mobile number",
      "orgtoken": "hrm",
      "accountnbr": 123456,
      "ts": "2017-11-06T14:57:34+01:00"
    }
  ],
  "status": "OK"
}

The passed parameters are:

type: Is it an email related webhook ((smtp) or is it SMS related (sms).
event: The type of event: hard_bounce, soft_bounce, blocked,spam, invalid_email, deferred
ts: The timestamp when the event occured.
to: The email address or mobile number concerned.
source_docid: The id of the document concerned.
notificationid: The internal notificationid (for reference only).
reason: A human readable description (if any) of the event.

What you should do next: Remove the document using the document_remove service and upload the document (and descriptor) again after making the necessary corrections. Note:: As a result of the removal of the document the webhook(s) event will also be removed from the platform. Example (failure):

{
  "reason": "Unparseable date: \"2017-11-01T12:00:00+0X:00\"",
  "status": "FAILED"
}

Error Response In case of a severe error a 500 Internal Server Error is thrown (this should only happen in care cases).

Notes

Do not call this request more than once every 3 minutes and define the x-oksign-starttime and x-oksign-endtime as moving timestamps. Example:

Time of request	x-starttime	x-endtime
09:05:00	09:00:00	09:05:00
09:10:00	09:05:00	09:10:00
09:15:00	09:10:00	09:15:00

Credits retrieve service

URL	`https://oksign.be/services/rest/v1/credits/retrieve`
Title	Credits retrieve Retrieve info about your credits balance (quantity), when the credits expire (validuntil), the storage capacity (max_account_size) and storage in use (account_size).
Method	GET
Request Headers	The x-oksign-authorization header's value is the combination of: Your accountnumber; The authoriation token defined in your account; The organizational token defined in your account Example: `x-oksign-authorization = 100693;463204-5BC1F362-85AD-34A3-9DB5-DC891D20979E;marketing` The accept header should be application/json as a response in JSON format is returned. `accept = application/json; charset=utf-8`
Body	The body is empty.
Success Response	The response is a JSONObject indicating the status (OK, FAILED) and the reason. If the status is OK the reason contains the credit info (as a JONObject). Example (success): { "account_size": 16858965, "max_account_size": 1048576000, "paid": true, "quantity": 25, "subscription": "PRE", "validuntil": "2021-08-21T23:59:59+01:00" } Example (failure): { "reason": "Invalid format x-oksign-docid. Found: 'zzz'. Expected: A valid format", "status": "FAILED" }
Error Response	In case of a severe error a 500 Internal Server Error is thrown (this should only happen in care cases).
Notes

Audittrail retrieve service

URL	`https://oksign.be/services/rest/v1/audittrail/retrieve`
Title	Audit Trail retrieve * The Audit Trail Report is only available for documents uploaded in your account after 2021-05-05. * keeps track of what happened with your document. The non-editable Audit Trail report - delivered in PDF format certified by a Betrust signature - ensures that every action on your document is tracked and time-stamped, to provide proof of access, review, and signature. The records also include a hash of each version of the PDF document to prove the records belong to the (signed) document. Consult the Audit Trail Report to know what info is tracked. Note: Call this service when all signatures are placed in the document. The Audit Trail report remains available until 18 months after the date of when the original document was uploaded in your account. The Audit Trail report remains available even if the signed document has been removed from your account.
Method	GET
Request Headers	The x-oksign-authorization header's value is the combination of: Your accountnumber; The authoriation token defined in your account; The organizational token defined in your account Example: `x-oksign-authorization = 100693;463204-5BC1F362-85AD-34A3-9DB5-DC891D20979E;marketing` The x-oksign-docid is the signed_docid (as of 2023-04-15). `x-oksign-docid = 670816-483B7F54-8591-DDF9-FA77-9042AED3E8FD` The accept header should be application/pdf as the (signed) document is returned as a PDF file. `accept = application/pdf`
Body	The body is empty.
Success Response	The response is a PDF document (bytes). Example (success): %PDF-1.5 %µµµµ 1 0 obj <</Type/Catalog/Pages 2 0 R/Lang(nl-BE) /StructTreeRoot 59 0 R/MarkInfo<</Marked true>>>> endobj ...
Error Response	A Status code 400 SC_BAD_REQUEST is thrown in case the passed documentid (x-oksign-docid) in absent or invalid. A Status code 404 SC_NOT_FOUND is thrown in case the requested document is not found on the platform. Post Request is not successful: (400) Invalid format x-oksign-docid. Found: '329259-580F2A2A-E7C6-3770-E7CE-B767701E7291xx'. Expected: A valid format Post Request is not successful: (404) No PDF document (in documents table) found for docid: 813009-187AB32B-A6DF-4298-F8A6-D9ED64DEBD86
Notes

Briefcase create service

URL https://oksign.be/services/rest/v1/briefcase/create

Title

Briefcase create
Create a briefcase containing multiple documents that are signed together using one signing link for each signer.
Advantages:

The briefcase appears in the Active Documents tab.

The response contains the signing links for all signers mentioned in the FormDescriptors of the documents in the briefcase.
Use the Notifications.upload service to inform signer(s) a briefcase is ready to be signed.

Disadvantage

A document can only be part of one briefcase. If a briefcase is created with a document already part of another briefcase an error is thrown.
The briefcase remains in the Active Documents tab untill 1) all documents are completely signed (and the briefcase is automatically removed from the Active Documents tab) or 2) the briefcase is removed using the Briefcase.remove service.
Any (partially) signed documents are available in the Signed Documents tab (even after removal of the briefcase).

Method POST

Request
Headers

The x-oksign-authorization header's value is the combination of:

Your accountnumber;
The authoriation token defined in your account;
The organizational token defined in your account

Example: x-oksign-authorization = 100693;463204-5BC1F362-85AD-34A3-9DB5-DC891D20979E;marketing
The content-type header should be application/json as the body of this request is a serialized JSONObject.

content-type = application/json; charset=utf-8

The accept header should be application/json as a response in JSON format is returned.

accept = application/json; charset=utf-8

Body

Upload a JSONObject to the

platform defining which document(s) to sign (and other info).
The JSONObject has following parameters:

Raw
{
	"list": [
		"909543-EF3A6CC0-AD17-933D-429C-BCAFD0B8BE84",
		"719992-6742F248-331E-927F-8546-AE4B5A3E9AC1"
	],
	"returnurl": "https://www.betrust.be",
	"callbackurl": "https://www.yourwebsite.be/callback",
        "webhookurl": "https://www.yourwebsite.be/webhook",
	"packagename": "Bundle insurances reference AB-8475-985",
}

Parameter	R/O	Description
`list`	Required JSONArray	The list of previously uploaded documents (and their FormDescriptors) that needs to be signed.
`returnurl`	Optional JSONArray	The returnURL - if defined - is used to redirect the browser to whatever location is requested after the signer has signed the document(s). If absent, the returnURL as defined by the Organisational token is used. Following parameters are added to the returnURL. Example - not URLEncoded for visibility: ?status=OK &source=Briefcase &token=394003-EB9D793E-FC02-5244-97E5-67B55987D673 &signerid=bt_00000000-0000-0000-0000-000000000002 &source_docids=["220365-22F464C6-954D-06BD-5B8A-AB90EE4A2624","654988-9F010472-4E0A-6041-E957-D10D1476FA64"] &signed_docids=["391834-645DDD55-6314-04C3-FBBF-EA8AF6C71064","480235-F15ED4D5-736F-15E3-151A-F698A97F06A8"] &orgtoken=test &accountnbr=100292 &ts=2021-01-14T15:35:07+01:00 The `status` is OK if at least one document has been successfully signed, FAILED otherwise. The `source` is a Briefcase. The `token` is the Briefcase token. The `signerid` defines the id of the signer who has signed the document(s). The `source_docids` references the documents (as defined in the `list`) which have been signed. It is possible that not all documents are signed. They will not appear here. The `signed_docids` contains the corresponding docid of the signed documents. The `orgtoken` the name of the organisational token as defined by this `x-oksign-authorization`. The `accountnbr` contains the accountnumber. The `ts` defines the current timestamp. Note: You can add your own parameters when defining the returnURL. They will be added in the response.
`callbackurl`	Optional String	Once the document(s) has been signed the callbackURL - if defined - is used to inform your application (otherwise API polling can be used). If absent, the callbackURL as defined by the Organisational token is used. Following parameters are added to the callbackURL. Example: - not URLEncoded for visibility: ?source=Briefcase &token=394003-EB9D793E-FC02-5244-97E5-67B55987D673 &signerid=bt_00000000-0000-0000-0000-000000000002 &source_docids=["220365-22F464C6-954D-06BD-5B8A-AB90EE4A2624","654988-9F010472-4E0A-6041-E957-D10D1476FA64"] &signed_docids=["391834-645DDD55-6314-04C3-FBBF-EA8AF6C71064","480235-F15ED4D5-736F-15E3-151A-F698A97F06A8"] &orgtoken=test &accountnbr=100292 &ts=2021-01-14T15:35:07+01:00 The `source` is a Briefcase. The `token` is the SignExpres token. The `signerid` defines the id of the signer who has signed the document(s). The `source_docids` references the documents (as defined in the `list`) which have been signed. It is possible that not all documents are signed. They will not appear here. The `signed_docids` contains the corresponding docid of the signed documents. The `orgtoken` contains the name of the organisational token by which the document was uploaded with. The `accountnbr` contains the accountnumber. The `ts` defines the current timestamp. Note: You can add your own parameters when defining the callbackURL. They will be added in the response.
`webhookurl`	Optional String	If emails or SMSs are send, the GET webhookURL - if defined - is called in case of any errors (or use the Webhooks.retrieve service as a polling mechanism to get an overview of errors). If absent, the webhookURL as defined by the Organisational token is used. Following parameters are added to the webhookURL. Example: - not URLEncoded for visibility: ?source_doc = 671478-B7056444-D... &source_docid = 671478-B7056444-D... &webhookinfo = {...JSONObjct see below...} The `source_doc` is the docid of the document that has been uploaded before. Note: This is the old parameter name, please use source_docid. The `source_docid` is the docid of the document that has been uploaded before. The `webhookinfo` is a JSONobject containing the details of the webhook: { "accountnbr": 100292, "source_docid": "671478-B7056444-...", "notificationid": "202311151220-1B4137-...", "type": "smtp", "event": "blocked", "reason": "blocked : due to blacklist user", "orgtoken": "radarwerk", "to": "bill.gates@hotmail.com", "ts": "2023-11-15T12:21:26" } The `accountnbr` contains the accountnumber this webhook belongs to. The `source_docid` of the document that has been uploaded before. The `notificationid` for internal reference only. The `type`: of notification: SMTP (email) or SMS. The `event` describes the webhook event: `hard_bounce`, `soft_bounce`, `blocked`, `spam`, `invalid_email`, `deferred"` . The `reason` describes the event in human language. The `orgtoken` used to upload the document. The `to` is the email address or mobile numer of the recipient. The `ts` defines the current timestamp..
`packagename`	Optional String	The name of this briefcase. This is shown in the Active Documents tab, in the email(s) and/or SMSs sent and during the signing process.

Success Response

The response is a JSONObject indicating the status (OK, FAILED) and the reason.
If OK the docid parameter contains the id of the brieefcase and the reason is a JSONObject containing a list of signingurls for each signer defined in the list of documents. The URL can be send to the signer or be used in your (portal) application to have the document signed immediately (Face-2-Face).

Example (success):

{
	"docid": "028651-25AAAF19-97B9-8BFD-7C46-05F95D1B6252",
	"reason": [
		{
			"id": "bt_00000000-0000-0000-0000-000000000001",
			"name": "Bill Gates",
			"url": "https://oksign.be/sign/100292/hERAOm..."
		}
	],
	"status": "OK"
}

Notes:

The docid in the response is the id of the briefcase, but to remain consistent with other services this is referred to as docid.
Each signer should be referenced by the same signerid in each Form Descriptor for each document defined in the list.
Ech document in the list should have the same owner.
A lg parameter can be added at the end of each signing URL to define the language to use during the signing process. The allowed values are nl, fr, en, da, de, pl, es, it, pt. Example:
```
https://oksign.be/sign/100292/hERAOm...?lg=nl
```
A fitinviewport parameter can be added at the end of each signing URL to fit the pages of the document in the viewport during the signing process. By default the document's pages are shown in full size during the signing process - screenshot (A). fitinviewport=true shows all pages completely in the viewport - screenshot (B).. Example:
```
https://oksign.be/sign/100292/hERAOm...?lg=nl&fitinviewport=true
```

Example (failure):

{
 "reason": "Invalid format x-oksign-docid. Found: 'zzz'. Expected: A valid format",
 "status": "FAILED"
}

Error Response In case of a severe error a 500 Internal Server Error is thrown (this should only happen in care cases).

Notes

Briefcase retrieve service

URL	`https://oksign.be/services/rest/v1/briefcase/retrieve`
Title	SignExpress retrieve Retrieve a previously uploaded Briefcase JSONObject from the platform
Method	GET
Request Headers	The x-oksign-authorization header's value is the combination of: Your accountnumber; The authoriation token defined in your account; The organizational token defined in your account Example: `x-oksign-authorization = 100693;463204-5BC1F362-85AD-34A3-9DB5-DC891D20979E;marketing` The x-oksign-docid is the token you received when creating the Briefcase using the `Briefcase.create` service. `x-oksign-docid= 670816-483B7F54-8591-DDF9-FA77-9042AED3E8FD` The content-type header should be application/json as the body is in JSON format: `content-type = application/json; charset=utf-8` The accept header should be application/json as a response in JSON format is returned. `accept = application/json; charset=utf-8`
Body	The body is empty.
Success Response	The response is a JSONObject indicating the status (OK, FAILED) and the reason. Example (success): { "reason": { "callbackurl": "https://www.mycompany.com/oksign/callback", "list": [ "491984-B0FDB09A-6A5D-13BF-C890-476051598574" ], "orgtoken": "testststsst", "packagename": "Bundle insurances AB-1234-454", "returnurl": "https://www.mycompany.com", }, "status": "OK" } Example (failure): { "reason": "Invalid format x-oksign-token. Found: 'zzz'. Expected: A valid format", "status": "FAILED" }
Error Response	In case of a severe error a 500 Internal Server Error is thrown (this should only happen in care cases).
Notes

Briefcase remove service

URL	`https://oksign.be/services/rest/v1/briefcase/remove`
Title	Briefcase remove Remove a previously created Briefcase from the platform. Note: The documents in the briefcase are not removed and are still available in your account.
Method	DELETE
Request Headers	The x-oksign-authorization header's value is the combination of: Your accountnumber; The authoriation token defined in your account; The organizational token defined in your account Example: `x-oksign-authorization = 100693;463204-5BC1F362-85AD-34A3-9DB5-DC891D20979E;marketing` The x-oksign-docid is the id you received in the Briefcase.create response. `x-oksign-docid = 670816-483B7F54-8591-DDF9-FA77-9042AED3E8FD` The content-type header should be application/json as the body is in JSON format: `content-type = application/json; charset=utf-8` The accept header should be application/json as a response in JSON format is returned. `accept = application/json; charset=utf-8`
Body	The body is empty.
Success Response	The response is a JSONObject indicating the status (OK, FAILED) and the reason (if FAILED). Example (success): {"status": "OK" } Example (failure): { "reason": "Invalid format x-oksign-token. Found: '837366-9A8BC315-3C28-2CF2-14D0-3840700XXXXX'. Expected: A valid format",, "status": "FAILED" }
Error Response	In case of a severe error a 500 Internal Server Error is thrown (this should only happen in care cases).
Notes

SignExpress create service

URL https://oksign.be/services/rest/v1/signexpress/create

Title SignExpress create

Add a 'Sign now' button in your application and use the SignExpress service to have an end-to-end flow between your application and OK!Sign.
This way documents can be completed/signed from within your application.

Method POST

Request
Headers

The x-oksign-authorization header's value is the combination of:

Your accountnumber;
The authoriation token defined in your account;
The organizational token defined in your account

content-type = application/json; charset=utf-8

The accept header should be application/json as a response in JSON format is returned.

accept = application/json; charset=utf-8

Body

Upload a JSONObject to the

platform defining which document(s) to sign (and other info).
The JSONObject has following parameters:

Raw
{
	"list": [
		"108041-88213B3D-05E0-36F4-6F03-980B723A8293",
	],
	"signerinfo": {
		"actingas": "CEO",
		"email": "bill.gates@ms.com",
		"id": "bt_00000000-0000-0000-0000-000000000001",
		"mobile": "+32495123456",
		"name": "Bill Gates"
	},
	"returnurl": "https://www.betrust.be",
	"callbackurl": "https://www.yourwebsite.be/callback",
	"validityperiod": 3000,
	"packagename": "Bundle insurances reference AB-8475-985",
}

Parameter	R/O	Description
`list`	Required JSONArray	The list of previously uploaded documents (and their FormDescriptors) that needs to be signed. Note: There is no check if the passed list of documents actually exist. Any non-existing documents are ignored during the signing process.
`signerinfo`	Required JSONObject	A JSONObject defining the signer's email, name, actingas (function) and mobile number. The `id` is required, the other parameters can be left empty. Note: The `id` refers to a signerid as defined in the `FormDesc.upload` service for a previously uploaded document that is referenced in the `list`. If the the signer's name, actingas (function) and email are defined, the 'Personal info needed' screen is skipped and the signer can immediately view and sign the document. If the signer needs to be able to modify this data, add a `readonly=false` key/value pair. { "name": "John Lennon", "mobile": "+32495123456", "actingas": "Singer / Songwriter", "id": "bt_00000000-0000-0000-0000-000000000100", "email": "john.lennon@imagine.com" "readonly": false, }
`returnurl`	Optional JSONArray	The returnURL - if defined - is used to redirect the browser to whatever location is requested after the signer has signed the document(s). If absent, the returnURL as defined by the Organisational token is used. Following parameters are added to the returnURL. Example - not URLEncoded for visibility: ?status=OK &source=SignExpress &token=394003-EB9D793E-FC02-5244-97E5-67B55987D673 &signerid=bt_00000000-0000-0000-0000-000000000002 &source_docids=["220365-22F464C6-954D-06BD-5B8A-AB90EE4A2624","654988-9F010472-4E0A-6041-E957-D10D1476FA64"] &signed_docids=["391834-645DDD55-6314-04C3-FBBF-EA8AF6C71064","480235-F15ED4D5-736F-15E3-151A-F698A97F06A8"] &orgtoken=test &accountnbr=100292 &ts=2021-01-14T15:35:07+01:00 The `status` is OK if at least one document has been successfully signed, FAILED otherwise. The `source` is a SignExpress. The `token` is the SignExpress token. The `signerid` defines the id of the signer who has signed the document(s). The `source_docids` references the documents (as defined in the `list`) which have been signed. It is possible that not all documents are signed. They will not appear here. The `signed_docids` contains the corresponding docid of the signed documents. The `orgtoken` the name of the organisational token as defined by this `x-oksign-authorization`. The `accountnbr` contains the accountnumber. The `ts` defines the current timestamp. Note: You can add your own parameters when defining the returnURL. They will be added in the response.
`callbackurl`	Optional String	Once the document(s) has been signed the callbackURL - if defined - is used to inform your application (otherwise API polling can be used). If absent, the callbackURL as defined by the Organisational token is used. Following parameters are added to the callbackURL. Example: - not URLEncoded for visibility: ?source=SignExpress &token=394003-EB9D793E-FC02-5244-97E5-67B55987D673 &signerid=bt_00000000-0000-0000-0000-000000000002 &source_docids=["220365-22F464C6-954D-06BD-5B8A-AB90EE4A2624","654988-9F010472-4E0A-6041-E957-D10D1476FA64"] &signed_docids=["391834-645DDD55-6314-04C3-FBBF-EA8AF6C71064","480235-F15ED4D5-736F-15E3-151A-F698A97F06A8"] &orgtoken=test &accountnbr=100292 &ts=2021-01-14T15:35:07+01:00 The `source` is a SignExpress. The `token` is the SignExpres token. The `signerid` defines the id of the signer who has signed the document(s). The `source_docids` references the documents (as defined in the `list`) which have been signed. It is possible that not all documents are signed. They will not appear here. The `signed_docids` contains the corresponding docid of the signed documents. The `orgtoken` contains the name of the organisational token by which the document was uploaded with. The `accountnbr` contains the accountnumber. The `ts` defines the current timestamp. Note: You can add your own parameters when defining the callbackURL. They will be added in the response.
`validityperiod`	Optional Int	Defines how long (in seconds) this token is valid. If absent the validityperiod is 90 days.
`packagename`	Optional String	The name of this package. This is shown during the signing process if needed.

Success Response

The response is a JSONObject indicating the status (OK, FAILED) and the reason.
If OK the reason is a JSONObject containing the link to the

editor and some other info. The URL can be send to the signer or be used in your (portal) application to have the document signed immediately (Face-2-Face).

Example (success):

{
	"reason": {
		"id": "bt_00000000-0000-0000-0000-000000000001",
		"name": "Bill Gates",
		"token": "364260-5686ECAD-006B-32C8-8093-830E9CA81584",
		"url": "https://oksign.be/sign/100292/hERAOm..."
	},
	"status": "OK"
}

Notes:

A lg parameter can be added at the end of each signing URL to define the language to use during the signing process. The allowed values are nl, fr, en, da, de, pl, es, it, pt. Example:
```
https://oksign.be/sign/100292/hERAOm...?lg=nl
```
A fitinviewport parameter can be added at the end of each signing URL to fit the pages of the document in the viewport during the signing process. By default the document's pages are shown in full size during the signing process - screenshot (A). fitinviewport=true shows all pages completely in the viewport - screenshot (B).. Example:
```
https://oksign.be/sign/100292/hERAOm...?lg=nl&fitinviewport=true
```

Example (failure):

{
 "reason": "Invalid format x-oksign-docid. Found: 'zzz'. Expected: A valid format",
 "status": "FAILED"
}

Error Response In case of a severe error a 500 Internal Server Error is thrown (this should only happen in care cases).

Notes

SignExpress retrieve service

URL	`https://oksign.be/services/rest/v1/signexpress/retrieve`
Title	SignExpress retrieve Retrieve a previously uploaded SignExpress tokeninfo JSONObject from the platform
Method	GET
Request Headers	The x-oksign-authorization header's value is the combination of: Your accountnumber; The authoriation token defined in your account; The organizational token defined in your account Example: `x-oksign-authorization = 100693;463204-5BC1F362-85AD-34A3-9DB5-DC891D20979E;marketing` The x-oksign-token is the token you received when uploading the SignExpress tokeninfo using the `SignExpress.create` service. `x-oksign-token = 670816-483B7F54-8591-DDF9-FA77-9042AED3E8FD` The content-type header should be application/json as the body is in JSON format: `content-type = application/json; charset=utf-8` The accept header should be application/json as a response in JSON format is returned. `accept = application/json; charset=utf-8`
Body	The body is empty.
Success Response	The response is a JSONObject indicating the status (OK, FAILED) and the reason. Example (success): { "reason": { "callbackurl": "https://www.mycompany.com/oksign/callback", "list": [ "491984-B0FDB09A-6A5D-13BF-C890-476051598574" ], "orgtoken": "testststsst", "packagename": "Bundle insurances AB-1234-454", "returnurl": "https://www.mycompany.com", "signerinfo": { "actingas": "CEO", "email": "bill.gates@ms.com", "id": "bt_00000000-0000-0000-0000-000000000001", "mobile": "+32495123456", "name": "Bill Gates" }, "token": "133998-D720A35D-8CAB-242A-69B0-F596B1569845", "valid_until": "2021-01-14T17:26:53+01:00", "validityperiod": 3000 }, "status": "OK" } Example (failure): { "reason": "Invalid format x-oksign-token. Found: 'zzz'. Expected: A valid format", "status": "FAILED" }
Error Response	In case of a severe error a 500 Internal Server Error is thrown (this should only happen in care cases).
Notes

SignExpress remove service

URL	`https://oksign.be/services/rest/v1/signexpress/remove`
Title	SignExpress remove Remove a previously uploaded SignExpress tokeninfo JSONObject from the platform
Method	DELETE
Request Headers	The x-oksign-authorization header's value is the combination of: Your accountnumber; The authoriation token defined in your account; The organizational token defined in your account Example: `x-oksign-authorization = 100693;463204-5BC1F362-85AD-34A3-9DB5-DC891D20979E;marketing` The x-oksign-token is the token you received in the SignExpress.create response. `x-oksign-token = 670816-483B7F54-8591-DDF9-FA77-9042AED3E8FD` The content-type header should be application/json as the body is in JSON format: `content-type = application/json; charset=utf-8` The accept header should be application/json as a response in JSON format is returned. `accept = application/json; charset=utf-8`
Body	The body is empty.
Success Response	The response is a JSONObject indicating the status (OK, FAILED) and the reason (if FAILED). Example (success): {"status": "OK" } Example (failure): { "reason": "Invalid format x-oksign-token. Found: '837366-9A8BC315-3C28-2CF2-14D0-3840700XXXXX'. Expected: A valid format",, "status": "FAILED" }
Error Response	In case of a severe error a 500 Internal Server Error is thrown (this should only happen in care cases).
Notes

EditorExpress create service

URL https://oksign.be/services/rest/v1/editorexpress/create

Title

EditorExpress create
The EditorExpress create service allows you to call the

editor from your own application.
The

editor acts as a 'scratchpad' allowing your user to define fields interactively.

The flow is as follows:

Upload the PDF/Word document using the Document.upload service
(Optional) Upload a FormDescriptor defining some (prepopulated) fields
Call this service (see details below). You'll receive a link to an editor instance
From within your application redirect the browser to the editor using the link.
The user defines (signature) fields in the editor
The user clicks the Save or Cancel button
The browser is redirected using the returnURL defined in this service with the status=OK (Save) or status=FAILED (Cancel) as uri parameter
Retrieve the updated FormDescriptor using the FormDesc.retrieve service
Remove the document using the Document.remove service
Remove the signerurls from the retrieved FormDescripto as these are no longer valid.

Update the Form descriptor (optional) and continue with the regular API methods flow.

Method POST

Request
Headers

The x-oksign-authorization header's value is the combination of:

Your accountnumber;
The authoriation token defined in your account;
The organizational token defined in your account

content-type = application/json; charset=utf-8

The accept header should be application/json as a response in JSON format is returned.

accept = application/json; charset=utf-8

Body

Upload a JSONObject to the

platform defining which document(s) to sign (and other info).
The JSONObject has following parameters:

Raw
{
  "list": ["744417-9457921D-3641-6480-D8AE-CD163CF66AEB"],
  "contacts": [
    {
      "actingas": "FCO",
      "email": "belinda.gates@ms.com",
      "mobile": "+32495123456",
      "name": "Belinda Gates"
    },
    {
      "actingas": "CEO",
      "email": "bill.gates@ms.com",
      "mobile": "+32495123789",
      "name": "Bill Gates"
    }
  ],
  "returnurl": "https://www.betrust.be",
  "validityperiod": 300,
  "showAnonymousSigners": true,
  "showTeammembers": true,
  "showSigningOptions": {
     "eid": true,
     "itsme": true,
     "pen": false,
     "tan": true
  }
}

Parameter	R/O	Description
`list`	Required JSONArray	The docid of the document to show in the editor. Note: Currently this list should contain exact 1 entry.
`contacts`	Optional JSONArray	A list of contacts that are used to populate the dropdown list in each signature field. The `name` and `email` are required (non empty), the other parameters can be left empty. Note: If no contacts are defined the user can select anonymous signers (Signer-1, ... , Signer-8).
`returnurl`	Optional JSONArray	The returnURL - if defined - is used to redirect the browser to whatever location is requested after the user leaves the editor by clicking on the Save or Cancel button. If absent, the returnURL as defined by the Organisational token is used. Following parameters are added to the returnURL. Example - not URLEncoded for visibility: ?status=OK &source=EditorExpress &token=394003-EB9D793E-FC02-5244-97E5-67B55987D673 &orgtoken=test &accountnbr=100292 &ts=2021-01-14T15:35:07+01:00 The `status` is OK if the user clicked on the Save button in the editor, FAILED if clicked on Cancel. The `source` is the EditorExpress service. The `token` is the EditorExpress token. The `orgtoken` contains the name of the organisational token as defined by this `x-oksign-authorization`. The `accountnbr` contains the accountnumber. The `ts` defines the current timestamp. Note: You can add your own parameters when defining the returnURL. They will be added in the response.
`validityperiod`	Optional Int	Defines how long (in seconds) this token is valid. If absent the validityperiod is 1 day.
`showAnonymousSigners`	Optional Boolean	Defines if anonymous signers (Signer-1, Signer-2, ...) are shown when defining a signature box in de editor. Default `true`.
`showMeSigner`	Optional Boolean	Defines if the counter signature (Me) is shown when defining a signature box in de editor. Default `true`. This option is deprecated and replaced with `showTeammembers`
`showTeammembers`	Optional Boolean	Defines if the teammembers are shown when defining a signature box in de editor. Default `true`.
`showSigningOptions`	Optional JSONObject	Defines which signing options are shown when defining a signature box in de editor. If absent all signing options are shown. This is the same as passing following JSONObject: { "eid": true, "itsme": true, "pen": true, "tan": true }

Success Response

The response is a JSONObject indicating the status (OK, FAILED) and the reason.
If OK the reason is a JSONObject containing the link to the editor instance and some other info. From within your application the browser can be redirected to this url. When the user leaves the editor the browser is returned to the returnurl as defined in this service.

Example (success):

{
  "reason": {
    "token": "373727-A879E26D-50EC-E67A-CF94-00BB049F7479",
    "url": "https://oksign.be/edit/100292/u7uv7Qq5QWe..."
  },
  "status": "OK"
}

Notes:

A lg parameter can be added at the end of the url defining the language to use in the Editor. The allowed values are nl, fr and en. Example:
```
https://oksign.be/edit/100292/hERAOm...?lg=nl
```

Example (failure):

{
 "reason": "Invalid format x-oksign-docid. Found: 'zzz'. Expected: A valid format",
 "status": "FAILED"
}

Error Response In case of a severe error a 500 Internal Server Error is thrown (this should only happen in care cases).

Notes

EditorExpress retrieve service

URL	`https://oksign.be/services/rest/v1/editorexpress/retrieve`
Title	EditorExpress retrieve Retrieve a previously uploaded EditorExpress tokeninfo JSONObject from the platform
Method	GET
Request Headers	The x-oksign-authorization header's value is the combination of: Your accountnumber; The authoriation token defined in your account; The organizational token defined in your account Example: `x-oksign-authorization = 100693;463204-5BC1F362-85AD-34A3-9DB5-DC891D20979E;marketing` The x-oksign-token is the token when uploading the EditorExpress tokeninfo using the `EditorExpress.create` service. `x-oksign-token = 670816-483B7F54-8591-DDF9-FA77-9042AED3E8FD` The accept header should be application/json as a response in JSON format is returned. `accept = application/json; charset=utf-8`
Body	The body is empty.
Success Response	The response is a JSONObject indicating the status (OK, FAILED) and the reason. Example (success): { "reason": { "list": [ "744417-9457921D-3641-6480-D8AE-CD163CF66AEB" ], "contacts": [ { "actingas": "FCO", "email": "belinda.gates@ms.com", "mobile": "+32495123456", "name": "Belinda Gates" }, { "actingas": "CEO", "email": "bill.gates@ms.com", "mobile": "+32495123789", "name": "Bill Gates" } ], "returnurl": "https://www.betrust.be", "validityperiod": 300 }, "status": "OK" } Example (failure): { "reason": "Invalid format x-oksign-token. Found: 'zzz'. Expected: A valid format", "status": "FAILED" }
Error Response	In case of a severe error a 500 Internal Server Error is thrown (this should only happen in care cases).
Notes

EditorExpress remove service

URL	`https://oksign.be/services/rest/v1/editorexpress/remove`
Title	EditorExpress remove Remove a previously uploaded EditorExpress tokeninfo JSONObject from the platform
Method	DELETE
Request Headers	The x-oksign-authorization header's value is the combination of: Your accountnumber; The authoriation token defined in your account; The organizational token defined in your account Example: `x-oksign-authorization = 100693;463204-5BC1F362-85AD-34A3-9DB5-DC891D20979E;marketing` The x-oksign-token is the token when uploading the EditorExpress tokeninfo using the `EditorExpress.create` service. `x-oksign-token = 670816-483B7F54-8591-DDF9-FA77-9042AED3E8FD` The accept header should be application/json as a response in JSON format is returned. `accept = application/json; charset=utf-8`
Body	The body is empty.
Success Response	The response is a JSONObject indicating the status (OK, FAILED) and the reason (if FAILED). Example (success): {"status": "OK" } Example (failure): { "reason": "Invalid format x-oksign-token. Found: '837366-9A8BC315-3C28-2CF2-14D0-3840700XXXXX'. Expected: A valid format",, "status": "FAILED" }
Error Response	In case of a severe error a 500 Internal Server Error is thrown (this should only happen in care cases).
Notes

Email attachment upload service

URL	`https://oksign.be/services/rest/v1/emailattachment/upload`
Title	Email attachment upload Upload a file to be added as attachment to an email send from your account. The attachment is added to the email sent to signer(s) to inform a document is ready to be signed. The correct sequence to use this service is: Upload a document (PDF or Word) to your account using the `Document.upload` service. Upload file(s) to be used as attachments referring the docid if the document uploaded in the previous step using this service. Upload a Form descriptor (describing the form's fields) to your account using the `Formdesc.upload` service. If the Form descriptor contains a `notifications-->email` object an email is send and the uploaded attachments are added to the email. The attachments are also visible in the Email editor for the document concerned. Example:
Method	POST
Request Headers	The x-oksign-authorization header's value is the combination of: Your accountnumber; The authoriation token defined in your account; The organizational token defined in your account Example: `x-oksign-authorization = 100693;463204-5BC1F362-85AD-34A3-9DB5-DC891D20979E;marketing` The x-oksign-docid is the docid you received when uploading the document `Document.upload` service. Attachment(s) are attached to emails sent from your account to inform signer(s) this document (referenced with the `x-oksign-docid`) is ready to be signed. `x-oksign-docid = 670816-483B7F54-8591-DDF9-FA77-9042AED3E8FD` The x-oksign-filename is the filename of the attachment. Headers only support US-ASCII characters. Example: `x-oksign-filename = name.pdf` The content-type of the uploaded file. The accept header should be application/json as a response in JSON format is returned. `accept = application/json; charset=utf-8`
Body	Put the raw content of the file in the body. Example: %PDF-1.5 %µµµµ 1 0 obj <</Type/Catalog/Pages 2 0 R/Lang(nl-BE) /StructTreeRoot 59 0 R/MarkInfo<</Marked true>>>> endobj ...
Success Response	The response is a JSONObject indicating the status (OK, FAILED) and the reason is the ID of the uploaded document. This ID is needed with other webservices. Example: { "reason": "670816-483B7F54-8591-DDF9-FA77-9042AED3E8FD", "status": "OK" }
Error Response	In case of a severe error a 500 Internal Server Error is thrown.
Notes	The maximum size of all attachments uploaded linked to the document to sign (referenced with the `x-oksign-docid`) is 7Mb. Following types of files can be uploaded: application/pdf application/msword application/vnd.openxmlformats-officedocument.wordprocessingml.document application/vnd.openxmlformats-officedocument.spreadsheetml.sheet application/vnd.ms-excel text/csv text/plain application/zip application/vnd.openxmlformats-officedocument.presentationml.presentation application/vnd.ms-powerpoint image/png image/jpg image/jpeg IMPORTANT: Uploaded attachment files remain in your account until all signatures in the main document are in place (afterwards the uploaded document and any attachments are automatically removed) or the document is removed by you.

Email attachment remove service

URL	`https://oksign.be/services/rest/v1/emailattachment/remove`
Title	Email attachment remove Remove a previously uploaded file to be used as attachment from your account.
Method	DELETE
Request Headers	The x-oksign-authorization header's value is the combination of: Your accountnumber; The authoriation token defined in your account; The organizational token defined in your account Example: `x-oksign-authorization = 100693;463204-5BC1F362-85AD-34A3-9DB5-DC891D20979E;marketing` The x-oksign-attachid is the id of the previously uploaded file using the `EmailAttachment.upload` service. `x-oksign-attachid = 670816-483B7F54-8591-DDF9-FA77-9042AED3E8FD` The accept header should be application/json as a response in JSON format is returned. `accept = application/json; charset=utf-8`
Body	The body is empty.
Success Response	The response is a JSONObject indicating the status (OK, FAILED) and the reason (if FAILED). Example (success): {"status": "OK" } Example (failure): { "reason": "Attachment cannot be removed as Form Descriptor has already been uploaded", "status": "FAILED" }
Error Response	In case of a severe error a 500 Internal Server Error is thrown (this should only happen in care cases).
Notes

Contacts upload service

URL https://oksign.be/services/rest/v1/contacts/upload

Title Contacts upload
Insert or update contacts in the account's contacts list.
Important: The uniqueness (primary key) of each contact is defined by its email AND name fields. This allows you to define multiple contacts with the same email address.

Method POST

Request
Headers

The x-oksign-authorization header's value is the combination of:

Your accountnumber;
The authoriation token defined in your account;
The organizational token defined in your account

Example: x-oksign-authorization = 100693;463204-5BC1F362-85AD-34A3-9DB5-DC891D20979E;marketing

The x-oksign-clean defines whether or not the current contact list should be emptied before uploading the contacts.

x-oksign-clean=true

The content-type header should be application/json as the body is in JSON format:

content-type = application/json; charset=utf-8

The accept header should be application/json as a response in JSON format is returned.

accept = application/json; charset=utf-8

Body

A JSONArray containing the contact(s) to be added or updated in the account's contact list.
The JSONArray has following parameters:

Raw
[
	{
		"actingas": "CEO",
		"email": "bill.gates@microsoft.com",
		"group": "",
		"mobile": "+32488177123",
		"name": "Bill Gates"
	},
	{
		"actingas": "COO",
		"email": "melinda.gates@microsoft.com",
		"group": "",
		"mobile": "+32488177123",
		"name": "Melinda Gates"
	}
]

The passed JSONArray contains a list of contacts. Each contact contains following key/value pairs:

Parameter	R/O	Description
`email`	Required String	The email address of the contact.
`name`	Required String	The name of the contact.
`actingas`	Optional String	The capcity, status of the contact (CEO, Shareholder, Client, ...).
`mobile`	Optional String	The mobile number of of the contact in E164 format. Example: +32495123456.
`group`	Optional String	The group the contact belongs to. The group can be used to send a reusable document (GUI only) to all contacts in the group.

Success Response

The response is a JSONObject indicating the status (OK, FAILED) and the reason (optional).

Example (success):

{
	"status": "OK",
        "reason" : 83
}

If OK the reason contains the number of contacts added.
Example (failure):

{
	"reason": [
		"'name' not found for contact: {\"email\":\"bill.gates@microsoft.com\",\"namexxx\":\"Bill Gates\"}",

	],
	"status": "FAILED"
}

If FAILED the reason contains a list of contacts with errors.
Note: Contacts for which an error is detected are skipped during the upload process, the other contacts are uploaded.

Error Response In case of a severe error a 500 Internal Server Error is thrown (this should only happen in care cases).

Notes

Contacts retrieve service

URL	`https://oksign.be/services/rest/v1/contacts/retrieve`
Title	SignExpress retrieve Retrieve a list of the account's contacts.
Method	GET
Request Headers	The x-oksign-authorization header's value is the combination of: Your accountnumber; The authoriation token defined in your account; The organizational token defined in your account Example: `x-oksign-authorization = 100693;463204-5BC1F362-85AD-34A3-9DB5-DC891D20979E;marketing` The accept header should be application/json as a response in JSON format is returned. `accept = application/json; charset=utf-8`
Body	The body is empty.
Success Response	The response is a JSONObject indicating the status (OK, FAILED) and the reason. The reason contains a JSONArray with the list of contacts. Example (success): Raw { "reason": [ { "actingas": "CEO", "email": "bill.gates@microsoft.com", "group": "", "mobile": "+32488177123", "name": "Bill Gates" }, { "actingas": "COO", "email": "melinda.gates@microsoft.com", "group": "", "mobile": "+32488177123", "name": "Melinda Gates" } ] , "status": "OK" } Example (failure): { "reason": "Invalid format x-oksign-token. Found: 'zzz'. Expected: A valid format", "status": "FAILED" }
Error Response	In case of a severe error a 500 Internal Server Error is thrown (this should only happen in care cases).
Notes

Contacts remove service

URL https://oksign.be/services/rest/v1/contacts/remove

Title Contacts remove
Remove contacts in the account's contacts list.
Important: The uniqueness (primary key) of each contact is defined by its email AND name fields. This allows you to define multiple contacts with the same email address.

Method POST

Request
Headers

The x-oksign-authorization header's value is the combination of:

Your accountnumber;
The authoriation token defined in your account;
The organizational token defined in your account

Example: x-oksign-authorization = 100693;463204-5BC1F362-85AD-34A3-9DB5-DC891D20979E;marketing
The content-type header should be application/json as the body is in JSON format:

content-type = application/json; charset=utf-8

The accept header should be application/json as a response in JSON format is returned.

accept = application/json; charset=utf-8

Body

A JSONArray containing the contact(s) to be removed in the account's contact list.
The JSONArray has following parameters:

Raw
[
	{
		"email": "bill.gates@microsoft.com",
		"name": "Bill Gates"
	},
	{
		"email": "melinda.gates@microsoft.com",
		"name": "Melinda Gates"
	}
]

The passed JSONArray contains a list of contacts to remove. Each contact contains following key/value pairs:

Parameter	R/O	Description
`email`	Required String	The email address of the contact.
`name`	Required String	The name of the contact.

Success Response

The response is a JSONObject indicating the status (OK, FAILED) and the reason (optional).

Example (success):

{
	"status": "OK",
        "reason" : 15
}

If OK the reason contains the number of contacts removed. Example (failure):

{
	"reason": [
		"'name' not found for contact: {\"email\":\"bill.gates@microsoft.com\",\"namexxx\":\"Bill Gates\"}",

	],
	"status": "FAILED"
}

If FAILED the reason contains a list of errors detected.
Note: Contacts for which an errors is detected are not processed.

Error Response In case of a severe error a 500 Internal Server Error is thrown (this should only happen in care cases).

Notes

Email templates retrieve service

URL	`https://oksign.be/services/rest/v1/email-templates/retrieve`
Title	Email templates retrieve Retrieve a list of all email templates defined in the account.
Method	GET
Request Headers	The x-oksign-authorization header's value is the combination of: Your accountnumber; The authoriation token defined in your account; The organizational token defined in your account Example: `x-oksign-authorization = 100693;463204-5BC1F362-85AD-34A3-9DB5-DC891D20979E;marketing` The accept header should be application/json as a response in JSON format is returned. `accept = application/json; charset=utf-8`
Body	The body is empty.
Success Response	The response is a JSONObject indicating the status (OK, FAILED) and the reason. If the status is OK the reason contains the list of email templates (as a JSONArray). Example (success): Raw { "reason": [ { "body": "<p>Geachte,...</p>", "id": "000000-F6A3AE5C-84DC-459B-57C2-CB61B5B256AA", "name": "Contract-nl ", "reminder_days": "10", "repeat": "3", "subject": "Uw bestelbon te ondertekenen " }, { "body": "<p>Dear,...</p>", "id": "001234-F6A31234-84DC-1234-57C2-CB61B5B256AA", "name": "Contract-en", "reminder_days": "10", "repeat": "3", "subject": "Your order form ready to sign" } ] } The `id` is immutable. Once assigned to an email template it will never change. Example (failure): { "reason": "Invalid x-oksign-authorization pattern. Found: '999999;999999;test'. Expected: A valid pattern", "status": "FAILED" }
Error Response	In case of a severe error a 500 Internal Server Error is thrown (this should only happen in care cases).
Notes

Users retrieve service

URL	`https://oksign.be/services/rest/v1/users/retrieve`
Title	Users retrieve Retrieve a list of all users.
Method	GET
Request Headers	The x-oksign-authorization header's value is the combination of: Your accountnumber; The authoriation token defined in your account; The organizational token defined in your account Example: `x-oksign-authorization = 100693;463204-5BC1F362-85AD-34A3-9DB5-DC891D20979E;marketing` The accept header should be application/json as a response in JSON format is returned. `accept = application/json; charset=utf-8`
Body	The body is empty.
Success Response	The response is a JSONObject indicating the status (OK, FAILED) and the reason. If the status is OK the reason contains the list of users (as a JSONArray). Example (success): Raw { "reason": [ { "actingas": "CEO", "email": "bill.gates@microsoft.com", "language": "en", "mobile": "+32495123456", "name": "Bill Gates", "role": "owner", "signerid": "bt_00000000-0000-0000-0000-000000000000", "status": "active", "ts": "2023-11-21T11:18:14+01:00" }, { "actingas": "CEO", "email": "belinda.gates@microsoft.com", "language": "en", "mobile": "+32495123789", "name": "Belinda Gates", "role": "user", "signerid": "bt_00000000-0000-0000-0000-001097449068", "status": "active", "ts": "2023-11-21T11:18:14+01:00" } ], "status": "OK" } The `signerid` is immutable. Once assigned to a user it will never change. Example (failure): { "reason": "Invalid x-oksign-authorization pattern. Found: '999999;999999;test'. Expected: A valid pattern", "status": "FAILED" }
Error Response	In case of a severe error a 500 Internal Server Error is thrown (this should only happen in care cases).
Notes

OrgtokenInfo update service

URL https://oksign.be/services/rest/v1/orgtokeninfo/update

Title Orgtokeninfo update
Update the callbackurl, returnurl and webhookurl values linked to an Organisational token (API key - x-oksign-authorization).

Method POST

Request
Headers

The x-oksign-authorization header's value is the combination of:

Your accountnumber;
The authoriation token defined in your account;
The organizational token defined in your account

Example: x-oksign-authorization = 100693;463204-5BC1F362-85AD-34A3-9DB5-DC891D20979E;marketing

The content-type header should be application/json as the body is in JSON format:

content-type = application/json; charset=utf-8

The accept header should be application/json as a response in JSON format is returned.

accept = application/json; charset=utf-8

Body

A JSONArray containing the callbackurl, returnurl and webhookurl key/value pairs to be updated. These values are linked to the passed Organisational token (API key - x-oksign-authorization).
The JSONArray has following parameters:

Raw
{
	"callbackurl": "https://your.website.be/oksign/callback/...",
	"returnurl": "",
	"webhookurl": "https://your.website.be/oksign/webhook/..."
}

The passed JSONArray contains following key/value pairs:

Parameter	R/O	Description
`callbackurl`	Required String	The callbackurl value. If no callbackurl is needed, leave this value empty.
`returnurl`	Required String	The returnurl value. If no returnurl is needed, leave this value empty.
`webhookurl`	Required String	The webhookurl value. If no webhookurl is needed, leave this value empty.

Consult the OK!Sign API for more information regarding the use of the callbackurl, returnurl and webhookurl.

Success Response

The response is a JSONObject indicating the status (OK, FAILED) and the reason (optional).

Example (success):

{
	"status": "OK"
}

Example (failure):

{
	"reason": [
		"Missing key 'callbackurl'"
	],
	"status": "FAILED"
}

If FAILED the reason contains a list of errors.

Error Response In case of a severe error a 500 Internal Server Error is thrown (this should only happen in care cases).

Notes

API libraries

API libraries are provided for different languages. Checkout and use from Github using the links below. All you need is an API access key to get started with them. You can create your access key from API Console, after you sign up for an account with

.
Note: Maximum allowed timeout is 120 seconds.

PHP	https://github.com/brunogoossens/OKSign-examples
NodeJS	https://github.com/brunogoossens/OKSign-examples

Note: Some libraries might be outdated and not have been updated with the latest API changes.