--- title: "Add face/Selfie image" url: "https://developer.incode.com/api-reference/add-face-third-party/" section: "api-reference" group: "Face capture" version: "v1.1" status: "live" endpoint: "POST /omni/add/face/third-party" --- # Add face/Selfie image `POST /omni/add/face/third-party` Base URL: `https://demo-api.incodesmile.com` — Incode demo environment Uploads selfie image for onboarding session. Response will contain data regarding liveness — if that is the photo of a real person. Number of retries is not limited. **Note**: After selfie and front-id are uploaded, endpoint for comparing faces process-face on those two images can be called. It is required that person is alone on the photo. ## Path & query parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `imageType` | query | string | | Image type. Default is selfie | | `captureType` | query | string | | Enum: `AUTO`, `MANUAL`, `NATIVE`, `UPLOAD` | | `externalCaptureId` | query | string | | | | `recordingId` | query | string | | | | `api-version` | header | string | yes | | ## Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `base64Image` | string | | Image of user's face represented in base64. | | `imageUrl` | string | | URL of face image, required to belong to a whitelisted domain | | `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. | ## Responses ### 200 OK Response body (`application/json`): | Field | Type | Required | Description | | --- | --- | --- | --- | | `age` | integer (int32) | | Age of th person in the photo. | | `isBright` | boolean | | We recommend capturing another photo if value is false. | | `confidence` | number (float) | | Value 0 means that person on photo is alive. We recommend capturing another photo if value is 1. | | `hasLenses` | boolean | | We recommend capturing another photo if value is true. | | `hasFaceMask` | boolean | | Checked only if configured in the session flow. We recommend capturing another photo if value is true. | | `hasClosedEyes` | boolean | | Checked only if configured in the session flow. We recommend capturing another photo if value is true. | | `hasHeadCover` | boolean | | Checked only if configured in the session flow. We recommend capturing another photo if value is true. | | `faceOccluded` | boolean | | Checked only if configured in the session flow. We recommend capturing another photo if value is true. | | `sessionStatus` | string | | SessionStatus Enum: `Alive`, `Closed`, `Deleted` | | `captureAttemptsLimit` | CaptureAttemptsLimitDto | | Checked only if configured in the session flow. | | `captureAttemptsLimit.max` | integer (int32) | | Maximum number of attempts to capture a photo. | | `captureAttemptsLimit.remaining` | integer (int32) | | Number of remaining attempts to capture a photo. | ### 400 Custom error statuses: - 4010: More than one face detected - 4019: Face not found - 4077: Selfie image has low quality - 4078: Selfie face is occluded or partially covered Response body (`application/json`): | Field | Type | Required | Description | | --- | --- | --- | --- | | `timestamp` | integer (int64) | | UTC timestamp in milliseconds | | `status` | integer (int32) | | Custom error code or HTTP status code | | `error` | string | | HTTP status error | | `message` | string | | Custom error message | | `path` | string | | Endpoint path | | `details` | object | | Custom error details | ## 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/add/face/third-party \ -H "x-api-key: " \ -H "api-version: 1.0" \ -H "Content-Type: application/json" \ -d '{ "base64Image": "", "imageUrl": "", "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 }' ``` ### Node ```js const res = await fetch("https://demo-api.incodesmile.com/omni/add/face/third-party", { method: "POST", headers: { "x-api-key": "", "api-version": "1.0", "Content-Type": "application/json", }, body: JSON.stringify({ "base64Image": "", "imageUrl": "", "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 }), }); 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/add/face/third-party", headers=headers, json={ "base64Image": "", "imageUrl": "", "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 }) data = res.json() ``` ### Java ```java HttpRequest req = HttpRequest.newBuilder() .uri(URI.create("https://demo-api.incodesmile.com/omni/add/face/third-party")) .header("x-api-key", "") .header("api-version", "1.0") .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString("{\n \"base64Image\": \"\",\n \"imageUrl\": \"\",\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}")) .build(); HttpResponse res = HttpClient.newHttpClient() .send(req, HttpResponse.BodyHandlers.ofString()); ``` ### Example response ```json { "success": true, "status": "OK" } ```