Skip to content
Fotobots Partner Docs

Face Search for Race Timing Apps

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://sandbox-api.fotobots.run/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.fotobots.run/r2/probe?X-Amz-Signature=...",
  "imageId": "probe_face_uuid_789"
}

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

Terminal window
curl -X PUT "https://storage.fotobots.run/r2/probe?X-Amz-Signature=..." \
  -H "Content-Type: image/jpeg" \
  --data-binary "@selfie.jpg"

Query the album index using the imageId:

Terminal window
curl -X POST https://sandbox-api.fotobots.run/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.fotobots.run/preview/photo_uuid_101.jpg",
      "thumbnailUrl": "https://cdn.fotobots.run/thumb/photo_uuid_101.jpg",
      "confidence": 0.985,
      "boundingBox": {
        "top": 210,
        "left": 450,
        "width": 120,
        "height": 150
      }
    }
  ],
  "total": 1
}