--- title: "Authentication with face/selfie image" url: "https://developer.incode.com/api-reference/onboarding-authentications-authenticate-third-party/" section: "api-reference" group: "Onboarding authentication" version: "v1.1" status: "live" endpoint: "POST /omni/onboarding-authentications/authenticate/third-party" --- # Authentication with face/selfie image `POST /omni/onboarding-authentications/authenticate/third-party` Base URL: `https://demo-api.incodesmile.com` — Incode demo environment Authenticate user by comparing base64 image from request and user's existing face template. In case of One to one authentication, user is first found in DB by hint from request. At least one of criteria parameter must be sent in request. In case of One to N authentication, hint is not used. In case face doesn't match error response is returned. ## Path & query parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `api-version` | header | string | yes | | ## Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `base64Image` | string | yes | Image of user's face represented in base64. | | `faceCoordinates` | FaceCoordinatesDto | | Face coordinates | | `faceCoordinates.leftEyeX` | number (float) | yes | Left eye coordinates for X | | `faceCoordinates.leftEyeY` | number (float) | yes | Left eye coordinates for Y | | `faceCoordinates.rightEyeX` | number (float) | yes | Right eye coordinates for X | | `faceCoordinates.rightEyeY` | number (float) | yes | Right eye coordinates for Y | | `faceCoordinates.mouthX` | number (float) | | Left mouth coordinates for X. Note: the field is deprecated, use leftMouthX instead | | `faceCoordinates.leftMouthX` | number (float) | | Left mouth coordinates for X | | `faceCoordinates.mouthY` | number (float) | | Left mouth coordinates for Y. Note: the field is deprecated, use leftMouthY instead | | `faceCoordinates.leftMouthY` | number (float) | | Left mouth coordinates for Y | | `faceCoordinates.rightMouthX` | number (float) | yes | Right mouth coordinates for X | | `faceCoordinates.rightMouthY` | number (float) | yes | Right mouth coordinates for Y | | `faceCoordinates.noseTipX` | number (float) | yes | Nose coordinates for X | | `faceCoordinates.noseTipY` | number (float) | yes | Nose coordinates for Y | | `faceCoordinates.x` | number (float) | yes | X coordinate of face rectangle. | | `faceCoordinates.y` | number (float) | yes | Y coordinate of face rectangle. | | `faceCoordinates.width` | number (float) | yes | Width of face rectangle. | | `faceCoordinates.height` | number (float) | yes | Height of face rectangle. | | `hint` | string | | Customer hint. Possible hints are: customer id, email, phone number... | | `recordingId` | string | | Id of recording used in spoof detection. | ## Responses ### 200 OK Response body (`application/json`): | Field | Type | Required | Description | | --- | --- | --- | --- | | `overallStatus` | string | | Authentication status: FAIL/PASS. Enum: `PASS`, `FAIL` | | `captureAttemptsLimit` | CaptureAttemptsLimitDto | | Checked only if configured in the session flow. Shows remaining number of attempts, and maximum number of attempts allowed. | | `captureAttemptsLimit.max` | integer (int32) | | Maximum number of attempts to capture a photo. | | `captureAttemptsLimit.remaining` | integer (int32) | | Number of remaining attempts to capture a photo. | | `candidate` | string | | Id of matched candidate. | | `error` | OnboardingAuthenticationErrorDto | | Error name and description pair. Possible error names are: INACTIVE_SESSION, NONEXISTENT_CUSTOMER, LENSES_DETECTED, FACE_MASK_DETECTED, HEAD_COVER_DETECTED, CLOSED_EYES_DETECTED, FACE_TOO_DARK, SPOOF_ATTEMPT_DETECTED, USER_IS_NOT_RECOGNIZED, SELFIE_IMAGE_LOW_QUALITY, MULTIPLE_FACES_DETECTED, HINT_NOT_PROVIDED, FACE_NOT_FOUND, FACE_CROPPING_FAILED, FACE_TOO_SMALL, FACE_TOO_BLURRY, BAD_PHOTO_QUALITY, PROCESSING_ERROR, BAD_REQUEST | | `error.name` | string | | | | `error.message` | string | | | ## Code samples Generated from this endpoint's method, path, and the conventional Incode headers. The base URL is the Incode demo environment; replace `` with a key for your region. ### cURL ```bash curl -X POST https://demo-api.incodesmile.com/omni/onboarding-authentications/authenticate/third-party \ -H "x-api-key: " \ -H "api-version: 1.0" \ -H "Content-Type: application/json" \ -d '{ "base64Image": "", "faceCoordinates": "", "faceCoordinates.leftEyeX": 0, "faceCoordinates.leftEyeY": 0, "faceCoordinates.rightEyeX": 0, "faceCoordinates.rightEyeY": 0, "faceCoordinates.mouthX": 0, "faceCoordinates.leftMouthX": 0, "faceCoordinates.mouthY": 0, "faceCoordinates.leftMouthY": 0, "faceCoordinates.rightMouthX": 0, "faceCoordinates.rightMouthY": 0, "faceCoordinates.noseTipX": 0, "faceCoordinates.noseTipY": 0, "faceCoordinates.x": 0, "faceCoordinates.y": 0, "faceCoordinates.width": 0, "faceCoordinates.height": 0, "hint": "", "recordingId": "" }' ``` ### Node ```js const res = await fetch("https://demo-api.incodesmile.com/omni/onboarding-authentications/authenticate/third-party", { method: "POST", headers: { "x-api-key": "", "api-version": "1.0", "Content-Type": "application/json", }, body: JSON.stringify({ "base64Image": "", "faceCoordinates": "", "faceCoordinates.leftEyeX": 0, "faceCoordinates.leftEyeY": 0, "faceCoordinates.rightEyeX": 0, "faceCoordinates.rightEyeY": 0, "faceCoordinates.mouthX": 0, "faceCoordinates.leftMouthX": 0, "faceCoordinates.mouthY": 0, "faceCoordinates.leftMouthY": 0, "faceCoordinates.rightMouthX": 0, "faceCoordinates.rightMouthY": 0, "faceCoordinates.noseTipX": 0, "faceCoordinates.noseTipY": 0, "faceCoordinates.x": 0, "faceCoordinates.y": 0, "faceCoordinates.width": 0, "faceCoordinates.height": 0, "hint": "", "recordingId": "" }), }); const data = await res.json(); ``` ### Python ```python import requests headers = { "x-api-key": "", "api-version": "1.0", "Content-Type": "application/json", } res = requests.post("https://demo-api.incodesmile.com/omni/onboarding-authentications/authenticate/third-party", headers=headers, json={ "base64Image": "", "faceCoordinates": "", "faceCoordinates.leftEyeX": 0, "faceCoordinates.leftEyeY": 0, "faceCoordinates.rightEyeX": 0, "faceCoordinates.rightEyeY": 0, "faceCoordinates.mouthX": 0, "faceCoordinates.leftMouthX": 0, "faceCoordinates.mouthY": 0, "faceCoordinates.leftMouthY": 0, "faceCoordinates.rightMouthX": 0, "faceCoordinates.rightMouthY": 0, "faceCoordinates.noseTipX": 0, "faceCoordinates.noseTipY": 0, "faceCoordinates.x": 0, "faceCoordinates.y": 0, "faceCoordinates.width": 0, "faceCoordinates.height": 0, "hint": "", "recordingId": "" }) data = res.json() ``` ### Java ```java HttpRequest req = HttpRequest.newBuilder() .uri(URI.create("https://demo-api.incodesmile.com/omni/onboarding-authentications/authenticate/third-party")) .header("x-api-key", "") .header("api-version", "1.0") .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString("{\n \"base64Image\": \"\",\n \"faceCoordinates\": \"\",\n \"faceCoordinates.leftEyeX\": 0,\n \"faceCoordinates.leftEyeY\": 0,\n \"faceCoordinates.rightEyeX\": 0,\n \"faceCoordinates.rightEyeY\": 0,\n \"faceCoordinates.mouthX\": 0,\n \"faceCoordinates.leftMouthX\": 0,\n \"faceCoordinates.mouthY\": 0,\n \"faceCoordinates.leftMouthY\": 0,\n \"faceCoordinates.rightMouthX\": 0,\n \"faceCoordinates.rightMouthY\": 0,\n \"faceCoordinates.noseTipX\": 0,\n \"faceCoordinates.noseTipY\": 0,\n \"faceCoordinates.x\": 0,\n \"faceCoordinates.y\": 0,\n \"faceCoordinates.width\": 0,\n \"faceCoordinates.height\": 0,\n \"hint\": \"\",\n \"recordingId\": \"\"\n}")) .build(); HttpResponse res = HttpClient.newHttpClient() .send(req, HttpResponse.BodyHandlers.ofString()); ``` ### Example response ```json { "success": true, "status": "OK" } ```