Quickstart & API reference.
Authentication, endpoints, request and response shapes, errors and limits — everything to make your first call.
Introduction
The SIMSIM Face API is a REST API for detecting, verifying, identifying and analysing human faces. Every endpoint accepts an image over HTTPS and returns JSON, with the same authentication and error model.
SIMSIM stores irreversible face templates, not the original photos. You are responsible for collecting consent where the law requires it — see regional requirements.
Quickstart
Create a free account
250 requests a month, every endpoint unlocked, no card.
Copy your API token
Keep it server-side and send it as the token header.
Make your first call
POST an image as multipart/form-data and read the JSON back.
Authentication
Send your token in the token header on every request. Never embed it in a mobile app or browser — call SIMSIM from your backend. Missing or invalid tokens return 401.
Endpoints
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/recognize | Face Recognition — Identify enrolled people in a photo (1:N) with a confidence score per match. |
| POST | /v1/verify | Face Verification — Confirm two photos show the same person (1:1) — selfie-to-ID for KYC. |
| POST | /v1/liveness | Liveness Detection — Tell a real, present person from a printed photo, screen replay or mask. |
| POST | /v1/detect | Face Detection — Find every face in an image with bounding boxes and facial landmarks. |
| POST | /v1/attributes | Face Attributes — Estimate age, detect expression and read head pose from a single photo. |
| POST | /v1/persons | Enrol a person's face template into your gallery |
| DELETE | /v1/persons/{id} | Delete a person and all their templates |
Verify (1:1)
Compare two images and get a similarity score and a match decision against your threshold.
# Selfie-to-ID match (1:1) with liveness
curl -X POST https://api.sim-sim.io/v1/verify \
-H "token: YOUR_API_TOKEN" \
-F "photo1=@selfie.jpg" \
-F "photo2=@id_card.jpg"
# → 200 OK
{
"match": true,
"similarity": 0.974,
"liveness": { "live": true, "score": 0.991 }
}Recognize (1:N)
Search a photo against your enrolled gallery. Returns each detected face with the best match, confidence and bounding box.
{
"faces": [
{ "person_id": "p_8Hq2", "name": "ada.lovelace", "confidence": 0.992, "box": [148, 96, 212, 240] }
]
}Liveness
Returns live (boolean) and a score from 0 to 1. Combine it with verification for KYC; learn how liveness works.
Image guidelines
- JPEG or PNG, up to 5 MB; faces at least 100 px wide work best.
- Even, front-facing light; avoid heavy backlight and motion blur.
- Don't crop tightly — include the whole head and some background.
- Resize very large images client-side to cut upload time.
Errors
- 400 — malformed request, unreadable image or no face found.
- 401 — missing or invalid token.
- 413 — image too large.
- 429 — per-minute or monthly limit reached.
- 5xx — retry with exponential back-off.
Rate limits
Each plan sets a transactions-per-minute ceiling and a monthly allowance; exceeding either returns 429. Limits per plan are on the pricing page.
Deleting data
Delete a person with DELETE /v1/persons/{id} — their templates are removed permanently. Build deletion into your account-closure flow to meet retention obligations under BIPA, GDPR and DPDP.
Endpoint names and response fields shown here illustrate the API's shape. Your dashboard reference is authoritative for your account.
Ready to build on faces?
Create a free account, grab your token and make your first recognition call in minutes.