> 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/authentication/authentication-factors/biometric-device-selfie-id/integration-methods/face-match-api/api-reference/transaction-initiation.md). # 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 :

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

| {% hint style="info" %} 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. {% endhint %} {% tabs %} {% tab title="200: OK " %} ```json { "uri": "https://{environment-url}/realms/{partner-id}/protocol/api/authenticate", "bearerToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjNTIxMGQyYy04NTRiLTQ3NDAtYjE3Mi02NzlkNWYxMTg4NWYiLCJleGVjdXRpb24iOiJjOTJhNWFhNi1mYTY5LTRiMTctOTg5OS1iZDllYTk5ZTNkMmUiLCJ0YWJfaWQiOiJNNURXT3RPQTFLVSIsIm5iZiI6MTcwMTQxMDkyNiwic2Vzc2lvbl9jb2RlIjoiZ3RwYkNMSWxkUDNXT1hGblBtSjFKQlAwcjQyNXFOQUJzOHNaZWl0M0NvbyIsInNlc3Npb25faWRlbnRpZmllciI6Ik01RFdPdE9BMUtVIiwiZXhwIjoxNzAxNDExMjI2LCJpYXQiOjE3MDE0MTA5MjYsImF1dGhfc2Vzc2lvbl9pZCI6ImM1MjEwZDJjLTg1NGItNDc0MC1iMTcyLTY3OWQ1ZjExODg1ZiIsImp0aSI6ImNmMDUwY2JlLWQxNWMtNGQzOC04MjY5LWQwNDI2ZTVjNjI4OSJ9.s0YAWoCLnSdJ90kQr29sqzVLG7oCqKN3IcYrKZr3Pu8", "authType": "FaceMatch", "sessionIdentifier": "M5DWOtOA1KU" } ``` {% endtab %} {% endtabs %} {% tabs %} {% tab title="Curl" %} ```http 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' ``` {% endtab %} {% tab title="Python" %} ```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) ``` {% endtab %} {% tab title="NodeJS" %} ```javascript 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); }); ``` {% endtab %} {% tab title="Java" %} ```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(); ``` {% endtab %} {% tab title="C#" %} ```csharp 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); ``` {% endtab %} {% tab title="PHP" %} ```php '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; ``` {% endtab %} {% endtabs %} ### 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. ```json { "uri": "https://{environment-url}/realms/{partner-id}/protocol/api/authenticate", "bearerToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjNTIxMGQyYy04NTRiLTQ3NDAtYjE3Mi02NzlkNWYxMTg4NWYiLCJleGVjdXRpb24iOiJjOTJhNWFhNi1mYTY5LTRiMTctOTg5OS1iZDllYTk5ZTNkMmUiLCJ0YWJfaWQiOiJNNURXT3RPQTFLVSIsIm5iZiI6MTcwMTQxMDkyNiwic2Vzc2lvbl9jb2RlIjoiZ3RwYkNMSWxkUDNXT1hGblBtSjFKQlAwcjQyNXFOQUJzOHNaZWl0M0NvbyIsInNlc3Npb25faWRlbnRpZmllciI6Ik01RFdPdE9BMUtVIiwiZXhwIjoxNzAxNDExMjI2LCJpYXQiOjE3MDE0MTA5MjYsImF1dGhfc2Vzc2lvbl9pZCI6ImM1MjEwZDJjLTg1NGItNDc0MC1iMTcyLTY3OWQ1ZjExODg1ZiIsImp0aSI6ImNmMDUwY2JlLWQxNWMtNGQzOC04MjY5LWQwNDI2ZTVjNjI4OSJ9.s0YAWoCLnSdJ90kQr29sqzVLG7oCqKN3IcYrKZr3Pu8", "authType": "FaceMatch", "sessionIdentifier": "M5DWOtOA1KU" } ``` Response Schema ```json { "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 ```json { "error": "invalid_request", "errorDescription": "Client ID invalid" } ``` Response Schema ```json { "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](/identity-stack/authentication/authentication-factors/biometric-device-selfie-id/integration-methods/selfie-id-api/api/error-scenarios.md) section. {% hint style="info" %} To complete the FaceMatch authentication process, follow up by using the [FaceMatch completion](/identity-stack/authentication/authentication-factors/biometric-device-selfie-id/integration-methods/selfie-id-api/api/api-reference/authentication/transaction-completion.md) API. {% endhint %}