faceping.aidocs

API quickstart

From a sandbox key to a person enrolled and checked in on a device, in a handful of calls.

You can follow this with your sandbox key (fp_test_, from Dashboard → Developers → Sandbox keys), free and before you apply: it works on one practice list in your sandbox. Once you're live, use an API key from the same page instead (fp_…), within your plan's limits (the free pilot is one list and up to 500 people; paid plans have no list or people limits). Every step below works in both.

The practice list. With a sandbox key you get one check-in list at a time (delete it to start another), up to 25 people, 1:1 verification (Verify) only, and each face is deleted 24 hours after it was enrolled. Nothing is billed. Enrolment links, the widget and check-in devices all work, and the enrolment page shows a "Sandbox test" banner. Your sandbox's list is separate from your live lists: a sandbox key never sees live lists, and an API key never sees the practice list.

Set it in your shell:

export FACEPING_API_KEY="fp_test_…"   # your sandbox key; once you're live, an API key (fp_…)
export FACEPING="https://api-eu.faceping.ai"

Every call goes to https://api-eu.faceping.ai (hosted in the EU; UK and US regions on request) with the key in the X-Api-Key header. Live API keys (fp_) belong on your server: never put one in a web page, an app or a device. The widget and devices use their own short-lived, single-purpose tokens. Your sandbox key (fp_test_) is the one exception: it goes in test apps too, and it also works here on your practice list, so keep test apps within your team and revoke the key under Developers if it leaks.

1. Create a check-in list#

A check-in list (a "list" for short) is a set of people you'll verify. Everyone you enrol belongs to a list. There are two kinds:

Kind For example Faces are deleted
With an end date A show, a festival, a course 0 to 30 days after the list ends (retentionDays, default 7), on the server and every device
Ongoing (no end date) Gym members, visitors Each person's face at most maxAgeMonths (1 to 36) after they enrolled, or sooner when you remove them

A list with an end date:

curl -X POST $FACEPING/v1/lists \
  -H "X-Api-Key: $FACEPING_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Autumn Live",
    "startsAt": "2026-11-20T18:00:00Z",
    "endsAt":   "2026-11-20T23:00:00Z",
    "alternativeEntryAvailable": true,
    "retentionDays": 7,
    "country": "GB"
  }'

An ongoing list, say a gym's members, leaves out endsAt and says how long to keep each face instead:

curl -X POST $FACEPING/v1/lists \
  -H "X-Api-Key: $FACEPING_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Riverside Gym members",
    "maxAgeMonths": 12,
    "alternativeEntryAvailable": true,
    "country": "GB"
  }'

maxAgeMonths is required for an ongoing list (the dashboard suggests 12). Each member's face is then deleted 12 months after they enrolled (logged as MaxAgeReached), or sooner if you remove them. They can simply enrol again, which starts their 12 months afresh. FacePing doesn't track when people check in (checks happen offline on the device and are never sent to us), so the clock runs from enrolment, not last visit.

Send either endsAt or maxAgeMonths, not both. startsAt is optional (it defaults to now), and retentionDays only applies to lists with an end date. Enrolment opens as soon as the list exists, even before startsAt, and closes when the list ends: if you copy the dated example, change its dates, or try the ongoing one.

Save the returned id: it's the listId in every other call. Copy it from the response into your shell (or, with jq, add | jq -r .id to the create call and wrap it: export LIST_ID=$(curl … | jq -r .id)):

export LIST_ID="paste-the-id-here"

Every POST and PATCH with a body needs -H "Content-Type: application/json"; without it the API answers 415. alternativeEntryAvailable must be true: people always need a way to check in without their face. (In the dashboard, a live account confirms this once, with a tick on its first New list form, for all its lists.) matchMode defaults to Verify (the device checks the face against the person whose ID was scanned, and no one else). Once you're live, leave out retentionDays or matchMode to use your account defaults from Dashboard → Settings (7 days and Verify unless you change them). With a sandbox key, the response has sandbox: true: every face on a practice list is deleted 24 hours after enrolment, whatever you sent, so the list's retentionDays, maxAgeMonths and deleteAfter come back null, and each person's deleteAfter says when. The sandbox has one practice list per account, so a second create gets 409. If someone on your team already made it, use theirs rather than deleting it:

export LIST_ID=$(curl -s $FACEPING/v1/lists -H "X-Api-Key: $FACEPING_API_KEY" | jq -r '.[0].id')

A practice list with an end date still stops taking enrolments when it ends, so an ongoing one (the dashboard's default) is easiest to come back to.

country is where people check in, as a 2-letter ISO 3166-1 code (GB, IE, FR, US and so on). It decides the consent wording people see: US gets the US biometric data release, EU and EEA countries the EU wording, and anywhere else (the UK included) the UK wording. Leave it out and the list follows your account's country. The response includes consentVersion, the wording that applies. You can rename the list or change its country with PATCH /v1/lists/{listId} (for example {"name": "Autumn Live 2026"}) until the first person enrols; after that both are fixed, because everyone on a list agrees to the same wording, and it names the list.

POST /v1/lists →

2. Set up the widget#

Tell people who you are and link your face check-in privacy notice (template). Once you're live, do this once, in Dashboard → Settings: every list uses it.

To use different details for one list only, set them on that list. The call merges: fields you leave out (or send as null) stay as they are, and an empty string clears one so the list falls back to your account settings. In the sandbox, set them here: account-wide details are a live setting, so the practice list needs its own before you can create enrolment links. (If you create the practice list in the dashboard, the New list form asks for them, and leaves out retention and 1:N: a practice list is always 1:1, with each face deleted 24 hours after enrolment.)

curl -X POST $FACEPING/v1/lists/$LIST_ID/widget \
  -H "X-Api-Key: $FACEPING_API_KEY" -H "Content-Type: application/json" \
  -d '{ "organizationName": "Acme Live", "privacyUrl": "https://acme.example/face-privacy", "brandColor": "#0066ff" }'

POST /v1/lists/{listId}/widget →

When someone signs up, joins or buys a ticket, your server creates a single-use enrolment link for them (201 Created). personId is your ID for the person: a ticket number or membership number.

curl -X POST $FACEPING/v1/lists/$LIST_ID/enrollment-links \
  -H "X-Api-Key: $FACEPING_API_KEY" -H "Content-Type: application/json" \
  -d '{ "personId": "ACME-000123" }'
# → { "token": "fpe_…", "expiresAt": "…", "url": "https://faceping.ai/enroll#t=fpe_…" }

POST /v1/lists/{listId}/enrollment-links →

A link is valid for 30 minutes, right for showing the widget on your confirmation page. For a link you email or text, pass validForHours (up to 336) in the request.

A full list refuses new links with 409: 25 people on a practice list (on the pilot, 500). A link sent earlier that's opened once the list is full shows "Face check-in is full for this list. Please use the usual way in." before the consent step, so nobody consents or takes a photo for a place they can't have.

4. Show the widget#

On your confirmation or welcome page:

<div data-faceping-token="fpe_…"></div>
<script src="https://faceping.ai/widget.js" async></script>

The person ticks the consent boxes, takes a selfie and they're enrolled. No photo touches your servers. Or simply open the token's url in a browser to try it yourself.

5. Check who's enrolled#

curl $FACEPING/v1/lists/$LIST_ID/people -H "X-Api-Key: $FACEPING_API_KEY"
# → { "total": 1, "page": 1, "people": [ { "personId": "ACME-000123", "enrolledAt": "…", "source": "Widget", … } ] }

curl $FACEPING/v1/lists/$LIST_ID/people/ACME-000123 -H "X-Api-Key: $FACEPING_API_KEY"   # one person, or 404

GET /v1/lists/{listId}/people →

Enrol someone from your server#

If you collect the photo and consent yourself, enrol from your server instead of the widget. Show the person the list's exact wording first: GET /v1/lists/$LIST_ID/consent returns it filled in, with its consentVersion. To try it, use a selfie of yourself (or of a colleague who has agreed), a JPEG or PNG. This builds the request with jq, reading the list's consentVersion first (the version must match the wording the person saw; it needs the list's organisation name and privacy link from step 2). It uses the same person as the link above, so step 7 works whichever way you enrolled them (enrolling someone again replaces their face):

base64 -i me.jpg > me.b64      # macOS. On Linux: base64 -w0 me.jpg > me.b64
CV=$(curl -s $FACEPING/v1/lists/$LIST_ID/consent -H "X-Api-Key: $FACEPING_API_KEY" | jq -r .consentVersion)
jq -n --rawfile img me.b64 --arg cv "$CV" '{
  personId: "ACME-000123",
  imageBase64: ($img | gsub("\\s"; "")),
  consent: { consentVersion: $cv, givenAt: (now | todate), explicitBiometricConsent: true }
}' | curl -X POST $FACEPING/v1/lists/$LIST_ID/people \
  -H "X-Api-Key: $FACEPING_API_KEY" -H "Content-Type: application/json" --data-binary @-
# → 201 { "personId": "ACME-000123", "modelId": "…", "deleteAfter": "…" }

givenAt is when the person agreed (required). Enrolment takes a few seconds, as the photo is turned into a face template and then discarded: set your HTTP client's timeout to 30 seconds or more. Requests over 15 MB get 413. The full rules, including under-16s and the US written release, are in Server-side enrolment.

GET /v1/lists/{listId}/consent →

POST /v1/lists/{listId}/people →

6. Add a check-in device#

A check-in device gets its own read-only token for this one list (201 Created). Keep the token: it's shown once.

curl -X POST $FACEPING/v1/lists/$LIST_ID/devices \
  -H "X-Api-Key: $FACEPING_API_KEY" -H "Content-Type: application/json" \
  -d '{ "label": "North entrance, lane 2" }'
# → { "id": "…", "label": "North entrance, lane 2", "prefix": "fpd_…", "token": "fpd_…", "expiresAt": … }
# On a practice list, expiresAt is null: the token lasts until you revoke it or delete the list.
export DEVICE_ID="paste-the-id-here"     # the device's id, for revoking it in step 8
export DEVICE_TOKEN="paste-the-token-here"

curl $FACEPING/v1/lists/$LIST_ID/devices -H "X-Api-Key: $FACEPING_API_KEY"     # lastSyncAt shows when each device last synced

POST /v1/lists/{listId}/devices →

Check the token works before it goes into an app. It takes the device token in its own header (not X-Api-Key), downloads no faces and doesn't count as a sync:

curl $FACEPING/v1/device -H "X-Device-Token: $DEVICE_TOKEN"
# → { "deviceId": "…", "label": "North entrance, lane 2", "listId": "…", "listName": "Autumn Live", "sandbox": true, "peopleEnrolled": 1, "expiresAt": null, "lastSyncAt": null }

A mistyped or revoked token, or one whose list has been deleted, gets 401. The message says if a token was revoked; once a list is deleted its tokens go with it, so a deleted list's token reads the same as a mistyped one.

GET /v1/device →

7. Check the person in on the device#

Put the device token in your app instead of the sandbox key, run it, and verify the person you enrolled (through the link or from your server) by their personId, ACME-000123. The code for every platform (setting the token, syncing and showing what arrived, verifying a person) is in Devices and offline sync. The device syncs the list's faces when it starts and works offline from then on.

Each Get started guide ends with this step for its platform: .NET MAUI, Avalonia, Android, iOS, Flutter, React Native and Capacitor. All seven starter apps also run as check-in devices, with two settings: the device token and the person to verify (see each README).

Optional: check the result on your server. The device signs every result it returns. Copy the result's signedResult (log it from your app) and send it to FacePing with your sandbox key, to see what your server would get:

curl -X POST "$FACEPING/v1/check-results/verify" \
  -H "X-Api-Key: $FACEPING_API_KEY" -H "Content-Type: application/json" \
  -d '{"signedResult":"PASTE_IT_HERE"}'

It answers with the person, the outcome and the device, once: a second try is 409 replayed. In your own app, pass your server's nonce to the check too. See Signed check results.

8. Remove a person, revoke a device, start again#

Remove one person (withdrawn consent, an erasure request): their face goes at once, and devices drop it at their next sync. Revoke a device you no longer use: it wipes its copy at its next sync.

curl -X DELETE $FACEPING/v1/lists/$LIST_ID/people/ACME-000123 -H "X-Api-Key: $FACEPING_API_KEY"   # 204, or 404 if they're not on the list
curl -X DELETE $FACEPING/v1/lists/$LIST_ID/devices/$DEVICE_ID -H "X-Api-Key: $FACEPING_API_KEY"   # 204 (DEVICE_ID from step 6)

DELETE /v1/lists/{listId}/people/{personId} →

DELETE /v1/lists/{listId}/devices/{deviceId} →

To clear the practice list and try again (or to make room for a different one), delete it. This deletes every face on it at once, and devices wipe their copy at their next sync:

curl -X DELETE $FACEPING/v1/lists/$LIST_ID -H "X-Api-Key: $FACEPING_API_KEY"   # 204; a second delete gets 404, as the list is gone

DELETE /v1/lists/{listId} →

That's the whole flow. Next, embed the widget properly and read Devices and offline sync. Framework-specific code is in Examples.