Auther Check

Auther CHECK API v6.0.0

The simplify is better!

We build a new generation human biometric authentication platform that is easy to integrate into existing applications, services or hardware products. We've designed an easy-to-use REST API so integration will go smoothly!
For liveness detection and anti-spoofing, we've developed Auther Embedded.

Overview

This page describes the technical requirements that must be met to start using facial recognition technology in your applications and products. Please read all the sections in detail and strictly follow the requirements specified in the documentation and your integration will go quickly and smoothly. Sign-up and get a free plan for testing!

Quick start guide

To send your first request, follow the steps below. For faster and more convenient testing, we recommend using Postman. Sign-up and get the API Key to authorize your requests.

Glossary

List of terms that are used in requests and responses:

Image requirements

The input image as base64-encoded bytes is required. For successful preparation of the Bade64-encoded image, before you sent requests, follow to the next criteria:

Image verification criteria

To successfully create a person_id, the image of the person you submit for enrollment will be verified for compliance with the following criteria:

Requests

All API requests must be sent in JSON format with the header:

Key
Content-Type
Api-Key
Value
application/json
api_key
Content-Type: application/json
Api-Key: api_key

{  
   "code": "F_001",   
   "type": "string",  
   "message": "string"
}

Authorization

Every request sent must be authenticated using the API Key. It should be sent in an HTTP header. You can create and manage your API Keys in the back-office. To get the API Key, you need to Sign-up and get a free plan for testing.

Required credentials

api_key

Base URL

https://api.auther.ai

Request headers

Key
Api-key
Value
api_key

Response headers

Key
Request-Id
Value
request_id

Create person

To register a person in the system, please submit a Base64-encoded image of a a person on where the person looks straight ahead and also prepare the person_id you want to assign to this person in advance. When preparing the reference image, follow the requirements described above in the Image requirements section. Download "faceImage" sample.

URL:
POST
/person/face/{person_id}

Request headers

Go to request headers

Request Body

Parameter
faceImage
Type
string
Request body

{
  "faceImage": "string"
}

Response headers

Go to response headers

Status code 200

Parameter
created
personId
updated
Type
string
string
string
200 Ok

{
"personId": "string",
"created": "2020-09-03T16:05:08.938Z",
"updated": "2020-09-04T16:05:08.938Z"
}

Status code 400

Parameter
code
message
Type
string
string
400 Bad Request

{
   "code": "string",
   "message": "string"
}

Codes and messages for response 400

Codes
F_012
F_011
F_010
F_009
F_008
F_007
F_006
F_005
F_004
F_003
F_002
F_001
CP_002
R_002
R_003
Messages
“Face exists”
“Wrong face size when image check"
“Wrong face yaw”
“Wrong face pitch”
“Wrong face roll”
“Sharpness is bad”
“Brightness is bad”
“Sunglasses exists”
“Mouth is open”
“Eyes are closed”
“Most likely face doesn’t exist”
“Should be one face”
“Customer profile already exists with id %s”
“Request body exception”
“Fields validation exception”

Status codes: 401, 403, 500

Update person

To update the data of a person in the system, please submit a Base64-encoded image of a a person on where the person looks straight ahead and also indicate the person_id of the person you want to assign new data to.
For preparing the reference image, follow the requirements described above in the Image requirements section.

URL:
PUT
/person/face/{person_id}

Request headers

Go to request headers

Request Body

Parameter
faceImage
Type
string
Request body

{
  "faceImage": "base64format_string"
}

Response headers

Go to response headers

Status code 200

Parameter
created
personId
updated
Type
string
string
string
200 Ok

{
"personId": "string",
"created": "2020-09-03T16:05:08.938Z",
"updated": "2020-09-04T16:05:08.938Z"
}

Status code 400

Parameter
code
message
Type
string
string
400 Bad request

{
   "code": "string",
   "message": "string"
}

Codes and messages for response 400

Codes
F_012
F_011
F_010
F_009
F_008
F_007
F_006
F_005
F_004
F_003
F_002
F_001
CP_002
R_002
R_003
Messages
“Face exists”
“Wrong face size when image check"
“Wrong face yaw”
“Wrong face pitch”
“Wrong face roll”
“Sharpness is bad”
“Brightness is bad”
“Sunglasses exists”
“Mouth is open”
“Eyes are closed”
“Most likely face doesn’t exist”
“Should be one face”
“Customer profile already exists with id %s”
“Request body exception”
“Fields validation exception”

HTTP Status code: 404

Parameter
code
message
Type
string
string
404 Bad request

{
   "code": "NF_001",
   "message": "Face not found in collection"
}

Codes and messages for response 404

Codes
NF_001
Messages
“Face not found in collection”

HTTP Status code: 401, 403, 500

Remove person

To remove a person's data from the system, just send the person_id parameter. The person's data will be deleted and the person_id will also be deleted.

URL:
DELETE
/person/face/{person_id}

Request headers

Go to request headers

Request Body

no parameters

Response headers

Go to response headers

HTTP Status code: 200

200 Ok


HTTP Status code: 400

Parameter
code
message
Type
string
string
400 Bad request

{
   "code": "string",
   "message": "string"
}

Codes and messages for response 400

Codes
R_002
R_003
CP_005
Messages
“Request body exception”
“Fields validation exception”
“Number of available requests exceeded”

HTTP Status code: 404

Parameter
code
message
Type
string
string
404 Bad request

{
   "code": "NF_001",
   "message": "Face not found in collection"

Codes and messages for response 404

Codes
NF_001
Messages
“Face not found in collection”

HTTP Status codes: 401, 403, 500

Get person [beta]

To check if the person_id already exist in the system, just specify the path with person_id . If the person_id exist in response you will get the same person_id and information when person was created and updated.

URL:
GET
/person/face/{person_id}

Request headers

Go to request headers

Request Body

no parameters

Response headers

Go to response headers

HTTP Status code: 200

200 Ok

{
"personId": "string",
"created": "2020-09-03T16:05:08.938Z",
"updated": "2020-09-04T16:05:08.938Z"
}

HTTP Status code: 400

Parameter
code
message
Type
string
string
400 Bad request

{
   "code": "string",
   "message": "string"
}

Codes and messages for response 400

Codes
R_002
R_003
CP_005
Messages
“Request body exception”
“Fields validation exception”
“Number of available requests exceeded”

HTTP Status code: 404

Parameter
code
message
Type
string
string
404 Bad request

{
   "code": "NF_001",
   "message": "Face not found in collection"

Codes and messages for response 404

Codes
NF_001
Messages
“Face not found in collection”

HTTP Status codes: 401, 403, 500

Identify person

Submit the Base64-encoded image. With this request, we start 1:N searching for the most similar enrolled person in our system. The search result will be person_id, which matches the searched one by 98%.
To improve the quality and speed of recognition, follow the image requirements for the submitted images. Download "faceImage" sample.

URL:
POST
/person/recognize-face

Request headers

Go to request headers

Request Body

Parameter
faceImage
Type
string
Request body

{
 "faceImage": "string"
}

Response headers

Go to response headers

HTTP Status code: 200

Parameter
created
personId
updated
Type
string
string
string
200 Ok

{
"personId": "string",
"created": "2020-09-03T16:05:08.938Z",
"updated": "2020-09-04T16:05:08.938Z"
}

HTTP Status code: 400

Parameter
code
message
Type
string
string
400 Bad request

{
   "code": "string",
   "message": "string"
}

Codes and messages for response 400

Codes
R_002
R_003
F_011
CP_005
Messages
“Request body exception”
“Fields validation exception”
“Wrong face size when image check”
“Number of available requests exceeded”

HTTP Status code: 410

Parameter
code
message
Type
string
string
410 No person matched

{
   "code": "string",
   "message": "string"
}

Codes and messages for response 410

Codes
RF_001
Messages
“No person matched”

HTTP Status codes: 401, 403, 500

Verify person [beta]

Comparison of the face of a person who declares that his face belongs to the known person_id. With this request, we start 1:1 matching for the enrolled person in our system. If the submitted person's face matches to 80% with the person's image that belongs to the declared person_id, then the verification result is successful.

URL:
POST
/person/verify-face/{person_id}

Request headers

Go to request headers

Request Body

Parameter
faceImage
Type
string
Request body

{
 "faceImage": "string"
}

Response headers

Go to response headers

HTTP Status code: 200

Parameter
personId
created
updated
Type
string
string
string
200 Ok

{
"personId": "string",
"created": "2020-09-03T16:05:08.938Z",
"updated": "2020-09-04T16:05:08.938Z"
}

HTTP Status code: 400

Parameter
code
message
Type
string
string
400 Bad request

{
   "code": "R_002",
   "message": "Request body exception"
}

Codes and messages for response 400

Codes
R_002
R_003
CP_005
Messages
“Request body exception”
“Fields validation exception”
“Number of available requests exceeded”
200 Ok

{
"personId": "string",
"created": "2020-09-03T16:05:08.938Z",
"updated": "2020-09-04T16:05:08.938Z"
}

HTTP Status code: 404

Parameter
code
message
Type
string
string
404 Bad request

{
   "code": "R_002",
   "message": "Request body exception"
}

Codes and messages for response 404

Codes
NF_001
Messages
“Face not found in collection”

HTTP Status codes: 401, 403, 500

Compare person [beta]

Compares the face on the sourceImage with the largest face detected on the targetImage.
By default, the submitted sourceImage will be compared the targetImage with the 80% of similarity threshold. If you want to compare images with a custom similarity threshold (for example, 98%), specify this number in the request body [option]. In response, you get the similarity value of the facesMatched images.

URL:
POST
/person/compare-face

Request headers

Go to request headers

Request Body

Parameter
targetImage
sourcetImage
Type
string
string
Request body

{
"targetImage": "string",
"sourceImage": "string"
}

Request Body [option]

Parameter
targetImage
sourceImage
similarityThreshold
Type
string
string
number
Request body

{
"targetImage": "string",
"sourceImage": "string",
"similarityThreshold": number
}

Response headers

Go to response headers

HTTP Status code: 200

Parameter
facesMatched
Type
number
200 Ok

{
"facesMatched": number
}

HTTP Status code: 400

Parameter
code
message
Type
string
string
400 Bad request

{
   "code": "R_002",
   "message": "Request body exception"
}

Codes and messages for response 400

Codes
R_002
R_003
CP_005
Messages
“Request body exception”
“Fields validation exception”
“Number of available requests exceeded”

HTTP Status codes: 401, 403, 500

Response status codes

The custom 200 and 400 response codes are listed in the description for each request. Common server response codes are listed below.

HTTP Status code: 200

Parameter
personId
created
updated
Type
string
string
string
200 Ok

{
"personId": "string",
"created": "2020-09-03T16:05:08.938Z",
"updated": "2020-09-04T16:05:08.938Z"
}

HTTP Status code: 400

Parameter
code
message
Type
string
string
400 Bad request

{
 "code": "string",
 "message": "string"
}

HTTP Status code: 401

Parameter
code
message
Type
string
string
401 Unauthorized

{
 "code": "string",
 "message": "string"
}

HTTP Status code: 403

Parameter
code
message
Type
string
string
403 Forbidden

{
 "code": "string",
 "message": "string"
}

HTTP Status code: 404

Parameter
code
message
Type
string
string
404 Face not found

{
 "code": "string",
 "message": "string"
}

HTTP Status code: 500

Parameter
code
message
Type
string
string
500 Internal Server Error

{
 "code": "string",
 "message": "string"
}

ENTERPRISE ONLY

Data encryption RSA-2048

This section describes how to use SHA-256 hashing and optional RSA-2048 encryption to sign requests. In this way, you can improve the security of data transmission. This option is available only for enterprise clients.

Signing with RSA-2048 [enterprise only]

This section describes how to use SHA-256 hashing and optional RSA-2048 encryption to sign requests. In this way, you can improve the security of data transmission. This option is available only for enterprise clients.

Required credentials

api_key
signing_key

Base URL

https://api.auther.ai

Request headers

Key
Api-key
Signature
Timestamp
Value
api_key
request_signature
timestamp

Response headers

Key
Request-Id
Signature
Value
request_id
response_signature

Build request signature [enterprise only]

To create a request signature using hashing and encryption, follow the step-by-step instructions below:

Verify response signature [enterprise only]

To decrypt the request signature using hashing and encryption, follow the step-by-step instructions below:

hash#1
=
hash#2

Forming line for request signature [enterprise only]

base url
+
uri
+
request_body
+
current_timestamp

Forming line for response signature [enterprise only]

base url
+
uri
+
response_body
+
current_timestamp

Have a question or wanna share your ideas?

Join Community