This guide walks you from a blank slate to your first successful face identification call in under 10 minutes.

The process has two distinct phases:

Prerequisites

• A FR-APIaaS account: sign up for free.
• curl or any HTTP client (Postman, Insomnia, etc.).

Step 1: Create an account

Sign up for a FR-APIaaS account. After verifying your email you will land in the dashboard where all setup steps take place.

Step 2: Create a collection

In the dashboard, go to Collections and click New Collection. Give it a name (e.g. employees) and save. Note the collection ID shown on the detail page. Your application will use this ID in every API request.

Step 3: Issue an API key

Go to API Keys in the dashboard and click New Key. Select the collection you just created and give the key a name (e.g. production-server). Copy the key value shown. It is only displayed once and cannot be retrieved later. Store it in your environment variables or secrets manager.

# Store as an environment variable — never hard-code in source
export FR_API_KEY="fr_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export FR_COLLECTION_ID="col_01j8zxk..."

Step 4: Enroll a face

From your application, use the API key to enroll faces. No login required, just the key in the X-API-Key header. The external_id links the face to your own user or record identifier.

curl -X POST https://your-domain.com/api/v1/collections/COLLECTION_ID/faces \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "image=@alice.jpg" \
  -F "external_id=user_alice_001" \
  -F 'metadata={"name":"Alice Smith","department":"Engineering"}'

{
  "success": true,
  "data": {
    "face_id": "face_01j9...",
    "external_id": "user_alice_001",
    "quality_score": 0.94,
    "liveness_score": 0.98,
    "created_at": "2024-01-15T10:05:00Z"
  }
}

Step 5: Identify a face

Search the collection for the top-K matching faces. The API returns a list of matches sorted by similarity score.

curl -X POST https://your-domain.com/api/v1/collections/COLLECTION_ID/identify \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "image=@query.jpg" \
  -F "top_k=3" \
  -F "threshold=0.55"

{
  "success": true,
  "data": {
    "matches": [
      {
        "face_id": "face_01j9...",
        "external_id": "user_alice_001",
        "similarity": 0.97,
        "metadata": {"name": "Alice Smith", "department": "Engineering"}
      }
    ],
    "query_time_ms": 42
  }
}

A similarity score above 0.55 is typically a confident match. Tune the threshold based on your use-case security requirements: higher for stricter access control, lower for more permissive matching.

Try it now

Use the playground below to run a live identification request against your own collection. Enter your API key and collection ID in Settings, upload a photo, and hit Send.

What's next?

• Read Authentication to understand the two auth modes (JWT vs API Key).
• See Verification for 1:1 face comparison.
• Set up Webhooks to receive real-time events.