> ## Documentation index > Fetch the complete documentation index at: https://developer.rhombus.com/llms.txt > Use it to discover all available pages before exploring further. # Upload face matchmakers > Upload face matchmaker images for one or more people. The uploaded file name is matched to a person's name. If a person is not found and createPersonIfNotFound is set to true, a new person is created. ```http POST https://api2.rhombussystems.com/api/faceRecognition/matchmaker/uploadFaceMatchmakers ``` EU organizations send the same request to `https://api2.eu.rhombussystems.com`. ## Authentication and parameters - `x-auth-apikey` (header, required): Your Rhombus API key. Must be accompanied by the `x-auth-scheme` header set to `api-token` (or `partner-api-token` for partner endpoints). - `Authorization` (header): instead of an API key, an OAuth access token (`Bearer `) with the `write` scope. - `transaction` (query, string | null): Unique transaction id to track the face matchmakers upload progress. If not specified, the system will generate it. - `createPersonIfNotFound` (query, boolean | null): If a person is not found and createPersonIfNotFound is set to true, a new person is created - `x-auth-scheme` (header, string, default: `api-token`): Authentication scheme identifier. Use `api-token` or `partner-api-token` with the `x-auth-apikey` header, `api` or `partner-api` with `x-auth-apikey` plus a client certificate, `api-oauth-token` or `partner-api-oauth-token` with `x-auth-access-token`, and `federated-token` with `x-auth-ft`. A request with `Authorization: Bearer ` and no `x-auth-scheme` is treated as OAuth, and `federated-token` may also be sent as the `x-auth-scheme` and `x-auth-ft` query parameters. One of: `api-token`, `api`, `api-oauth-token`, `federated-token`, `partner-api-token`, `partner-api`, `partner-api-oauth-token`. - `x-auth-org` (header, string): Client organization UUID (22-character RUUID), for partner credentials only. With it the call runs in that client organization with the partner support authority's role. Without it a partner credential runs as the partner organization, which outside the partner endpoints is deprecated (responses carry `Deprecation` and `Sunset: Tue, 05 Jan 2027 00:00:00 GMT`). A malformed value returns 400 `INVALID_AUTH_ORG`; a client organization the partner cannot access returns 403 `PARTNER_CLIENT_ACCESS_DENIED`. ## Response 200 OK. Content type: `application/json` - `fileUploadResults` (array | null): List of file upload results for each uploaded face matchmaker - `transactionId` (string | null): Transaction ID to track face matchmakers upload progress ## Errors Also 400, 401, 403, 429, 500, 503 with the standard error body (`errorCode`, `errorMsg`): https://developer.rhombus.com/errors ## OpenAPI ````yaml openapi: 3.0.1 info: title: Rhombus API version: "1.0" servers: - description: Production Server url: https://api2.rhombussystems.com security: - ApiKeyAuth: [] paths: /api/faceRecognition/matchmaker/uploadFaceMatchmakers: post: description: "Upload face matchmaker images for one or more people. The uploaded file name is matched to a person's name. If a person is not found and createPersonIfNotFound is set to true, a new person is created. " operationId: uploadFaceMatchmakers parameters: - description: Unique transaction id to track the face matchmakers upload progress. If not specified, the system will generate it. in: query name: transaction schema: nullable: true type: string - description: If a person is not found and createPersonIfNotFound is set to true, a new person is created in: query name: createPersonIfNotFound schema: nullable: true type: boolean - description: "Authentication scheme identifier. Use `api-token` or `partner-api-token` with the `x-auth-apikey` header, `api` or `partner-api` with `x-auth-apikey` plus a client certificate, `api-oauth-token` or `partner-api-oauth-token` with `x-auth-access-token`, and `federated-token` with `x-auth-ft`. A request with `Authorization: Bearer ` and no `x-auth-scheme` is treated as OAuth, and `federated-token` may also be sent as the `x-auth-scheme` and `x-auth-ft` query parameters." example: api-token in: header name: x-auth-scheme required: false schema: default: api-token enum: - api-token - api - api-oauth-token - federated-token - partner-api-token - partner-api - partner-api-oauth-token type: string - description: "Client organization UUID (22-character RUUID), for partner credentials only. With it the call runs in that client organization with the partner support authority's role. Without it a partner credential runs as the partner organization, which outside the partner endpoints is deprecated (responses carry `Deprecation` and `Sunset: Tue, 05 Jan 2027 00:00:00 GMT`). A malformed value returns 400 `INVALID_AUTH_ORG`; a client organization the partner cannot access returns 403 `PARTNER_CLIENT_ACCESS_DENIED`." in: header name: x-auth-org required: false schema: format: RUUID maxLength: 22 minLength: 22 type: string requestBody: content: multipart/form-data: schema: type: object properties: file: type: string format: binary description: A .jpg or .png image named after the person. Repeat the part for each image. required: - file description: "Multipart form-data containing a .jpg or .png file. Maximum file size: 5MB." responses: "200": content: application/json: schema: $ref: "#/components/schemas/Facerecognition_matchmaker_UploadFaceMatchmakersWSResponse" description: OK "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "429": $ref: "#/components/responses/TooManyRequests" "500": $ref: "#/components/responses/InternalServerError" "503": $ref: "#/components/responses/ServiceUnavailable" security: - ApiKeyAuth: [] - oauth2: - write summary: Upload face matchmakers tags: - Face Recognition Matchmaker Webservice components: schemas: Facerecognition_matchmaker_UploadFaceMatchmakersWSResponse: description: Response object for uploading face matchmakers with transaction tracking and upload results. properties: fileUploadResults: description: List of file upload results for each uploaded face matchmaker items: $ref: "#/components/schemas/Facerecognition_matchmaker_FileUploadResult" nullable: true type: array transactionId: description: Transaction ID to track face matchmakers upload progress example: txn_12345 nullable: true type: string type: object Facerecognition_matchmaker_FileUploadResult: description: Result of a file upload process for face matchmaker creation, including success status and error messages. properties: fileName: description: The name of the uploaded file. nullable: true type: string message: description: Error message that occurred during upload. nullable: true type: string success: description: Indicates whether the file upload was successful. Note, that even if upload was successful, subsequent operations, such as adding the uploaded file as a matchmaker, may fail. nullable: true type: boolean type: object securitySchemes: ApiKeyAuth: description: Your Rhombus API key. Must be accompanied by the `x-auth-scheme` header set to `api-token` (or `partner-api-token` for partner endpoints). in: header name: x-auth-apikey type: apiKey oauth2: description: 'OAuth 2.0 authorization code flow with PKCE (`S256`). Send the access token as `Authorization: Bearer `. Each operation lists the scopes it requires; a token without them is refused 403 with `WWW-Authenticate: Bearer error="insufficient_scope"`.' flows: authorizationCode: authorizationUrl: https://console.rhombus.com/oauth/authorize refreshUrl: https://auth-web.rhombussystems.com/oauth/token scopes: physical: Unlock doors and elevators, lockdown, alarms, speakers and robots read: View cameras, footage and settings write: Change settings and data tokenUrl: https://auth-web.rhombussystems.com/oauth/token type: oauth2 ````