NAV Navbar
Logo

Face Search

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 "faceImage=@/Users/lby/Desktop/faceImage.jpg" \
-F "idNumber=******" \
-F "referId=332093" \
-F "imageType=PHOTO_FACE" \


"https://ph-api.advance.ai/ph/openapi/face-identity/v1/face-search"

Request URL

https://ph-api.advance.ai/ph/openapi/face-identity/v1/face-search
POST (multipart/form-data)

Notes:

Request Header Parameters:

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

Request Parameters:

Parameter Description
faceImage file Image of the person
referId string transaction reference id in merchant’s database, should be a unique id, such as order id or reference id. The max length is 48
idNumber string the id number of the person, number only, no negative number allowed, no float number allowed
imageType string the type of image should be PHOTO_FACE, otherwise we will returnPARAMETER_ERROR

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

Example of Successful Response:

{
    "code":"SUCCESS",
    "transactionId": "196eb0c777789e58",
    "pricingStrategy": "PAY",
    "message":"OK",
    "data":{
       "result":[
                        {
                            "referId":"332090",
                            "idNumber":"************",
                            "similarity":89.0
                        },
                        {
                            "referId":"332091",
                            "idNumber":"************",
                            "similarity":88.0
                        }
                    ],
        "imageId":"FACE_SEARCH-eb6ce0ae6b33a6b6_20190107144540742_9103533175.jpg"
    }

}

no hit

{
    "code":"SUCCESS",
    "transactionId": "196eb0c777789e58",
    "pricingStrategy": "PAY",
    "message":"OK",
    "data":{
       "result":[],
        "imageId":"FACE_SEARCH-eb6ce0ae6b33a6b6_20190107144540742_9103533175.jpg"
    },
    "extra": null

}

Example of Face Search Time Out Response:


{
  "message": "Face search timeout, please retry later",
  "data": null,
  "extra": null,
  "code": "FACE_SEARCH_TIMEOUT",
  "transactionId": "196eb0c777789e58",
  "pricingStrategy": "FREE"
}

Example of No Face Detected Response:

{
    "code":"NO_FACE_DETECTED",
    "message":"No Face detected from the uploaded pictures",
    "data":{
        "result":null,
        "imageId":null
    },
    "extra":null,
    "transactionId":"73e46a361437bf7e",
    "pricingStrategy":"PAY"
}

Example of Invalid Id Number(length > 50) Response:

{
  "message": "ID number format invalid",
  "data": null,
  "extra": null,
  "code": "PARAMETER_ERROR",
  "transactionId": "196eb0c777789e58",
  "pricingStrategy": "FREE"
}

Example of Refer Id(length > 30) Response:

{
  "message": "Refer id invalid",
  "data": null,
  "extra": null,
  "code": "PARAMETER_ERROR",
  "transactionId": "196eb0c777789e58",
  "pricingStrategy": "FREE"
}

Example of Parameter Error Response:

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

{
  "message": "Invalid image format, image format should be one of jpeg/jpg/png, and request content type should be image/jpeg or image/png",
  "data": null,
  "extra": null,
  "code": "PARAMETER_ERROR",
  "transactionId": "196eb0c777789e58",
  "pricingStrategy": "FREE"
}

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


{
    "code":"PARAMETER_ERROR",
    "message":"Parameter error,please check your request whether has illegal parameters",
    "data":null,
    "extra":null,
    "transactionId":"f6e202745c3ede67",
    "pricingStrategy":"FREE"
}

Response Description:

Parameter Description
code Face Search 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 result : the list of the result details,click here for the breakdown of this JSON object
imageId : the image identifier of our system
extra Extra response info (Exception Message)

Result Detail:

Field Name Description
referId string the transaction reference id that you use as a parameter
similarity float Face similarity rate between the 2 pictures, the rate value is always between number 0-100, a rate closer to 100 indicates a higher similarity between the two faces
idNumber string Id number of the people with faces similar to the photo uploaded, with different id numbers from the one inputted

Response Code

Status Code Message
PARAMETER_ERROR free the detail of parameter error info will be here
FACE_SEARCH_TIMEOUT free Face search timeout, please retry later
NO_FACE_DETECTED pay No Face detected from the uploaded pictures

Note: Please remember to add a handler for these 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:

Code Sample

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

Request Url

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

Notes:

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

Notes:

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:

Request URL & Parameters

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

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