Regula FaceSDK Web API (6.1.0)

Download OpenAPI specification

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 in all combinations

header Parameters
X-RequestID
string

Request header label.

Request Body schema: application/json
tag
string

Session identificator.

thumbnails
boolean
Deprecated
Default: false

Deprecated, use the crop field in outputImageParams instead.

required
Array of objects (MatchImage)

The array of all images included in the comparison.

object

Whether 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 … 34 more
Array of objects (MatchImageDetection)

The array of detected faces.

Array of objects (MatchImageResult)

The array of matching results.

object

A free-form object containing person's extended attributes.

Request samples

Content type
application/json
{
  • "tag": "string",
  • "thumbnails": false,
  • "images": [
    • {
      • "index": 0,
      • "type": 1,
      • "data": "string",
      • "detectAll": false
      }
    ],
  • "outputImageParams": {
    • "backgroundColor": null,
    • "crop": {
      • "padColor": null,
      • "returnOriginalRect": null,
      • "size": null,
      • "type": 0
      }
    }
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "detections": [
    • {
      • "faces": [
        • {
          • "faceIndex": 0,
          • "landmarks": [
            ],
          • "rotationAngle": 0,
          • "roi": [
            ],
          • "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": { }
}

Detect face, evaluate attributes, assess the portrait quality

header Parameters
X-RequestID
string

Request header label.

Request Body schema: application/json
tag
string

Session identificator.

object (ProcessParam)

The processing parameters.

image
string <byte> (ImageData)

Base64 encoded image.

thumbnails
boolean
Default: false

Deprecated, use the crop field in processParam instead.

Responses

Response Schema: application/json
code
required
integer (FaceSDKResultCode)
Enum: 0 1 2 3 4 … 34 more
object (DetectResult)

Request samples

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": [
            ]
          }
        ]
      },
    • "attributes": {
      • "config": [
        • {
          • "name": "Age"
          }
        ]
      }
    },
  • "image": "string",
  • "thumbnails": false
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "results": {
    • "detections": [
      • {
        • "crop": "string",
        • "attributes": {
          • "details": [
            ],
          • "elapsedTime": 0
          },
        • "landmarks": [
          • [
            ]
          ],
        • "quality": {
          • "nonCompliant": [
            ],
          • "detailsGroups": [
            ],
          • "details": [
            ],
          • "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 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
name
required
string

Person 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.

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

Content type
application/json
{
  • "name": "string",
  • "metadata": { },
  • "groups": [
    • "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ]
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "metadata": { },
  • "groups": [
    • "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
  • "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 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.

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

Content type
application/json
{
  • "name": "string",
  • "metadata": { },
  • "groups": [
    • "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
  • "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.

name
string

Person 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

Content type
application/json
{
  • "name": "string",
  • "metadata": { },
  • "groups": [
    • "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ]
}

Response samples

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

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

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

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

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

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

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

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

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

Content type
application/json
{
  • "tag": "string",
  • "name": "string",
  • "metadata": { }
}

Response samples

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

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

Content type
application/json
{
  • "tag": "string",
  • "name": "string",
  • "metadata": { }
}

Response samples

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

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

Content type
application/json
{
  • "items": [
    • {
      • "name": "string",
      • "metadata": { },
      • "groups": [
        • "497f6eca-6276-4993-bfeb-53cbbbba6f08"
        ],
      • "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

Content type
application/json
{
  • "addItems": [
    • "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
  • "removeItems": [
    • "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ]
}

Response samples

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.

tag
string

Session identificator.

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 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 name.

object or null

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 name.

object or null

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

Content type
application/json
{
  • "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
}

Response samples

Content type
application/json
{
  • "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": [
          • [
            ]
          ],
        • "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 assessment

query Parameters
transactionId
required
string <uuid>

ID of the current liveness transaction.

Responses

Response Schema: application/json
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.

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.

Response samples

Content type
application/json
{
  • "code": 0,
  • "status": null,
  • "tag": "string",
  • "transactionId": "string",
  • "video": "string",
  • "age": [
    • { }
    ],
  • "portrait": "string",
  • "metadata": { }
}

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

Content type
application/json
{ }