Skip to content
Fotobots Partner Docs

Face Search for Race Timing Apps

The .fotobots.dev addresses on this page are staging examples. Use the URL and API key for your own environment.

This guide explains how to integrate facial recognition search into your runner results portal or mobile app. Runners take a selfie, and Fotobots returns all matched race photos in sub-second time.

The 2-Step Search Workflow

  1. Step 1: Upload the runner’s selfie (probe image) to obtain a temporary imageId.
  2. Step 2: Query the album index using the probe imageId to retrieve matching photos.

Step 1: Upload Selfie Probe Image

Request a signed upload slot for the probe face:

Terminal window
curl -X POST https://api.fotobots.dev/openapi/photos/search/face/signed \
  -H "Content-Type: application/json" \
  -H "x-api-key: fb_test_YOUR_KEY" \
  -d '{
    "albumId": "d3b07384-d113-4a37-b4d6-f3ec0a4b7f8c"
  }'

Response

{
  "uploadUrl": "https://storage.example.com/probe?X-Amz-Signature=...",
  "imageId": "probe_face_uuid_789"
}

Upload the runner’s selfie image binary to the uploadUrl:

Set UPLOAD_URL to the signed uploadUrl returned by the API, then run:

Terminal window
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/jpeg" \
  --data-binary "@selfie.jpg"

Query the album index using the imageId:

Terminal window
curl -X POST https://api.fotobots.dev/openapi/photos/search/face/list \
  -H "Content-Type: application/json" \
  -H "x-api-key: fb_test_YOUR_KEY" \
  -d '{
    "albumId": "d3b07384-d113-4a37-b4d6-f3ec0a4b7f8c",
    "imageId": "probe_face_uuid_789"
  }'

Response

{
  "photos": [
    {
      "id": "photo_uuid_101",
      "url": "https://cdn.example.com/preview/photo_uuid_101.jpg",
      "thumbnailUrl": "https://cdn.example.com/thumb/photo_uuid_101.jpg",
      "confidence": 0.985,
      "boundingBox": {
        "top": 210,
        "left": 450,
        "width": 120,
        "height": 150
      }
    }
  ],
  "total": 1
}

The storage URLs above are examples. Use the signed URL returned by the API; do not construct it yourself.