2FACE

2FACE is a full-service identity verification solution for compliance and KYC. It takes care of online digital identity verification, reducing fraud and delivering insights on your customer identity.

Introduction

Welcome to the 2FACE RESTful API documentation. This documentation will help you get started with the service. If you have any questions you can use write us an email at [email protected] to get in contact with us.

Navigating the documentation

2FACE endpoints are organized by function. Each section contains an overview of the available endpoint, a description of configurable options, as well as an example of how to use them.

Function	Description	Quick Link
Session Management	Contains endpoints related to starting or closing sessions.	Session Management
Jobs	Contains endpoints related to jobs initiated by users or the manager.	Jobs
Faces	Collection of endpoints related to face detection and recognition operations.	Faces
Documents	Collection of endpoints related to document classification and data extraction operations.	Documents
Users	Collection of endpoints allowing search operations of users that have attempted a validation.	Users
Attempts	Contains the endpoints that can be used to get the information of attempts and operate on them.	Users

You can always import 2FACES API by using this Postman Collection.

Authentication

2FACE's API provides two methods for authentication:

App API Key

This is the preferred authentication method for unattended production applications. API keys can be created and invalidated via the company applications admin panel and should be passed as an HTTP header using the Authorization key.

Session Token

Some endpoints require a valid and active session token instead of an API key. These tokens can be created with the endpoints in the Session Management section and should be passed as an HTTP header using the X-Tagshelf-Session key.

♻️Session Management

We recommend that you don't expose your api key in your client app. They are meant to be used from a backend server; session tokens, on the other hand, are safe to use in any environment.

---

Limiting

To ensure fair usage and optimal performance of our API, we have implemented rate limiting measures. These limits help maintain stability and prevent abuse of the platform. Please take note of the following details:

Overall Rate Limit

You can make up to 2,500 API requests per minute.

Authenticated requests are associated with the authenticated user, regardless of the used authentication method. This means that all requests authorized by a user share the same quota of 2500 requests per minute even if they authenticate with different tokens owned by the same user.

Retry Limits on Specific Endpoints

Starting from July 1st, 2023, we have introduced a new feature that includes a retry limit on certain endpoints. The affected endpoints are those beginning with /documents and /faces. When making requests to these endpoints, you will receive a response headers named

• x-attempt-limit indicating the number of retries allowed.

• x-attempt-retries indicating the number of retries remaining.

Once you reach the retry limit, you must create a new session in order to keep using these endpoints.

Example

Headers x-attempt-limit: 3

x-attempt-retries: 2

This means that you can retry the request a maximum of 3 times if needed and you have 2 remaining retries.

Why Retry Limits?

The retry limits are implemented to enhance the stability and efficiency of our platform. They provide better control over retries, allowing you to manage your integration more effectively.

If you need to make multiple requests to the affected endpoints, please ensure that you handle the retry limits appropriately.

File Size Limiting

You can upload files up to 10MB in regular requests.

---

User Agent

All API requests MUST include a valid User-Agent header key-value pair. Requests without a valid User-Agent header will be rejected.

We request that you use your TagShelf username, or the name of your application, for the User-Agent header key-value pair. This allows us to identify your API requests properly and contact you if there are problems.

Here's an example:

User-Agent: Amazing-magical-App

cURL and Postman send a valid User-Agent header key-value pair by default. If you do not provide a valid User-Agent header via cURL (or via an alternative client), you will receive an HTTP status code 403 response.