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.
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:
faceIndex: 0
, imageIndex: 0
faceIndex: 1
, imageIndex: 0
faceIndex: 0
, imageIndex: 1
faceIndex: 1
, imageIndex: 1
X-RequestID | string Request header label. |
tag | string Session identificator, should be unique for each session. |
thumbnails | any Deprecated Use |
required | Array of objects (MatchImage) All images included in the comparison. |
object Whether to process the uploaded image according to the indicated settings. |
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. |
{- "tag": "string",
- "thumbnails": null,
- "images": [
- {
- "index": 0,
- "type": 1,
- "data": "string",
- "detectAll": false
}
], - "outputImageParams": {
- "backgroundColor": null,
- "crop": {
- "padColor": null,
- "returnOriginalRect": null,
- "size": null,
- "type": 0
}
}
}
{- "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": { }
}
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.
X-RequestID | string Request header label. |
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. |
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. |
{- "tag": "string",
- "images": [
- {
- "content": "string",
- "type": 1
}
], - "groupIds": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}
{- "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",
- "metadata": { },
- "groups": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "createdAt": "string",
- "updatedAt": "string"
}
]
}
], - "imageIndex": 0,
- "status": 0
}
]
}
Detect face, evaluate attributes, assess the portrait quality
X-RequestID | string Request header label. |
tag | string Session identificator, should be unique for each session. |
object (ProcessParam) The processing parameters. | |
image | string <byte> (ImageData) Base64-encoded image. |
thumbnails | boolean Default: false Deprecated, use the |
code required | integer (FaceSDKResultCode) Enum: 0 1 2 3 4 … 36 more The result code, see the FaceSDKResultCode enum. |
object (DetectResult) |
{- "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
}
{- "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
}
}
X-RequestID | string Request header label. |
name required | 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. |
name required | 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. |
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. |
statusCode | integer Status code. |
type | string Error type. |
msg | string Error message. |
object A free-form object containing group's extended attributes. |
{- "name": "string",
- "metadata": { },
- "groups": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}
{- "name": "string",
- "metadata": { },
- "groups": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "createdAt": "string",
- "updatedAt": "string"
}
personId required | string <uuid> Person ID. |
X-RequestID | string Request header label. |
name required | 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. |
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. |
statusCode | integer Status code. |
type | string Error type. |
msg | string Error message. |
object A free-form object containing group's extended attributes. |
statusCode | integer Status code. |
type | string Error type. |
msg | string Error message. |
object A free-form object containing group's extended attributes. |
{- "name": "string",
- "metadata": { },
- "groups": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "createdAt": "string",
- "updatedAt": "string"
}
personId required | string <uuid> Person ID. |
X-RequestID | string Request header label. |
Request body for the Person to update.
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. |
statusCode | integer Status code. |
type | string Error type. |
msg | string Error message. |
object A free-form object containing group's extended attributes. |
statusCode | integer Status code. |
type | string Error type. |
msg | string Error message. |
object A free-form object containing group's extended attributes. |
{- "name": "string",
- "metadata": { },
- "groups": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}
{- "statusCode": 0,
- "type": "string",
- "msg": "string",
- "metadata": { }
}
personId required | string <uuid> Person ID. |
X-RequestID | string Request header label. |
statusCode | integer Status code. |
type | string Error type. |
msg | string Error message. |
object A free-form object containing group's extended attributes. |
statusCode | integer Status code. |
type | string Error type. |
msg | string Error message. |
object A free-form object containing group's extended attributes. |
{- "statusCode": 0,
- "type": "string",
- "msg": "string",
- "metadata": { }
}
personId required | string <uuid> Person ID. |
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. |
X-RequestID | string Request header label. |
page | integer Current page number. |
totalPages | integer Total number of pages. |
Array of objects (Image) |
statusCode | integer Status code. |
type | string Error type. |
msg | string Error message. |
object A free-form object containing group's extended attributes. |
statusCode | integer Status code. |
type | string Error type. |
msg | string Error message. |
object A free-form object containing group's extended attributes. |
{- "page": 1,
- "totalPages": 2,
- "items": [
- {
- "id": "string",
- "contentType": "string",
- "createdAt": "string",
- "updatedAt": "string",
- "path": "string",
- "url": "string",
- "metadata": { }
}
]
}
personId required | string <uuid> Person ID. |
X-RequestID | string Request header label. |
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. |
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. |
statusCode | integer Status code. |
type | string Error type. |
msg | string Error message. |
object A free-form object containing group's extended attributes. |
statusCode | integer Status code. |
type | string Error type. |
msg | string Error message. |
object A free-form object containing group's extended attributes. |
{- "tag": "string",
- "image": {
- "contentType": "string",
- "content": "string",
- "imageUrl": "string",
- "resizeOptions": {
- "width": 0,
- "height": 0,
- "quality": 100
}
}, - "threshold": 0,
- "limit": 0
}
{- "id": "string",
- "contentType": "string",
- "createdAt": "string",
- "path": "string",
- "url": "string",
- "metadata": { }
}
personId required | string <uuid> Person ID. |
imageId required | string Image ID. |
X-RequestID | string Request header label. |
statusCode | integer Status code. |
type | string Error type. |
msg | string Error message. |
object A free-form object containing group's extended attributes. |
statusCode | integer Status code. |
type | string Error type. |
msg | string Error message. |
object A free-form object containing group's extended attributes. |
{- "statusCode": 0,
- "type": "string",
- "msg": "string",
- "metadata": { }
}
personId required | string <uuid> Person ID. |
imageId required | string Image ID. |
X-RequestID | string Request header label. |
statusCode | integer Status code. |
type | string Error type. |
msg | string Error message. |
object A free-form object containing group's extended attributes. |
statusCode | integer Status code. |
type | string Error type. |
msg | string Error message. |
object A free-form object containing group's extended attributes. |
{- "statusCode": 0,
- "type": "string",
- "msg": "string",
- "metadata": { }
}
personId required | string <uuid> Person ID. |
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. |
X-RequestID | string Request header label. |
Array of objects (Group) Array of Groups that are found during the search. | |
page | integer Current page number. |
totalPages | integer Total number of pages. |
statusCode | integer Status code. |
type | string Error type. |
msg | string Error message. |
object A free-form object containing group's extended attributes. |
statusCode | integer Status code. |
type | string Error type. |
msg | string Error message. |
object A free-form object containing group's extended attributes. |
{- "items": [
- {
- "name": "string",
- "metadata": { },
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "createdAt": "string"
}
], - "page": 1,
- "totalPages": 2
}
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. |
X-RequestID | string Request header label. |
Array of objects (Group) Array of Groups that are found during the search. | |
page | integer Current page number. |
totalPages | integer Total number of pages. |
statusCode | integer Status code. |
type | string Error type. |
msg | string Error message. |
object A free-form object containing group's extended attributes. |
{- "items": [
- {
- "name": "string",
- "metadata": { },
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "createdAt": "string"
}
], - "page": 1,
- "totalPages": 2
}
X-RequestID | string Request header label. |
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. |
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. |
statusCode | integer Status code. |
type | string Error type. |
msg | string Error message. |
object A free-form object containing group's extended attributes. |
{- "tag": "string",
- "name": "string",
- "metadata": { }
}
{- "name": "string",
- "metadata": { },
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "createdAt": "string"
}
groupId required | string <uuid> Group ID. |
X-RequestID | string Request header label. |
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. |
statusCode | integer Status code. |
type | string Error type. |
msg | string Error message. |
object A free-form object containing group's extended attributes. |
statusCode | integer Status code. |
type | string Error type. |
msg | string Error message. |
object A free-form object containing group's extended attributes. |
{- "name": "string",
- "metadata": { },
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "createdAt": "string"
}
groupId required | string <uuid> Group ID. |
X-RequestID | string Request header label. |
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. |
statusCode | integer Status code. |
type | string Error type. |
msg | string Error message. |
object A free-form object containing group's extended attributes. |
statusCode | integer Status code. |
type | string Error type. |
msg | string Error message. |
object A free-form object containing group's extended attributes. |
{- "tag": "string",
- "name": "string",
- "metadata": { }
}
{- "statusCode": 0,
- "type": "string",
- "msg": "string",
- "metadata": { }
}
groupId required | string <uuid> Group ID. |
X-RequestID | string Request header label. |
statusCode | integer Status code. |
type | string Error type. |
msg | string Error message. |
object A free-form object containing group's extended attributes. |
{- "statusCode": 0,
- "type": "string",
- "msg": "string",
- "metadata": { }
}
groupId required | string <uuid> Group ID. |
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. |
X-RequestID | string Request header label. |
Array of objects (Person) | |
page | integer Current page number. |
totalPages | integer Total number of pages. |
statusCode | integer Status code. |
type | string Error type. |
msg | string Error message. |
object A free-form object containing group's extended attributes. |
statusCode | integer Status code. |
type | string Error type. |
msg | string Error message. |
object A free-form object containing group's extended attributes. |
{- "items": [
- {
- "name": "string",
- "metadata": { },
- "groups": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "createdAt": "string",
- "updatedAt": "string"
}
], - "page": 1,
- "totalPages": 2
}
groupId required | string <uuid> Group ID. |
X-RequestID | string Request header label. |
Request body for person IDs to add or remove.
addItems | Array of strings <uuid> Add items. |
removeItems | Array of strings <uuid> Remove items. |
statusCode | integer Status code. |
type | string Error type. |
msg | string Error message. |
object A free-form object containing group's extended attributes. |
statusCode | integer Status code. |
type | string Error type. |
msg | string Error message. |
object A free-form object containing group's extended attributes. |
{- "addItems": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "removeItems": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}
{- "statusCode": 0,
- "type": "string",
- "msg": "string",
- "metadata": { }
}
X-RequestID | string Request header label. |
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. |
tag | string Session identificator, should be unique for each session. |
object Uploaded image. | |
object (OutputImageParams) Whether 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 |
threshold | number <float> The similarity threshold. |
limit | integer The maximum number of results to be returned. |
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 |
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 |
msg | string Default: "Descriptor already calculated" |
statusCode | integer Default: 400 |
type | string Default: "BadParamsException" |
{- "createPerson": {
- "name": "string",
- "metadata": { }
}, - "groupIds": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "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
}
{- "code": 0,
- "persons": [
- {
- "name": "string",
- "metadata": { },
- "groups": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "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": { }
}
transactionId required | string <uuid> ID of the current liveness transaction. |
code | integer Result code, one of the FaceSDKResultCode enum values. See the enum: https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/face-sdk-result-code/ |
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. |
{- "code": 0,
- "status": null,
- "tag": "string",
- "transactionId": "string",
- "video": "string",
- "age": [
- { }
], - "portrait": "string",
- "metadata": { }
}