> For the complete documentation index, see [llms.txt](https://legacy-docs.usesmileid.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://legacy-docs.usesmileid.com/products/for-individuals-kyc/electronic-signature.md).

# 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](/integration-options/rest-api.md), and signing is available using the [Web Embed](/integration-options/web-mobile-web/web-integration.md).

## 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](https://docs.usesmileid.com/integration-options/rest-api/signing-your-api-request/generate-signature#generating-the-signature) |
| 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

<table><thead><tr><th width="156">Environment</th><th width="412">URL</th><th>HTTP Method</th></tr></thead><tbody><tr><td>Sandbox:</td><td>https://testapi.smileidentity.com/v1/documents</td><td>POST</td></tr><tr><td>Production:</td><td>https://api.smileidentity.com/v1/documents</td><td>POST</td></tr></tbody></table>

#### **Request Values**

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

<table data-header-hidden><thead><tr><th width="230">Name</th><th>Type</th><th width="150">Required</th><th>Description</th></tr></thead><tbody><tr><td>Name</td><td>Type</td><td>Required</td><td>Description</td></tr><tr><td>name</td><td>string</td><td>Yes</td><td>The name of the document. This is displayed in the Client SDKs</td></tr><tr><td>description</td><td>string</td><td>Yes</td><td>A short description of the uploaded document</td></tr><tr><td>document_type</td><td>string</td><td>Yes</td><td><p><code>SINGLE</code> or <code>TEMPLATE.</code></p><p><code>SINGLE</code> refers to documents that are signed once. <code>TEMPLATE</code> refers to documents that are signed multiple times</p></td></tr><tr><td>file</td><td>string</td><td>Yes</td><td>This field expects a file stream of the document to be uploaded. Only files of type application/pdf are accepted.</td></tr><tr><td>partner_id</td><td>string</td><td>Yes</td><td>This is your organization's Partner ID obtained from the SmileID Portal</td></tr></tbody></table>

#### Example Form-Encoded Request Body

```http
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.

<table data-header-hidden><thead><tr><th>Name</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>string</td><td>The ID for the document uploaded</td></tr><tr><td>signature</td><td>string</td><td>The outgoing Signature, you can use this to verify that the response is from Smile ID</td></tr><tr><td>timestamp</td><td>string</td><td>The outgoing timestamp in ISO date/time format, use this to calculate the outgoing Signature</td></tr></tbody></table>

#### **Example JSON Response**

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

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

### Retrieve Document Metadata

<table><thead><tr><th width="156">Environment</th><th width="412">URL</th><th>HTTP Method</th></tr></thead><tbody><tr><td>Sandbox:</td><td>https://testapi.smileidentity.com/v1/documents</td><td>GET</td></tr><tr><td>Production:</td><td>https://api.smileidentity.com/v1/documents</td><td>GET</td></tr></tbody></table>

#### **Request Params**

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

<table data-header-hidden><thead><tr><th width="230">Name</th><th>Type</th><th width="150">Required</th><th>Description</th></tr></thead><tbody><tr><td>Name</td><td>Type</td><td>Required</td><td>Description</td></tr><tr><td>ids</td><td>string</td><td>Yes</td><td>A comma-separated list of document_ids</td></tr></tbody></table>

#### Example Request

```http
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.

<table data-header-hidden><thead><tr><th>Name</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td>documents</td><td>array&#x3C;document></td><td>The list of document(s)</td></tr><tr><td>document.id</td><td>string</td><td>The ID of the document</td></tr><tr><td>document.link</td><td>string</td><td>A URL for the document</td></tr><tr><td>document.name</td><td>string</td><td>The name of the document</td></tr><tr><td>document.size</td><td>number</td><td>The size of the document in bytes</td></tr></tbody></table>

#### **Example JSON Response**

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

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

### Sign Document

<table><thead><tr><th width="156">Environment</th><th width="424">URL</th><th>HTTP Method</th></tr></thead><tbody><tr><td>Sandbox:</td><td>https://testapi.smileidentity.com/v1/documents/sign</td><td>POST</td></tr><tr><td>Production:</td><td>https://api.smileidentity.com/v1/documents/sign</td><td>POST</td></tr></tbody></table>

#### **Request Params**

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

<table data-header-hidden><thead><tr><th width="230">Name</th><th width="132">Type</th><th width="150">Required</th><th>Description</th></tr></thead><tbody><tr><td>Name</td><td>Type</td><td>Required</td><td>Description</td></tr><tr><td>ids</td><td>string</td><td>Yes</td><td>A comma-separated list of document_ids</td></tr><tr><td>name</td><td>string</td><td>Yes</td><td>Signatory's name</td></tr><tr><td>image</td><td>string</td><td>Yes</td><td>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.</td></tr><tr><td>document_read_at</td><td>string</td><td>Yes</td><td>ISO-8601 Timestamp</td></tr><tr><td>partner_params</td><td>string</td><td>Yes</td><td>A "stringified" JSON object containing the partner parameters below</td></tr><tr><td>{user_id}</td><td>string</td><td>Yes</td><td>A user_id from the partner organization</td></tr><tr><td>{job_id}</td><td>string</td><td>Yes</td><td>A job_id from the partner organization</td></tr><tr><td>{job_type}</td><td>number</td><td>Yes</td><td>12 - The job_type for Electronic Signature</td></tr></tbody></table>

#### Example Request

```http
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**

```json
{
  "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](#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](#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](/further-reading/troubleshooting/troubleshooting-error-2204-and-2205-youre-not-authorized-to-do-that.md)\\

### Product Specific Result Codes and Texts

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://legacy-docs.usesmileid.com/products/for-individuals-kyc/electronic-signature.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.