Skip to main content

Quickstart

This guide walks you through the minimal flow: upload a photo, wait for the search to complete, select matches, and read the results. All steps use the production base URL https://dashboard.face2social.com/api/v1.

Prerequisites​

  • A Face2Social account with at least one available credit. See the Authentication guide for sign-up and token retrieval.
  • Optional but recommended: read GET /users/me first. canSearch: false means the user must buy a plan before uploading, and paymentStage tells you which step charges the credit (step 4 or step 5).
  • A JPEG or PNG photo to search with.

Step 1 — Upload the photo​

curl -X POST https://dashboard.face2social.com/api/v1/search/upload \
  -H "Authorization: Bearer <your-token>" \
  -F "file=@/path/to/photo.jpg"

The API responds synchronously with a searchId before any heavy processing starts:

{
  "searchId": "64a7f3c2...",
  "status": "processing",
  "detectedFaces": 1
}

Save the searchId — you will use it in all subsequent steps. detectedFaces: 0 means no face was found in the photo.

Upload never spends a credit. A 402 Payment Required here means the search limit was reached: a user without a subscription has used the free searches and must buy a plan (GET /credits shows searchesUsed / searchesLimit).

Step 2 — Poll the search status​

The search runs asynchronously. Poll GET /search/{searchId}/status until status is completed or preview:

curl https://dashboard.face2social.com/api/v1/search/64a7f3c2.../status \
  -H "Authorization: Bearer <your-token>"

Alternatively, subscribe to real-time status updates via GET /search/{searchId}/status/stream (Server-Sent Events).

Possible status values are processing, preview (an early partial result with a thumbnail), completed, and error (the search failed; see message). Proceed to the next step when the status is completed.

If the status response contains showAgeRestrictionPopup: true, the user must accept the age restriction terms before viewing results. Confirm it with POST /search/{searchId}/age-restriction-consent (returns 204).

Step 3 — Retrieve matches​

curl https://dashboard.face2social.com/api/v1/search/64a7f3c2.../matches \
  -H "Authorization: Bearer <your-token>"

This returns candidate matches grouped by social network (groups, first page each), plus totalCount and maxSelectable — the most matches one select call may carry. Load more matches for one network with GET /search/{searchId}/matches/{source}?cursor=<nextCursor>. Match images are blurred at this stage — this is by design. You must select (confirm) the matches before results are unlocked.

Step 4 — Select matches and deduct a credit​

POST /search/{searchId}/select confirms your intent to view the full results. The request body must include matchIds — the list of match IDs the user selected from the previous step, at most maxSelectable (an empty array means "None of those" for all sources). Selection can be made only once per search; a second call returns 400.

When the user's paymentStage is selection, this step deducts one credit, and returns 402 Payment Required if no credits are available. When it is results, nothing is charged here.

curl -X POST https://dashboard.face2social.com/api/v1/search/64a7f3c2.../select \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"matchIds": ["<matchId>", ...]}'

Step 5 — Get results​

curl https://dashboard.face2social.com/api/v1/search/64a7f3c2.../results \
  -H "Authorization: Bearer <your-token>"

Returns the full, unblurred profile data for the matched profiles. Add ?getSocialprofiler=true to include the Social Profiler report once it is ready (or use GET /search/{searchId}/socialprofiler).

tip

When the user's paymentStage is results, the credit is charged at this step instead of at selection. With no credits the call still returns 200, but with isBlurred: true and masked profile data. See Subscription and Credits for the full paywall matrix.

Search history​

Retrieve past searches with GET /search/history (cursor-paginated: cursor, limit). Get one search with GET /search/{searchId}, and delete it from history with DELETE /search/{searchId}.

Next steps​