OKSign API - REST services

OKSign API

This information is only available in English.

History

Document history
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 Sign online - OKSign Logo API to easily scale from simple eSignature integrations to complex enterprise applications.
The Sign online - OKSign Logo 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
Login into your account and check the number of credits and available/maximum storage. Example:
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:
  1. Upload a document (PDF or Word) to the Sign online - OKSign Logo platform using the Document.upload service.
  2. Upload a form descriptor (describing the form's (signature) fields) to the Sign online - OKSign Logo platform using the Formdesc.upload service.
  3. The Formdesc.upload service returns a signing URL you can send to the signer(s).
  4. 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).
  5. 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).
  6. 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.

  7. 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.

  8. 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).
  9. Use the Document.remove service to remove the (signed) document from the Sign online - OKSign Logo platform.

List of available services

Basic services:

Document.upload POST Upload a document (PDF or Word) to the Sign online - OKSign Logo platform
FormDesc.upload POST Upload the Form Descriptor to the Sign online - OKSign Logo platform
Notifications.upload POST Upload the Notifications to the Sign online - OKSign Logo 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 Sign online - OKSign Logo platform
Document.exists GET Does a (signed) document still exists on the Sign online - OKSign Logo platform?
Document.remove DELETE Remove a (signed) document from the Sign online - OKSign Logo 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 Sign online - OKSign Logo platform.

Email Attachment services
The Email Attachment services allows you to add attachment(s) to an email sent via your Sign online - OKSign Logo 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 Sign online - OKSign Logo platform.
EmailAttachment.remove DELETE Remove a previously uploaded attachment file.

EditorExpress services
The EditorExpress services allows you to invoke the Sign online - OKSign Logo 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 Sign online - OKSign Logo 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 Sign online - OKSign Logo 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:
  1. Login into your account;
  2. Select the Active documents (Actieve documenten, Documents actifs) button
  3. Click on the wrench fa-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).
  4. The Forms Editor opens. Select the fa-wrench API button to copy the Form Descriptor (JSONObject):
  5. 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
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:
  • 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).
    E.164 Format Country Code Country Subscriber Number
    +32495123456 32 BE 495123456
    +442071838750 44 GB 2071838750
    +551155256325 55 BR 1155256325
  • A validity check is done on email and mobile number. If not valid, an error is thrown.


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:
  1. In your PDF/Word document mark each field position with a unique text, for example: _sb1_
  2. Now reference this text in the marker key/value pair of the corresponding field (see below).
  3. You no longer define the pagenbr, posX and posY parameters (as you don't know these values).
  4. 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 Sign online - OKSign Logo 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 Sign online - OKSign Logo 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:
  1. Login into your account;
  2. Select REST API in the menu.
  3. Select SignerIDs
  4. A list appears of all teammembers (users) and their corresponding signerid.
  5. 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 signign 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 Sign online - OKSign Logo 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 Sign online - OKSign Logo 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 Sign online - OKSign Logo 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 Sign online - OKSign Logo 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
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.

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 Sign online - OKSign Logo account after 2021-05-05. ***
Sign online - OKSign Logo 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 Sign online - OKSign Logo 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.
    • Briefcase OKSign
  • 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 Sign online - OKSign Logo 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 signign 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
    Fit Signing screen in viewport | OKSign
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 Sign online - OKSign Logo 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 Sign online - OKSign Logo 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
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 Sign online - OKSign Logo 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 Sign online - OKSign Logo 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 signign 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 Sign online - OKSign Logo 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 Sign online - OKSign Logo 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 Sign online - OKSign Logo editor from your own application.
The Sign online - OKSign Logo editor acts as a 'scratchpad' allowing your user to define fields interactively.

The flow is as follows:
  1. Upload the PDF/Word document using the Document.upload service
  2. (Optional) Upload a FormDescriptor defining some (prepopulated) fields
  3. Call this service (see details below). You'll receive a link to an Sign online - OKSign Logo editor instance
  4. From within your application redirect the browser to the Sign online - OKSign Logo editor using the link.
  5. The user defines (signature) fields in the editor
  6. The user clicks the Save or Cancel button
  7. The browser is redirected using the returnURL defined in this service with the status=OK (Save) or status=FAILED (Cancel) as uri parameter
  8. Retrieve the updated FormDescriptor using the FormDesc.retrieve service
  9. Remove the document using the Document.remove service
  10. 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
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 Sign online - OKSign Logo 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 Sign online - OKSign Logo 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 Sign online - OKSign Logo 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 Sign online - OKSign Logo 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:
  1. Upload a document (PDF or Word) to your Sign online - OKSign Logo account using the Document.upload service.
  2. Upload file(s) to be used as attachments referring the docid if the document uploaded in the previous step using this service.
  3. Upload a Form descriptor (describing the form's fields) to your Sign online - OKSign Logo 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 Sign online - OKSign Logo 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 Sign online - OKSign Logo 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): 
{
	"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  

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): 
{
  "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

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 Sign online - OKSign Logo.
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.