The enrolment widget
Let people opt in on your own sign-up or ticket page: two lines of HTML and one server call.
The widget is FacePing's own page (faceping.ai/enroll) shown inside your sign-up, ticket or welcome page. It shows your name and privacy notice, collects the person's consent in their own hands, takes the selfie and enrols them. The photo goes straight from the person's browser to FacePing (it never reaches your servers) and is discarded once the face template is made.
Before you start#
Once your account is live, set your details once, in Dashboard → Settings: your organisation name (the name people know you by: your venue, gym, company or brand), a link to your face check-in privacy notice, and optionally a brand colour. Every list's widget uses them. FacePing won't create tokens until the organisation name and privacy notice link are set, so no one is ever asked to consent without a notice to read.
In the sandbox, set them on your practice list instead (account-wide details are a live setting): fill them in when you create the list in the dashboard (the New list form asks for them), or later open the list's Enrol people tab and choose Change for this list, or call POST /v1/lists/{listId}/widget with your sandbox key. The enrolment page then works exactly as it will live, with a "Sandbox test" banner, and each face is deleted 24 hours after enrolment. The consent wording on a practice list says so too: the person agrees to their face being kept for 24 hours, for a sandbox test.
Need something different for one list (a festival run under another brand, or a second site, say)? Override any of the three for that list only: open the list's Enrol people tab and choose Change for this list, or use the API. The API call merges: a field you leave out (or send as null) stays as it is, so you can change just the colour. Send a field as an empty string to clear it and fall back to your account settings again (in the sandbox there are none, so enrolment links need the organisation name and privacy link set):
POST /v1/lists/{listId}/widget →
1. Create an enrolment link on your server#
An enrolment link holds a token (fpe_…) that lets one person enrol once, for one personId (your ID for them: a ticket number or membership number). Create it when you render the confirmation page (it's valid for 30 minutes):
curl -X POST https://api-eu.faceping.ai/v1/lists/$LIST_ID/enrollment-links \
-H "X-Api-Key: $FACEPING_API_KEY" -H "Content-Type: application/json" \
-d '{ "personId": "ACME-000123" }'
POST /v1/lists/{listId}/enrollment-links →
Your API key stays on your server. The token is safe to put in the page: it can only enrol that one person, once, and expires.
2. Embed it#
<div data-faceping-token="fpe_…"></div>
<script src="https://faceping.ai/widget.js" async></script>
The loader replaces the div with an iframe that resizes itself. To mount it yourself (for example in a single-page app, after fetching the token):
FacePing.mount(document.getElementById("face-checkin"), token);
3. Listen for the result#
The container fires DOM events you can use to update your own records:
| Event | When |
|---|---|
faceping:ready |
The widget loaded and shows the consent step |
faceping:enrolled |
The person is enrolled for face check-in |
faceping:declined |
The person chose to check in without their face |
faceping:error |
The token was invalid or expired, or the list is full (event.detail.message; event.detail.reason is "full" for a full list) |
document.addEventListener("faceping:enrolled", () => markTicket("face"));
document.addEventListener("faceping:declined", () => markTicket("standard"));
What people see#
- Consent: your organisation name, the list name and the consent wording for the list's country (with when the face is deleted filled in: which wording), a link to your privacy notice, an "under 16" option that asks for a parent or guardian, and "No thanks, I'll use the usual way in" as a button the same size and weight as "Continue".
- Camera: a live view with a face guide (front camera), or "Upload a photo instead". "No thanks, I'll use the usual way in" is here too. Saying no doesn't use up the link: the person can open it again and enrol until it expires.
- Check: "Happy with this photo?", retake or send. Unusable photos (no face, two faces, too small) are explained and can be retaken, up to 5 attempts per token.
- Done: "You're all set", plus when their face data will be deleted.
If the list is full by the time someone opens a link sent earlier, the page says "Face check-in is full for this list. Please use the usual way in." before the consent step, and fires faceping:error with reason: "full". Nobody is asked to consent or take a photo for a place they can't have.
Enrolment links#
No website changes needed: send the person a link instead. Open the list's Enrol people tab, choose Send a link, enter their Person ID (a ticket or membership number), pick how long it's valid and copy the link. From your server, pass validForHours (up to 336, never past the end of a list with an end date) and send the returned url:
curl -X POST https://api-eu.faceping.ai/v1/lists/$LIST_ID/enrollment-links \
-H "X-Api-Key: $FACEPING_API_KEY" -H "Content-Type: application/json" \
-d '{ "personId": "ACME-000123", "validForHours": 168 }'
Links work once and only for that person's ID. Send each one only to the person it's for.
Your website's security policy#
If your site sends a Content-Security-Policy header, allow the widget:
script-src https://faceping.ai;
frame-src https://faceping.ai;
The iframe asks for the camera (allow="camera"); nothing else on your page gets access to it.