Transaction Initiation

The FaceMatch API is used when the user wants to authenticate by comparing their face against a specific image or template. This API call will initiate the process and respond with a session ID, bearer token, and a follow up URI.

API Description

Method : GET

URL : https://{environment-url}/realms/{partner-id}/protocol/api/init

Parameters

Name	Type	Description
template_url*	String	The partner is required to provide the template image URL for the face match, representing the user-verified image that will be compared with the selfie for the Face Match. Eg : https://app-springboot.auth-stage.vida.id/template/download?template=19789378
kyc_event_id*	string	Unique KYC event id obtained after the KYC verification process
client_id*	String	A unique client id that is shared for each partner.
client_secret*	String	A unique key that is generated for each product configured for the partner.
type*	String	Type of the authentication Eg: FaceMatch

Either the template_url or the kyc_event_id must be passed as a mandatory parameter. If both parameters are provided, the kyc_event_id is given preference.

200: OK

{
    "uri": "https://{environment-url}/realms/{partner-id}/protocol/api/authenticate",
    "bearerToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjNTIxMGQyYy04NTRiLTQ3NDAtYjE3Mi02NzlkNWYxMTg4NWYiLCJleGVjdXRpb24iOiJjOTJhNWFhNi1mYTY5LTRiMTctOTg5OS1iZDllYTk5ZTNkMmUiLCJ0YWJfaWQiOiJNNURXT3RPQTFLVSIsIm5iZiI6MTcwMTQxMDkyNiwic2Vzc2lvbl9jb2RlIjoiZ3RwYkNMSWxkUDNXT1hGblBtSjFKQlAwcjQyNXFOQUJzOHNaZWl0M0NvbyIsInNlc3Npb25faWRlbnRpZmllciI6Ik01RFdPdE9BMUtVIiwiZXhwIjoxNzAxNDExMjI2LCJpYXQiOjE3MDE0MTA5MjYsImF1dGhfc2Vzc2lvbl9pZCI6ImM1MjEwZDJjLTg1NGItNDc0MC1iMTcyLTY3OWQ1ZjExODg1ZiIsImp0aSI6ImNmMDUwY2JlLWQxNWMtNGQzOC04MjY5LWQwNDI2ZTVjNjI4OSJ9.s0YAWoCLnSdJ90kQr29sqzVLG7oCqKN3IcYrKZr3Pu8",
    "authType": "FaceMatch",
    "sessionIdentifier": "M5DWOtOA1KU"
}

Curl

curl --location --request GET 'https://{environment-url}/realms/{partner-id}/protocol/api/init?type=FaceMatch&client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3&template_url=https://app-springboot.auth-stage.vida.id/template/download?template=1978937890'

Python

import requests

url = "https://{environment-url}/realms/{partner-id}/protocol/api/init?type=FaceMatch&client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3&template_url=https://app-springboot.auth-stage.vida.id/template/download?template=1978937890"

payload={}
headers = {}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

NodeJS

var axios = require('axios');

var config = {
  method: 'get',
  url: 'https://{environment-url}/realms/{partner-id}/protocol/api/init?type=FaceMatch&client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3&template_url=https://app-springboot.auth-stage.vida.id/template/download?template=1978937890',
  headers: { }
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Java

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("https://{environment-url}/realms/{partner-id}/protocol/api/init?type=FaceMatch&client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3&template_url=https://app-springboot.auth-stage.vida.id/template/download?template=1978937890")
  .method("GET", body)
  .build();
Response response = client.newCall(request).execute();

C#

var client = new RestClient("https://{environment-url}/realms/{partner-id}/protocol/api/init?type=FaceMatch&client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3&template_url=https://app-springboot.auth-stage.vida.id/template/download?template=1978937890");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://{environment-url}/realms/{partner-id}/protocol/api/init?type=FaceMatch&client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3&template_url=https://app-springboot.auth-stage.vida.id/template/download?template=1978937890',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Success Response

The follow up request can be initiated with the uri and the bearerToken along with the user selfie using the Transaction Completion API. The server will then compare this selfie with the image provided in the template URL.

{
    "uri": "https://{environment-url}/realms/{partner-id}/protocol/api/authenticate",
    "bearerToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjNTIxMGQyYy04NTRiLTQ3NDAtYjE3Mi02NzlkNWYxMTg4NWYiLCJleGVjdXRpb24iOiJjOTJhNWFhNi1mYTY5LTRiMTctOTg5OS1iZDllYTk5ZTNkMmUiLCJ0YWJfaWQiOiJNNURXT3RPQTFLVSIsIm5iZiI6MTcwMTQxMDkyNiwic2Vzc2lvbl9jb2RlIjoiZ3RwYkNMSWxkUDNXT1hGblBtSjFKQlAwcjQyNXFOQUJzOHNaZWl0M0NvbyIsInNlc3Npb25faWRlbnRpZmllciI6Ik01RFdPdE9BMUtVIiwiZXhwIjoxNzAxNDExMjI2LCJpYXQiOjE3MDE0MTA5MjYsImF1dGhfc2Vzc2lvbl9pZCI6ImM1MjEwZDJjLTg1NGItNDc0MC1iMTcyLTY3OWQ1ZjExODg1ZiIsImp0aSI6ImNmMDUwY2JlLWQxNWMtNGQzOC04MjY5LWQwNDI2ZTVjNjI4OSJ9.s0YAWoCLnSdJ90kQr29sqzVLG7oCqKN3IcYrKZr3Pu8",
    "authType": "FaceMatch",
    "sessionIdentifier": "M5DWOtOA1KU"
}

Response Schema

{
    "uri": "{URI OF THE FOLLOW UP REQUEST FOR TRANSACTION COMPLETION}",
    "bearerToken": "{BEARER TOKEN TO BE ADDED IN AUTHORIZATION HEADER OF TRANSACTION COMPLETION REQUEST}",
    "authType": "{AUTHENTICATION TYPE}",
    "sessionIdentifier": "{SESSION ID TO REMAIN WITH PARTNER SERVER}"
}

Error Response

{
    "error": "invalid_request",
    "errorDescription": "Client ID invalid"
}

Response Schema

{
    "error": "{TYPE OF ERROR}",
    "errorDescription": "{REASONING FOR THE ERROR}"
}

Error Codes

If a request to our API is successful, it will return an HTTP status code 200 (OK)

For a complete list of error codes and their meanings, refer to the Error Scenarios section.

To complete the FaceMatch authentication process, follow up by using the FaceMatch completion API.