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

EnvironmentURLHTTP 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

EnvironmentURLHTTP 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

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

CodeTextDescriptionCategory

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

CodeTextDescriptionCategory

0810

Documents Signed

The end-user successfully signed the document

Approved

PreviousBasic KYCNextEnhanced KYC

Last updated