FaceQuest® is facial recognition software as a service. That also provides an API (Application Programming Interface) for interacting with your client application easily.
You do not need jazzy infra or AI coding skills to recognize faces in your software. FaceQuest® enables you to concentrate on building your own software, without additional investment and maintenance for high end infrastructure.
FaceQuest® does not care what programming language you use to code. As long as you can call HTTP(s) API end-points from your code, you could recognize faces from Java, JavaScript, Ruby, Scala.
For more details visit our API Docs here
If you want to integrate an API backend using Node.js and Java, we have created a sample client in github repository for Node.js and Java.
We need some basic credentials for authentication of our API’s.
Email: We require an email registered with Facequest.io
Secret: Facequest API secret key that you have set from Facequest web UI
Constant-Authorization-Token: A constant “bearer” required for all requests via API.
To call API endpoints we have used Postman or you can use a terminal or command prompt and make a curl request as per examples given in the api documentation page.
APIs for FaceQuest®’s 1:1 Face verification.
Here step by step guide is given for how to do face verification, get verification logs, track verification results through verification ID, fetch photo upload URL and file path of the photo to be verified through facequest API. To create a face verification request through API, First we need to have the file path of the photo to be uploaded for face verification, one is reference face file path and other is photo to be verified file path. We use this file path in the request we have to post from our terminal to facequest API endpoint.
We are using Postman to make all requests to the API endpoint.
How to make cURL requests using Postman?
Returns pre-signed URLs to upload reference photo and the photo to be verified. For the authentication we use email address, secret token and constant authorization token “bearer”.
Here is the sample cURL request to get upload URLs.
curl -X GET 'https://verifyapi.facequest.io/api/v1/verification/uploadurl' \
-H 'secret: secret_that_i_set_in_facequest_web_ui' \
-H 'email: email_id_registered_with_facequest' \
-H 'accept: application/json' \
-H 'authorizationtoken: bearer' \
--compressed
Example: Fetch upload URL
In this example we make curl requests through a Postman client that returns us a reference face “upload URL” and “file path” and photo to be verified “upload URL” and “file path”.
This url and file path are used to create face verification request through API. We need to pass the file path that is given in this response when creating a face verification request.
To upload photos on which we have to do face verification, first we need to upload it via our API endpoint. We already have an upload URL of photos that’s fetched from the above API endpoint response like this example.
{
"data": {
"referencePhoto": {
"uploadUrl": "https://facequest-verification-faces.s3.amazonaws.com/267c04d0-e9cf-431f-b614-e878cc781162%40gmail_com/ec5000c4-88a6-4d73-83b2-6fb97a765f15?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIARNEJIG26A2OHGS6C%2F20210125%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20210125T105249Z&X-Amz-Expires=1800&X-Amz-Signature=f811d061c4e763f84c57d30d19f34fc0b6dbe3b92ca2155285262d4d5784a4ea&X-Amz-SignedHeaders=host",
"filePath": "267c04d0-e9cf-431f-b614-e878cc781162@gmail_com/ec5000c4-18a6-4d73-83b2-6fb97a765f15"
},
"photoToBeVerified": {
"uploadUrl": "https://facequest-verification-faces.s3.amazonaws.com/267c04d0-e9cf-431f-b614-e878cc781162%40gmail_com/0aa76efd-1475-4790-8d8d-232a875ceca8?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIARNEJIG26A2OHGS6C%2F20210125%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20210125T105249Z&X-Amz-Expires=1800&X-Amz-Signature=4107f113e268221a614572fea6e3b62acc3881e509fd64ef6ae75cd14199f2a5&X-Amz-SignedHeaders=host",
"filePath": "267c04d0-e9cf-431f-b614-e878cc781162@gmail_com/0aa76efd-1475-4790-8d8d-232a875ceca1"
}
},
"errorMessage": ""
}
Example: Fetch URL API Response
Here we have the upload URL and file path of reference photo and photo to be verified. This url is useful for uploading reference photo and photo to be verified.
Example: Upload Reference Photo & Photo to be Verified
In the above given example we have to upload both reference photo and photo to be verified via PUT request through postman. Just copy the reference photo upload URL, create a PUT request and paste the URL that we copied earlier. Also, we have to send an image file(Reference Photo or Photo to be verified) with this request.
Repeat the same process for “photo to be verified”. Just copy “Photo to be verified” URL and select file then create a new PUT request with it to upload the photo.
Creates a new verification request with/without using the stored reference photo from folders. The progress of this request can be tracked asynchronously.
We just have to pass a reference photo file path and photo to be verified file path to create this request. We can copy file path response from the “Fetch upload URL” endpoint.
Sample cURL request:
curl -X POST 'https://verifyapi.facequest.io/api/v1/verification' \
-H 'secret: secret_that_i_set_in_facequest_web_ui' \
-H 'email: email_id_registered_with_facequest' \
-H 'accept: application/json' \
-H 'authorizationtoken: bearer' \
--compressed
Payload to be passed with the request: We have to pass the payload given below with the value of tile, notes, referencePhotoFilePath, photoToBeVerifiedFilePath, and useStoredPhotoForReference.
{
"title": "verify photo sample",
"notes": "sample notes",
"referencePhotoFilePath": "String",
"photoToBeVerifiedFilePath": "String",
"useStoredPhotoForReference": "false"
}
If you want to use a stored photo for reference then you just need to pass the true value in “useStoredPhotoForReference” otherwise pass false. See this example given below to create a verification request from API. This returns the “Verification Request ID” back.
Example: Create verification request
Track any verification request using verificationRequestId, returned upon invoking POST request at URL /api/v1/verification.
For the verification we just need to pass Verification Request ID to the api endpoint that we copied from the “create verification request” response.
Sample cURL request:
curl -X GET 'https://verifyapi.facequest.io/api/v1/verification/{verificationRequestId}' \
-H 'secret: secret_that_i_set_in_facequest_web_ui' \
-H 'email: email_id_registered_with_facequest' \
-H 'accept: application/json' \
-H 'authorizationtoken: bearer' \
--compressed
Example: Track verification request
This gives us the verification result back with matched percentage, title and notes.
To fetch face verification logs that you have done earlier, you only need to get data from the API endpoint as per given example.
Just paste this command in the terminal or make a curl request using Postman, that gives us all verification logs data in JSON format.
Sample cURL request:
curl -X GET 'https://verifyapi.facequest.io/api/v1/verification/logs' \
-H 'secret: secret_that_i_set_in_facequest_web_ui' \
-H 'email: email_id_registered_with_facequest' \
-H 'accept: application/json' \
-H 'authorizationtoken: bearer' \
-compressed
You just have to add your Facequest login email Id and Secret token that you have set from the Facequest UI dashboard.
Example: Fetch verification logs
In this curl request we passed email, secret and constant authorization token “bearer” in our case. In the example given below we make GET request for all verification logs through Postman.
If there is no data to show it will return an empty object back with status code 200. In case of unauthorized request it returns an “unauthorized” error message with status code 401.
To create a folder with the given name where the reference photos can be uploaded. Maximum limit of reference photos per folder is 100, we use this API given in example.
For the authorization we just need to have Email registered with Facequest.io, Secret token and Authorization token “bearer”.
sample cURL request:
curl -X POST 'https://app.facequest.io/api/v1/folders/{name}' \
-H 'secret: secret_that_i_set_in_facequest_web_ui' \
-H 'email: email_id_registered_with_facequest' \
-H 'accept: application/json' \
-H 'authorizationtoken: bearer' \
--compressed
In the above Post request, you have to pass the folder name at this api endpoint “https://app.facequest.io/api/v1/folders/{name}”. This creates a new folder with the given name. See this example given here, how to create a new folder through API.
Example: Create a new folder
After successfully creating the folder it gives us the following response back.
{
"page": {
"totalElements": 1
},
"_embedded": [
{
"id": "b55b2b9d-5b66-49ac-babc-3382d48b570c",
"user_id": "267c04d0-e9cf-431f-b614-e878cc781162",
"name": "sample",
"parent_folder": null,
"created": "2021-01-20T08:11:22.586Z",
"last_updated": "2021-01-20T08:11:22.586Z"
}
]
}
To retrieve all folders that you have created earlier, use this API endpoint that gives a list of all folders as a JSON response.
curl -X GET 'https://app.facequest.io/api/v1/folders' \
-H 'secret: secret_that_i_set_in_facequest_web_ui' \
-H 'email: email_id_registered_with_facequest' \
-H 'accept: application/json' \
-H 'authorizationtoken: bearer' \
--compressed
Note: special characters like “/” or “\” (slash) are not allowed to enter in folder names. For example: “folder-name/example” or “folder-name\example”.
This gives us all folders that you have created as a JSON response.
{
"page": {
"totalElements": 2
},
"_embedded": [
{
"id": "f66d18d3-18cc-4801-a75b-9a425bebc12",
"user_id": "267c04d0-e9cf-431f-b614-e878cc681462",
"name": "sample",
"parent_folder": null,
"created": "2021-01-20T08:09:43.468Z",
"last_updated": "2021-01-20T08:09:43.468Z"
},
{
"id": "b55b2b9d-5b66-49ac-babc-3382d48b5112",
"user_id": "267c04d0-e9cf-431f-b614-e878cc721162",
"name": "sample2",
"parent_folder": null,
"created": "2021-01-20T08:11:22.586Z",
"last_updated": "2021-01-20T08:11:22.586Z"
}
]
}
If you want to delete any folder by using folder ID. Every folder has UUID.
Sample cURL request:
curl -X DELETE 'https://app.facequest.io/api/v1/folders/{folderId}' \
-H 'secret: secret_that_i_set_in_facequest_web_ui' \
-H 'email: email_id_registered_with_facequest' \
-H 'accept: application/json' \
-H 'authorizationtoken: bearer' \
--compressed
After successful request you get “success” message like this:
{
"id": "db4c9444-3a7e-438e-ad7d-e486badff7df",
"status": "SUCCESS"
}
Creates a reference photo with the given name within the given folder. You have to pass Reference Photo name, Folder ID and File path to create reference photo in the particular folder. Just make a request with a cURL command in your terminal.
Note: Make sure that you are in the same directory from where you selected image file.
After successful request it returns photo ID with “Success” message.
Example: Create a Reference Photo
Retrieve Reference photo from given folder with folderId. You need to pass the folderId that you have created earlier with this request that returns all image data as a response.
Sample cURL request:
curl -X GET \
https://app.facequest.io/api/v1/reference-faces/folder/{folderId} \
-H 'secret: secret_that_i_set_in_facequest_web_ui' \
-H 'email: email_id_registered_with_facequest' \
-H 'accept: application/json' \
-H 'authorizationtoken: bearer' \
--compressed
Example: Retrieve a Reference Photo
Sample response:
{
"page": {
"totalElements": 1
},
"_embedded": [
{
"id": "5f42d765-c26c-436a-92a5-36803412125a",
"name": "John Doe",
"owned_by_user": "1df0a952-3796-11ea-aec2-2e728ce34125",
"last_detected_time": "2020-12-08T08:55:19.847Z",
"picture_url": "https://mk6kd5pdmpkiyr.s3.amazonaws.com/reference/8adare24-f3b8-4a2b-bd98-f0cb19245754.jpeg?AWSAccessKeyId=AKIARNEJIER6A2OHGS6C&Expires=1607675535&Signature=VaUw946p15htqh2wy8IcOqQBQDg%3D",
"folder_id": "123e4567-e89b-12d3-a456-426655440000",
"face_encoding": null
}
]
}
If you want to replace a reference photo then use this api endpoint to replace images by passing image id with api request, email, secret and photo to be replaced.
If you send a request from the terminal then make sure that you are in the same directory where the image exists, otherwise it gives an error & image contains at least one face.
curl -X PUT \
https://app.facequest.io/api/v1/reference-faces/replace-photo/{photoId} \
-H 'secret: secret_that_i_set_in_facequest_web_ui' \
-H 'email: email_id_registered_with_facequest' \
-H 'accept: application/json' \
-H 'authorizationtoken: bearer' \
-H 'content-type: multipart/form-data' \
-F file=@upload.jpg
Example: Replace Reference Photo
The response returns a replaced image ID with a success message like this.
{
"id": "cdef9444-3a7e-438e-ad7d-e486badff7df",
"status": "SUCCESS"
}