API Overview
This page lists the public REST endpoints exposed by the Identities controllers. GraphQL endpoints are intentionally out of scope for this guide.
It is highly recommended to generate a typed client from the OpenAPI schema before building requests by hand.
Swagger / OpenAPI is disabled by default on each Identities deployment. For development, use eConnect's always-on test instance, which has the full schema available:
- Swagger UI:
https://montana.econnectclouddev.com/identities/swagger/index.html - Swagger Schema:
https://montana.econnectclouddev.com/identities/swagger/v1/swagger.json
All paths below are appended to your base URL. On cloud that includes the /identities prefix
(https://customername.econnectcloud.com/identities/api/v1/authenticate); on-premise the app listens on HTTPS port
5009 with no prefix (https://<host>:5009/api/v1/authenticate). See
Getting Started → Base URL. Every endpoint except
authenticate requires an Authorization: Bearer <JWT> header.
Authentication & Users
| Method | Path | Description | Min Permission |
|---|---|---|---|
POST | /api/v1/authenticate | Exchange username/password for a JWT. | None (anonymous) |
GET | /api/v1/renewToken | Renew a still-valid JWT. | Authenticated |
GET | /auth/v1/user/profile | Current session profile (email, roles, token). | Authenticated |
Face Edge ⭐
The focus of this guide. See the Face Edge pages for full details and runnable examples.
| Method | Path | Description | Min Permission |
|---|---|---|---|
POST | /api/v1/faceEdge/publishWithResponse | Publish a detected face and return detection results. | Face Publishing |
POST | /api/v1/faceEdge/publish | Publish a detected face (fire-and-forget). | Face Publishing |
POST | /api/v1/faceEdge/recognize | Match a cropped/aligned face to an enrolled person. | Face Recognize |
POST | /api/v1/faceEdge/lookup | Match an uploaded face / embeddings (multipart). | Face Recognize |
Face Recognition
Documented with examples on the Face Recognition page.
| Method | Path | Description | Min Permission |
|---|---|---|---|
POST | /api/v1/faces/faceDetect | Detect faces in an image. | Face Detection |
POST | /api/v1/faces/faceEnroll | Enroll a face for a person. | Face Enrollment |
POST | /api/v1/faces/faceCompare | Compare two faces (1:1). | Face Detection |
GET | /api/v1/faces/checkImageReference/{referenceId} | Check whether an enrollment image reference exists. | Face Enrollment |
People
| Method | Path | Description |
|---|---|---|
GET | /api/v1/people | Query people (by tag or entity field). |
GET | /api/v1/people/{personId} | Get a single person. |
GET / PUT / DELETE | /api/v1/people/{personId}/aliases | Read / upsert / delete aliases. |
GET / PUT / DELETE | /api/v1/people/{personId}/tags | Read / upsert / delete person tags. |
GET / PUT / DELETE | /api/v1/people/{personId}/notes | Read / upsert / delete notes. |
PUT | /api/v1/people/{personId}/addresses | Upsert an address. |
GET / PUT / DELETE | /api/v1/people/{personId}/entityFields | Read / upsert / delete custom fields. |
GET | /api/v1/people/enrollmentPhoto/{faceId} | Download an enrollment photo. |
GET | /api/v1/people/detectionPhoto/{faceId}/{detectionId} | Download a detection photo. |
People reads require Read All Identity (or the matching granular read permission such as Read Aliases, Read Tags); writes require Mutate All Identity (or the matching granular mutate permission). Dedicated pages cover the common operations:
- Get Identity — read a single person by id.
- Search People — query people by tag or entity field.
- Person Management — upsert/delete aliases, tags, notes, addresses, fields.
- Photos & Documents — enrollment/detection photos and file documents.
Tags
Documented with examples on the Tag Management page.
| Method | Path | Description | Min Permission |
|---|---|---|---|
GET | /api/v1/Tags | List tags. | Read Tags |
POST | /api/v1/Tags | Create a tag. | Add Tags |
GET | /api/v1/Tags/{tagId} | Get a tag. | Read Tags |
PUT | /api/v1/Tags/{tagId} | Update a tag. | Edit Tags |
DELETE | /api/v1/Tags/{tagId} | Delete a tag. | Delete Tags |
Detections
Documented with examples on the Detections page.
| Method | Path | Description | Min Permission |
|---|---|---|---|
GET | /api/v1/people/detections/faceId/{faceId} | Query detections by face. | Read Detections |
GET | /api/v1/people/detections/personId/{personId} | Query detections by person. | Read Detections |
Entity Field Settings
| Method | Path | Description |
|---|---|---|
PUT | /api/v1/EntityFieldSettings/{entityType}/stringField/{fieldId} | Configure a string custom-field. |
PUT | /api/v1/EntityFieldSettings/{entityType}/datetimeField/{fieldId} | Configure a date/time custom-field. |
For full request/response details on any endpoint, consult the Swagger UI for your server or generate a client from the OpenAPI schema — see Getting Started → OpenAPI / Swagger.