> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/rest-api/midapi-v2.md).

# MIDAPI v2

**MIDAPI v2** is the synchronous Rest API of Facephi's API ecosystem. It exposes Identity Verification and antifraud services through REST endpoints authenticated with OAuth2, designed for integrators and backend developers.

### Concepts: client platform and Consumer

Before integrating any MIDAPI v2 service, it is worth knowing the two concepts around which access is organized:

* **Client platform**: represents the unique relationship between the client and Facephi. It is identified with the header `platform-id` and has an associated API Key. There is a single platform per client.
* **Consumer**: represents a channel or business vertical of the client (for example, the web channel and the mobile app, or verticals such as insurance and investments). It is identified with the header `consumer-id`. Each consumer only has the contracted services enabled for that channel, with independent usage limits and traceability.

As part of service onboarding, the client will be provided with the **base URL** of the API, the **platform credentials** and **at least one consumer** (one for each channel or vertical that needs to be integrated). All routes in this guide are relative to that base URL (for example, `POST <URL base>/consumer/token`). This model makes it possible to manage permissions, limits, and traceability independently by channel, while maintaining a single platform per client.

With these two concepts, the access Token is obtained: the platform issues Tokens for its consumers, and each operational call is made on behalf of a consumer. The details are in [Authentication](/docs.facephi-en/rest-api/midapi-v2/autenticacion.md).

#### Authorizations

All calls to the operational endpoints must include the following keys in the request header:

| Key             | Value                                                 | Required    |
| --------------- | ----------------------------------------------------- | ----------- |
| `Authorization` | Consumer Token in Bearer format `Bearer <token>`      | **Yes**     |
| `consumer-id`   | Consumer identifier                                   | **Yes**     |
| `operation-id`  | Identifier of the operation for the referenced assets | Conditional |

The header `operation-id` is mandatory when the request references any asset by key. See [Storage](/docs.facephi-en/rest-api/midapi-v2/storage.md).

#### Error responses

All endpoints return errors with the same structure:

| Parameter    | Type    | Description         |
| ------------ | ------- | ------------------- |
| `message`    | string  | Error description.  |
| `statusCode` | integer | HTTP response code. |

```json
{
  "message": "Missing operation-id header, required when the request references stored assets",
  "statusCode": 400
}
```

### The assets model

The MIDAPI v2 validation services work on **assets**: the end-user captures. An asset can be provided with inline content in the call itself, or by reference to a previously stored asset.

Key-based reference is available in all identity validation services **identity**. The exceptions are explicit: [Form OCR](/docs.facephi-en/rest-api/midapi-v2/document-services/form-ocr.md) and the [voice](/docs.facephi-en/rest-api/midapi-v2/voice-services.md) services are exclusively online, and [Document Validation](/docs.facephi-en/rest-api/midapi-v2/document-services/document-validation.md) is reference-only.

The reference flow is: create the [operation](/docs.facephi-en/rest-api/midapi-v2/operations/create-operation.md), [store](/docs.facephi-en/rest-api/midapi-v2/storage/save-asset.md) each asset, and send the obtained keys to the validation service together with the header `operation-id`. It is developed step by step, with its diagram, in [Common Flow](/docs.facephi-en/rest-api/midapi-v2/flujo-comun.md). Services that support both modes identify the reference with `source: FILE_KEY`; those that only support reference do not include that field. The asset mode, the available contexts, and the key format are in [Storage](/docs.facephi-en/rest-api/midapi-v2/storage.md).

### Available services

* [**Operations**](/docs.facephi-en/rest-api/midapi-v2/operations.md): operation lifecycle that groups the assets of a session and sets their expiration.
* [**Storage**](/docs.facephi-en/rest-api/midapi-v2/storage.md): storage of the assets that validation services later reference, with the asset mode, contexts, and key format.
* [**Document Services**](/docs.facephi-en/rest-api/midapi-v2/document-services.md): validation of the authenticity of the Identity document, identity OCR and printed OCR.
* [**Biometric Services**](/docs.facephi-en/rest-api/midapi-v2/biometric-services.md): liveness check and face comparison.
* [**Face Collections**](/docs.facephi-en/rest-api/midapi-v2/face-collections.md): registration and 1:N search of faces in collections.
* [**Security & Compliance**](/docs.facephi-en/rest-api/midapi-v2/security-compliance.md): Injection Attack Detection on Face Capture.
* [**Validation Services**](/docs.facephi-en/rest-api/midapi-v2/validation-services.md): IP, email, and phone fraud risk.
* [**Voice Services**](/docs.facephi-en/rest-api/midapi-v2/voice-services.md): voice enrollment and authentication.