> 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-completion.md). # Transaction Completion The FaceMatch Completion API is used to complete the FaceMatch provisioning or authentication process. The user sends a base64 encoded image of their face for verification. Since FaceMatch does not involve a credential ID, the server responds with a JWT containing the `sessionIdentifier` received during initiation. This allows the transaction state to be tracked. ## API Description **Method** : `POST` **URL** : Follow up url received as part of the response of the Transaction Initiation API ### Parameters | Name | Type | Description | | -------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | client\_id\* | String | A unique client id that is shared for each partner | | **image**\* | base64 string | Selfie Image of the user as Base 64 | | or | | | | **liveliness\_transaction\_id** | String | The liveliness verification transaction id received as part of the Vida Liveliness verification process (e.g. Vida Liveliness SDK) | {% hint style="info" %} The partner can either submit the user's selfie image as a Base64 encoded string for KYC verification or provide the `liveness_transaction_id` from the liveness verification SDK, allowing us to retrieve the verified image directly from the liveness process. {% endhint %} #### Headers | Name | Type | Description | | ------------------------------------------------ | ------ | ------------------------------------------------------------ | | Authentication\* | String | Bearer {Bearer Token Received in Transaction Initaition API} | | Content-Type | String | application/`x-www-form-urlencoded` | {% tabs %} {% tab title="200: OK " %} ```json { "entity": { "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJYbnNBNFVPdlkyU0JLSkdnX1ppTHN1Tk8tZ2dlLVB0RXZzX2twRTBhd3RnIn0.eyJleHAiOjE3MDE1ODI1MTYsIm5iZiI6MTcwMTU4MjIxNiwiaWF0IjoxNzAxNTgyMjE2LCJhdXRoX3RpbWUiOjE3MDE1ODIyMTYsImp0aSI6IjBjZDljNGUyLTEwZGYtNDNmZS04NGMwLWE0MmI0ZDVhOTRjMyIsImlzcyI6Imh0dHBzOi8va2V5Y2xvYWsuYXV0aC1zdGFnZS52aWRhLmlkL3JlYWxtcy9zcHJpbmdib290LXF1aWNrc3RhcnQiLCJzdWIiOiJhMjI4YTM1NS05NTczLTQzNjgtYWYzMC01NWUwYTA1MjgwMTAiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJhcGkiLCJzZXNzaW9uX3N0YXRlIjoiZThjOGY0ZDQtZWNkMi00Nzc0LWE5ZTMtM2JhYzMwOWY4NjkyIiwic2NvcGUiOiIiLCJzaWQiOiJlOGM4ZjRkNC1lY2QyLTQ3NzQtYTllMy0zYmFjMzA5Zjg2OTIiLCJ0ZW1wbGF0ZV91cmwiOiJodHRwczovL21vY2staW1hZ2VzLmZvb2Jhci52aWRhLmlkL21vY2stbHYtZm0_bHZzPTAuOTQmZm1zPTAuOTAiLCJmYWNlTWF0Y2hNZXNzYWdlIjoiU2VsZmllIHBob3RvIGRvZXMgbm90IG1hdGNoIHdpdGggcmVmZXJlbmNlIHBob3RvIiwiZmFjZU1hdGNoU2NvcmUiOiIwLjkiLCJsaXZlbGluZXNzU2NvcmUiOiIwLjk0Iiwic2Vzc2lvbl9pZGVudGlmaWVyIjoiUzhZVzltVjN4MjQiLCJ0eXBlIjoiRmFjZU1hdGNoIiwibGl2ZWxpbmVzc0NvZGUiOiIxMDQzIiwibGl2ZWxpbmVzc01lc3NhZ2UiOiJTZWxmaWUgcGhvdG8gaXMgYSBsaXZlIHBob3RvIn0.EMJKXNYRYW6X9z5fV479fIGLxlXRiLouzasF6_WqEVTOEvgCeFZ6KakV9C1tWSUq2MLU427FkIw5b4qiNERNABEXmI2yPkZpoAatP6LAErxS0WsKVbQddde6CWQCz9LFHY9I8ySpQhQyrx-gZ_V-nVdFz7rW8oiUIcMIF4zlfpnG98ZsscMIzvjVYDMS05YhX53TywewqpGOqXjqjx53NNGcXXot8HynW2nmhsixpuEZVBQU6BoPDVeW8FglFgSMkxfPxa4wkrak-oDJ4SPEAwteGp0mGyPMilT0HiktQVxyT1EhtjwnQlNKvrOXY1-K8hAOZsAwaHrqwutvfmraEg", "accessExpiresIn": 300, "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJmMjFhZGYyZS03NWU2LTQ5Y2UtOWYwZi00ZDEwNjE0MDA4NGEifQ.eyJleHAiOjE3MDE1ODQwMTYsImlhdCI6MTcwMTU4MjIxNiwianRpIjoiYjVjZjA2ZGUtZGI5NC00NjMwLTg2YWYtMDM0ODdmYTgyMzUyIiwiaXNzIjoiaHR0cHM6Ly9rZXljbG9hay5hdXRoLXN0YWdlLnZpZGEuaWQvcmVhbG1zL3NwcmluZ2Jvb3QtcXVpY2tzdGFydCIsImF1ZCI6Imh0dHBzOi8va2V5Y2xvYWsuYXV0aC1zdGFnZS52aWRhLmlkL3JlYWxtcy9zcHJpbmdib290LXF1aWNrc3RhcnQiLCJzdWIiOiJhMjI4YTM1NS05NTczLTQzNjgtYWYzMC01NWUwYTA1MjgwMTAiLCJ0eXAiOiJSZWZyZXNoIiwiYXpwIjoiYXBpIiwic2Vzc2lvbl9zdGF0ZSI6ImU4YzhmNGQ0LWVjZDItNDc3NC1hOWUzLTNiYWMzMDlmODY5MiIsInNjb3BlIjoiIiwic2lkIjoiZThjOGY0ZDQtZWNkMi00Nzc0LWE5ZTMtM2JhYzMwOWY4NjkyIn0.ybSUM9mPGdoUX-NgU4dJvFbQ7hZ0w81VYsi5qGFVcS0", "refreshExpiresIn": 1800, "authType": "FaceMatch" }, "uri": "https://{environment-url}/realms/{partner-id}/protocol/api/authenticate", "bearerToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJlOGM4ZjRkNC1lY2QyLTQ3NzQtYTllMy0zYmFjMzA5Zjg2OTIiLCJleGVjdXRpb24iOm51bGwsInRhYl9pZCI6IlM4WVc5bVYzeDI0IiwibmJmIjoxNzAxNTgyMjE2LCJzZXNzaW9uX2NvZGUiOiJyUlh3cFhXU0hORW1wU0pSUTEzNXVaV3Zmb0tYZmFleFRjU1haZjBCdXhVIiwic2Vzc2lvbl9pZGVudGlmaWVyIjoiUzhZVzltVjN4MjQiLCJleHAiOjE3MDE1ODI1MTYsImlhdCI6MTcwMTU4MjIxNiwiYXV0aF9zZXNzaW9uX2lkIjoiZThjOGY0ZDQtZWNkMi00Nzc0LWE5ZTMtM2JhYzMwOWY4NjkyIiwianRpIjoiNTlmYzk2ZjQtYzRkZS00MDM0LTljMGItZTQ0MWQ4OTU5ZDNhIn0.tNXAf3xyIvRCBvnrtJnSO2dUe8LRiP3K_k5RX9nhb_o", "authType": "FaceMatch" } ``` {% endtab %} {% endtabs %} {% tabs %} {% tab title="Curl" %} ```http curl --location --request POST 'https://{environment-url}/realms/{partner-id}/protocol/api/authenticate' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'image=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAfQAAAH0CAMAAAD8CC+4+ipPLnhsiBY4oRVTogCWPuy71gAg5NUdg8J/wvc/wBDUDohi1/pvwAAAABJRU5ErkJggg==' \ --data-urlencode 'client_id=api' ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://{environment-url}/realms/{partner-id}/protocol/api/authenticate" payload='image=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAAfQAAAH0CAMAAAD8CC%2B4%2BipPLnhsiBY4oRVTogCWPuy71gAg5NUdg8J%2Fwvc%2FwBDUDohi1%2FpvwAAAABJRU5ErkJggg%3D%3D&client_id=api' headers = { 'Authorization': 'Bearer ', 'Content-Type': 'application/x-www-form-urlencoded' } response = requests.request("POST", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="NodeJS" %} ```javascript var axios = require('axios'); var qs = require('qs'); var data = qs.stringify({ 'image': 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAfQAAAH0CAMAAAD8CC+4+ipPLnhsiBY4oRVTogCWPuy71gAg5NUdg8J/wvc/wBDUDohi1/pvwAAAABJRU5ErkJggg==', 'client_id': 'api' }); var config = { method: 'post', url: 'https://{environment-url}/realms/{partner-id}/protocol/api/authenticate', headers: { 'Authorization': 'Bearer ', 'Content-Type': 'application/x-www-form-urlencoded' }, data : data }; 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("application/x-www-form-urlencoded"); RequestBody body = RequestBody.create(mediaType, "image=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAfQAAAH0CAMAAAD8CC+4+ipPLnhsiBY4oRVTogCWPuy71gAg5NUdg8J/wvc/wBDUDohi1/pvwAAAABJRU5ErkJggg==&client_id=api"); Request request = new Request.Builder() .url("https://{environment-url}/realms/{partner-id}/protocol/api/authenticate") .method("POST", body) .addHeader("Authorization", "Bearer ") .addHeader("Content-Type", "application/x-www-form-urlencoded") .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="C#" %} ```csharp var client = new RestClient("https://{environment-url}/realms/{partner-id}/protocol/api/authenticate"); client.Timeout = -1; var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/x-www-form-urlencoded"); request.AddParameter("image", "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAfQAAAH0CAMAAAD8CC+4+ipPLnhsiBY4oRVTogCWPuy71gAg5NUdg8J/wvc/wBDUDohi1/pvwAAAABJRU5ErkJggg=="); request.AddParameter("client_id", "api"); IRestResponse response = client.Execute(request); Console.WriteLine(response.Content); ``` {% endtab %} {% tab title="PHP" %} ```php 'https://{environment-url}/realms/{partner-id}/protocol/api/authenticate', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS => 'image=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAAfQAAAH0CAMAAAD8CC%2B4%2BipPLnhsiBY4oRVTogCWPuy71gAg5NUdg8J%2Fwvc%2FwBDUDohi1%2FpvwAAAABJRU5ErkJggg%3D%3D&client_id=api', CURLOPT_HTTPHEADER => array( 'Authorization: Bearer ', 'Content-Type: application/x-www-form-urlencoded' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ### Success Response The access token issued after a successful face match validation functions is a JWT token, which includes details such as liveliness and face match scores. The [signed JWT tokens](/identity-stack/authentication/authentication-factors/biometric-device-selfie-id/integration-methods/face-match-api/api-reference/signed-jwt-tokens.md) contain parameters along with corresponding explanations. The `uri` and `bearerToken` in the response will be used in case of the multi authenticator flow and it can be ignored in the case when single authenticator is used. ```json { "entity": { "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJYbnNBNFVPdlkyU0JLSkdnX1ppTHN1Tk8tZ2dlLVB0RXZzX2twRTBhd3RnIn0.eyJleHAiOjE3MDE1ODI1MTYsIm5iZiI6MTcwMTU4MjIxNiwiaWF0IjoxNzAxNTgyMjE2LCJhdXRoX3RpbWUiOjE3MDE1ODIyMTYsImp0aSI6IjBjZDljNGUyLTEwZGYtNDNmZS04NGMwLWE0MmI0ZDVhOTRjMyIsImlzcyI6Imh0dHBzOi8va2V5Y2xvYWsuYXV0aC1zdGFnZS52aWRhLmlkL3JlYWxtcy9zcHJpbmdib290LXF1aWNrc3RhcnQiLCJzdWIiOiJhMjI4YTM1NS05NTczLTQzNjgtYWYzMC01NWUwYTA1MjgwMTAiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJhcGkiLCJzZXNzaW9uX3N0YXRlIjoiZThjOGY0ZDQtZWNkMi00Nzc0LWE5ZTMtM2JhYzMwOWY4NjkyIiwic2NvcGUiOiIiLCJzaWQiOiJlOGM4ZjRkNC1lY2QyLTQ3NzQtYTllMy0zYmFjMzA5Zjg2OTIiLCJ0ZW1wbGF0ZV91cmwiOiJodHRwczovL21vY2staW1hZ2VzLmZvb2Jhci52aWRhLmlkL21vY2stbHYtZm0_bHZzPTAuOTQmZm1zPTAuOTAiLCJmYWNlTWF0Y2hNZXNzYWdlIjoiU2VsZmllIHBob3RvIGRvZXMgbm90IG1hdGNoIHdpdGggcmVmZXJlbmNlIHBob3RvIiwiZmFjZU1hdGNoU2NvcmUiOiIwLjkiLCJsaXZlbGluZXNzU2NvcmUiOiIwLjk0Iiwic2Vzc2lvbl9pZGVudGlmaWVyIjoiUzhZVzltVjN4MjQiLCJ0eXBlIjoiRmFjZU1hdGNoIiwibGl2ZWxpbmVzc0NvZGUiOiIxMDQzIiwibGl2ZWxpbmVzc01lc3NhZ2UiOiJTZWxmaWUgcGhvdG8gaXMgYSBsaXZlIHBob3RvIn0.EMJKXNYRYW6X9z5fV479fIGLxlXRiLouzasF6_WqEVTOEvgCeFZ6KakV9C1tWSUq2MLU427FkIw5b4qiNERNABEXmI2yPkZpoAatP6LAErxS0WsKVbQddde6CWQCz9LFHY9I8ySpQhQyrx-gZ_V-nVdFz7rW8oiUIcMIF4zlfpnG98ZsscMIzvjVYDMS05YhX53TywewqpGOqXjqjx53NNGcXXot8HynW2nmhsixpuEZVBQU6BoPDVeW8FglFgSMkxfPxa4wkrak-oDJ4SPEAwteGp0mGyPMilT0HiktQVxyT1EhtjwnQlNKvrOXY1-K8hAOZsAwaHrqwutvfmraEg", "accessExpiresIn": 300, "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJmMjFhZGYyZS03NWU2LTQ5Y2UtOWYwZi00ZDEwNjE0MDA4NGEifQ.eyJleHAiOjE3MDE1ODQwMTYsImlhdCI6MTcwMTU4MjIxNiwianRpIjoiYjVjZjA2ZGUtZGI5NC00NjMwLTg2YWYtMDM0ODdmYTgyMzUyIiwiaXNzIjoiaHR0cHM6Ly9rZXljbG9hay5hdXRoLXN0YWdlLnZpZGEuaWQvcmVhbG1zL3NwcmluZ2Jvb3QtcXVpY2tzdGFydCIsImF1ZCI6Imh0dHBzOi8va2V5Y2xvYWsuYXV0aC1zdGFnZS52aWRhLmlkL3JlYWxtcy9zcHJpbmdib290LXF1aWNrc3RhcnQiLCJzdWIiOiJhMjI4YTM1NS05NTczLTQzNjgtYWYzMC01NWUwYTA1MjgwMTAiLCJ0eXAiOiJSZWZyZXNoIiwiYXpwIjoiYXBpIiwic2Vzc2lvbl9zdGF0ZSI6ImU4YzhmNGQ0LWVjZDItNDc3NC1hOWUzLTNiYWMzMDlmODY5MiIsInNjb3BlIjoiIiwic2lkIjoiZThjOGY0ZDQtZWNkMi00Nzc0LWE5ZTMtM2JhYzMwOWY4NjkyIn0.ybSUM9mPGdoUX-NgU4dJvFbQ7hZ0w81VYsi5qGFVcS0", "refreshExpiresIn": 1800, "authType": "FaceMatch" }, "uri": "https://{environment-url}/realms/{partner-id}/protocol/api/authenticate", "bearerToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJlOGM4ZjRkNC1lY2QyLTQ3NzQtYTllMy0zYmFjMzA5Zjg2OTIiLCJleGVjdXRpb24iOm51bGwsInRhYl9pZCI6IlM4WVc5bVYzeDI0IiwibmJmIjoxNzAxNTgyMjE2LCJzZXNzaW9uX2NvZGUiOiJyUlh3cFhXU0hORW1wU0pSUTEzNXVaV3Zmb0tYZmFleFRjU1haZjBCdXhVIiwic2Vzc2lvbl9pZGVudGlmaWVyIjoiUzhZVzltVjN4MjQiLCJleHAiOjE3MDE1ODI1MTYsImlhdCI6MTcwMTU4MjIxNiwiYXV0aF9zZXNzaW9uX2lkIjoiZThjOGY0ZDQtZWNkMi00Nzc0LWE5ZTMtM2JhYzMwOWY4NjkyIiwianRpIjoiNTlmYzk2ZjQtYzRkZS00MDM0LTljMGItZTQ0MWQ4OTU5ZDNhIn0.tNXAf3xyIvRCBvnrtJnSO2dUe8LRiP3K_k5RX9nhb_o", "authType": "FaceMatch" } ``` Response Schema ```json { "entity": { "accessToken": "{JWT TOKEN WITH TRANSACTION DETAILS AND INCLUDING SESSION IDENTIFIER AND THE FACEMATCH SCORE}", "accessExpiresIn": 300, "refreshToken": "{REFRESH TOKEN}", "refreshExpiresIn": 1800, "authType": "{AUTHENTICATION TYPE}" }, "uri": "{URI OF THE FOLLOW UP REQUEST FOR TRANSACTION COMPLETION}", "bearerToken": "{BEARER TOKEN TO BE ADDED IN AUTHORIZATION HEADER OF FOLLOW UP REQUEST}", "authType": "{AUTHENTICATION TYPE}", } ``` ### Error Response ```json { "error": "Unprocessable Entity", "errorDescription": "message=Unprocessable Entity;livelinessScore=0.0;faceMatchScore=0.0" } ``` Response Schema ```json { "error": "{TYPE OF ERROR}", "errorDescription": "{REASONING FOR THE ERROR}" } ``` ### Error Codes 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.