Regula Face SDK Web API (6.4.0)

Regula Face SDK is a cross-platform biometric verification solution for a digital identity verification process and image quality assurance. The SDK enables convenient and reliable face capture on the client side (mobile, web, and desktop) and further processing on the client or server side.

The Face SDK includes the following features:

Here is the OpenAPI specification on GitHub.

Clients

JavaScript client for the browser and node.js based on axios
Java client compatible with jvm and android
Python 3.5+ client
C# client for .NET & .NET Core

matching

compare faces (1:1)

To perform a comparison of faces in the same image or in two different images, use POST /api/match. It's possible to compare faces in the same image or in two different images, this is defined by the images.type parameter.

The face detection result is displayed in the detections field. Each face is identified by two parameters: faceIndex (the index number of the face) and imageIndex (the index number of the image on which the face is detected). So, if there are two images each of which has two faces in them, the parameters will be the following:

First face in the first image: faceIndex: 0, imageIndex: 0
Second face in the first image: faceIndex: 1, imageIndex: 0
First face of the second image: faceIndex: 0, imageIndex: 1
Second face in the second image: faceIndex: 1, imageIndex: 1

header Parameters

X-RequestID

string

Request header label.

Request Body schema: application/json

tag	string Session identificator, should be unique for each session.
thumbnails	any Deprecated Use `outputImageParams.crop` instead.
required	Array of objects (MatchImage) All images included in the comparison.
	object (OutputImageParams) Allows to process the uploaded image according to the indicated settings.

Responses

Response Schema: application/json

code required	integer (FaceSDKResultCode) Enum: 0 1 2 3 4 … 36 more The result code, see the FaceSDKResultCode enum.
	Array of objects (MatchImageDetection) The detection results.
	Array of objects (MatchImageResult) The comparison results.
	object A free-form object containing person's extended attributes.

Request samples

Payload

Content type

application/json

{"tag": "string",
"thumbnails": null,
"images": [{"index": 0,
"type": 1,
"data": "string",
"detectAll": false
}
],
"outputImageParams": {"backgroundColor": [128,
128,
128
],
"crop": {"type": 0,
"padColor": [128,
128,
128
],
"size": [300,
400
],
"returnOriginalRect": true
}
}
}

Response samples

200

Content type

application/json

{"code": 0,
"detections": [{"faces": [{"faceIndex": 0,
"landmarks": [["x",
"y"
]
],
"rotationAngle": 0,
"roi": ["x",
"y",
"width",
"height"
],
"thumbnail": "string",
"crop": "string"
}
],
"imageIndex": 0,
"status": 0
}
],
"results": [{"firstIndex": 0,
"firstFaceIndex": 0,
"first": 1,
"secondIndex": 0,
"secondFaceIndex": 0,
"second": 1,
"score": 0,
"similarity": 0
}
],
"metadata": { }
}

match and search (1:1 + 1:N)

To compare several images from a document and look up a person in the database in one request, use POST /api/match_and_search. In this case, the calculation of the descriptor will be performed only once, as opposed to using two requests for the same operation. If only one person is identified, matching is not performed and only search is carried out.

header Parameters

X-RequestID

string

Request header label.

Request Body schema: application/json

tag	string Session identificator, should be unique for each session.
	Array of objects Person's images.
groupIds	Array of strings <uuid> IDs of the groups in which the search is performed.

Responses

Response Schema: application/json

code required	integer (FaceSDKResultCode) Enum: 0 1 2 3 4 … 36 more The result code, see the FaceSDKResultCode enum.
	Array of objects (MatchImageResult) The match and search results.
elapsedTime	number <float> Time the processing has taken, ms.
	object A free-form object containing person's extended attributes.
	Array of objects The detection results.

Request samples

Payload

Content type

application/json

{"tag": "string",
"images": [{"content": "string",
"type": 1
}
],
"groupIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}

Response samples

200

Content type

application/json

{"code": 0,
"results": [{"firstIndex": 0,
"firstFaceIndex": 0,
"first": 1,
"secondIndex": 0,
"secondFaceIndex": 0,
"second": 1,
"score": 0,
"similarity": 0
}
],
"elapsedTime": 1.317137987,
"metadata": { },
"detections": [{"faces": [{"faceIndex": 0,
"landmarks": [["x",
"y"
]
],
"rotationAngle": 2.1272900104522705,
"roi": ["x",
"y",
"width",
"height"
],
"thumbnail": "string",
"crop": "string",
"persons": [{"images": [{"id": "string",
"contentType": "string",
"createdAt": "string",
"updatedAt": "string",
"path": "string",
"url": "string",
"metadata": { },
"similarity": 0,
"distance": 0
}
],
"name": "string",
"externalId": "string",
"metadata": { },
"groups": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"ttl": null,
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"createdAt": "string",
"updatedAt": "string"
}
]
}
],
"imageIndex": 0,
"status": 0
}
]
}

detect and check quality

Use the POST api/detect endpoint to analyze images, recognize faces in them, and return cropped and aligned portraits of the detected people.

The Face Detection feature lets you:

Check face image quality: Assess whether a portrait meets certain standards, for example, ICAO, Schengen visa, USA visa. To perform image quality check, use the processParam.quality field.
Evaluate face attributes: Estimate the age range of a person; check whether the eyes are occluded, closed, or open; detect a facial expression or smile; see if there are glasses, sunglasses, head coverage, medical mask, etc. To evaluate attributes, add the processParam.attributes field.

You can perform Face Detection in two ways:

By adding parameters manually. In this case, the configuration is not saved and can not be automatically repeated.
By a processing scenario that includes certain parameters. You can use predefined scenarios or add custom ones.

header Parameters

X-RequestID

string

Request header label.

Request Body schema: application/json

tag	string Session identificator, should be unique for each session.
	object (ProcessParam) The processing parameters.
image	string <byte> (ImageData) Base64-encoded image.
thumbnails	boolean Deprecated Default: false Use `processParam.outputImageParams.crop` instead.

Responses

Response Schema: application/json

code required	integer (FaceSDKResultCode) Enum: 0 1 2 3 4 … 36 more The result code, see the FaceSDKResultCode enum.
	object (DetectResult)

Request samples

Payload

Content type

application/json

{"tag": "string",
"processParam": {"scenario": "OldMode",
"onlyCentralFace": false,
"outputImageParams": {"backgroundColor": [128,
128,
128
],
"crop": {"type": 0,
"padColor": [128,
128,
128
],
"size": [300,
400
],
"returnOriginalRect": true
}
},
"quality": {"backgroundMatchColor": [128,
128,
128
],
"config": [{"name": "ImageWidth",
"range": ["x",
"y"
]
}
]
},
"attributes": {"config": [{"name": "Age"
}
]
}
},
"image": "string",
"thumbnails": false
}

Response samples

200

Content type

application/json

{"code": 0,
"results": {"detections": [{"crop": "string",
"attributes": {"details": [{ }
],
"elapsedTime": 0
},
"landmarks": [["x",
"y"
]
],
"quality": {"nonCompliant": ["ImageWidthToHeight",
"Yaw"
],
"detailsGroups": [{"groupId": 1,
"name": "ImageCharacteristics",
"totalCount": 5,
"compliantCount": 4
}
],
"details": [{"groupId": 1,
"name": "ImageWidth",
"range": ["x",
"y"
],
"status": 0,
"value": 0
}
],
"score": -1,
"timer": 0.420364111661911
},
"roi": ["x",
"y",
"width",
"height"
],
"thumbnail": "string"
}
],
"detectorType": 0,
"landmarksType": 0,
"scenario": "OldMode",
"timer": 0.8479356
}
}

person

Create person

header Parameters

X-RequestID

string

Request header label.

Request Body schema: application/json

name required	string Person's name.
externalId	string Person's ID, used for linking search results to an ID in an external system. Can be set when creating a Person, stored in the database, and included in the search to return only Persons with the specified ID. Optional.
	object A free-form object containing person's extended attributes.
groups	Array of strings <uuid> Groups a person should be placed to. If no group is specified in request, a Default group is created and the person is placed to it.
ttl	integer or null Default: null The lifespan of the Person's records, seconds. Optional.

Responses

Response Schema: application/json

name required	string Person's name.
externalId	string Person's ID, used for linking search results to an ID in an external system. Can be set when creating a Person, stored in the database, and included in the search to return only Persons with the specified ID. Optional.
	object A free-form object containing person's extended attributes.
groups	Array of strings <uuid> Groups a person should be placed to. If no group is specified in request, a Default group is created and the person is placed to it.
ttl	integer or null Default: null The lifespan of the Person's records, seconds. Optional.
id	string <uuid> Person ID. The list of persons is sorted by decreasing ID value.
createdAt	string Person creation date.
updatedAt	string Person update date.

Response Schema: application/json

statusCode	integer Status code.
type	string Error type.
msg	string Error message.
	object A free-form object containing group's extended attributes.

Request samples

Payload

Content type

application/json

{"name": "string",
"externalId": "string",
"metadata": { },
"groups": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"ttl": null
}

Response samples

201
400

Content type

application/json

{"name": "string",
"externalId": "string",
"metadata": { },
"groups": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"ttl": null,
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"createdAt": "string",
"updatedAt": "string"
}

Get person

path Parameters

personId

required

string <uuid>

Person ID.

header Parameters

X-RequestID

string

Request header label.

Responses

Response Schema: application/json

name required	string Person's name.
externalId	string Person's ID, used for linking search results to an ID in an external system. Can be set when creating a Person, stored in the database, and included in the search to return only Persons with the specified ID. Optional.
	object A free-form object containing person's extended attributes.
groups	Array of strings <uuid> Groups a person should be placed to. If no group is specified in request, a Default group is created and the person is placed to it.
ttl	integer or null Default: null The lifespan of the Person's records, seconds. Optional.
id	string <uuid> Person ID. The list of persons is sorted by decreasing ID value.
createdAt	string Person creation date.
updatedAt	string Person update date.

Response Schema: application/json

statusCode	integer Status code.
type	string Error type.
msg	string Error message.
	object A free-form object containing group's extended attributes.

Response Schema: application/json

statusCode	integer Status code.
type	string Error type.
msg	string Error message.
	object A free-form object containing group's extended attributes.

Response samples

200
400
404

Content type

application/json

{"name": "string",
"externalId": "string",
"metadata": { },
"groups": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"ttl": null,
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"createdAt": "string",
"updatedAt": "string"
}

Update person

path Parameters

personId

required

string <uuid>

Person ID.

header Parameters

X-RequestID

string

Request header label.

Request Body schema: application/json

Request body for the Person to update.

externalId	string Person's ID, used for linking search results to an ID in an external system. Can be set when creating a Person, stored in the database, and included in the search to return only Persons with the specified ID. Optional.
name	string Person's name.
	object A free-form object containing person's extended attributes.
groups	Array of strings <uuid> Groups a person should be placed to. If no group is specified in request, a Default group is created and the person is placed to it.

Responses

Response Schema: application/json

statusCode	integer Status code.
type	string Error type.
msg	string Error message.
	object A free-form object containing group's extended attributes.

Response Schema: application/json

statusCode	integer Status code.
type	string Error type.
msg	string Error message.
	object A free-form object containing group's extended attributes.

Request samples

Payload

Content type

application/json

{"externalId": "string",
"name": "string",
"metadata": { },
"groups": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}

Response samples

400
404

Content type

application/json

{"statusCode": 0,
"type": "string",
"msg": "string",
"metadata": { }
}

Delete person

path Parameters

personId

required

string <uuid>

Person ID.

header Parameters

X-RequestID

string

Request header label.

Responses

Response Schema: application/json

statusCode	integer Status code.
type	string Error type.
msg	string Error message.
	object A free-form object containing group's extended attributes.

Response Schema: application/json

statusCode	integer Status code.
type	string Error type.
msg	string Error message.
	object A free-form object containing group's extended attributes.

Response samples

400
404

Content type

application/json

{"statusCode": 0,
"type": "string",
"msg": "string",
"metadata": { }
}

Get person images

path Parameters

personId

required

string <uuid>

Person ID.

query Parameters

page	integer Default: 1 The page number to get a list of persons or groups.
size	integer Default: 1000 The page size with a list of persons or groups, items.

header Parameters

X-RequestID

string

Request header label.

Responses

Response Schema: application/json

page	integer Current page number.
totalPages	integer Total number of pages.
	Array of objects (Image)

Response Schema: application/json

statusCode	integer Status code.
type	string Error type.
msg	string Error message.
	object A free-form object containing group's extended attributes.

Response Schema: application/json

statusCode	integer Status code.
type	string Error type.
msg	string Error message.
	object A free-form object containing group's extended attributes.

Response samples

200
400
404

Content type

application/json

{"page": 1,
"totalPages": 2,
"items": [{"id": "string",
"contentType": "string",
"createdAt": "string",
"updatedAt": "string",
"path": "string",
"url": "string",
"metadata": { }
}
]
}

Add person image

path Parameters

personId

required

string <uuid>

Person ID.

header Parameters

X-RequestID

string

Request header label.

Request Body schema: application/json

Image to add.

tag	string Session identificator.
required	object Uploaded image.
threshold	number <float> The similarity threshold.
limit	integer The maximum number of results to be returned.

Responses

Response Schema: application/json

id	string Response image ID. The list is sorted by decreasing ID value.
contentType	string Original media type of the returned image.
createdAt	string Returned image creation date.
path	string Returned image path.
url	string Returned image URL.
	object A free-form object containing person's extended attributes.

Response Schema: application/json

statusCode	integer Status code.
type	string Error type.
msg	string Error message.
	object A free-form object containing group's extended attributes.

Response Schema: application/json

statusCode	integer Status code.
type	string Error type.
msg	string Error message.
	object A free-form object containing group's extended attributes.

Request samples

Payload

Content type

application/json

{"tag": "string",
"image": {"contentType": "string",
"content": "string",
"imageUrl": "string",
"resizeOptions": {"width": 0,
"height": 0,
"quality": 100
}
},
"threshold": 0,
"limit": 0
}

Response samples

200
400
404

Content type

application/json

{"id": "string",
"contentType": "string",
"createdAt": "string",
"path": "string",
"url": "string",
"metadata": { }
}

Get person image by id

path Parameters

personId required	string <uuid> Person ID.
imageId required	string Image ID.

header Parameters

X-RequestID

string

Request header label.

Responses

Response Schema: image/*

string <binary>

Response Schema: application/json

statusCode	integer Status code.
type	string Error type.
msg	string Error message.
	object A free-form object containing group's extended attributes.

Response Schema: application/json

statusCode	integer Status code.
type	string Error type.
msg	string Error message.
	object A free-form object containing group's extended attributes.

Response samples

400
404

Content type

application/json

{"statusCode": 0,
"type": "string",
"msg": "string",
"metadata": { }
}

Delete image of person

path Parameters

personId required	string <uuid> Person ID.
imageId required	string Image ID.

header Parameters

X-RequestID

string

Request header label.

Responses

Response Schema: application/json

statusCode	integer Status code.
type	string Error type.
msg	string Error message.
	object A free-form object containing group's extended attributes.

Response Schema: application/json

statusCode	integer Status code.
type	string Error type.
msg	string Error message.
	object A free-form object containing group's extended attributes.

Response samples

400
404

Content type

application/json

{"statusCode": 0,
"type": "string",
"msg": "string",
"metadata": { }
}

Get person groups

path Parameters

personId

required

string <uuid>

Person ID.

query Parameters

page	integer Default: 1 The page number to get a list of persons or groups.
size	integer Default: 1000 The page size with a list of persons or groups, items.

header Parameters

X-RequestID

string

Request header label.

Responses

Response Schema: application/json

	Array of objects (Group) Array of Groups that are found during the search.
page	integer Current page number.
totalPages	integer Total number of pages.

Response Schema: application/json

statusCode	integer Status code.
type	string Error type.
msg	string Error message.
	object A free-form object containing group's extended attributes.

Response Schema: application/json

statusCode	integer Status code.
type	string Error type.
msg	string Error message.
	object A free-form object containing group's extended attributes.

Response samples

200
400
404

Content type

application/json

{"items": [{"name": "string",
"metadata": { },
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"createdAt": "string"
}
],
"page": 1,
"totalPages": 2
}

group

Get groups

query Parameters

page	integer Default: 1 The page number to get a list of persons or groups.
size	integer Default: 1000 The page size with a list of persons or groups, items.

header Parameters

X-RequestID

string

Request header label.

Responses

Response Schema: application/json

	Array of objects (Group) Array of Groups that are found during the search.
page	integer Current page number.
totalPages	integer Total number of pages.

Response Schema: application/json

statusCode	integer Status code.
type	string Error type.
msg	string Error message.
	object A free-form object containing group's extended attributes.

Response samples

200
400

Content type

application/json

{"items": [{"name": "string",
"metadata": { },
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"createdAt": "string"
}
],
"page": 1,
"totalPages": 2
}

Create group

header Parameters

X-RequestID

string

Request header label.

Request Body schema: application/json

Request body for the group to create.

tag	string Session identificator.
name required	string Group to create name.
required	object A free-form object containing group's extended attributes.

Responses

Response Schema: application/json

name	string Group to create name.
	object A free-form object containing group's extended attributes.
id	string <uuid> Group ID.
createdAt	string Group creation date.

Response Schema: application/json

statusCode	integer Status code.
type	string Error type.
msg	string Error message.
	object A free-form object containing group's extended attributes.

Request samples

Payload

Content type

application/json

{"tag": "string",
"name": "string",
"metadata": { }
}

Response samples

201
400

Content type

application/json

{"name": "string",
"metadata": { },
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"createdAt": "string"
}

Get group

path Parameters

groupId

required

string <uuid>

Group ID.

header Parameters

X-RequestID

string

Request header label.

Responses

Response Schema: application/json

name	string Group to create name.
	object A free-form object containing group's extended attributes.
id	string <uuid> Group ID.
createdAt	string Group creation date.

Response Schema: application/json

statusCode	integer Status code.
type	string Error type.
msg	string Error message.
	object A free-form object containing group's extended attributes.

Response Schema: application/json

statusCode	integer Status code.
type	string Error type.
msg	string Error message.
	object A free-form object containing group's extended attributes.

Response samples

200
400
404

Content type

application/json

{"name": "string",
"metadata": { },
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"createdAt": "string"
}

Update group

path Parameters

groupId

required

string <uuid>

Group ID.

header Parameters

X-RequestID

string

Request header label.

Request Body schema: application/json

Request body for the group to update.

tag	string Session identificator.
name required	string Group to create name.
required	object A free-form object containing group's extended attributes.

Responses

Response Schema: application/json

statusCode	integer Status code.
type	string Error type.
msg	string Error message.
	object A free-form object containing group's extended attributes.

Response Schema: application/json

statusCode	integer Status code.
type	string Error type.
msg	string Error message.
	object A free-form object containing group's extended attributes.

Request samples

Payload

Content type

application/json

{"tag": "string",
"name": "string",
"metadata": { }
}

Response samples

400
404

Content type

application/json

{"statusCode": 0,
"type": "string",
"msg": "string",
"metadata": { }
}

Delete group

path Parameters

groupId

required

string <uuid>

Group ID.

header Parameters

X-RequestID

string

Request header label.

Responses

Response Schema: application/json

statusCode	integer Status code.
type	string Error type.
msg	string Error message.
	object A free-form object containing group's extended attributes.

Response samples

404

Content type

application/json

{"statusCode": 0,
"type": "string",
"msg": "string",
"metadata": { }
}

Get group persons

path Parameters

groupId

required

string <uuid>

Group ID.

query Parameters

page	integer Default: 1 The page number to get a list of persons or groups.
size	integer Default: 1000 The page size with a list of persons or groups, items.

header Parameters

X-RequestID

string

Request header label.

Responses

Response Schema: application/json

	Array of objects (Person)
page	integer Current page number.
totalPages	integer Total number of pages.

Response Schema: application/json

statusCode	integer Status code.
type	string Error type.
msg	string Error message.
	object A free-form object containing group's extended attributes.

Response Schema: application/json

statusCode	integer Status code.
type	string Error type.
msg	string Error message.
	object A free-form object containing group's extended attributes.

Response samples

200
400
404

Content type

application/json

{"items": [{"name": "string",
"externalId": "string",
"metadata": { },
"groups": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"ttl": null,
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"createdAt": "string",
"updatedAt": "string"
}
],
"page": 1,
"totalPages": 2
}

Add/remove persons to group

path Parameters

groupId

required

string <uuid>

Group ID.

header Parameters

X-RequestID

string

Request header label.

Request Body schema: application/json

Request body for person IDs to add or remove.

addItems	Array of strings <uuid> Add items.
removeItems	Array of strings <uuid> Remove items.

Responses

Response Schema: application/json

statusCode	integer Status code.
type	string Error type.
msg	string Error message.
	object A free-form object containing group's extended attributes.

Response Schema: application/json

statusCode	integer Status code.
type	string Error type.
msg	string Error message.
	object A free-form object containing group's extended attributes.

Request samples

Payload

Content type

application/json

{"addItems": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"removeItems": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}

Response samples

400
404

Content type

application/json

{"statusCode": 0,
"type": "string",
"msg": "string",
"metadata": { }
}

search

Find person by image in groups

header Parameters

X-RequestID

string

Request header label.

Request Body schema: application/json

	object If a person is not found, a new person entry is created using the descriptor calculated while searching.
groupIds	Array of strings <uuid> IDs of the groups in which the search is performed.
	object (FilterSearchRequest) Allows to filter the search results based on the Person's `name`. If enabled, only the search results that meet the filter condition will be returned.
tag	string Session identificator, should be unique for each session.
	object Uploaded image.
	object (OutputImageParams) Allows to process the uploaded image according to the indicated settings.
detectAll	boolean (detectAll) Default: false Whether to detect all faces in the image. If set to `false`, only the most central face is detected.
threshold	number <float> The similarity threshold.
limit	integer The maximum number of results to be returned.

Responses

Response Schema: application/json

code	integer Result code. It is returned only with response 200.
	Array of objects (SearchPerson) Array of Person images. It is returned only with response 200.
id	string or null <uuid> Person ID. The list of persons is sorted by decreasing ID value.
createdAt	string or null Person creation date.
updatedAt	string or null Person update date.
groups	Array of strings or null <uuid> List of groups this person belongs to.
name	string or null Person's name.
	object A free-form object containing person's extended attributes. Available when a person is being created

Response Schema: application/json

code	integer Result code. It is returned only with response 200.
	Array of objects (SearchPerson) Array of Person images. It is returned only with response 200.
id	string or null <uuid> Person ID. The list of persons is sorted by decreasing ID value.
createdAt	string or null Person creation date.
updatedAt	string or null Person update date.
groups	Array of strings or null <uuid> List of groups this person belongs to.
name	string or null Person's name.
	object A free-form object containing person's extended attributes. Available when a person is being created

Response Schema: application/json

msg	string Default: "Descriptor already calculated"
statusCode	integer Default: 400
type	string Default: "BadParamsException"

Request samples

Payload

Content type

application/json

{"createPerson": {"name": "string",
"metadata": { },
"ttl": null
},
"groupIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"filter": {"op": "in",
"field": "string",
"value": ["string"
]
},
"tag": "string",
"image": {"contentType": "string",
"content": "string",
"imageUrl": "string",
"resizeOptions": {"width": 0,
"height": 0,
"quality": 100
}
},
"outputImageParams": {"backgroundColor": [128,
128,
128
],
"crop": {"type": 0,
"padColor": [128,
128,
128
],
"size": [300,
400
],
"returnOriginalRect": true
}
},
"detectAll": false,
"threshold": 0,
"limit": 0
}

Response samples

200
201
400

Content type

application/json

{"code": 0,
"persons": [{"name": "string",
"externalId": "string",
"metadata": { },
"groups": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"ttl": null,
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"createdAt": "string",
"updatedAt": "string",
"detection": {"code": 0,
"crop": "string",
"detectorType": 0,
"hash": "string",
"idx": 0,
"image": "string",
"landmarks": [["x",
"y"
]
],
"landmarksType": 2,
"msg": "string",
"roi": ["x",
"y",
"width",
"height"
],
"versionSDK": "5.2.245.687"
},
"images": [{"id": "string",
"contentType": "string",
"createdAt": "string",
"updatedAt": "string",
"path": "string",
"url": "string",
"metadata": { },
"similarity": 0,
"distance": 0
}
]
}
],
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"createdAt": "string",
"updatedAt": "string",
"groups": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"name": "string",
"metadata": { }
}

liveness 2.0

liveness check

To verify the presence of a real person in front of a camera, use the GET /api/v2/liveness endpoint. When starting, you can specify tag which all attempts to read liveness will be bound to. If left unspecified, the application automatically generates one. The calling application returns tag and transactionId. One session may include many transactions, and from a transaction ID it is clear which session it belongs to.

When specifying tag, note that only Latin uppercase and lowercase letters, digits, and symbols - and _ are allowed. The maximum supported number of characters is 127.

The metadata (device model, screen data, frame size, app ID and version, OS version, platform, SDK version, etc.), a person's selfie and video of the liveness detection session are stored on the backend at: faceapi-session/year={year}/month={month}/day={day}/hour={hour}/minute={minute}/{tag}/transactionId

By default, liveness checks operate with eventual consistency. This means that when you submit a request and receive a response, the associated data (like the selfie and session video) may be saved after the response is sent. If this doesn't meet your requirements, you can switch to strong consistency; refer to the Architecture page for details.

To access the liveness transaction data, use GET /api/v2/liveness?transactionId={transactionId}.

query Parameters

transactionId

required

string <uuid>

ID of the current liveness transaction.

Responses

Response Schema: application/json

code	integer Result code, see the FaceSDKResultCode enum.
status	integer Default: null Whether the liveness detection is confirmed `0` or not `1`.
tag	string Session identificator, should be unique for each session.
transactionId	string Transaction ID, there can be several transactions within one session.
video	string Link to the session video, depends on the selected storage type. Learn more
	Array of objects Approximate age with an accuracy of +/-3 years.
portrait	string Link to the portrait, depends on the selected storage type. Learn more
	object A free-form object containing person's extended attributes.
type	integer (LivenessType) Default: 0 Enum: 0 1 Liveness detection can be performed in two modes: active `0` and passive `1`. Learn more

Response samples

200

Content type

application/json

{"code": 0,
"status": null,
"tag": "string",
"transactionId": "string",
"video": "string",
"age": [{ }
],
"portrait": "string",
"metadata": { },
"type": 0
}

diagnostics

Checking the license status

header Parameters

X-RequestID

string

Request header label.

Responses

Response Schema: application/json

property name*

additional property

any

Response Schema: application/json

property name*

additional property

any

Response samples

200
400

Content type

application/json

{ }