Electronic Signature
Last updated
Last updated
The Electronic Signature APIs allow you to:
Upload documents for signing by end-users
Have end-users sign previously uploaded documents
This API will return a value of Documents Signed.
Currently only available via the Rest API, and signing is available using the Web Embed.
The Electronic Signature APIs use form-encoded request bodies, and JSON-encoded response bodies. They also support authentication using HTTP Headers.
Authentication Headers are presented below
Header Name | Header Value |
---|---|
The Upload Documents API has the following input parameters which should be contained in a form-encoded request body
The Electronic Signature API returns a set of top level values as well as a detailed set of actions that can be used for a more granular evaluation of the individual fields.
For the Sign Endpoint (this is the same response sent to the callback of the asynchronous endpoint)
The Upload Documents API has the following input parameters which should be contained in a form-encoded request body
The Electronic Signature API returns a set of top level values as well as a detailed set of actions that can be used for a more granular evaluation of the individual fields.
For the Sign Endpoint (this is the same response sent to the callback of the asynchronous endpoint)
The Upload Documents API has the following input parameters which should be contained in a form-encoded request body
Example JSON Response
For the Sign Endpoint
Result codes details what the current (or final) result of a job is. Result Codes for all jobs fall into one of three categories:
This means no further processing is possible on the job. General failures occur when a job could not be submitted due to a logical/technical issue. These jobs do not show up in the portal and do not have a Smile Job ID.
* - read more on how to troubleshoot this error here\
Environment | URL | HTTP Method |
---|---|---|
Environment | URL | HTTP Method |
---|---|---|
Environment | URL | HTTP Method |
---|---|---|
Code | Text | Description | Category |
---|---|---|---|
Code | Text | Description | Category |
---|---|---|---|
SmileID-Request-Signature
This is calculated using your organisation's API Key and Partner ID. You can generate it following the guide
SmileID-Partner-ID
This is your organization's Partner ID obtained from the SmileID Portal
SmileID-Timestamp
This is the ISO-8601 Date-Time string, used to calculate the SmileID-Request-Signature
Sandbox:
https://testapi.smileidentity.com/v1/documents
POST
Production:
https://api.smileidentity.com/v1/documents
POST
Name
Type
Required
Description
name
string
Yes
The name of the document. This is displayed in the Client SDKs
description
string
Yes
A short description of the uploaded document
document_type
string
Yes
SINGLE
or TEMPLATE.
SINGLE
refers to documents that are signed once. TEMPLATE
refers to documents that are signed multiple times
file
string
Yes
This field expects a file stream of the document to be uploaded. Only files of type application/pdf are accepted.
partner_id
string
Yes
This is your organization's Partner ID obtained from the SmileID Portal
id
string
The ID for the document uploaded
signature
string
The outgoing Signature, you can use this to verify that the response is from Smile ID
timestamp
string
The outgoing timestamp in ISO date/time format, use this to calculate the outgoing Signature
Sandbox:
https://testapi.smileidentity.com/v1/documents
GET
Production:
https://api.smileidentity.com/v1/documents
GET
Name
Type
Required
Description
ids
string
Yes
A comma-separated list of document_ids
documents
array<document>
The list of document(s)
document.id
string
The ID of the document
document.link
string
A URL for the document
document.name
string
The name of the document
document.size
number
The size of the document in bytes
Sandbox:
https://testapi.smileidentity.com/v1/documents/sign
POST
Production:
https://api.smileidentity.com/v1/documents/sign
POST
Name
Type
Required
Description
ids
string
Yes
A comma-separated list of document_ids
name
string
Yes
Signatory's name
image
string
Yes
This field expects a file stream of the signature to be uploaded. Only files of type image/svg+xml, image/jpeg, image/png are accepted.
document_read_at
string
Yes
ISO-8601 Timestamp
partner_params
string
Yes
A "stringified" JSON object containing the partner parameters below
{user_id}
string
Yes
A user_id from the partner organization
{job_id}
string
Yes
A job_id from the partner organization
{job_type}
number
Yes
12 - The job_type for Electronic Signature
2405
Error - "You are not authorized to do that" *
An invalid signature was used to sign the request.
-
2213
Error - A required parameter is missing
Not all the required keys were submitted in the info.json or request payload. Please check request values for this product.
-
2204
Error - A parameter is of the wrong data type
The format of one of the request values was wrong. Please check request values for this product.
-
2205
Error - You are not authorized to do that. *
An invalid signature was used to sign the request.
-
0810
Documents Signed
The end-user successfully signed the document
Approved