Developers
Face recognition API
Call recognition over HTTP from any language — against a service deployed inside your own environment, with your own base URL, your own credentials and your own data residency.
- Deployed in your environment, not a public multi-tenant endpoint
- Any language that speaks HTTP
- One deployment serves many callers
- Endpoint reference released with an evaluation
In short
The Ayonix face recognition API is deployed into the customer's environment rather than offered as a public multi-tenant endpoint, so its base URL, credentials and data residency belong to the customer. This page describes the integration model; the endpoint reference is released with an evaluation.
The most important fact about this API is architectural rather than technical: it is deployed into your environment. There is no public endpoint, no shared tenancy and no vendor region holding your images — which is why the base URL and credentials are yours and cannot be documented here.
That also explains what this page is. It describes the operation set, the error model and the lifecycle in enough detail to design an integration, and defers the endpoint reference to the point where it can be generated from your actual deployment rather than guessed at here.
What makes a biometric API hard to integrate against
These are the questions a backend engineer needs answered before committing to a design, and the ones vendor pages usually leave until after a sales call.
Authentication is unclear until credentials arrive, so the design is blocked.
The deployment model and the authentication model are described on this page. The base URL and credentials belong to your deployment, which is also why they cannot be published here.
Request formats are inconsistent between operations.
Operations are listed on this page with what each needs and returns, so the shape of the integration can be designed before the reference arrives.
Error definitions are missing, so every failure looks the same to the caller.
The error taxonomy is set out below: what is retryable, what is a client error, and what needs a human. This is the part of an API contract that determines whether a caller behaves correctly under failure.
Video workflows are asynchronous and the API only documents synchronous calls.
Continuous video is an event-producing workload, not a request-response one. Webhooks and event retrieval are the documented route, and the distinction is explained rather than glossed over.
Security and rate-limit behaviour is undocumented until it bites in production.
Rate limiting, idempotency and transport security expectations are described here, because a caller that discovers them under load has already had an incident.
Identity lifecycle — update, re-enrol, delete — is an afterthought.
The lifecycle operations are first-class on this page, including verifiable deletion, because a data-subject request is answered with evidence rather than an assurance.
There is no deployment guidance, so the service is stood up badly.
The deployment model, network placement and what is logged are covered, because the API’s security properties come mostly from where it sits.
How it works
How an integration is actually built
The API is deployed into your environment first. That ordering is not incidental — it determines the base URL, the credentials and where the data lives.
-
Deploy the service
The API is installed inside your environment — on-premise, at the edge, or in your own private cloud — on a network segment you choose.
Fails when: The service is placed on a general-purpose segment, and biometric traffic is reachable from everywhere.
-
Establish credentials
Credentials are issued for your deployment and scoped to what each caller needs, rather than one key shared by every application.
Fails when: One credential is shared across services, so it can never be rotated without an outage.
-
Integrate the operations
Enrolment, quality assessment, verification and identification over HTTP, with the threshold returned alongside every score.
Fails when: The caller stores the score and discards the threshold, and the record becomes uninterpretable later.
-
Consume events
Webhooks for real time, event retrieval for reconciliation. Deliveries are at-least-once, so consumers must be idempotent.
Fails when: The webhook consumer is not idempotent, and a retry after a timeout creates a duplicate record.
Deployment model
Your network, your credentials, your data
Most of this API's security properties come from where it sits rather than from anything in the request format.
Callers
Customer applications-
Access control application
Verification at a door
-
Back-office service
Enrolment and lifecycle
-
Investigation tool
Identification against a gallery
Ayonix API service
Deployed in the customer environment-
Authentication and scoping
Per-caller credentials
-
Recognition engine
Quality, 1:1, 1:N, liveness
-
Template store
Encrypted at rest, on site
Consumers and records
-
Webhook consumers
Signed, at-least-once delivery
-
Event store
Retrievable for reconciliation
-
Audit log
Every call, every deletion
No traffic crosses the customer perimeter for recognition. Where the deployment is air-gapped, there is no external route at all.
Recognition is available to customer applications through an SDK and an HTTP API
- Source type
- Ayonix first-party statement
- Verified
- 2026-09-11 · Jan Mocary, Chief Technology Officer
What this does not establish
Confirms that an SDK and an HTTP API exist. It does not establish any specific function name, endpoint path, language binding or operating-system build, none of which is published on this site.
Operations
What the service does, and what each operation needs
Capability names rather than endpoint paths. This is enough to design an integration; the paths and payloads are released against your deployment, generated from its real contract.
Identity lifecycle
Enrol an identity
- Needs
- One or more images, an external identity reference, the target gallery
- Returns
- An enrolment record and the quality assessment for each image
A rejected image is more useful than an accepted bad one. Expect enrolment to refuse captures below the quality floor.
Update or re-enrol
- Needs
- The identity reference and a new capture
- Returns
- An updated enrolment record
Needed when appearance changes materially, and after an engine version change that alters template compatibility.
Delete an identity
- Needs
- The identity reference
- Returns
- Confirmation, and a deletion entry in the audit log
Deletion must be verifiable, because a data-subject request is answered with evidence rather than an assurance.
Recognition
Verify (1:1)
- Needs
- A capture and one identity reference
- Returns
- A decision, the similarity score and the threshold applied
Always returns the threshold alongside the score. A score without its threshold cannot be interpreted by the caller.
Identify (1:N)
- Needs
- A capture and a gallery reference
- Returns
- Ranked candidates with scores, and the threshold applied
Candidate count and gallery size both belong in the request, because they change what the result means.
Assess quality
- Needs
- A capture
- Returns
- A quality score and the reasons it is low
Worth calling separately during enrolment so a user can be asked to try again before anything is stored.
Events and operations
Retrieve events
- Needs
- A time range and a filter
- Returns
- Recognition events with their evidence references
The pull complement to webhooks, for reconciliation after an outage.
Receive webhooks
- Needs
- A registered endpoint and a shared secret
- Returns
- Signed event deliveries with retry
Verify the signature and treat deliveries as at-least-once. Design the consumer to be idempotent.
Health check
- Needs
- Nothing
- Returns
- Service state, engine state and version
Should distinguish "running" from "able to match", because those fail separately.
Why there are no paths on this page
Two reasons, and both matter. First, the service is deployed into your environment, so there is no shared endpoint anyone could call. Second, no verified public Ayonix API contract was available when this page was written, and publishing plausible-looking paths would produce confident client code against endpoints that may not exist — the same failure mode as inventing SDK function names. The reference, an OpenAPI specification where one is generated from the contract, is released with API access.
Error model
Five failure classes, five caller behaviours
The part of an API contract that determines whether a client behaves correctly under failure — and the part most often reduced to a single catch block.
| Class | What it means | Retry? | Correct caller behaviour |
|---|---|---|---|
| Quality rejection | The capture is below the quality floor | Not supported: Not as-is | Ask for another capture. Retrying the same image will fail identically. |
| No match | The comparison completed and nothing met the threshold | Not supported: No | A successful outcome, not an error. Handle it as a decision, and record the threshold. |
| Client error | Malformed request, bad reference, insufficient scope | Not supported: No | Fix the request. Retrying will produce the same result and consume rate limit. |
| Rate limited | Too many requests from this caller | Partial: Yes, with backoff | Exponential backoff with jitter. Immediate retry makes an overload worse. |
| Service unavailable | The engine or service is temporarily unable to serve | Partial: Yes, with backoff | Backoff, alert operations, and fail over to the fallback path the deployment defines. |
Distinguishing a quality rejection from a client error matters more than it looks: one asks the user to try again, the other means the integration is wrong.
Security and lifecycle
What has to be designed rather than configured
An API handling biometric data has requirements a general-purpose service does not, and most of them are the caller's to implement.
Idempotency
Every mutating request should carry an idempotency key, so a retry after a timeout does not enrol someone twice or leave a deletion half-applied.
Webhook verification
Verify the signature on every delivery and treat deliveries as at-least-once. A consumer that is not idempotent on the event identifier will double-count.
Credential scoping
One credential per consuming application, scoped to the operations it needs. A shared key cannot be rotated without an estate-wide outage, so it never is.
Versioning
Know which version you are calling and what changes between them — particularly whether templates remain compatible, since that determines re-enrolment cost.
Auditability
Every call, every enrolment and every deletion recorded with the caller identity. This is what answers a data-subject request or an audit, months later.
Retention
Submitted images, templates, event records and audit entries have different appropriate lifetimes. Configure each explicitly, enforce in software, and log deletion.
API integration checklist
Work through these while requesting access. Several change the deployment design rather than the client code, which is why they belong before the first request rather than after.
-
Decide where the service will sit
Which network segment, what may reach it, and what it may reach. Most of the API’s security properties come from its placement rather than from its code.
-
Scope credentials per caller
One credential per consuming application, scoped to the operations it needs, so a compromised one can be revoked without an estate-wide outage.
-
Plan credential rotation before go-live
How a credential is rotated without downtime. A credential that cannot be rotated will not be rotated.
-
Design idempotency into every write
Enrolment and deletion must tolerate a retry after a timeout without creating duplicates or silently failing. Use an idempotency key on every mutating request.
-
Handle each error class distinctly
Retryable, client error, quality rejection, no match, and service unavailable each deserve a different caller behaviour. One catch-all handler loses the information that decides what to do.
-
Store the threshold with every score
A similarity score without the threshold in force at the time cannot be interpreted afterwards, and afterwards is when someone disputes a decision.
-
Verify webhook signatures and expect duplicates
Treat deliveries as at-least-once, verify the signature on every one, and make the consumer idempotent on the event identifier.
-
Implement backoff and understand the rate limits
Exponential backoff with jitter, and a documented behaviour when limited. A client that retries immediately makes an overload worse.
-
Set retention for each data category
Submitted images, templates, event records and audit entries have different lifetimes. Configure each explicitly and log deletion.
-
Monitor the health check meaningfully
Distinguish "the process is running" from "the engine can match". They fail separately, and only the second one matters to a caller.
Frequently asked questions
Where is the Ayonix face recognition API hosted?
In your environment. It is deployed on-premise, at the edge or in your own private cloud rather than offered as a public multi-tenant endpoint, which means the base URL, the credentials and the data residency all belong to you. This is why no public endpoint reference appears on this page — there is no shared endpoint to document, and the reference is released against your deployment.
Why does this page not list endpoint paths and payloads?
Because no verified public Ayonix API contract was available when it was written, and publishing invented paths would be exactly the fabrication this site refuses elsewhere. What is published instead is the operation set, what each operation needs and returns, and the error and lifecycle model — which is what an engineer needs to design an integration. The endpoint reference, generated from the actual contract, is released with API access.
How does authentication work?
Credentials are issued for your deployment and should be scoped per consuming application rather than shared. Because the service runs inside your network, transport security and network placement do a large part of the work: the API should not be reachable from segments that have no business calling it. The specific authentication scheme for your deployment is confirmed with API access.
Is there an OpenAPI specification or a Postman collection?
Where one is generated from the verified API contract for your deployment, yes — it is released with API access. This site does not publish a downloadable specification, because a specification not generated from a real contract is worse than none: it produces confident client code against endpoints that may not exist.
How are continuous video workflows handled?
As an event-producing workload rather than a request-response one. Submitting frames synchronously in a loop is the wrong shape for continuous video and will not scale. Recognition runs against the stream and produces events, which reach you by webhook in real time and by event retrieval for reconciliation after an outage.
What should a client do when it is rate limited?
Back off exponentially with jitter and respect whatever retry guidance the response carries. A client that retries immediately turns a transient overload into a sustained one. Rate limits exist to protect a shared deployment from one misbehaving caller, and the limits for your deployment are stated with API access.
How is identity deletion handled?
As a first-class operation that produces evidence, not just an acknowledgement. Deleting an identity removes its templates and records the deletion in the audit log, because a data-subject request is answered by demonstrating deletion rather than asserting it. Related event records may have their own retention, and that relationship should be configured deliberately.
Should I use the API or the SDK?
The API when several applications need recognition, when your stack is in a language the SDK does not bind to, or when you would rather operate one service than embed a library in many. The SDK when recognition must run inside your own process for latency or because the video must not leave the application. Many deployments use both — the SDK at the gate, the API for everything behind it.
Related
Where to go next
Face recognition SDK
The in-process route, when latency matters more than language flexibility.
On-premise deployment
Sizing and placing the infrastructure the API runs on.
Security
What this site logs, what it never logs, and how to report a vulnerability.
Privacy and governance
Retention, deletion and data-subject requests as engineering requirements.
Accuracy and testing
Choosing the threshold your integration will store alongside every score.
Integrations
Where a VMS integration is a better fit than calling the API yourself.
Next step
Request API access
Tell us where the service will be deployed, which applications will call it, the expected request volume and whether continuous video is in scope. What comes back is a deployment design and the endpoint reference for it.