---
updatedAt: 2026-04-23T14:31:17.000Z
agentTools:
  projectIndex: https://docs.bynn.com/llms.txt
---

# Enroll a face into a collection

Enroll a single face into a collection by providing an image URL, base64-encoded image, or a file upload (multipart/form-data). The image must contain exactly one face. If no face or multiple faces are detected, an error is returned. You can optionally provide a name, external_id, and metadata for the enrolled face.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "BYNN API",
    "description": "The BYNN API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website’s client-side code). JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects. To make the API as explorable as possible, accounts have test mode and live mode API keys. There is no “switch” for changing between modes, just use the appropriate key to perform a live or test transaction. Requests made with test-mode credentials never hit live networks and incur no cost. **AUTHENTICATION:** Please use your **Private API Key** that looks like this `private_Nv7UpwQbSmWtUTiSWfw1bdHm` as the username and password in HTTP basic auth.",
    "termsOfService": "https://bynn.com/terms",
    "contact": {
      "name": "BYNN Development Team",
      "email": "hello@bynn.com",
      "url": "https://docs.bynn.com"
    },
    "license": {
      "name": "BYNN Documentation",
      "url": "https://docs.bynn.com"
    },
    "version": "1.0"
  },
  "tags": [
    {
      "name": "Face Enrollment",
      "description": "Operations about Face Enrollments"
    }
  ],
  "paths": {
    "/face-collections/{token}/enroll": {
      "post": {
        "summary": "Enroll a face into a collection",
        "description": "Enroll a single face into a collection by providing an image URL, base64-encoded image, or a file upload (multipart/form-data). The image must contain exactly one face. If no face or multiple faces are detected, an error is returned. You can optionally provide a name, external_id, and metadata for the enrolled face.",
        "parameters": [
          {
            "in": "path",
            "name": "token",
            "description": "Collection token (e.g. fc_abc123)",
            "required": true,
            "example": "fc_abc123def456",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/postFaceCollectionsTokenEnroll"
              }
            }
          },
          "required": true
        },
        "security": [
          {
            "PrivateKey": []
          }
        ],
        "responses": {
          "201": {
            "description": "Enroll a face into a collection",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Bynn_V1_Entities_FaceEntity"
                }
              }
            }
          },
          "400": {
            "description": "No face detected or multiple faces detected in image"
          },
          "401": {
            "description": "Unauthorized - Invalid or missing API key"
          },
          "404": {
            "description": "Collection not found"
          },
          "422": {
            "description": "Validation error - Invalid input"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        },
        "tags": [
          "Face Enrollment"
        ],
        "operationId": "postFaceCollectionsTokenEnroll"
      }
    }
  },
  "servers": [
    {
      "url": "//api.bynn.com/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "PrivateKey": {
        "type": "apiKey",
        "name": "Authorization",
        "in": "header",
        "description": "Enter your PRIVATE KEY token prefixed with `Bearer `, e.g. `Bearer your_token_here`"
      }
    },
    "schemas": {
      "postFaceCollectionsTokenEnroll": {
        "type": "object",
        "properties": {
          "image_url": {
            "type": "string",
            "description": "URL of the image containing a face",
            "example": "https://example.com/photo.jpg"
          },
          "base64_image": {
            "type": "string",
            "description": "Base64 strict encoded image data (max 20MB decoded)"
          },
          "file": {
            "type": "string",
            "format": "binary",
            "description": "Image file upload (multipart/form-data, max 20MB)"
          },
          "name": {
            "type": "string",
            "description": "Name or label for the enrolled face (max 255 characters)",
            "example": "John Doe"
          },
          "external_id": {
            "type": "string",
            "description": "External reference ID for your system (max 255 characters)",
            "example": "emp_12345"
          },
          "metadata": {
            "type": "object",
            "description": "Additional metadata to store with the face (max 16KB)",
            "example": {
              "department": "Engineering"
            }
          }
        },
        "description": "Enroll a face into a collection"
      },
      "Bynn_V1_Entities_FaceEntity": {
        "type": "object",
        "properties": {
          "face_id": {
            "type": "string",
            "example": "face_abc123def456",
            "description": "Unique face identifier with face_ prefix"
          },
          "name": {
            "type": "string",
            "example": "John Doe",
            "description": "Name or label for the enrolled face"
          },
          "external_id": {
            "type": "string",
            "example": "emp_12345",
            "description": "External reference ID for integration with your system"
          },
          "category": {
            "type": "string",
            "example": "celeb_sport",
            "description": "Face category (celeb_sport, celeb_movie, celeb_other, unknown)"
          },
          "metadata": {
            "type": "object",
            "example": {
              "department": "Engineering"
            },
            "description": "Additional metadata associated with the face"
          },
          "created_at": {
            "type": "string",
            "example": "2024-01-15T10:30:00Z",
            "description": "When the face was enrolled (ISO 8601)"
          }
        },
        "required": [
          "face_id",
          "name",
          "external_id",
          "category",
          "metadata",
          "created_at"
        ],
        "description": "Bynn_V1_Entities_FaceEntity model"
      }
    }
  }
}
```