> 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/sdks/backend-sdk/ine/technical_documentation/api_reference.md).

# API reference guide

## 1. Introduction

This document includes the description of the API of the service provided in the product **FacePhi INE Service**.

## 2. Rest API

JWT authentication is optional and is configured only at startup. When enabled, `GET /api/v1/health` and `GET /api/v1/version` remain public, while `POST /api/v1/facial/authentication` requires a valid JWT.

The service offers the following endpoints:

* **/api/v1/facial/authentication**: This endpoint is used to authenticate two facial photos. It supports image-image, template-template, and mixed image-template combinations. It returns a score value indicating whether the face belongs to the same person, and a probability indicating the similarity between the two faces. The image or template must be encoded in base64.
* **/api/v1/health**: This endpoint returns the service health status and remains public even when JWT authentication is enabled.
* **/api/v1/version**: This endpoint returns the service version and the SDK information.

The service does not expose endpoints `GET/POST /config` at runtime.

## 3. Photo types

```cpp
    INE              = 0
    JPEG             = 1
    TEMPLATE_RAW     = 2
    BEST_IMAGE_TOKEN = 3
```

## 4. Error codes

```cpp
	OK              = 0
    MALFORMED_JSON  = 400
    PHOTOA_EMPTY    = 401
    PHOTOB_EMPTY    = 402
    NO_PHOTOS       = 403
    POSE_INVALID    = 404
    PHOTOA_INVALID  = 405
    PHOTOB_INVALID  = 406
```

Payloads with malformed JSON or Base64 are returned as HTTP `400 BadRequest` with a field `message` that describes the problem.