Quickstart & API reference.
Everything you need to make your first call: authentication, endpoints, request and response shapes, errors, and limits.
Introduction
The SIMSIM Face API is a cloud REST API for detecting, comparing, verifying, and analysing human faces. Every endpoint takes an image and returns structured JSON, using the same authentication and response shape.
SIMSIM stores irreversible face templates, never the original photos.
Quickstart
Create a free account
Sign up and get 250 API requests a month, no credit card.
Grab your API token
Find it in your dashboard and keep it secret — send it as the token header.
Make your first call
POST an image to an endpoint and read the JSON response.
Authentication
Send your token in the token request header on every call. Requests without a valid token return 401.
curl -X POST https://api.sim-sim.io/v1/recognize \
-H "token: YOUR_API_TOKEN" \
-F "photo=@customer.jpg"Endpoints
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/recognize | Identify tagged people |
| POST | /v1/verify | 1:1 face match |
| POST | /v1/detect | Locate faces in an image |
| POST | /v1/liveness | Real person vs. spoof |
| POST | /v1/attributes | Age, gender, emotion |
Recognize
Returns each detected face with its matched name, confidence, and bounding box.
{
"faces": [
{ "name": "ada.lovelace", "confidence": 0.992, "box": [148, 96, 212, 240] }
]
}Errors
Errors use standard HTTP status codes with a JSON body describing the problem.
- 400 — the request was malformed or the image was unreadable.
- 401 — missing or invalid API token.
- 429 — you exceeded your plan's throughput or monthly allowance.
Rate limits
Each plan sets a transactions-per-minute ceiling and a monthly request allowance. When you hit either, calls return 429 until the window resets. See pricing for the limits on each plan.
Ready to build on faces?
Create an account, pick your language, follow the quickstart, and make your first recognition call in minutes.