Digital Signature

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

POST https://services-sandbox.vida.id/signer/v2/services/esign

Query Parameters

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

Headers

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

200: OK Unique ID per api call to track status updates

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

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

{
	"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"
	},
	"device": {
		"os": "R",
		"model": "KB2001",
		"uniqueId": "AF7KI0bly3aPIsYJ4+O+2QE",
		"networkProvider": "IND idea"
	},
	"signingInfo": [{
		// ... read further for more information
	}]
}

• The image size should not exceed 1 Mb

• doc or pdf file should be less than 10 Mb.

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

M = Mandatory | O = Optional | C = Conditional

requestInfo and device parameters are required by VIDA for regulatory and audit purposes.

---

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

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

This option is available for VIDA Verify service customer.

Parameter	Type	Req	Length	Description
vidaEkycEventId	string	M	36	Unique identifier obtained from the KYC (Know Your Customer) service response, representing a specific event or transaction related to user identity verification. The vidaEkycEventId is retrieved as a response from a KYC service request made to /main/v3/services/kyc

When raType is ext

{
  // ... other fields remain constant
  "user": {
    "fullName": "User 123",
    "email": "[e-mail]",
    "mobile": "[phone]",
    "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.

Parameter	Type	Req	Length	Description
fullName	string	M	255	Full name of the user
email	string	M	255	User's email address
mobile	string	M	20	The user's verified mobile number with the country code, provided in E.164 format without spaces or special characters. *Include the + and country code, e.g. [phone]
dob	string	M		User's date of birth, formatted as YYYY-MM-DD
govId	string	M	20	Government-issued identification number for the user
selfiePhoto	string	M		Base64 encoded string representing the user's selfie photo
idCardPhoto	string	M		Base64 encoded string representing the user's identification card photo
partnerId	string	M	255	Unique identifier representing the user's associated partner in UUID format

---

Signing Information (signingInfo)

When docType is template

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

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

Parameter	Type	Req	Length	Description
pdfTemplateId	string	M	36	Identifier for the PDF template being used in the signing process

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

{
  "signingInfo": [
    {
      "pdfTemplateId": "123",
      "formValues": {
        "fullName": "User 123",
        "phone": "[phone]",
        "email": "[e-mail]",
        "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.

Parameter	Type	Req	Length	Description
formValues	object	C		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. For example, in the given payload: fullName, phone, email, signupdate, activationdate, nik, name2, nik2: 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.

Form Fields

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

Parameter	Type	Req	Length	Description
formFields	array	C		Array of objects, each representing a form field in the PDF template
formFields[*].type	string	C		Specifies the type of the form field, which can be either "IMAGE" or "TEXT"
formFields[*].name	string	C		Corresponds to a specific form field in the PDF document. The exact names vary based on the form fields of the PDF template
formFields[*].value	string	C		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

When docType is nontemplate

{
  "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.

Parameter	Type	Req	Length	Description
pdfFile	string	M		Base64 encoded string of the PDF file to be used in the signing
pageNo	string	M		Page number in the PDF document where the signing or action is to occur
xPoint	string	M		X-coordinate on the PDF page to position the signature
yPoint	string	M		Y-coordinate on the PDF page to position the signature
height	string	M		Height of the signature
width	string	M		Width of the signature
clientFilename	string	O		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
qrEnable	boolean	O		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 Default false
appearance	object	O		Object specifying the appearance settings for the signing
appearance.type	string	C		provided: Visual signature featuring a client-provided image. standard: Visual signature using the VIDA standard logo. non_visual: Signature without any visual elements. Default standard
appearance.signImage	string	C		Base64 encoded string of the signature image

Response

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

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