Digitaal ondertekenen koppelen aan je applicatie via de API

Introduction

In cooperation with (the developers) of our customers, Stiply has created a powerful and blazingly fast RESTful API, to integrate our first class signing service in your own projects. The Stiply API is very easy to use and the reference documentation below should get you started in no time. Should you have any questions regarding the API whatsoever, or do you need a function that is not yet supported, then please don't hesitate to contact us at api@stiply.nl.

Privacy-by-design

Our application has been build with a privacy-by-design methodology in mind. That means that we only store the necessary personal data and that we keep it not longer than necessary. This means that we delete the signed documents and data after one month, at the end of the month.

How to use the API

To send a sign request to one or more signers, the following procedure should be followed:

Create a sign request
Add signer(s)
Send sign request

The status of a sign request may be checked at every moment. Once a sign request has been signed by all signers, the signed document and the proof document can be downloaded through the API.

URL and version

The base URL of the Stiply API is https://api.stiply.nl. The current version of the Stiply API is version 1.1. To use this the prefix for all API-calls is v1.1.https://api.stiply.nl/v1.1

Example

Should you want to use the PING function (as further described below) the URL you could call would be: https://api.stiply.nl/v1/actions/ping

Authentication

OAuth2

Starting from v1.1, authentication with the Stiply API will be through OAuth2 (https://oauth.net/2/). A full treatment of the OAuth2 protocol is beyond the scope of this article. Instead, the primary goal is to discuss what you need to do in order to work with OAuth2 in the context of the Stiply API.

Setup

First off, in order to connect with the Stiply API through OAuth you will need an account for which API access is enabled. Once this is done you will see an “API settings” item in the “Account” section of the right-top dropdown menu in the Stiply app:

Stiply_Connect_API_dropdown

Selecting this menu item will redirect you to a page where you can configure several API related settings^[1]. Specifically, the OAuth section will look something like:

Stiply_Connect_api_settings

Stiply offers two ways to use OAuth. The first one is the recommended, but also the most involved way to authenticate with the API. The second one is easier, but also less flexible and potentially less secure and is only really meant to be used for testing and experimentation purposes^[2]. We will first discuss the second option.

Personal Access Tokens

To create a new personal access token, simply click the “Create New Token” link. This will open a modal where you can enter the name of your new token:

Stiply_Connect_new_token_modal

After clicking the “Create” button you will receive a new personal access token:

Stiply_Connect_API_personal_access_token

This will be the only time it will be shown to you, so store it somewhere safely and don’t lose it. The token can now be used to make your requests to the Stiply API (see the Authentication section below). The token is valid for one month. Once it expires it can no longer be used to authenticate with the API and you will have to generate a new personal access token in order to do so.

Authorisation Code Grant

Although a personal access token is an easy way to connect with the Stiply API, the recommended way is by means of the authorisation code grant. This is a bit more involved and hence, we will discuss it in some detail.

In order to describe the authorisation redirect flow we will assume you have a consumer or client app. This app will be responsible for initiating and further handling of the authorisation redirect procedure that is at the base of OAuth2^[3].

The first step is to create a new OAuth client using the API settings page of the Stiply app:

Stiply_Connect_API_new_client_modal

The name of your client could essentially be anything, but ideally would be something your users will recognise and trust. The redirect URL field is where you will be redirected to after your user accepts your authorisation request^[4]. Once successfully created, you will see a new entry in the OAuth clients table:

Stiply_Connect_API_new_client

You can edit the details of this client or delete it if you no longer need it.

Now that you have registered a client with Stiply you can go ahead and reference it in your consumer app (i.e. your app that is consuming Stiply’s OAuth authentication services) in order to request an access token. The examples are written in PHP^[5], but should be easy enough to adapt to your own personal use case.

First off, the consuming application should make the following redirect request:

Route::get('/redirect', function (\Illuminate\Http\Request $request) { // Optional, but recommended; protection against XSRF

 $request->session()->put('state', $state = \Illuminate\Support\Str::random(40)); // Build the query parameter string to pass auth information to our request

 $query = http_build_query([ 'client_id' => 'my-client-id', 'redirect_uri' => 'http://consumer.test/callback', 'response_type' => 'code', 'state' => $state, ]);

 // Redirect the user to the OAuth authorisation page
 return redirect('https://app.stiply.nl/oauth/authorize?'.$query);
});

There are a couple of things to note here. As you can see, the “client_id” parameter is equal to the client id of the OAuth client we previously created in the Stiply app and the “redirect_uri” parameter is equal to the redirect URL field we specified when creating the client. Lastly, note that the root of the URL of our authorisation endpoint is https://app.stiply.nl (i.e. the URL of the Stiply app not the API). The root of the URL of our token endpoint is https://api.stiply.nl.

In response to this redirect request, and assuming the user is logged out of the Stiply app, the user will be redirected to the Stiply login page. After log in the user will be presented with the following view:

Stiply _Connect_API_auth_request

Clicking on the “Authorize” button then will redirect the user to your callback URL which in turn must be used to request the first access and refresh tokens:

// Route that user is forwarded back to after approving on server
Route::get('/callback', function (\Illuminate\Http\Request $request) {

 $state = $request->session()->pull('state');
   
 // If state parameters are different, someone else has initiated the request
 throw_unless(strlen($state) > 0 && $state === $request->state,\InvalidArgumentException::class);

 $http = new \GuzzleHttp\Client;

 $response = $http->post('https://api.stiply.nl/oauth/token', [
 'form_params' => [
  'grant_type' => 'authorization_code',
  'client_id' => 'my-client-id',
  'client_secret' => 'my-client-secret',
  'redirect_uri' => 'http://consumer.test/callback',
  'code' => $request->code, // Get authorisation code from the callback
  ],
 ]);

 // echo the response; normally we would save the access and refresh tokens in the DB
 return json_decode((string)$response->getBody(), true);
});

This will return a JSON response with the following content:

{
 "token_type": "Bearer",
 "expires_in": 1800,
 "access_token": "{accessToken}",
 "refresh_token": "{refreshToken}"
}

The access token can now be used to make your requests to the Stiply API (see the [Authentication](#authentiction) section). The access token is valid for 30 minutes. Once it expires you can use the refresh token to request a new access token:

// Route that may be used to request a new access token, using the refresh token
Route::get('/refresh_token', function () {
 $http = new \GuzzleHttp\Client;

 $response = $http->post('https://api.stiply.nl/oauth/token', [
  'form_params' => [
   'grant_type' => 'refresh_token',
   'refresh_token' => '{refreshToken}',
   'client_id' => 'my-client-id',
   'client_secret' => 'my-client-secret',
  ],
 ]);

 return json_decode((string) $response->getBody(), true);
});

This again will return a response of the form:

{
 "token_type": "Bearer",
 "expires_in": 1800,
 "access_token": "{accessToken}",
 "refresh_token": "{refreshToken}"
}

containing a new access and refresh token. Note that refresh tokens are valid for 14 days. Once they expire the user will have to restart the OAuth redirect procedure from the beginning.

In summary

1. Once a client has been created, you may use the client ID and secret to request an authorisation code from your application
2. Once the authorisation request has been approved the user will be redirected to your OAuth callback route from which you may now make a request to obtain your first access token using the authorisation code that is send along with your callback URL as a query parameter.
3. Once you have obtained your first access token you can use it to make requests to the Stiply API. Access tokens are valid for 30 minutes. Once they expire you can use the refresh token to request a new access (and refresh token). Refresh tokens are valid for 14 days, after which you will have to restart the authorisation redirect procedure from the beginning.

Authentication

Once you have obtained an access token, using either of the two previously discussed methods of generating such a token, authentication with the Stiply API is straightforward. Simply add a header to your request named “Authorization” and set its value equal to “Bearer YOUR_ACCESS_TOKEN”, where “YOUR_ACCESS_TOKEN” is the access token you either received in your callback or refresh token route in case of the authorisation code grant, or was displayed to you in the Stiply app after creating a new personal access token. An example in Postman:

Stiply_Connect_API_request

Note that the URL for making API requests using an access token is the URL of the Stiply API not the Stiply app and that all routes should be prefixed with v1.1 .

1: Currently, the only settings you can configure are purely OAuth related and hence, this tab will be selected by default.

2: It may also serve as a simpler approach to connect with the API, as it avoids the typical OAuth2 authorisation code redirect flow, but this is not recommended.

3: We assume you are already familiar with OAuth2 terminology and concepts that can, for instance, be found here: https://oauth2.thephpleague.com/terminology.

4: The root URL used here is purely for local test purposes. Hence the reason it starts with “http” and utilises the “.test” domain. In a more realistic setting it would rather look something like https://consumer.com.

5: Laravel to be exact, also see this for reference.

Reference

Ping

POST actions/ping (JSON)

Description

Test the API connections and authentication header

Preconditions

Status codes

200 Success 400 Wrong parameter

Parameters

Provide data in JSON

Parameters	Value	Description
ping_value	string	A string to send to the API. If the API responds correctly the same string will be returned

Example JSON

{"ping_value":"pong"}

Response

{  
 "ping_value": "pong",  
 "status_code": "200"
}

Create sign request

POST /sign_requests (FORM-DATA)

Description

Create new signature request.

Preconditions

Status codes

200 Success 400 Wrong parameter 415 Wrong media file type

Parameters

Provide data as FORM-DATA

Parameters	Value	Description
file	multipart/form-data	The file to be uploaded in DOC, DOCX or PDF
term	string	2 digit code representing the sign term (`1d` = 1 day, `2w` = 2 weeks, `3m` = 3 months)
doc_name (optional)	string	The name of the document. Please note this is not the name of the file but merely a label for the document.
message (optional)	string	The message to be included in the e-mail to the signers.
comment (optional)	string	A comment for internal use.
external_key (optional) (unique)	string	A key for your internal use so you don’t have to save the Stiply sign request key in your local database. However, your external key has to be unique.
call_back_url (optional)	url	An URL to be called by Stiply when the last signer has signed the document. Please note that key={sign_request_key} and external_key={external_key} shall be added to the call back url querystring.

Response

{
  "data": {
    "document": {
      "name": "End-user license agreement",
      "filename": "license-agreement.pdf",
      "file_size": "224615",
      "created_at": "2017-03-29T13:43:07+0200",
      "updated_at": "2017-03-29T13:43:07+0200"
    },
    "sign_request": {
      "key": "jgxfx3qYLaL9A2th3XejaOoODEp2QahRr1s5b3ki062JMu1k9n",
      "sent": 0,
      "sent_at": "0000-00-00 00:00:00",
      "all_signed": 0,
      "all_signed_at": "0000-00-00 00:00:00",
      "signed_hash": "",
      "proof_hash": "",
      "message": "Hi! Could you please sign our license agreement? Cheers!",
      "comment": "Customer wants to start asap",
      "external_key": "myexternalkey1234",
      "call_back_url": "https://www.myawesomewebsitecallbackurl.com/callback",
      "created_at": "2017-03-29T13:43:07+0200",
      "updated_at": "2017-03-29T13:43:07+0200",
      "terms": [
        {
          "term_code": "1w",
          "term_expired": 0,
          "term_expires": "0000-00-00 00:00:00",
          "created_at": "2017-03-29T13:43:07+0200"
        }
      ],
      "signers": []
    }
  }
}

Create signer

POST /sign_requests/[:sign_request_key]/signers (JSON)

Description

Add signer to sign request. This url may be called multiple times on one sign request to add multiple signers to the sign request.

Preconditions

Sign request must exist
Sign request has not been sent

Status codes

200 Success 400 Wrong parameter 403 Precondition failed 404 Sign request not found

Parameters

Provide data as JSON

Coordinates

To add a field by coordinates you have to specify the page, x-coordinate and y-coordinate of the field. Coordinates are in pixels, relative to the manager viewport. (0,0) is the top left corner. You can check the coordinates by logging in the manager (app.stiply.nl/manager) as an API-user and adding a field to a document: the coordinates will be displayed in the field. X-max: 516 Y-max: 956

Example

"signer_signature_fields":[{"page":1,"x":100,"y":200}]

Parameters	Value	Description
signer_email	email	The e-mail address of signer
signer_name	string	The name of signer
redirect_url (optional)	url	An URL to redirect the signer to when the signer has signed the document. Please note that key={sign_request_key}, signer_key={signer_key}, external_key={external_key}, status={success\|failure} and emandate_status={emandate_status} shall be added to the redirect url querystring.
signer_signature_fields	json array	Array with arrays containing signature field information, by using either a tag or coordinates.
signer_text_fields (optional)	json array	Text fields can be added in the same ways as signature fields: with a tag or with coordinates. The maximum values for the X and Y coordinates are: X-max: 524 Y-max: 1060 The top left of the field shall be positioned on the top left of the tag, provided that the field does not cross the page boundaries. You can optionally specify the width of the field, also provided that you keep within the minimum and maximum field dimensions. Example "signer_text_fields":[{"name":"text_field_1","width":"150"}] or "signer_text_fields":[{"page":1,"x":300,"y":300}, {"page":2,"x":400,"y":400}]
auth_method (optional)	string	Authentication method for signer. Currently `sms`, `emandate` and `idin`; are available as a valid option.
cell_phone_number (optional)	phone number	Cellular phone number of the signer is required in case auth_method is set to `sms`. Without setting auth_method to sms the phone number will not be saved. Phone numbers need to contain a country code as follows: `31655136642`
emandate (optional)	json array	You may add an optional emandate object, when auth_method is set to `emandate`. The emandate object has three parameters: instrument_code: Either `core` or `b2b`, core being for consumer emandates and b2b for business to business emandates. sequence_type: Either `rcur` or `ooff`, rcur being for a recurring emandate and ooff for a one-off emandate. emandate_id (optional): Your own emandate identifier. Is not set, Stiply will generate an emandate id for you. Example {"signer_email":"signer@stiply.nl","signer_signature_fields":[{"name":"signature_1"}], "auth_method":"emandate", "emandate":{"instrument_code":"core", "sequence_type":"rcur","emandate_id":"12345"}}
idin (optional)	json array	You may add an optional idin object, when auth_method is set to `idin`. The idin object has three parameters: prefix: The prefix of the name of the signer, for example if the signers name is Mike van der Meer, `van der` would be the prefix. last_name: The lastname of the signer, in the above example this would be `Meer`. date_of_birth: provide the date of birth of the signer here in the following format: `dd-mm-yyyy`, so for example `01-09-1982` Example {"signer_email":"signer@stiply.nl","signer_signature_fields":[{"name":"signature_1"}], "auth_method":"idin", "idin":{"prefix":"van der", "last_name":"meer","date_of_birth":"01-09-1982"}}
language (optional)	string	The language in which the signer receives correspondence. Current options are `nl`, `de`, `es`, `en`, `da`, `pl`, `it`, `fr`, `sv`. If no language is provided, the account language of sender will be used.
role (optional)	string	A signer can have different roles. When default, the signer will need to sign the document regularly. When the value `cc` is set as role, the signer shall be copy-only (cc).
invitation_method (optional)	string	If you would like to invite the signer yourself, you should set the invitation_method to `custom`. In that case Stiply shall not send an email with the sign request to the signer. Instead, when you send the sign request, the API shall return a unique sign link to you, which you can provide to the signer yourself.
message (optional)	string	You can send a specific message to a signer, that overrules the sign_request message in the mail to the signer.

Example JSON

{"signer_email":"signer@stiply.nl","signer_signature_fields":[{"name":"signature_0"}],"signer_text_fields":[{"name":"text_0"}], "auth_method":"sms","cell_phone_number":"31612345678"}

Response

{
  "data": {
    "key": "X7FylzU1MQlIaMEo4oec03lkQtI0wF2jtrEHQoXtotGDaDH5CI",
    "email": "signer@stiply.nl",
    "name": null,
    "order": 0,
    "language": "nl",
    "phone": 31612345678,
    "auth_method": "sms",
    "role": "",
    "sign_url": null,
    "emandate": [],
    "created_at": "2017-03-29T14:59:56+0200",
    "updated_at": "2017-03-29T14:59:57+0200",
    "signer_progresses": [],
    "fields": [
      {
        "type": "signature",
        "x": 91.34,
        "y": 865.35,
        "width": 250,
        "height": 125,
        "page": 1,
        "created_at": "2017-03-29T14:59:57+0200",
        "updated_at": "2017-03-29T14:59:57+0200"
      },
      {
        "type": "signature",
        "x": 144.64,
        "y": 755.36,
        "width": 230,
        "height": 20,
        "page": 1,
        "created_at": "2017-03-29T14:59:57+0200",
        "updated_at": "2017-03-29T14:59:57+0200"
      }
    ]
  }
}

Send sign request

POST /sign_requests/[:sign_request_key]/actions/send

Description

Send sign request to first signer

Preconditions

Sign request must exist
Sign request has not been sent
Sign request has at least 1 signer with at least 1 signature field

Status codes

200 Success 403 Precondition failed 404 Sign request not found

Parameters

Response

{
  "data": {
    "document": {
      "name": "End-user license agreement",
      "filename": "license-agreement.pdf",
      "file_size": "224615",
      "created_at": "2017-03-29T13:43:07+0200",
      "updated_at": "2017-03-29T13:43:07+0200"
    },
    "sign_request": {
      "key": "jfxfx3qYLoL9AHth3XejOOoODEp2QahRr1s5b3bi062JMu1k9n",
      "sent": 1,
      "sent_at": "2017-03-29T15:12:17+0200",
      "all_signed": 0,
      "all_signed_at": "0000-00-00 00:00:00",
      "signed_hash": "",
      "proof_hash": "",
      "message": "Hi! Could you please sign our license agreement? Cheers!",
      "comment": "Customer wants to start asap",
      "external_key": "myexternalkey1234",
      "call_back_url": "https://www.myawesomewebsitecallbackurl.com/callback",
      "created_at": "2017-03-29T13:43:07+0200",
      "updated_at": "2017-03-29T15:12:17+0200",
      "terms": [
        {
          "term_code": "1w",
          "term_expired": 0,
          "term_expires": "2017-04-05T15:12:17+0200",
          "created_at": "2017-03-29T13:43:07+0200"
        }
      ],
      "signers": [
        {
          "key": "X7FylzU1MQlIaMEo4oec03lkQtI0wF2jtrEHQoXtotGDaDH5CI",
          "email": "signer@stiply.nl",
          "name": null,
          "order": null,
          "phone": 31612345678,
          "auth_method": "sms",
          "created_at": "2017-03-29T14:59:56+0200",
          "updated_at": "2017-03-29T14:59:57+0200",
          "sign_url": null,
          "signer_progresses": [
            {
              "action": "mail_signrequest_sent",
              "ip": null,
              "location": null,
              "system": null,
              "value": "signer@stiply.nl",
              "created_at": "2017-03-29T15:12:17+0200",
              "status": null
            }
          ]
        }
      ]
    }
  }
}

Get signed document

GET /sign_requests/[:sign_request_key]/documents/actions/get_signed_document

Description

Get signed document of sign request.

Preconditions

Sign request must exist
Sign request has been signed by all signers

Status codes

200 Success 403 Precondition failed 404 Sign request not found

Parameters

Response

{
  "file_name": "license-agreement-[Ondertekend].pdf",
  "mimeType": "application/pdf",
  "file_size": "244087",
  "hash": "d24fe514aafcg15a79a9k3blb95b0237d0hf4d",
  "data": "JVBERi0xLjUNCiW1tbW1 (... long base64 ...) 00gl93a==",
  "status_code": "200"
}

Get proof document

GET /sign_requests/[:sign_request_key]/documents/actions/get_proof_document

Description

Get proof document of sign request.

Preconditions

Sign request must exist
Sign request has been signed by all signers

Status codes

200 Success 403 Precondition failed 404 Sign request not found

Parameters

Response

{
  "file_name": "license-agreement-[Bewijs].pdf",
  "mimeType": "application/pdf",
  "file_size": "244087",
  "hash": "2289ac9gkei61bd5b2306f90e27743fkaa184e64a",
  "data": "jQKJcOkw7zDtsOfC (... long base64 string ...) hg4fsa==",
  "status_code": "200"
}

Send reminder

POST /sign_requests/[:sign_request_key]/actions/send_reminder (JSON)

Description

Send a reminder e-mail to the current signer of the sign request.

Preconditions

Sign request must exist
Sign request has been sent

Status codes

200 Success 400 Wrong parameters 403 Precondition failed

Parameters

Response

{
  "data": {
    "document": {
      "name": "End-user license agreement",
      "filename": "license-agreement.pdf",
      "file_size": "224615",
      "created_at": "2017-03-29T16:57:19+0200",
      "updated_at": "2017-03-29T16:57:19+0200"
    },
    "sign_request": {
      "key": "eIGy1HCynD6B7QDo2gbsXeDoPKdjsLr1U8SNKGx1CMOzB77Peh",
      "sent": 1,
      "sent_at": "2017-03-29T16:58:16+0200",
      "all_signed": 0,
      "all_signed_at": "0000-00-00 00:00:00",
      "signed_hash": "",
      "proof_hash": "",
      "message": "Hi! Could you please sign our license agreement? Cheers!",
      "comment": "Customer wants to start asap",
      "external_key": "myexternalkey12345",
      "call_back_url": "https://www.myawesomewebsitecallbackurl.com/callback",
      "created_at": "2017-03-29T16:57:19+0200",
      "updated_at": "2017-03-29T16:58:16+0200",
      "terms": [
        {
          "term_code": "1w",
          "term_expired": 0,
          "term_expires": "2017-04-05T16:58:16+0200",
          "created_at": "2017-03-29T16:57:19+0200"
        }
      ],
      "signers": [
        {
          "key": "X7FylzU1MQlIaMEo4oec03lkQtI0wF2jtrEHQoXtotGDaDH5CI",
          "email": "signer@stiply.nl",
          "name": null,
          "order": null,
          "phone": 31612345678,
          "auth_method": "sms",
          "created_at": "2017-03-29T16:58:05+0200",
          "updated_at": "2017-03-29T16:58:06+0200",
          "sign_url": null,
          "signer_progresses": [
            {
              "action": "mail_signrequest_sent",
              "ip": null,
              "location": null,
              "system": null,
              "value": "signer@stiply.nl",
              "created_at": "2017-03-29T16:58:16+0200",
              "status": "failed"
            },
            {
              "action": "mail_reminder_sent",
              "ip": null,
              "location": null,
              "system": null,
              "value": "signer@stiply.nl",
              "created_at": "2017-03-29T16:58:27+0200",
              "status": null
            }
          ]
        }
      ]
    }
  }
}

Extend term

POST /sign_requests/[:sign_request_key]/actions/extend_term (JSON)

Description

Extend the term of an existing sign request.

Preconditions

Sign request must exist
Sign request has been sent

Status codes

200 Success 400 Wrong parameters

Parameters

Provide data in JSON

Parameters	Value	Description
term	string	2 digit code representing the sign term (`1d` = 1 day, `2w` = 2 weeks, `3m` = 3 months)

Example JSON

{"term":"2d"}

Response

{
  "data": {
    "document": {
      "name": "End-user license agreement",
      "filename": "license-agreement.pdf",
      "file_size": "224615",
      "created_at": "2017-03-29T16:57:19+0200",
      "updated_at": "2017-03-29T16:57:19+0200"
    },
    "sign_request": {
      "key": "eIGy1HCynD6B7QDo2gbsXeDoPKdjsLr1U8SNKGx1CMOzB77Peh",
      "sent": 1,
      "sent_at": "2017-03-29T16:58:16+0200",
      "all_signed": 0,
      "all_signed_at": "0000-00-00 00:00:00",
      "signed_hash": "",
      "proof_hash": "",
      "message": "Hi! Could you please sign our license agreement? Cheers!",
      "comment": "Customer wants to start asap",
      "external_key": "myexternalkey12345",
      "call_back_url": "https://www.myawesomewebsitecallbackurl.com/callback",
      "created_at": "2017-03-29T16:57:19+0200",
      "updated_at": "2017-03-29T16:58:16+0200",
      "terms": [
        {
          "term_code": "1w",
          "term_expired": 1,
          "term_expires": "2017-04-05T16:58:16+0200",
          "created_at": "2017-03-29T16:57:19+0200"
        },
               {
                  "term_code": "2d",
                  "term_expired": 0,
                  "term_expires": "2017-04-08T09:00:00+0200",
                  "created_at": "2017-04-06T09:00:00+0200"
               },
      ],
      "signers": [
        {
          "key": "X7FylzU1MQlIaMEo4oec03lkQtI0wF2jtrEHQoXtotGDaDH5CI",
          "email": "signer@stiply.nl",
          "name": null,
          "order": null,
          "phone": 31612345678,
          "auth_method": "sms",
          "created_at": "2017-03-29T16:58:05+0200",
          "updated_at": "2017-03-29T16:58:06+0200",
          "sign_url": null,
          "signer_progresses": [
            {
              "action": "mail_signrequest_sent",
              "ip": null,
              "location": null,
              "system": null,
              "value": "signer@stiply.nl",
              "created_at": "2017-03-29T16:58:16+0200",
              "status": "failed"
            },
            {
              "action": "mail_term_extended_sent",
              "ip": null,
              "location": null,
              "system": null,
              "value": "signer@stiply.nl",
              "created_at": "2017-03-29T16:58:27+0200",
              "status": null
            }
          ]
        }
      ]
    }
  }
}

Get sign requests

GET /sign_requests?sent=1&canceled=0&all_signed=1&$top=10&$skip=30

Description

Get a list with sign requests

Status codes

200 Success

Parameters

Parameters	Value	Description
sent (optional)	boolean	1: only return sent sign requests 0: only return unsent sign requests When not provided both sent and unsent sign requests are returned
canceled (optional)	boolean	1: only return canceled sign requests 0: only return sign requests that are not canceled When not provided the sign requests are not filtered on the canceled value.
all_signed (optional)	boolean	1: only return sign requests where all signers have signed the document 0: only return sign requests where some signers haven't signed the document When not provided the sign requests are not filtered on the all_signed value.
$top (optional)	integer between 1 and 100	The number of sign requests to return in the response default: 100
$skip (optional)	positive integer	The number of sign requests to skip in the response

Response

{
    "data": [
        {
            "sign_request": {
                "key": "hE0NNZTIYfxtDLNC2ylhSOqtM0tB9BoPY4qxpTHztTcRYbdLr2",
                "document_name": "Test4",
                "signers": [
                    {
                        "key": "Z64ykTPuCervprfJPv9zlqSAEN7cB2NUmLrtRtQJiTv4TCb7Pr",
                        "email": "john.doe@example.com"
                    }
                ],
                "sent": 1,
                "sent_at": "2019-09-05T09:01:26+0200",
                "all_signed": 1,
                "all_signed_at": "2019-09-05T09:06:34+0200",
                "signed_hash": "295c07e906b08540e991deea42b3ee86537b2309",
                "proof_hash": "5478387f2d9108c33a7450c46bde54ef25ffc83f",
                "canceled": 0,
                "canceled_at": "0000-00-00 00:00:00",
                "message": "Test",
                "comment": null,
                "external_key": null,
                "created_at": "2019-09-05T09:01:12+0200",
                "updated_at": "2021-01-12T13:41:01+0100"
            }
        },
        {
            "sign_request": {
                "key": "eEAaoGFXs6A9tiyDlDMqqCQ5dWEIJisgcbvnMe1rF2MITnoqxt",
                "document_name": "Test4",
                "signers": [
                    {
                        "key": "QuZpGpmFW5hGUdgi4pc8eU0Pk1gG04vRIbYnjLCc4d37TvcFED",
                        "email": "john.doe@example.com"
                    }
                ],
                "sent": 1,
                "sent_at": "2019-09-05T09:14:51+0200",
                "all_signed": 1,
                "all_signed_at": "2019-09-05T09:15:08+0200",
                "signed_hash": "efafec803f7152243b48048e64400e98443b78d2",
                "proof_hash": "fb7f3141e13cc1205b0c1840e2179f85c0fa6543",
                "canceled": 0,
                "canceled_at": "0000-00-00 00:00:00",
                "message": "Test",
                "comment": null,
                "external_key": null,
                "created_at": "2019-09-05T09:14:39+0200",
                "updated_at": "2021-01-12T13:41:01+0100"
            }
        },
        {
            "sign_request": {
                "key": "87T5XDF059SoJtSz9bclLJpphnKgCO83X3kcF2OffULzkdMtjX",
                "document_name": "Test4",
                "signers": [
                    {
                        "key": "FeSar9Qxhw2HFRjJKn6kyA81bOCzAloVEnwBxhHHtgmag0HNpG",
                        "email": "john.doe@example.com"
                    }
                ],
                "sent": 1,
                "sent_at": "2019-09-05T12:14:49+0200",
                "all_signed": 1,
                "all_signed_at": "2019-09-05T13:38:24+0200",
                "signed_hash": "b97d1ac1e3c406ea15771281ebc9619fabb3ef69",
                "proof_hash": "5d879de09ea7d203b4ded9d583e033f2f83c970c",
                "canceled": 0,
                "canceled_at": "0000-00-00 00:00:00",
                "message": null,
                "comment": null,
                "external_key": null,
                "created_at": "2019-09-05T09:27:45+0200",
                "updated_at": "2021-01-12T13:41:01+0100"
            }
        }
    ]
}

Get sign request key

GET /sign_requests/[:your_external_key]/actions/get_sign_request_key

Description

Get sign request key from external key (your local key).

Preconditions

Sign request must exist

Status codes

200 Success 400 External key not found or invalid

Parameters

Response

{
  "key": "eIGy1HCynD6B7QDo2gbsXeDoPKdjsLr1U8SNKGx1CMOzB77Peh",
  "status_code": "200"
}

Get sign request

GET /sign_requests/[:sign_request_key]

Description

Get a specific sign request

Preconditions

Sign request must exist

Status codes

200 Success 404 Sign request not found

Parameters

Response

{
  "data": {
    "document": {
      "name": "End-user license agreement",
      "filename": "license-agreement.pdf",
      "file_size": "224615",
      "created_at": "2017-03-29T16:57:19+0200",
      "updated_at": "2017-03-29T16:57:19+0200"
    },
    "sign_request": {
      "key": "eIGy1HCynD6B7QDo2gbsXeDoPKdjsLr1U8SNKGx1CMOzB77Peh",
      "sent": 1,
      "sent_at": "2017-03-29T16:58:16+0200",
      "all_signed": 0,
      "all_signed_at": "0000-00-00 00:00:00",
      "signed_hash": "",
      "proof_hash": "",
      "message": "Hi! Could you please sign our license agreement? Cheers!",
      "comment": "Customer wants to start asap",
      "external_key": "myexternalkey12345",
      "call_back_url": "https://www.myawesomewebsitecallbackurl.com/callback",
      "created_at": "2017-03-29T16:57:19+0200",
      "updated_at": "2017-03-29T16:58:16+0200",
      "terms": [
        {
          "term_code": "1w",
          "term_expired": 1,
          "term_expires": "2017-04-05T16:58:16+0200",
          "created_at": "2017-03-29T16:57:19+0200"
        },
               {
                  "term_code": "2d",
                  "term_expired": 0,
                  "term_expires": "2017-04-08T09:00:00+0200",
                  "created_at": "2017-04-06T09:00:00+0200"
               },
      ],
      "signers": [
        {
          "key": "X7FylzU1MQlIaMEo4oec03lkQtI0wF2jtrEHQoXtotGDaDH5CI",
          "email": "signer@stiply.nl",
          "name": null,
          "order": null,
          "phone": 31612345678,
          "auth_method": "sms",
          "created_at": "2017-03-29T16:58:05+0200",
          "updated_at": "2017-03-29T16:58:06+0200",
          "sign_url": null,
          "signer_progresses": [
            {
              "action": "mail_signrequest_sent",
              "ip": null,
              "location": null,
              "system": null,
              "value": "signer@stiply.nl",
              "created_at": "2017-03-29T16:58:16+0200",
              "status": "failed"
            },
            {
              "action": "mail_reminder_sent",
              "ip": null,
              "location": null,
              "system": null,
              "value": "signer@stiply.nl",
              "created_at": "2017-03-29T16:58:27+0200",
              "status": null
            }
          ]
        }
      ]
    }
  }
}

Delete sign request

DELETE /sign_requests/[:sign_request_key]

Description

Delete a specific sign request

Preconditions

Sign request must exist

Status codes

200 Success 404 Sign request not found 422 Deleting sign request not succesful

Parameters

Response

{
  "message": "Ondertekenverzoek en document succesvol verwijderd.",
  "status_code": "200"
}

Get signer

GET /sign_requests/[:sign_request_key]/signers/[:signer_key]

Description

Get a specific signer

Preconditions

Sign request must exist
Signer must exist

Status codes

200 Success 404 Sign request or signer not found

Parameters

Response

{
  "data": [
    {
      "key": "xuSfW4HkRZHW2dRZipk8jIefqYVsMdWXK3QmWALbMJ216NPdRZ",
      "email": "signer@stiply.nl",
      "name": null,
      "order": 0,
      "language": "nl",
      "phone": 31612345678,
      "auth_method": "sms",
      "role": "",
      "sign_url": null,
      "emandate": [],
      "created_at": "2017-03-29T16:58:05+0200",
      "updated_at": "2017-03-29T16:58:06+0200",
      "signer_progresses": [
        {
          "action": "mail_signrequest_sent",
          "ip": null,
          "location": null,
          "system": null,
          "value": "signer@stiply.nl",
          "created_at": "2017-03-29T16:58:16+0200"
        },
        {
          "action": "mail_reminder_sent",
          "ip": null,
          "location": null,
          "system": null,
          "value": "signer@stiply.nl",
          "created_at": "2017-03-29T16:58:27+0200"
        }
      ],
      "fields": [
        {
          "type": "signature",
          "x": 91.34,
          "y": 865.35,
          "width": 250,
          "height": 125,
          "page": 1,
          "created_at": "2017-03-29T16:58:06+0200",
          "updated_at": "2017-03-29T16:58:06+0200"
        },
        {
          "type": "signature",
          "x": 144.64,
          "y": 755.36,
          "width": 230,
          "height": 20,
          "page": 1,
          "created_at": "2017-03-29T16:58:06+0200",
          "updated_at": "2017-03-29T16:58:06+0200"
        }
      ]
    }
  ]
}

Update signer

PUT /sign_requests/[:sign_request_key]/signers/[:signer_key] (JSON)

Description

Update the e-mail address and/or telephone number of a signer who has not yet signed. It is required to post both values, email and phone, when updating. Should you only want to update one of these, just submit the original value of the other. Please note that in case a signer has already received the sign request email and you update the email address of the signer afterwards, the link in the signer’s e-mail will not work anymore. The signer shall not receive a new sign request e-mail on the new e-mail address. Please use Send Reminder for that purpose after the e-mail address has been updated. If you only update the phone number the original sign link still works so no reminder is required.

Preconditions

Sign request must exist
Signer must exist
Signer has not signed

Status codes

200 Success 400 Wrong parameters 404 Sign request or signer not found

Parameters

Provide data in JSON

Parameters	Value	Description
new_email	email	New email of signer to which the reminder mail will be send. This value will replace the e-mail of the signer permanently
new_cell_phone_number	phone number	New phone number of signer to which the authentication text will be send. This value will replace phone number of the signer permanently

Example JSON

{"new_email":"newemail@stiply.nl","new_cell_phone_number":"+31612345678"}

Response

{
  "data": [
    {
      "key": "xuSfW4HkRZHW2dRZipk8jIefqYVsMdWXK3QmWALbMJ216NPdRZ",
      "email": "newemail@stiply.nl",
      "name": null,
      "order": 0,
      "language": "nl",
      "phone": 31612345678,
      "auth_method": "sms",
      "role": "",
      "sign_url": null,
      "emandate": [],
      "created_at": "2017-03-29T16:58:05+0200",
      "updated_at": "2017-03-29T16:58:06+0200",
      "signer_progresses": [
        {
          "action": "mail_signrequest_sent",
          "ip": null,
          "location": null,
          "system": null,
          "value": "signer@stiply.nl",
          "created_at": "2017-03-29T16:58:16+0200"
        },
        {
          "action": "mail_reminder_sent",
          "ip": null,
          "location": null,
          "system": null,
          "value": "signer@stiply.nl",
          "created_at": "2017-03-29T16:58:27+0200"
        }
      ],
      "fields": [
        {
          "type": "signature",
          "x": 91.34,
          "y": 865.35,
          "width": 250,
          "height": 125,
          "page": 1,
          "created_at": "2017-03-29T16:58:06+0200",
          "updated_at": "2017-03-29T16:58:06+0200"
        },
        {
          "type": "signature",
          "x": 144.64,
          "y": 755.36,
          "width": 230,
          "height": 20,
          "page": 1,
          "created_at": "2017-03-29T16:58:06+0200",
          "updated_at": "2017-03-29T16:58:06+0200"
        }
      ]
    }
  ]
}

Delete signer

DELETE /sign_requests/[:sign_request_key]/signers/[:signer_key]

Description

Delete a specific signer

Preconditions

Sign request must exist
Sign request has not been sent
Signer must exist

Status codes

200 Success 404 Sign request not found 422 Deleting signer not succesful

Parameters

Response

{
  "message": "Ondertekenaar succesvol verwijderd.",
  "status_code": "200"
}

Stiply Connect API documentatie

Introduction

Authentication

Reference

Introduction

Privacy-by-design

How to use the API

URL and version

Example

SDK's we provide

Authentication

OAuth2

Setup

Personal Access Tokens

Authorisation Code Grant

In summary

Authentication

Reference

Ping

Description

Preconditions

Status codes

Parameters

Example JSON

Response

Create sign request

Description

Preconditions

Status codes

Parameters

Response

Create signer

Description

Preconditions

Status codes

Parameters

Tags

Example

Coordinates

Example

Example

Example

Example

Example JSON

Response

Send sign request

Description

Preconditions

Status codes

Parameters

Response

Get signed document

Description

Preconditions

Status codes

Parameters

Response

Get proof document

Description

Preconditions

Status codes

Parameters

Response

Send reminder

Description

Preconditions

Status codes

Parameters

Response

Extend term

Description

Preconditions

Status codes

Parameters

Example JSON

Response

Get sign requests

Description

Status codes

Parameters