Developer Guide

Learn how to access and integrate SignSpace service via an application programming interface (API).

This is a stripped-down version of the API documentation suited for the most basic integration case. In short, these are the steps in order to successfully create a signing request:

  1. Authenticate yourself by using instructions provided here: API documentation for SignSpace v2#Authentication
  2. Create file or files in SignSpace by following instructions provided here: Create File(s). Store the created files' IDs internally for further use.
  3. Create a signing request with the files created in Step 2 by following instructions provided in Create Signing Request. Store the ID of the created signing request for further use.
  4. Retrieve signed documents by following instructions from Downloading Signed Files

 

Authentication

Here are the respective URLs for partner sandbox environment and the production environment:

  Partner sandbox environment Production environment
Cognito IdP URL https://signspace.staging-vastuugroup.fi/auth/token https://app.signspace.com/auth/token
Signspace API URL https://signspace.staging-vastuugroup.fi/api/v1/ https://app.signspace.com/api/v1/

 

To retrieve an access token, make a POST request to identity provider URL similar to this:

curl -X POST --user $CLIENT_CREDENTIALS -d "grant_type=client_credentials" $IDENTITY_PROVIDER_URL

 

$CLIENT_CREDENTIALS - the client ID and secret separated by a colon (<client_id>:<client_secret>)

 

Once you receive the token, use it in all requests like this:

curl -X GET -H "Authorization: Bearer $TOKEN" $URL

 

 

1. Create File(s)

Endpoint: /api/v1/files.create

Scopes needed: files.create

Description: Creates a file from Base64 encoding and returns the created object.

Allowed parameters:

Parameter Description
acting_handle Id of value of the acting handle
name Name of the file
base64 Base64 encoding of the file
importance_order Number of priority for displaying the file in the signing process. Higher the number, the earlier the file will be shown.

Note: Parameters in bold are mandatory.

Example request payload:

{
    "acting_handle": "robot.email@domain.com",
    "base64": "dGVzdCBkb2N1bWVudA==",
    "name": "File name",
    "importance_order": 1
}
 

cURL:

curl -XPOST -H "Authorization: Bearer $TOKEN" -H "Content-type: application/json" -d '{"acting_handle": "robot.email@domain.com", "base64": "dGVzdCBkb2N1bWVudA==", "name": "File name", "importance_order": 1}' 'https://signspace.staging-vastuugroup.fi/api/v1/files.create'

 

 

2. Create Signing Request

Endpoint: /api/v1/tasks.signingRequest.create

Scopes needed: tasks.signingRequest.create

Description: Creates a signing request task and returns the created object.

Allowed parameters:

 
Parameter Description

version

 Version of signing request to use. Either "v1" or "v2". For version 2 use "v2"
title Title of signing request
signing_discussion_disabled If set to "true", users will not be able to post any messages to the conversations related to the signing request. Default is "false"
signature_strength

"light" - Signatory will be able to sign without any verifications (this is the default)

"strong" - Signatory will perform one-time strong electronic identification during the signing process using Bank ID or Mobile ID
recipient_language Set the language in which users will receive emails regarding the signing request. Options: "en", "fi", "sv". Default: "en"
participants_list_order_respected If set to "true", you can set order in which the signatories will sign in
participants List of participants objects:
  Field Description
  handle Email address of the recipient
  role Role of the participant. Use "signer" for signatory and "watcher" for CC.
  display_name Full name of the participant. If empty, user will have to fill this information in the signing process
  position Order of when the signatory should sign. e.g. 1, 2, 3. Only applicable if participants_list_order_respected is enabled.

Example:

{
    "handle": "namesurname@domain.com",
    "role": "signer",
    "display_name": "Name Surname"
}
owners_handles List of handles that will have owner privileges (acting_handle is added by default). To add group, use this format "group:63a199d56cd3aa8f6875e3b3" where 63a199d56cd3aa8f6875e3b3 is the group ID.
overdue_signing_disabled If set to "true", signing after due_date is not possible. Default is "false"
invitation_type

"default_signing" - Default setting. All signatories gain access to the space of the signing request.

"force_swr" - If set, both registered and unregistered signatories will be forced to use the signing without registration flow. Signatories will not gain access to the space of the signing request (except for the creator of the signing request)
files List of files IDs. Can be retrieved from the response payload of files.create (field name _id)
due_date ISO format date of due date. After passing the date, signing request is put in "OVERDUE" state. You can control whether signatories can sign in that state with "overdue_signing_disabled" parameter
description Description of task
create_conversation If set to "true", this will create a container for the signing request. For version v2, set this to True. This replaces the need for calling two more endpoints to fully create and send out the signing request.
cannot_sign_disabled If set to "true", users will not be able to decline signing. Default is "false"
acting_handle ID or email of the acting handle


Note: Parameters in bold are mandatory.

Example request payload:

{
    "files": ["62a85fd06cd3aa6e70d1af2d"],
    "title": "Signing request title",
    "description": "Signing request description",
    "acting_handle": "robot.email@domain.com",
    "create_conversation": true,
    "participants": [{
            "handle": "signatory1@domain.com",
            "role": "signer",
            "display_name": "Name Surname"
        },
        {
            "handle": "participant0@handle.com",
            "role": "signer"
        }
    ],
    "recipient_language": "fi",
    "version": "v2"
}


cURL:

curl -XPOST -H "Authorization: Bearer $TOKEN" -H "Content-type: application/json" -d '{"files": ["62a85fd06cd3aa6e70d1af2d"], "title": "Signing request title", "description": "Signing request description", "acting_handle": "robot.email@domain.com", "participants": [{ "handle": "signatory1@domain.com", "role": "signer", "display_name": "Name Surname" }, { "handle": "participant0@handle.com", "role": "signer"} ], "create_conversation": true, "recipient_language": "fi", "version": "v2"}' 'https://signspace.staging-vastuugroup.fi/api/v1/tasks.signingRequest.create'

 

Downloading Signed Files

Summary: In order to retrieve the signed documents you will need to fetch all completed signing requests by either using endpoint /api/v1/tasks.list or /api/v1/tasks.get (if you have the IDs of the signing requests). Both endpoints return a list of signing requests. You can retrieve the IDs of signed files by accessing the field "signed_files" of these signing request objects. Once the IDs are retrieved, files can be downloaded via /api/v1/files.download endpoint. More information about how to use the endpoints below:

Listing completed signing requests

Endpoint: /api/v1/tasks.list (GET)

Scopes needed: tasks.list

Description: Returns all signing requests available.

Allowed parameters:

Parameter name Options Description
status "complete" | "in_progress" | "open" | "on_hold" | "cancelled" Filter by status of the signing requests
type "signing_request" Filter by type of task. For this case it should always be "signing_request"
limit Default: 20 Limit the maximum number of signing requests returned


Example cURL:

curl -XGET -H "Authorization: Bearer $TOKEN" 'https://signspace.staging-vastuugroup.fi/api/v1/tasks.list?type=signing_request&amp;status=complete&amp;limit=100'

 

Endpoint: /api/v1/tasks.get (GET)

Scopes needed: tasks.get

Description: Returns a list of signing requests filtered by given IDs.

Example cURL:

curl -XGET -H "Authorization: Bearer $TOKEN" 'https://signspace.staging-vastuugroup.fi/api/v1/tasks.get?id=62a85fc66cd3aa6e70d1af2c&amp;id=62a85fd06cd3aa6e70d1af2d'

 

Downloading files

Endpoint: /api/v1/files.download

Allowed methods: GET

Description: Downloads file that matches the given ID. Also scans the file for viruses if the file has not been scanned in the last 6 hours.

Allowed parameters:

Parameter Description
id Id or a list of IDs of file to download


cURL:

curl -XGET -H "Authorization: Bearer $TOKEN" 'https://signspace.staging-vastuugroup.fi/api/v1/files.download?id=62a85fc66cd3aa6e70d1af2c&amp;id=62a85fd06cd3aa6e70d1af2d'

 

Cancel Signing Request

Endpoint: /api/v1/tasks.cancel

Allowed methods: POST

Description: Marks the task as cancelled, disabling participants from performing actions to it.

Allowed parameters:

acting_handle Value or id of handle that is initializing the signing
task ID of the signing request


Example payload:

{
    "acting_handle": "robot.email@domain.com",
    "task": "63a198e76cd3aa8f6875e3b2"
}


cURL:

curl -XPOST -H "Authorization: Bearer token" -H "Content-type: application/json" -d '{"acting_handle": "robot.email@domain.com","task": "63a198e76cd3aa8f6875e3b2"}' 'https://signspace.staging-vastuugroup.fi/api/v1/tasks.cancel'

 

Re-open Signing Request

Endpoint: /api/v1/tasks.open

Allowed methods: POST

Description: Re-opens the signing request after it was cancelled or put on hold. After the signing request is re-opened, all the pending signatories can sign the attached documents.

Allowed parameters:

acting_handle Value or id of handle that is initializing the signing
task ID of the signing request

 


Example payload:

{
    "acting_handle": "robot.email@domain.com",
    "task": "63a198e76cd3aa8f6875e3b2"
}

 

cURL:

curl -XPOST -H "Authorization: Bearer token" -H "Content-type: application/json" -d '{"acting_handle": "robot.email@domain.com","task": "63a198e76cd3aa8f6875e3b2"}' 'https://signspace.staging-vastuugroup.fi/api/v1/tasks.open'

 

Edit Files of a Signing Request

Endpoint: /api/v1/tasks.signingRequest.update

Allowed methods: POST

Description: Endpoint for editing signing request's parameters, including files. The endpoint will set the new list of files on the signing request. This means that previous files will no longer be signable if their IDs are not in the files list.

Allowed parameters:

acting_handle Value or id of handle that is initializing the signing
task ID of the signing request
files List of file ids


Example payload:

{
    "acting_handle": "robot.email@domain.com",
    "task": "63a198e76cd3aa8f6875e3b2",
    "files": ["63a19b546cd3aa8f6875e3b4", "63a19b566cd3aa8f6875e3b5"]
}

 

cURL:

curl -XPOST -H "Authorization: Bearer token" -H "Content-type: application/json" -d '{"acting_handle": "robot.email@domain.com", "task": "63a198e76cd3aa8f6875e3b2", "files": ["63a19b546cd3aa8f6875e3b4", "63a19b566cd3aa8f6875e3b5"]}' 'https://signspace.staging-vastuugroup.fi/api/v1/tasks.signingRequest.update'

 

Enable SSN (Social Security Number) Verification

In order to enable verification of SSN for signatories, the request payload of /api/v1/tasks.signingRequest.create needs to be appended with "is_protected: true"

If protection is enabled, the participants models can now also be appended with property "nin". Example payload:

Example request payload:

 {
    ...
    "is_protected": true,
    "participants": [
        {
            "handle": "signatory2@domain.com",
            "role": "signer",
            "nin": "234242-12"
        },
        {
            "handle": "signatory1@domain.com",
            "role": "signer",
            "display_name": "Name Surname",
            "nin": "123456-12"
        }
    ],
}

If nin is set on the participant model with signer role, the signatory will have to strongly verify their identity. If the SSN returned from the identity provider matches, the user is able to access the documents and sign.

If display_name is also set on the participant model with protection enabled, the name will also be compared against their full name returned from the identity provider. If at least two words in the full name match, the verification is approved.

Adding Metadata To a Signing Request

Metadata is supported on signing requests on SignSpace. In order to take it into use, the metadata fields and metadata templates have to be created in the SignSpace UI by an organisation admin. Once done, the IDs of the fields and templates have to be stored and mapped on your end.

In order to add metadata on a signing request, append the request payload of /api/v1/tasks.signingRequest.create as follows:

Example payload:

{
    ...
    "metadata_template": "6659c53f6cd3aa12a84e08f3", # ID of the metadata template that was created in the SignSpace UI
    "metadata": {
        "6659c5826cd3aa12a84e08f4": {"value": "Example A"}, # Key is an ID of the metadata field created in the UI. Value is passed as {"value": value}
        "6659c5826cd3aa12a84e08f5": {"value": "Example B"},
    }
}

 

 

 

Latest posts

Lorem ipsum dolor sit amet, consectetur adipiscing elit.