> For the complete documentation index, see [llms.txt](https://docs.vida.id/identity-stack/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vida.id/identity-stack/sign/other-services/sign-inline-api/digital-signature.md).

# Digital Signature

This API enables VIDA's partners to request an digital signature for the user.

<mark style="color:green;">`POST`</mark> `https://services-sandbox.vida.id/signer/v2/services/esign`

#### Query Parameters

| Name    | Type   | Description                                                                                                                                                                                                                                                                                                                                                                        |
| ------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| raType  | String | <p>User verification obligation source.</p><p></p><p><strong><code>int</code></strong> : User verification is obligated at Vida </p><p><strong><code>ext</code></strong> : User verification is obligated at Client </p><p></p><p>Default value when empty is ‘<code>int</code>’</p>                                                                                               |
| docType | String | <p>Document source.</p><p> </p><p><strong><code>template</code></strong> : Document is in Vida cloud. </p><p><strong><code>nontemplate</code></strong> : Document is supplied by Client in request body. </p><p><strong><code>hash</code></strong> : hash of Document is supplied by Client in request body. </p><p></p><p>Default value when empty is ‘<code>template</code>’</p> |

#### Headers

| Name          | Type   | Description                                  |
| ------------- | ------ | -------------------------------------------- |
| Authorization | String | Bearer \<Token received from Authentication> |
| Content-Type  |        | application/json                             |

{% tabs %}
{% tab title="200: OK Unique ID per api call to track status updates" %}

```json
{
 "data":{
  "id":"8efa9d73-c7df-4aa8-8705-29ca45b0ef32"
 }
}
```

{% endtab %}
{% endtabs %}

### Request Body

Request body If you want to add or update the text values in the PDF template, you can send the request either in format 1 (form values) or format 2 (form fields), but if you want to add the image in the PDF template you must send the request in format 2 (form fields).&#x20;

<pre class="language-json"><code class="lang-json">{
	"partnerTrxId": "ab00e8f5-ab00-46f2-b8e7-5cdcc147b988",	
	"user": {
		// ... read further for more informations
	},
	"requestInfo": {
		"userAgent": "Mozilla/5.0 (X11;Linux x86_64) AppleWebKit / 537.36",
		"srcIp": "172.217.22.14",
		"consentTimestamp": "1702362951"
<strong>	},
</strong>	"device": {
		"os": "R",
		"model": "KB2001",
		"uniqueId": "AF7KI0bly3aPIsYJ4+O+2QE",
		"networkProvider": "IND idea"
	},
	"signingInfo": [{
		// ... read further for more information
	}]
}
</code></pre>

{% hint style="info" %}

* The image size should not exceed 1 Mb
* doc or pdf file should be less than 10 Mb.
  {% endhint %}

<table><thead><tr><th width="279">Parameter</th><th width="106">Type</th><th width="70">Req</th><th width="70" data-type="number">Length</th><th>Description</th></tr></thead><tbody><tr><td>partnerTrxId</td><td>string</td><td>M</td><td>255</td><td>Unique transaction identifier in a UUID format</td></tr><tr><td>user</td><td>object</td><td>M</td><td>null</td><td>Object containing user-specific information (details provided separately)</td></tr><tr><td>requestInfo</td><td>object</td><td>M</td><td>null</td><td>Object holding data about the user request</td></tr><tr><td>requestInfo.userAgent</td><td>string</td><td>M</td><td>null</td><td>Identifies the browser and operating system used by the user</td></tr><tr><td>requestInfo.srcIp</td><td>string</td><td>M</td><td>128</td><td>Source IP address from which the request originated</td></tr><tr><td>requestInfo.consentTimestamp</td><td>string</td><td>M</td><td>null</td><td>Timestamp indicating when the user gave consent in Unix time format</td></tr><tr><td>device</td><td>object</td><td>M</td><td>null</td><td>Object detailing the user's device information, including operating system, model, unique ID, and network provider</td></tr><tr><td>device.os</td><td>string</td><td>M</td><td>64</td><td>Operating system of the user's device</td></tr><tr><td>device.model</td><td>string</td><td>M</td><td>64</td><td>Model identifier of the user's device</td></tr><tr><td>device.uniqueId</td><td>string</td><td>M</td><td>128</td><td>Unique identifier for the user's device</td></tr><tr><td>device.networkProvider</td><td>string</td><td>M</td><td>64</td><td>Name of the network provider for the user's device</td></tr><tr><td>signingInfo</td><td>array</td><td>M</td><td>5</td><td>Array of objects containing information about the signing process (details provided separately)</td></tr></tbody></table>

{% hint style="info" %}
**M** = Mandatory | **O** = Optional | **C** = Conditional

`requestInfo` and `device` parameters are required by VIDA for regulatory and audit purposes.
{% endhint %}

***

This endpoint handles different data structures based on query parameters.

**Query Parameters**

* `raType`: Determines the structure of the `user` object in the request.
  * Values: `int` | `ext`
* `docType`: Dictates the structure of the `signingInfo` object.
  * Values: `template` | `nontemplate`

***

### Request Payloads

### User (`user`)

#### When `raType` is `int`

```json
{
  // ... other fields remain constant
  "user": {
    "vidaEkycEventId": "46f8c3d0-bf60-434e-8139-56db02b2999a"
  },
  // ... other fields remain constant
}
```

This option is available for VIDA Verify service customer.

<table><thead><tr><th width="180">Parameter</th><th width="87">Type</th><th width="52">Req</th><th width="86">Length</th><th>Description</th></tr></thead><tbody><tr><td>vidaEkycEventId</td><td>string</td><td>M</td><td>36</td><td><p>Unique identifier obtained from the KYC (Know Your Customer) service response, representing a specific event or transaction related to user identity verification.</p><p></p><p>The <code>vidaEkycEventId</code> is retrieved as a response from a KYC service request made to <code>/main/v3/services/kyc</code></p></td></tr></tbody></table>

#### When `raType` is `ext`

```json
{
  // ... other fields remain constant
  "user": {
    "fullName": "User 123",
    "email": "user.123@email.com",
    "mobile": "+628412345689",
    "dob": "1988-10-23",
    "govId": "3511002310880001",
    "selfiePhoto": "<base64>",
    "idCardPhoto": "<base64>",
    "partnerId": "8277d25f-8a4f-4acd-b8c6-0929129d9d3b"
  },
  // ... other fields remain constant
}
```

This option is used when VIDA partner verify the user information themself.

<table><thead><tr><th width="140.33984375">Parameter</th><th width="95.48046875">Type</th><th width="78.96875">Req</th><th width="96.12890625">Length</th><th>Description</th></tr></thead><tbody><tr><td>fullName</td><td>string</td><td>M</td><td>255</td><td>Full name of the user</td></tr><tr><td>email</td><td>string</td><td>M</td><td>255</td><td>User's email address</td></tr><tr><td>mobile</td><td>string</td><td>M</td><td>20</td><td>The user's verified mobile number with the country code, provided in E.164 format without spaces or special characters. <br><br>*<em>Include the <code>+</code> and country code, e.g. <code>+6281234567890</code></em></td></tr><tr><td>dob</td><td>string</td><td>M</td><td></td><td>User's date of birth, formatted as YYYY-MM-DD</td></tr><tr><td>govId</td><td>string</td><td>M</td><td>20</td><td>Government-issued identification number for the user</td></tr><tr><td>selfiePhoto</td><td>string</td><td>M</td><td></td><td>Base64 encoded string representing the user's selfie photo</td></tr><tr><td>idCardPhoto</td><td>string</td><td>M</td><td></td><td>Base64 encoded string representing the user's identification card photo</td></tr><tr><td>partnerId</td><td>string</td><td>M</td><td>255</td><td>Unique identifier representing the user's associated partner in UUID format</td></tr></tbody></table>

***

### Signing Information (`signingInfo`)

#### When `docType` is `template`

```json
{
  "signingInfo": [
    {
      "pdfTemplateId": "634",
      // ... other fields specific to template
    }
  ]
}
```

This option is available for partner who want to use previously uploaded templates from OSS

<table><thead><tr><th width="163">Parameter</th><th width="85">Type</th><th width="63">Req</th><th width="96">Length</th><th>Description</th></tr></thead><tbody><tr><td>pdfTemplateId</td><td>string</td><td>M</td><td>36</td><td>Identifier for the PDF template being used in the signing process</td></tr></tbody></table>

#### Form Formats

To add or update text in the PDF template, use either format 1 (form values) or format 2 (form fields). However, to add images to the PDF template, you must use format 2 (form fields) only.

#### Form Values

```json
{
  "signingInfo": [
    {
      "pdfTemplateId": "123",
      "formValues": {
        "fullName": "User 123",
        "phone": "+6284123456789",
        "email": "user.123@email.com",
        "signupdate": "25-10-2022",
        "activationdate": "25-10-2022",
        "nik": "3511002310880001",
        "name2": "User 123",
        "nik2": "3511002310880001"
      }
    }
  ]
}
```

The `formValues` object within the `signingInfo` JSON structure contains key-value pairs where each key corresponds to a form field name in the specified PDF template. The values provided for these keys will be used to fill in the respective form fields in the PDF. For example, the key `"fullName"` in `formValues` will populate the form field named `"fullName"` in the PDF template with the value `"gavril "`. This mapping ensures that the data provided in `formValues` aligns correctly with the form fields in your PDF template.

<table><thead><tr><th width="194">Parameter</th><th width="85">Type</th><th width="63">Req</th><th width="96">Length</th><th>Description</th></tr></thead><tbody><tr><td>formValues</td><td>object</td><td>C</td><td></td><td><p>Object with dynamically named keys that correspond to the form fields in the PDF template. The values provided here are used to populate the respective fields in the PDF document.</p><p>For example, in the given payload:</p><ul><li><strong>fullName</strong>, <strong>phone</strong>, <strong>email</strong>, <strong>signupdate</strong>, <strong>activationdate</strong>, <strong>nik</strong>, <strong>name2</strong>, <strong>nik2</strong>: These are examples of keys that represent form fields in the PDF document. The exact keys and their number can vary depending on the specific PDF template used. Each key's value is intended to fill in the corresponding field in the PDF.</li></ul></td></tr></tbody></table>

#### Form Fields

```json
{
  "signingInfo": [
    {
      "pdfTemplateId": "123",
      "formFields": [{
        "type": "IMAGE",
        "name": "imagektp",
        "value": "<base64>"
       },
       {
         "type": "TEXT",
         "name": "fullName",
         "value": "User 123"
        }]
    }
  ]
}
```

<table><thead><tr><th width="197">Parameter</th><th width="85">Type</th><th width="63">Req</th><th width="96">Length</th><th>Description</th></tr></thead><tbody><tr><td>formFields</td><td>array</td><td>C</td><td></td><td>Array of objects, each representing a form field in the PDF template</td></tr><tr><td>formFields[*].type</td><td>string</td><td>C</td><td></td><td>Specifies the type of the form field, which can be either "IMAGE" or "TEXT"</td></tr><tr><td>formFields[*].name</td><td>string</td><td>C</td><td></td><td>Corresponds to a specific form field in the PDF document. The exact names vary based on the form fields of the PDF template</td></tr><tr><td>formFields[*].value</td><td>string</td><td>C</td><td></td><td>Content to be filled into the form field. For "IMAGE" type, this is a base64 encoded string of the image; for "TEXT" type, this is the actual text content</td></tr></tbody></table>

#### When `docType` is `nontemplate`

```json
{
  "signingInfo": [
    {
      "pdfFile": "<base64>",
      "pageNo": "1",
      "xPoint": "10",
      "yPoint": "10",
      "height": "10",
      "width": "20",
      "clientFilename": "File Name 123",
      "qrEnable": true,
      "appearance": {
        "type": "standard",
        "signImage": ""
      }
    }
  ]
}
```

This option is available for partner who want to use their own PDF file.

<table><thead><tr><th>Parameter</th><th width="119">Type</th><th width="90">Req</th><th width="100">Length</th><th>Description</th></tr></thead><tbody><tr><td>pdfFile</td><td>string</td><td>M</td><td></td><td>Base64 encoded string of the PDF file to be used in the signing</td></tr><tr><td>pageNo</td><td>string</td><td>M</td><td></td><td>Page number in the PDF document where the signing or action is to occur</td></tr><tr><td>xPoint</td><td>string</td><td>M</td><td></td><td>X-coordinate on the PDF page to position the signature</td></tr><tr><td>yPoint</td><td>string</td><td>M</td><td></td><td>Y-coordinate on the PDF page to position the signature</td></tr><tr><td>height</td><td>string</td><td>M</td><td></td><td>Height of the signature</td></tr><tr><td>width</td><td>string</td><td>M</td><td></td><td>Width of the signature</td></tr><tr><td>clientFilename</td><td>string</td><td>O</td><td></td><td>Name displayed on QR verification pages; defaults to PDF title if empty, and to an empty string if both clientFilename and PDF title are absent</td></tr><tr><td>qrEnable</td><td>boolean</td><td>O </td><td></td><td>Boolean indicating whether a QR code is to be included in the signed document. Position of QR is bottom right of last page of document<br><br>Default <code>false</code></td></tr><tr><td>appearance</td><td>object</td><td>O</td><td></td><td>Object specifying the appearance settings for the signing</td></tr><tr><td>appearance.type</td><td>string</td><td>C</td><td></td><td><ul><li><strong><code>provided</code></strong>: Visual signature featuring a client-provided image.</li><li><strong><code>standard</code></strong>: Visual signature using the VIDA standard logo.</li><li><strong><code>non_visual</code></strong>: Signature without any visual elements.</li></ul><p>Default <code>standard</code></p></td></tr><tr><td>appearance.signImage</td><td>string</td><td>C</td><td></td><td>Base64 encoded string of the signature image</td></tr></tbody></table>

### Response

```json
{
    "data":{
        "id":"8efa9d73-c7df-4aa8-8705-29ca45b0ef32"
    }
}
```

**`id`** : Unique ID per api call to track status updates

#### Error Handling

Non-success status code responses will have a body with error details

```json
{
	"errors": [{
		"code": 31003,
		"title": "Invalid template id ",
		"detail": "Invalid template id "
	}]
}
```

#### Error Codes

| code  | Description                                            |
| ----- | ------------------------------------------------------ |
| 1000  | An unknown error occurred while processing the request |
| 1001  | Unable to generate certificate                         |
| 1006  | The request is missing a required parameter            |
| 21001 | Requested method not allowed                           |
| 21003 | The requested resource was not found                   |
| 31002 | No Templates configured for the partner                |
| 31003 | Provided template Id is invalid                        |
| 31004 | Name contains invalid characters                       |
| 31005 | Product attributes not found                           |
| 31007 | Failed to validate certificate                         |
| 31008 | PDF file provided in the request body is not valid     |
| 31009 | ekycEventId not found                                  |
| 31010 | Invalid transaction id                                 |
| 31011 | Invalid ApiKey                                         |
| 31012 | Invalid Encryption CVV                                 |
| 31013 | Expired Encryption CVV                                 |
| 31014 | Invalid Verify Signature                               |
| 31015 | Invalid Token                                          |
| 31016 | Invalid Request DocType                                |
| 31017 | Invalid KYC Event Id                                   |