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:
- Authenticate yourself by using instructions provided here: API documentation for SignSpace v2#Authentication
- Create file or files in SignSpace by following instructions provided here: Create File(s). Store the created files' IDs internally for further use.
- 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.
- 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/ |
Signspace's /auth/token endpoint acts as a proxy to AWS Cognito's token endpoint. More details about Cognito's token endpoint
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&scope=$SCOPES" $IDENTITY_PROVIDER_URL |
$CLIENT_CREDENTIALS - the client ID and secret separated by a colon (<client_id>:<client_secret>)
(Optional) $SCOPES - a list of scopes separated by spaces (e.g. "conversations tasks")
Notes about scopes:
- When migrating from GLUU to Cognito, API clients should remove the scope parameter from the authentication request
- When using Cognito, scopes can be used, but are not mandatory. If the client omits scopes from the request or submits an empty list of scopes, all available scopes will be returned in the JWT token
- If sending scopes, "signspace_api" scope is mandatory. Make sure to add it to the list of scopes.
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: { |
| 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&status=complete&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&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&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"}, } } |