Table of Contents
FACEIO Logo

The FACEIO REST API

Each FACEIO application is automatically assigned an API key. You can retrieve this key from the Application Manager on the FACEIO Console. The API key let you programmatically manage your application from your private backend environment, and using your favorite programming language as long as it supports HTTPS. The HTTP endpoints are built on TLS. Our API is RESTful and it:

  • Uses built-in HTTP capabilities for passing parameters and authentication.
  • Responds with standard HTTP response codes to indicate errors.
  • Always returns JSON for each request whether successful or not.
Notice

Please note that API calls (REST HTTP Endpoints) and Widget instantiation (via the fio.js JavaScript library) are totally unrelated. Widget instantiation (ie facial enrollment & authentication) occurs on the client side (user’s browser), is unmetered and unrestricted for all users while API calls must originate from your private application backend and is subject to quota & throttling (mostly Freemium plan). Refer to our Pricing Table for the REST API quota limits (if applicable).

API Access Point URL

  • The FACEIO API’s base endpoint is located at https://api.faceio.net/.

  • The request URL scheme is https://api.faceio.net/cmd?param=val&param2=val2 where cmd is the API Endpoint you want to call and param=val are the endpoint parameters (if any). Each endpoint may handle both GET & POST requests at the same time, and all our HTTP API Endpoints are exactly invoked the same way.

  • Health & Status dashboard is located at status.faceio.net for real-time monitoring.

Summary

Access Point URL api.faceio.net
Health Check Endpoint api.faceio.net/status
Architecture RESTFul
HTTP & TLS Protocols Version 1.1/2/3 (TLS 1.2/3 Enforced)
Authentication Key Based
Network Cloudflare
HTTP Response MIME Type application/json
HTTP Status & Error Codes See Below
List of Endpoints See Below

Retrieve your API Key

When you create a new FACEIO application, you are given automatically an API key. Retrieving this API key is straightforward. Follow the steps below to fetch and manage your HTTP API key:

  1. Connect to your account via the FACEIO Console first.
  2. On the console main view, visit the Application Manager .
  3. Select the target application for which you want to retrieve your API key and/or gather analytics on your HTTP API calls.
  4. Navigate  to the API key tab from the manager main view.
  5. You're all set. You can now copy your API key, make HTTP API calls, gather analytics, request quota increase, and so forth...

Authentication

You authenticate to the target FACEIO API endpoint by embedding your API key in the incoming HTTP request. Refer to the section above on how to retrieve and manage this API Key.

Authentication Methods

Authentication to the API occurs via two manners. Use the one you feel comfortable with:

HTTP Header

Embed your API Key in the WWW-Authenticate HTTP header of the incoming request as follows: WWW-Authenticate: Bearer API_KEY.
Replace API_KEY with your application’s private API Key.
Query Parameter

Or simply include your API key within your POST or GET request like any other parameters an API Endpoint would take as follows: https://api.faceio.net/endpoint?param=val&key=API_KEY

 Do not forget to keep your API keys handy, and make sure they are used by authorized scripts only.

HTTP Responses, Status & Error Codes

The following HTTP status codes are always returned following each request. All API Endpoints, always returns application/json for each request whether successful or not.

200

The target API endpoint executed the requested operation successfully.
400 Bad Request - Often missing a required parameter.
401 Unauthorized - Missing or Invalid API Key.
404 Not Found - The requested item (i.e. Facial ID) does not exist.
405 The HTTP method is not handled by this API endpoint.
429 Too many requests from this IP address/API Key. Refer to the Pricing Table for API Quota & Limits (if applicable).
500 Server Side Error or Maintenance Planned (We'll notify you anyway).

REST API Endpoints

The following section enumerates all the exposed FACEIO REST API endpoints. Enhancements & new endpoints are added on each new release. This is the reference document you should follow. If you have any suggestion or feature request, please open a new support ticket via the FACEIO Console.

Endpoints Documentation

DELETEFACIALID

Endpoint Access URL https://api.faceio.net/deletefacialid
Description Programmtically delete (total purge), a Facial ID, its linked payload data, and associated biometrics hash from a given FACEIO application.

The Facial ID is a Unique Identifier (UUID) assigned anonymously by the underlying Facial Recognition Engine to each enrolled user on your FACEIO application after after his consent when he complete on-boarding on your application. You can learn more about the Facial ID on its dedicated page.

Enrollment occurs via a single call to the enroll() method of the fio.js, facial recognition JavaScript library you already implemented on your website, web or mobile app.
Availability All Plans
HTTP Method GET
HTTP Parameters
Field Type Required Description
key HEX String YES Your application REST API Key. Each FACEIO application is automatically assigned an API Key in order to authenticate to the REST API Server. Refer to the section above on how to retrieve your API key from the FACEIO Console.
fid String YES The target Facial ID, and linked data you want to purge from this FACEIO application.
HTTP Response
application/json
This API endpoint always return a JSON object whether the initiated request executed successfully or not. The following are the JSON fields returned in the response body:
Field Type Description
status Integer HTTP status code 200 indicates success. Any other error codes such as 401 (Request missing mandatory parameters such as your authentication API Key) indicates failure.
payload Boolean  TRUE, when the supplied Facial ID, associated payload data, and biometrics hash and data have been totally removed (purged) from this FACEIO application. FALSE, is returned on failure otherwise.

Facial ID Deletion Python Code Sample

CHECKFACIALID

Endpoint Access URL https://api.faceio.net/checkfacialid
Description Perform authenticity check of a given Facial ID. In other words, make sure the supplied Facial ID is valid & registered on the FACEIO application linked to this API key.

The Facial ID is a Unique Identifier (UUID) assigned anonymously by the underlying Facial Recognition Engine to each enrolled user on your FACEIO application after after his consent when he complete on-boarding on your application. You can learn more about the Facial ID on its dedicated page.

Enrollment occurs via a single call to the enroll() method of the fio.js, facial recognition JavaScript library you already implemented on your website, web or mobile app.
Availability Paid/Upgraded Plans Only. Refer to our Pricing Page for additional information.
HTTP Method GET
HTTP Parameters
Field Type Required Description
key HEX String YES Your application REST API Key. Each FACEIO application is automatically assigned an API Key in order to authenticate to the REST API Server. Refer to the section above on how to retrieve your API key from the FACEIO Console.
fid String YES The target Facial ID being verified against this FACEIO application.
HTTP Response
application/json
This API endpoint always return a JSON object whether the initiated request executed successfully or not. The following are the JSON fields returned in the response body:
Field Type Description
status Integer HTTP status code 200 indicates success. Any other error codes such as 401 (Request missing mandatory parameters such as your authentication API Key) indicates failure.
valid Boolean  TRUE, when the supplied Facial ID, is valid & registered on this FACEIO application. FALSE, is returned otherwise.

Check Facial ID Python Code Sample

setfacialidpayload

Endpoint Access URL https://api.faceio.net/setfacialidpayload
Description Set or change payload data linked to a particular enrolled user on your FACEIO application via its Facial ID. The supplied payload will be forwarded back to you (fio.js integration) upon successful, future authentication of this particular user.
Availability Paid/Upgraded Plans Only. Refer to our Pricing Page for additional information.
HTTP Method POST
HTTP Parameters
Field Type Required Description
key HEX String YES Your application REST API Key. Each FACEIO application is automatically assigned an API Key in order to authenticate to the REST API Server. Refer to the section above on how to retrieve your API key from the FACEIO Console.
fid String YES The target Facial ID you want to update the PIN code for.
payload String/Raw Data YES The payload data to be linked to the given Facial ID (set via the facialid parameter above). The supplied payload will be forwarded back to you (fio.js website integration) upon successful, future authentication of this particular user.
HTTP Response
application/json
This API endpoint always return a JSON object whether the initiated request executed successfully or not. The following are the JSON fields returned in the response body:
Field Type Description
status Integer HTTP status code 200 indicates success. Any other error codes such as 401 (Request missing mandatory parameters such as your authentication API Key) indicates failure.
payload Boolean  TRUE, when the payload have been successfully linked to the supplied Facial ID. FALSE, is returned on failure otherwise.

setfacialidpincode

Endpoint Access URL https://api.faceio.net/setfacialidpincode
Description Set or change the PIN code linked to a particular enrolled user on your FACEIO application via its Facial ID.
Availability Paid/Upgraded Plans Only. Refer to our Pricing Page for additional information.
HTTP Method POST
HTTP Parameters
Field Type Required Description
key HEX String YES Your application REST API Key. Each FACEIO application is automatically assigned an API Key in order to authenticate to the REST API Server. Refer to the section above on how to retrieve your API key from the FACEIO Console.
fid String YES The target Facial ID you want to update the PIN code for.
pin Number YES The new PIN code to be linked to the given Facial ID (set via the facialid parameter above). Once updated, the user has to confirm this new PIN code in order for the Facial Authentication to succeed when prompted for. The new PIN code must contains at least 4 digits and no more than 16.
HTTP Response
application/json
This API endpoint always return a JSON object whether the initiated request executed successfully or not. The following are the JSON fields returned in the response body:
Field Type Description
status Integer HTTP status code 200 indicates success. Any other error codes such as 401 (Request missing mandatory parameters such as your authentication API Key) indicates failure.
payload Boolean  TRUE, when the PIN code have been successfully updated. FALSE, is returned on failure otherwise.

Change PIN Code of a given Facial ID Python Code Sample

STAT

Endpoint Access URL https://api.faceio.net/stat
Description Gather statistics on your active FACEIO application. Stats includes total indexed faces, total API calls, most recent indexed faces, etc. Please note that application stats are updated each 5 minutes.
Availability Paid/Upgraded Plans Only. Refer to our Pricing Page for additional information.
HTTP Method GET
HTTP Parameters
Field Type Required Description
key HEX String YES Your application REST API Key. Each FACEIO application is automatically assigned an API Key in order to authenticate to the REST API Server. Refer to the section above on how to retrieve your API key from the FACEIO Console.
HTTP Response
application/json
This API endpoint always return a JSON object whether the initiated request executed successfully or not. The following are the JSON fields returned in the response body:
Field Type Description
status Integer HTTP status code 200 indicates success. Any other error codes such as 401 (Request missing mandatory parameters such as your authentication API Key) indicates failure.
total_api_calls Integer Total number of API calls made by this application so far. Please note that freemium application are subject to API throttling, and must upgrade for larger API quota. Refer to our Pricing Page for additional information.
total_indexed_faces Integer Total number of anonymously indexed faces. Please note that freemium application are subject to low facial index quota, and must upgrade for larger indexes. Refer to our Pricing Page for additional information.
last_indexed_faces Integer Array of most recent, generated Facial IDs.

ABOUT

Endpoint Access URL https://api.faceio.net/about
Description Return copyright notice and version information of the running FACEIO API server(s).
Availability All Plans
HTTP Method GET
HTTP Parameters None
HTTP Response
application/json
This endpoint always succeed (HTTP status code 200) with a JSON object holding the following fields:
Field Type Description
status Integer HTTP status code 200 indicates success, any other code indicates failure.
payload String Copyright notice and version information related the running FACEIO API server(s).

STATUS

Endpoint Access URL https://api.faceio.net/status
Description Return health status information of the running FACEIO API server(s). Health status can also be monitored at real-time via status.faceio.net.
Availability All Plans
HTTP Method GET
HTTP Parameters None
HTTP Response
application/json
This API endpoint always return a JSON object whether the initiated request executed successfully or not. The following are the JSON fields returned in the response body:
Field Type Description
status Integer HTTP status code 200 indicates success. Any other error codes such as 500 indicates failure, and REST API calls may not execute at the current time.
error String Error message indicating that the API server(s) are encountering request processing issues (status code != 200).
payload String Payload message indicating that the API server(s) are operational (status code 200).