Face Comparison

Note : Please first check the Glossary for basic information about ADVANCE API.

Code Sample

curl -X POST \
-H "X-ACCESS-TOKEN: {Your Access Token}" \
-H "Content-Type: multipart/form-data" \
-F "firstImage=@/Users/lby/Desktop/firstImage.jpg" \
-F "secondImage=@/Users/lby/Desktop/secondImage.jpg" \
"https://api.advance.ai/openapi/face-recognition/v4/check"

Request URL

https://api.advance.ai/openapi/face-recognition/v4/check
POST (form-data)

Request Header Parameters:

Parameter	Description
X-ACCESS-TOKEN	`string` Please Click here to get your access token

Request Parameters:

Parameter	Description
firstImage	`file` the first picture to be uploaded
secondImage	`file` the second picture to be uploaded

Note: Please check the image quality requirements in the Glossary to ensure that Face Comparison would work properly.

Added support for flip angle photos. Supported flip angles include: 90°, 180°, 270°. If the image is flipped, it will have a certain impact on the accuracy.
If there are multiple faces in the photo, the largest face will be selected for comparison.

Example of Success Response:

{
    "code":"SUCCESS",
    "transactionId": "196eb0c777789e58",
    "pricingStrategy": "PAY",
    "message":"OK",
    "data":{
        "similarity":69.0,
        "firstFace":{
            "id":"1",
            "left":618.0,
            "top":227.0,
            "right":715.0,
            "bottom":350.0
        },
        "secondFace":{
            "id":"2",
            "left":316.0,
            "top":552.0,
            "right":894.0,
            "bottom":1321.0
        }
    },
    "extra":null
}

Example of No Face Detected Response:

    {
        "code": "NO_FACE_DETECTED_FROM_FIRST_IMAGE",
        "message": "No Face detected from the uploaded first picture",
        "data": null,
        "extra": null,
        "transactionId": "7196eb0c77789e58",
        "pricingStrategy": "PAY"
    }

    {
        "code": "NO_FACE_DETECTED_FROM_SECOND_IMAGE",
        "message": "No Face detected from the uploaded second picture",
        "data": null,
        "extra": null,
        "transactionId": "8196eb0c11179e58",
        "pricingStrategy": "PAY"
    }

Example of Image Low Response:

    {
        "code": "FIRST_IMAGE_LOW_QUALITY_FACE",
        "message": "Face quality is too low of the uploaded first picture",
        "data": null,
        "extra": null,
        "transactionId": "77196eb0c7789e58",
        "pricingStrategy": "PAY"
    }

    {
        "code": "SECOND_IMAGE_LOW_QUALITY_FACE",
        "message": "Face quality is too low of the uploaded second picture",
        "data": null,
        "extra": null,
        "transactionId": "179e588196eb0c11",
        "pricingStrategy": "PAY"
    }

Example of Failed Request / Error Response:

{
  "message": "Invalid image size, max image size should be less than 2M, and image dimension should be between 256 * 256 and 4096 * 4096",
  "data": null,
  "extra": null,
  "code": "IMAGE_INVALID_SIZE",
  "transactionId": "196eb0c777789e58",
  "pricingStrategy": "FREE"
}

Response Description:

Parameter	Description
code	Face Comparison Status Code
transactionId	the request id, the max length is 64
pricingStrategy	whether the request will be charged, enum type: `FREE`, `PAY`
message	Status Code Explanation
data	`similarity` : Face similarity rate between the 2 uploaded pictures,the rate value is always between the number 0-100, a rate closer to 100 indicates a higher similarity between the two faces. Please refer to the Note below of given suggestions based on different similarities.
	`firstFace` : the face in the first picture, please click here for the breakdown of this JSON object
	`secondFace` : the face in the second picture,please click here for the breakdown of this JSON object
extra	Extra response info (Exception Message)

Note:

If the faces similarity is more than 70, the suggestion is pass.
If the faces similarity is from 55 to 70, the suggestion is manual check.
If the faces similarity is less than 55，the suggestion is rejection or using other methods to verify the user’s identity.

Response Object Breakdown:

Face Position:

Field Name	Description
id	`string` an identifier for the face in the picture.
left	`float` the pixel size from the left edge of the picture.
top	`float` the pixel size from the top edge of the picture.
right	`float` the pixel size from the right edge of the picture.
bottom	`float` the pixel size from the bottom edge of the picture.

Response Code

Status Code	Message
`IMAGE_INVALID_FORMAT`	`free` Invalid image format, image format should be one of jpeg/jpg/png, and request content type should be image/jpeg or image/png
`IMAGE_INVALID_SIZE`	`free` Invalid image size, max image size should be less than 2M, and image dimension should be between 256 * 256 and 4096 * 4096
`NO_FACE_DETECTED_FROM_FIRST_IMAGE`	`pay` No Face detected from the uploaded first picture
`NO_FACE_DETECTED_FROM_SECOND_IMAGE`	`pay` No Face detected from the uploaded second picture
`FIRST_IMAGE_LOW_QUALITY_FACE`	`pay` Face quality is too low of the uploaded first picture
`SECOND_IMAGE_LOW_QUALITY_FACE`	`pay` Face quality is too low of the uploaded second picture

Note: Please remember to add a handler for the Status Codes in the Glossary as well

Token Authentication

Request Parameters:

Parameter	Description
accessKey	`string` the accessKey
timestamp	`string` 13-digit-long timestamp, suggested 300 seconds before or after the current time when requesting the token
signature	`string` Combined accessKey, secretKey and timestamp, encrypted by SHA256. eg. accessKey: sampleaccesskey secretKey: samplesecretkey timestamp: 1665993522952 Combined: sampleaccesskeysamplesecretkey1665993522952 Encrypted based on the combined: 02209bbeaf0d0a3dd587f6a1ba22f84c98d142e3b545e77db7e4906ca56349f5
periodSecond	`string` `optional` Validity period defaults to 3600 seconds, minimum 60 seconds, maximum 86400 seconds. Unit is seconds

Note:

You can find accessKey, secretKey on the Websaas Platform -> Account -> Account Management
The timestamp in the “signature” must be consistent with parameter timestamp
Please remember to re-obtain a new valid token to do the authentication for the open APIs when the previous one is expired

Code Sample

curl -X POST \
-H "Content-Type: application/json" \
-d '{"accessKey":"22********70b","signature":"f786441e7b3d95f*****************853a5a244f9522","timestamp":1648785145789,"periodSecond":120}' \ 
"https://api.advance.ai/openapi/auth/ticket/v1/generate-token"

Request Url

https://api.advance.ai/openapi/auth/ticket/v1/generate-token
POST (application/json)

Example of Success Response:

{
    "code":"SUCCESS",
    "message":"OK",
    "data":{
    "token":"eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJoNV9saXZlbmVzcyIsInN1YiI6IntcImN1c3RvbWVySWRcIjo1NTAwMDI4MixcImFjY291bnRJZFwiOjU1MDAwMjg0LFwicmVhbElwXCI6XCI0NS4yNTEuMTA3LjExMVwifSIsImF1ZCI6IldFQiIsImlhdCI6MTY0MjU4MDA3MiwiZXhwIjoxNjQyNTgwMTkyfQ.HmIDcuSW67A59x7bnumjGp0Wdcz-FmoDrnHF1YGui6wVPfulLn4Izonay5LQnySgph1dbyC1E0LtifS-BJo8VA",
    "expiredTime":1642580192430
    },
    "extra":null,
    "transactionId":"6c2c50a3049ce67e",
    "pricingStrategy":"FREE"
}

Example of PARAMETER_ERROR Response:

{
    "code":"PARAMETER_ERROR",
    "message":"Parameter should not be empty",
    "data":null,
    "extra":null,
    "transactionId":"040e769e38f87e3e",
    "pricingStrategy":"FREE"
 }

{
    "code":"PARAMETER_ERROR",
    "message":"Timestamp error",
    "data":null,
    "extra":null,
    "transactionId":"a9c2a6c199ad5db5",
    "pricingStrategy":"FREE"
}

{
    "code":"PARAMETER_ERROR",
    "message":"Signature error",
    "data":null,
    "extra":null,
    "transactionId":"00b05cb9cf6f0fed",
    "pricingStrategy":"FREE"
}

Example of ACCOUNT_DISABLED Response:

{
    "code":"ACCOUNT_DISABLED",
    "message":"Account Disabled",
    "data":null,
    "extra":null,
    "transactionId":"5e00fded1272490e",
    "pricingStrategy":"FREE"
}

Example of CLIENT_ERROR Response:

{
    "code":"CLIENT_ERROR",
    "message":"HTTP 400 - Bad Request",
    "data":null,
    "extra":null,
    "transactionId":"bd5d5653c45d4c6e",
    "pricingStrategy":"FREE"
 }

Response Description:

Parameter	Description
`code`	Response Status Code
`message`	Message returned from server
`data`	`token` AccessToken
	`expiredTime` Expiration timestamp
`extra`	Extra response info such as exception message
`transactionId`	the request id, the max length is 64
`pricingStrategy`	whether the request will be charged, enum type: `FREE`, `PAY`

Response Code

Status Code	Message
`SUCCESS`	`free` OK
`PARAMETER_ERROR`	`free` Parameter should not be empty
	`free` Timestamp error
	`free` Signature error
`ACCOUNT_DISABLED`	`free` Account Disabled
`CLIENT_ERROR`	`free` HTTP 400 - Bad Request

Glossary

Welcome to the Glossary!

Please read the following to understand how ADVANCE API system, for a smooth integration. We will explain all the basics you need to know about our API.

Status Code

Our API responses will contain a Status Code indicating the result of the API call, whether it was successful, or an error occurred during the process
Each API will also have its own unique Status Codes that can only be found in the responses of the API
Your API usage will be charged based on the response Status Code, each Status Code listed in our API document will have either a free or pay tag with it
free means you will not be charged and paymeans that you will be charged
pay means you will be charged if the API response contains the said status code
Below are the commonly used Status Codes, these status codes could appear in all our API responses, so please remember to add a handler for these Status Codes

Notes:

Please use ‘Status Code’ in your strategy instead of ‘Message’, as 'Message’ is a detailed explanation for developer’s reference and may update without ADVANCE Notice.

Status Code	Message
`SUCCESS`	`pay` OK
`ERROR`	`free` Server error
`EMPTY_PARAMETER_ERROR`	`free` Parameter should not be empty
`INSUFFICIENT_BALANCE`	`free` Insufficient balance, please top up or contact your sales manager for help
`SERVICE_BUSY`	`free` Messages may look like: Rate limit is exceeded, please retry after the suggested time in HTTP Header. Retry-After :10s p.s. Please also note that this code may migrate to HTTP 429 Too Many Requests in the future. Quota exceeded: You have exceeded the daily quota for free queries, please contact out tech support for help
`IAM_FAILED`	`free` Access denied. Messages may look like: You are not authorized by the Identity and Access Management system Access Key not found Token not found or expired Access Key not found or expired Account not authorized for this country Account not authorized for this domain Account is expired. Please contact your sales manager for help Account is disabled. Please contact your sales manager for help Access denied: Token not found or expired
`PARAMETER_ERROR`	`free` The message is detailed error description, may includes: Parameter should not be empty Invalid phone number, please check your phone number format etc. p.s. Mobile number format should be country code + phone number(without leading 0 or dash or space e.g. +xx12345678); fixed-line number should be country code + area code + number(without leading 0)
`OVER_QUERY_LIMIT`	`free` Messages may look like: Quota exceeded. you have exceeded free query quota, please contact your sales manager for help Quota exceeded: You have exceeded free query quota for test account, please contact your sales manager for help
`CLIENT_ERROR`	`free` HTTP client error. Messages may look like: HTTP 400 - Bad Request HTTP 404 - Not Found HTTP 405 - Method Not Allowed etc. If you get this error, please check the API document or contact our tech support for help.
`RETRY_LATER`	`free` Query failed, please retry after the suggested time in HTTP Header. Retry-After :10s

Notes:

If the Status Code is SUCCESS, it may not be charged. Please check the code returned by each interface

Request URL & Parameters

Request URL can be found at each API document along with the request method (POST or GET or other request method) and Content Type (application/json or other content type)
Some parameters will have optional tag on them, this means the parameter is not mandatory for the request and they can be empty, however adding them might produce more accurate result, for example : Company check, zip code is an optional parameter but adding zip code parameter will return all the companies around that said zip code instead of all around Indonesia.
If a parameter does not have an optional tag, it means the parameter is mandatory and making request without them will return EMPTY_PARAMETER_ERROR response
Every parameter has a data type such as string, integer and file, please double check the parameter data type before making any request
Here’s an example of parameter explanation that can be found on each API document

Parameter	Description
requestString	`string` String value for API request
requestFile	`file` Request file for API request
requestInteger	`optional` `integer` Number value for API request

Response

ADVANCE API responds in JSON format
ADVANCE API response consists of 4 fields:
- code the Status Code;
- message detailed explanation of the Status Code;
- extra an exception message (should be empty most of the time);
- data the response content from ADVANCE;
Each service has its own data format, outlined in the API document
If the response format is very complicated (multiple different JSON object, nested JSON object), please refer to the Breakdown section of the Response Explanation
transactionId: It is strongly recommended to save the transactionId.
The following is an example of Response Explanation found in each API document:

Parameter	Description
code	API Status Code
message	Status Code Explanation
data	`field1`: explanation of the first information that will be returned from ADVANCE
	`field2`: explanation of the second information that will be returned from ADVANCE
extra	Extra response info (Exception Message)

Image Quality Requirements

The services check and extract the necessary information from the uploaded images, hence please ensure the uploaded images satisfy the following criteria:
- Is in one of the following image formats: PNG / JPG / JPEG
- Below 2 MB file size
- Minimum resolution of 256 x 256
- Maximum resolution of 4096 x 4096
For OCR services please also ensure that the uploaded images satisfy the following criteria:
- ID Card’s ratio in the uploaded photo is not so small that the words in the ID Card are unreadable
- ID Card’s orientation is in Vertical or Horizontal position and NOT heavily tilted (around 45 degree)
- Nothing is covering up the words in the ID Card (ex: Light Spot, Dirt, Ink, Shadow, etc)
- Have a clean background (No words or other picture in the background)