Electronic Signature

Overview

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.

Integration Options

Currently only available via the Rest API, and signing is available using the Web Embed.

API Endpoints

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

Upload Documents

Environment	URL	HTTP Method
Sandbox:	https://testapi.smileidentity.com/v1/documents	POST
Production:	https://api.smileidentity.com/v1/documents	POST

Request Values

The Upload Documents API has the following input parameters which should be contained in a form-encoded request body

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

Example Form-Encoded Request Body

POST /v1/documents HTTP/1.1
Host: api.smileidentity.com
SmileID-Request-Signature: HKFTUEUe77LWvF7F70GUN8GRkqpHSbOK0ONnPZkyy+I=
SmileID-Partner-ID: <partner_id>
SmileID-Timestamp: 2024-02-09T14:48:55.887Z
Content-Length: 646
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="partner_id"

<Partner_ID>
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="name"

Lease Agreement
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="description"

Rental lease agreement between John Doe and Property Managers Inc
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="document_type"

SINGLE
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="Hope_You_Like_Jammin_Too_featuring_The_Cavemen.pdf"
Content-Type: application/pdf

(data)
------WebKitFormBoundary7MA4YWxkTrZu0gW--

Return Values

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.

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

Example JSON Response

For the Sign Endpoint (this is the same response sent to the callback of the asynchronous endpoint)

{
  "id": "312b15a4-714c-49ca-8502-f0c23d907bad",
  "signature": "...",
  "timestamp": "2024-02-09T14:48:55.887Z"
}

Retrieve Document Metadata

Environment	URL	HTTP Method
Sandbox:	https://testapi.smileidentity.com/v1/documents	GET
Production:	https://api.smileidentity.com/v1/documents	GET

Request Params

The Upload Documents API has the following input parameters which should be contained in a form-encoded request body

Name	Type	Required	Description
ids	string	Yes	A comma-separated list of document_ids

Example Request

GET /v1/documents?ids=312b15a4-714c-49ca-8502-f0c23d907bad HTTP/1.1
Host: api.smileidentity.com
SmileID-Partner-ID: <partner_id>
SmileID-Request-Signature: 0+CcjDws8hgWFRmV9UfsuKHGqXq5wZl8qntvX7WKy64=
SmileID-Timestamp: 2024-02-09T16:25:03.223Z
Content-Type: text/plain
Content-Length: 22

Return Values

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.

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

Example JSON Response

For the Sign Endpoint (this is the same response sent to the callback of the asynchronous endpoint)

{
  "documents": [
    {
      "id": "312b15a4-714c-49ca-8502-f0c23d907bad",
      "link": "...",
      "name": "Lease Agreement",
      "size": 43684
    }
  ]
}

Sign Document

Environment	URL	HTTP Method
Sandbox:	https://testapi.smileidentity.com/v1/documents/sign	POST
Production:	https://api.smileidentity.com/v1/documents/sign	POST

Request Params

The Upload Documents API has the following input parameters which should be contained in a form-encoded request body

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

Example Request

POST /v1/documents/sign HTTP/1.1
Host: api.smileidentity.com
SmileID-Partner-ID: <partner_id>
SmileID-Request-Signature: aRKl+geOao8jlzLH2pKXUOLDH3Z1+XBoXGIc7vYiKYw=
SmileID-Timestamp: 2024-02-09T16:47:24.437Z
Content-Length: 687
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="image"; filename="_sample_base_signature.png"
Content-Type: image/png

(data)
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="partner_params"

{"job_id":"job-42", "job_type":12, "user_id":"user-42"}
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="document_read_at"

2024-02-09T16:47:29.446Z
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="ids"

312b15a4-714c-49ca-8502-f0c23d907bad
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="name"

John Doe
------WebKitFormBoundary7MA4YWxkTrZu0gW--

Example JSON Response

For the Sign Endpoint

{
  "ResultCode": "0810",
  "ResultText": "Documents Signed",
  "signature": "grq29Ti7Yg8Mv8e3aYSV0T/dtbFEp6163OCEPFSUhSo=",
  "timestamp": "2024-02-09T16:47:27.944Z"
}

Result Codes and Result Texts

Result codes details what the current (or final) result of a job is. Result Codes for all jobs fall into one of three categories:

General Failures Result Codes and Texts

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.

Code	Text	Description	Category
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.	-

* - read more on how to troubleshoot this error here\

Product Specific Result Codes and Texts

Code	Text	Description	Category
0810	Documents Signed	The end-user successfully signed the document	Approved