FACEIO REST API

Call the FACEIO REST API from your private backend to manage Facial IDs, compare face images, estimate age and gender, update payloads and PIN Codes, retrieve application statistics, and check API status.

OPEN FACEIO Console

Create an application in the FACEIO Console, then retrieve its private API key from the Application Manager. Keep the key on your backend.

The FACEIO REST API

Backend HTTP endpoints for Facial ID management, face verification, and application operations

Every FACEIO application is assigned an API key automatically. You can retrieve this key from the Application Manager on the FACEIO Console ↗. This private API key lets your backend call the FACEIO REST API from any programming language that supports HTTPS.

  • Uses standard HTTP capabilities for parameter passing and API key authentication.
  • Returns standard HTTP response codes to indicate success and error states.
  • Always returns JSON for every request, regardless of the outcome.

Important Notice

API calls and Widget instantiation via the fio.js JavaScript library are separate workflows. Enrollment and authentication happen client-side in the user's browser. REST API calls should originate from your private application backend and may be subject to quotas or throttling depending on your plan. If you are new to FACEIO, start with Getting Started, then use the Integration Guide. See the pricing table for REST API quota limits.

REST API Base 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 and param=val values are endpoint parameters. Each endpoint section below lists the supported HTTP method.
  • Monitor API health and status in real-time at status.faceio.net ↗.
API Summary
Access Point URL api.faceio.net
Health Check Endpoint api.faceio.net/status ↗
Architecture RESTful
HTTP and TLS Versions HTTP/1.1, HTTP/2, HTTP/3; TLS 1.2 and 1.3
Authentication Key Based ↓
Network Cloudflare
HTTP Response MIME Type application/json
HTTP Status Codes See Below ↓

Retrieve Your API Key

When you create a new FACEIO application, you are automatically assigned an API key. Follow these steps to retrieve and manage your key:

  1. 1 Log in to the FACEIO Console ↗.
  2. 2 Navigate to the Application Manager.
  3. 3 Select the application you wish to manage.
  4. 4 Click on the API Key tab.
  5. ✓ Copy the API key for your server-side HTTP API calls. The same tab provides API analytics and quota information.

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

Send the API key using one of the following supported methods:

HTTP Header

Embed your API Key in the WWW-Authenticate HTTP header:

WWW-Authenticate: Bearer API_KEY
Query Parameter

Or append the key to your POST or GET request URL:

https://api.faceio.net/endpoint?param=val&key=API_KEY

Security Warning: Keep your API keys secure. Never expose them in client-side code, public repositories, browser JavaScript, mobile app bundles, logs, or analytics tools. Use authorized server-side scripts only and review the security best-practice guide before production use.

HTTP Responses, Status & Error Codes

The following HTTP status codes are returned for each request. All API Endpoints return application/json regardless of success or failure. Handle failures explicitly on your backend before granting access, updating user records, or trusting a Facial ID state.

200 Success. The API endpoint executed the operation successfully.
400 Bad Request. Typically indicates a missing required parameter.
401 Unauthorized. Missing or Invalid API Key.
404 Not Found. The requested item (e.g., Facial ID) does not exist.
405 Method Not Allowed. The HTTP method is not handled by this endpoint.
429 Too Many Requests. Rate limit exceeded. Refer to the Pricing Table for quota limits.
500 Server Error. Server side error or maintenance (We'll notify you anyway).

Endpoints Documentation

DELETEFACIALID

GET
Endpoint Access URL https://api.faceio.net/deletefacialid
Description

Delete a Facial ID and its linked payload data from your FACEIO application. The operation also instructs the selected facial recognition engine to purge the associated biometric hash.

The Facial ID is a Unique Identifier (UUID) assigned anonymously to each enrolled user. Enrollment occurs via a call to the enroll() method of the fio.js client-side library.

Availability All Plans
HTTP Method GET

HTTP Parameters

Field Type Required Description
key HEX String YES Your application REST API Key.
fid String YES The target Facial ID you want to delete (purge).

HTTP Response

application/json

This API endpoint always returns a JSON object. The following fields are returned:

Field Type Description
status Integer Standard HTTP status code: 200 for success; otherwise an error status such as 401.
payload Boolean TRUE if the Facial ID and data were successfully purged. FALSE otherwise.
Facial ID Deletion Code Sample (Python)

CHECKFACIALID

GET
Endpoint Access URL https://api.faceio.net/checkfacialid
Description

Check whether a provided Facial ID is registered in the FACEIO application associated with the supplied API key.
Availability Paid/Upgraded Plans Only. Refer to the pricing page for more details.
HTTP Method GET

HTTP Parameters

Field Type Required Description
key HEX String YES Your application REST API Key.
fid String YES The target Facial ID to be verified.

HTTP Response

application/json

This API endpoint always returns a JSON object. The following fields are returned:

Field Type Description
status Integer Standard HTTP status code: 200 for success; otherwise an error status.
valid Boolean TRUE if the Facial ID is valid & registered. FALSE otherwise.
Facial ID Validation Code Sample (Python)

FACE-VERIFY

POST
Endpoint Access URL https://api.faceio.net/faceverify
Description

Compare Two Face Images

The faceverify endpoint compares faces in two images and returns matching results and similarity scores.

Submit a source image and a target image containing one face each. No prior FACEIO enrollment is required. Your backend must decide how to interpret the returned scores for its own workflow.

Privacy Note: Processing occurs in-memory (RAM). Images are purged immediately after analysis. No data is logged or stored. Review privacy best practices before adding face verification to production workflows.
Availability Paid/Upgraded Plans Only. Refer to the pricing page for more details.
HTTP Method POST

HTTP Parameters

Field Type Required Description
key HEX String YES Your application REST API Key.
src Base64 | URL YES The Source Person image. Must be a Base64 encoded string (data URI format) or a publicly accessible URL. Ensure only a single face is present.
target Base64 | URL YES The Target Person image to compare against the source. Must be a Base64 encoded string (data URI format) or a publicly accessible URL.

HTTP Response

application/json

This API endpoint always returns a JSON object. The following fields are returned:

Field Type Description
status Integer Standard HTTP status code: 200 for success; otherwise an error status.
same_person Boolean TRUE if source and target faces belong to same person. FALSE otherwise.
dist Float Distance similarity score from 0 to 1. A value closer to 1 indicates a higher probability that the faces belong to the same person.
sim Float Cosine similarity score (0 to 1). Closer to 1 indicates higher similarity.
Face Verify Code Sample (Python)

AGE-CHECK

POST
Endpoint Access URL https://api.faceio.net/agecheck
Description

Age and Gender Estimation

The agecheck endpoint returns age and gender estimates for the face in an uploaded image. No prior FACEIO enrollment is required. Treat age as an approximation, not proof of identity, an exact age, or a legal eligibility decision.

Privacy Note: Processing occurs in-memory (RAM). Images are purged immediately after analysis. No data is logged or stored. Review privacy best practices before adding age and gender estimation to production workflows.
Availability Paid/Upgraded Plans Only. Refer to the pricing page for more details.
HTTP Method POST

HTTP Parameters

Field Type Required Description
key HEX String YES Your application REST API Key.
img Base64 | URL YES The input image containing the face to analyze. Format: data:{MIME_type};base64,{data} or a publicly accessible URL.

HTTP Response

application/json

This API endpoint always returns a JSON object. The following fields are returned:

Field Type Description
status Integer Standard HTTP status code: 200 for success; otherwise an error status.
age Integer Estimated age of the person in the image.
gender String Gender estimation for the person in the image.
Age & Gender Verification Code Sample (Python)

SETFACIALIDPAYLOAD

POST
Endpoint Access URL https://api.faceio.net/setfacialidpayload
Description

Set or modify the payload data linked to a specific enrolled user via their Facial ID.

The stored payload is returned to your website or web app through fio.js after the user's next successful authentication. Use it for minimal application data such as an internal user ID. Do not place secrets or authorization decisions in the payload.
Availability Paid/Upgraded Plans Only. Refer to the pricing page for more details.
HTTP Method POST

HTTP Parameters

Field Type Required Description
key HEX String YES Your application REST API Key.
fid String YES The target Facial ID to update.
payload String/Raw Data YES The new payload data to associate with the Facial ID. This data will be returned during future authentications. Form strings, JSON, or another backend-owned payload format.

HTTP Response

application/json
Field Type Description
status Integer Standard HTTP status code: 200 for success; otherwise an error status.
payload Boolean TRUE if the payload was successfully updated. FALSE otherwise.

SETFACIALIDPINCODE

POST
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.
Availability Paid/Upgraded Plans Only. Refer to the pricing page for more details.
HTTP Method POST

HTTP Parameters

Field Type Required Description
key HEX String YES Your application REST API Key.
fid String YES The target Facial ID to update.
pin Number YES The new PIN code to link to the Facial ID. The user must confirm this PIN during future authentication when prompted. The PIN must contain at least 4 digits and no more than 16 digits.

HTTP Response

application/json

This API endpoint always returns a JSON object. The following fields are returned:

Field Type Description
status Integer Standard HTTP status code. 200 indicates success.
payload Boolean TRUE if the PIN code was successfully updated. FALSE otherwise.
Change PIN Code Sample (Python)

STAT

GET
Endpoint Access URL https://api.faceio.net/stat
Description

Gather analytics and statistics for your FACEIO application, including total indexed faces, API calls, and recent enrollments. Note: stats are cached and updated every 5 minutes.
Availability Paid/Upgraded Plans Only. Refer to the pricing page for more details.
HTTP Method GET

HTTP Parameters

Field Type Required Description
key HEX String YES Your application REST API Key.

HTTP Response

application/json

This API endpoint always returns a JSON object. The following fields are returned:

Field Type Description
status Integer Standard HTTP status code: 200 for success; otherwise an error status such as 401.
total_api_calls Integer Cumulative count of API calls made by this application.
total_indexed_faces Integer Total number of unique faces currently enrolled/indexed.
last_indexed_faces Array A list containing the Facial IDs of the most recently enrolled users.

ABOUT

GET
Endpoint Access URL https://api.faceio.net/about
Description

Retrieve version information and copyright notice of the running FACEIO API instance.
Availability All Plans
HTTP Method GET

HTTP Parameters

No parameters required.

HTTP Response

application/json
Field Type Description
status Integer Standard HTTP status code: 200 for success; otherwise an error status.
payload String Server version string and copyright notice.

STATUS

GET
Endpoint Access URL https://api.faceio.net/status
Description

Check the health status of the FACEIO API servers. Real-time status history is also available at status.faceio.net ↗.
Availability All Plans
HTTP Method GET

HTTP Parameters

No parameters required.

HTTP Response

application/json
Field Type Description
status Integer 200 indicates operational status (System OK). 500 indicates a maintenance or service disruption.
error String Error message (if status != 200).
payload String Status message (e.g., "System OK").

Connect Your Backend to the REST API

Create a FACEIO application, retrieve its private REST API key from the Console, and call the documented endpoints from your backend. Never expose the API key in browser or mobile client code.

Read Getting Started → Open FACEIO Console
99.7% LFW Accuracy