--- 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 Enum: `selfie`, `videoSelfie`, `id`, `nfc` | | `captureType` | query | string | | Enum: `AUTO`, `MANUAL`, `NATIVE`, `UPLOAD` | | `externalCaptureId` | query | string | | | | `recordingId` | query | string | | | | `api-version` | header | string | yes | Default: `1.0` | ## 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?imageType=%3CimageType%3E&captureType=%3CcaptureType%3E&externalCaptureId=%3CexternalCaptureId%3E&recordingId=%3CrecordingId%3E \ -H "x-api-key: " \ -H "X-Incode-Hardware-Id: " \ -H "api-version: 1.0" \ -H "Content-Type: application/json" \ -d '{ "faceCoordinates": { "leftEyeX": "", "leftEyeY": "", "rightEyeX": "", "rightEyeY": "", "rightMouthX": "", "rightMouthY": "", "noseTipX": "", "noseTipY": "", "x": "", "y": "", "width": "", "height": "" } }' ``` ### Node ```js const res = await fetch("https://demo-api.incodesmile.com/omni/add/face/third-party?imageType=%3CimageType%3E&captureType=%3CcaptureType%3E&externalCaptureId=%3CexternalCaptureId%3E&recordingId=%3CrecordingId%3E", { method: "POST", headers: { "x-api-key": "", "X-Incode-Hardware-Id": "", "api-version": "1.0", "Content-Type": "application/json", }, body: JSON.stringify({ "faceCoordinates": { "leftEyeX": "", "leftEyeY": "", "rightEyeX": "", "rightEyeY": "", "rightMouthX": "", "rightMouthY": "", "noseTipX": "", "noseTipY": "", "x": "", "y": "", "width": "", "height": "" } }), }); const data = await res.json(); ``` ### Python ```python import requests headers = { "x-api-key": "", "X-Incode-Hardware-Id": "", "api-version": "1.0", "Content-Type": "application/json", } res = requests.post("https://demo-api.incodesmile.com/omni/add/face/third-party?imageType=%3CimageType%3E&captureType=%3CcaptureType%3E&externalCaptureId=%3CexternalCaptureId%3E&recordingId=%3CrecordingId%3E", headers=headers, json={ "faceCoordinates": { "leftEyeX": "", "leftEyeY": "", "rightEyeX": "", "rightEyeY": "", "rightMouthX": "", "rightMouthY": "", "noseTipX": "", "noseTipY": "", "x": "", "y": "", "width": "", "height": "" } }) data = res.json() ``` ### Java ```java HttpRequest req = HttpRequest.newBuilder() .uri(URI.create("https://demo-api.incodesmile.com/omni/add/face/third-party?imageType=%3CimageType%3E&captureType=%3CcaptureType%3E&externalCaptureId=%3CexternalCaptureId%3E&recordingId=%3CrecordingId%3E")) .header("x-api-key", "") .header("X-Incode-Hardware-Id", "") .header("api-version", "1.0") .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString("{\n \"faceCoordinates\": {\n \"leftEyeX\": \"\",\n \"leftEyeY\": \"\",\n \"rightEyeX\": \"\",\n \"rightEyeY\": \"\",\n \"rightMouthX\": \"\",\n \"rightMouthY\": \"\",\n \"noseTipX\": \"\",\n \"noseTipY\": \"\",\n \"x\": \"\",\n \"y\": \"\",\n \"width\": \"\",\n \"height\": \"\"\n }\n}")) .build(); HttpResponse res = HttpClient.newHttpClient() .send(req, HttpResponse.BodyHandlers.ofString()); ``` ### Ruby ``` require "net/http" require "json" uri = URI("https://demo-api.incodesmile.com/omni/add/face/third-party?imageType=%3CimageType%3E&captureType=%3CcaptureType%3E&externalCaptureId=%3CexternalCaptureId%3E&recordingId=%3CrecordingId%3E") req = Net::HTTP::Post.new(uri) req["x-api-key"] = "" req["X-Incode-Hardware-Id"] = "" req["api-version"] = "1.0" req["Content-Type"] = "application/json" req.body = '{ "faceCoordinates": { "leftEyeX": "", "leftEyeY": "", "rightEyeX": "", "rightEyeY": "", "rightMouthX": "", "rightMouthY": "", "noseTipX": "", "noseTipY": "", "x": "", "y": "", "width": "", "height": "" } }' res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) } data = JSON.parse(res.body) ``` ### PHP ``` $ch = curl_init("https://demo-api.incodesmile.com/omni/add/face/third-party?imageType=%3CimageType%3E&captureType=%3CcaptureType%3E&externalCaptureId=%3CexternalCaptureId%3E&recordingId=%3CrecordingId%3E"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST"); curl_setopt($ch, CURLOPT_HTTPHEADER, [ "x-api-key: ", "X-Incode-Hardware-Id: ", "api-version: 1.0", "Content-Type: application/json", ]); curl_setopt($ch, CURLOPT_POSTFIELDS, '{ "faceCoordinates": { "leftEyeX": "", "leftEyeY": "", "rightEyeX": "", "rightEyeY": "", "rightMouthX": "", "rightMouthY": "", "noseTipX": "", "noseTipY": "", "x": "", "y": "", "width": "", "height": "" } }'); $data = json_decode(curl_exec($ch), true); curl_close($ch); ``` ### Example response ```json { "age": 0, "isBright": true, "confidence": 0, "hasLenses": true, "hasFaceMask": true, "hasClosedEyes": true, "hasHeadCover": true, "faceOccluded": true, "sessionStatus": "Alive", "captureAttemptsLimit": { "max": 0, "remaining": 0 } } ```