Skip to main content

Overview

Face Search is the API surface for 9Pic FaceFind, our AI face recognition photo search. Upload a participant’s selfie and the API returns paginated photos that match the selfie above the event’s confidence threshold.
Building a participant-facing gallery or search app? Follow the Participant App guide (coding agents get it in the 9pic-integration skill): call the API only from your backend, save each search ID, check Event Details first, keep one search identifier per search, and show previews rather than originals.
Each search is identified by a request_id (UUID). You can:
  • Omit request_id and let 9Pic generate one. The generated UUID is returned in the response so you can re-fetch the same results later without re-uploading the selfie.
  • Pass an existing request_id to retrieve cached results without re-running face matching.
Selfie/face search must be enabled for the event. Check the selfie_search flag from Event Details before calling this.

Why request_id Matters

A face search is expensive on our side and yours. Each POST /faces triggers an image upload, face matching against the event’s face index, confidence filtering, and a persisted result row. The request_id is what lets you do this work exactly once per user-intent and reuse the result everywhere else. Treat request_id as the canonical identifier for a single selfie search, not as a session token. The full idempotency model is documented in Conventions.

What problem it solves

How it optimises your system

  • Safe retries. If the connection drops after POST /faces completed, the same request_id returns the stored result — no second face match and no duplicate upload. A request_id keeps its first stored result: if the POST failed or face matching returned no match, a repeat POST with that id returns the same empty result. Start a fresh search (omit request_id, or send a new one) to try again.
  • Cheap pagination. Keep the saved request_id in your URL. Every page change becomes a GET /faces/{request_id}?page=N&page_size=32 instead of a re-search.
  • Decouple search trigger from result rendering. Your upload screen does the POST and stashes request_id. Your results screen, share screen, and download screen all read from GET /faces/{request_id}. None of them need the selfie file.
  • Stable, shareable references. A request_id lets your backend log, audit, retry, or reconcile a specific selfie search without storing the user’s selfie image.
  • Avoid rate limiting. External API calls that perform face matching are subject to stricter limits than read-only calls. Reusing request_id shifts your traffic from POST /faces (rate-limited, billable compute) to GET /faces/{request_id} (cheap reads), keeping integrations comfortably under quota even at peak.
1

POST once

Your backend generates a UUID, saves it with the event and your user or session, and sends it as request_id with the selfie in POST /faces. (You can omit request_id and save the one in the response instead.) Put the same ID in your frontend URL. See Save the Search ID.
2

GET many

Every subsequent action that needs results (pagination, refresh, deep-link, share) calls GET /faces/{request_id}?page=N&page_size=32.
3

Retry safely

After a dropped connection, call GET /faces/{request_id} with the id you sent. If the search completed, the stored result comes back. If the POST failed or returned an empty result, start a fresh search: that request_id keeps its empty result.
4

Hand off to download

Pass request_id as identifier (with method: "selfie") to Download Original Photos. No new search is needed.
Persist request_id in your URL (e.g. /results/:request_id). It survives refreshes, deep-links, and share intents without re-uploading the selfie.
A new POST /faces (with a fresh request_id) is treated as a new billable face search. Avoid issuing fresh POSTs on every page change, refresh, or component remount.

Endpoints

POST /faces — Upload a Selfie

Uploads a selfie image and returns the matching event photos.

Path Parameters

Query Parameters

Results are paginated. See the Pagination Model.

Multipart Form Fields

Example Request

To reuse an existing request_id, add -F "request_id=<uuid>" (cURL), include it in data={"request_id": "<uuid>"} (Python), or formData.append("request_id", "<uuid>") (JavaScript).

Example Response

Returns the cached result for a previous selfie search using its request_id. Useful for paging through results or refreshing a UI without re-uploading the selfie.

Path Parameters

Query Parameters

Results are paginated. See the Pagination Model.

Example Request

Example Response

The response shape is identical to POST /faces. Use the same model and the same Matches Found / No Matches payloads above.

Response Models

original_url is null in the standard face search response.
Use the request_id from this response with Download Original Photos (method: "selfie") to fetch presigned download links for the matched originals.

Error Responses

See Errors for canonical descriptions and retry guidance.