Profile photo comparison

Ask for permission first

Enable profile_photo_comparison under Identity access and include it in sign-in. Production use requires restricted-scope review. The person approves: “Compare photos you upload to this application with your enrolled face.” This does not release their reference image or change their UnifyID profile picture.

An existing connection must approve this new permission. The retired face_match_verified scope is refused; it was a historical verification result, not a photo-comparison service. No application or existing consent is automatically given the new capability.

Submit the exact proposed photo from your backend

POST /v1/profile-photo-comparisons with the person’s OAuth access token. Upload one JPEG or PNG, at most 2 MB, in the multipart photo field. Supply an Idempotency-Key of 8–128 letters, digits, dots, colons, underscores or hyphens. No account identifier or image URL is accepted; the token selects the person.

curl -X POST "$UNIFYID_API/v1/profile-photo-comparisons" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: profile-photo-2026-001" \
  -F "[email protected];type=image/jpeg"

const result = await unifyid.compareProfilePhoto({
  accessToken: session.unifyidAccessToken,
  photo: new Blob([uploadedBytes], { type: "image/jpeg" }),
  idempotencyKey: crypto.randomUUID(),
});
// Retain exactly uploadedBytes. The receipt covers that image_sha256.
if (result.environment === "production" && result.outcome === "match") {
  await saveProposedProfilePhoto(uploadedBytes);
}

{"data":{"comparison_id":"8c2a9c00-9631-4b89-a2d8-069c4bd7208a","outcome":"match","image_sha256":"<SHA-256 of the submitted bytes>","checked_at":"2026-10-18T12:00:00Z","environment":"production"}}

Handle every outcome

Provider failures are retryable 503 errors, never no_match. Rate limits return 429: 10 requests per minute per person per application, and 60 per application. Invalid permissions or revoked tokens are refused before a comparison or receipt is returned. A 409 can mean a comparison is in progress or the same key was used for different bytes.

Rehearse in Sandbox

Sandbox never invokes a biometric provider. Its default outcome is simulated match. Use X-UnifyID-Sandbox-Outcome with any outcome above, or unavailable for a retryable outage. The SDK exposes sandboxOutcome. Production rejects this override. Use a new key for each scenario: a retry replays the original result.

Retries, records and credits

Use the same key and image when retrying. A completed receipt is replayable for 24 hours while access remains authorized, with no repeat comparison or charge. Processing leases expire after two minutes. The hourly cleanup job removes expired operational receipts in bounded batches, except evidence still needed to settle a held credit reservation. Uploaded photos are processed in memory and are not stored. Sharing activity records the comparison-result release; repeated activity may be counted together.

The operation meter starts at one credit per completed match, no_match or inconclusive result. Invalid images, unavailable references and provider errors release the credit reservation. Sandbox does not debit the wallet; its application budget can still be rehearsed. The permission itself is not charged as an OAuth scope.

Reference images are encrypted at rest and retained with the account’s biometric reference. A comparison uses only that account’s reference, never a search across people. Account erasure removes the reference and operational receipts through the existing erasure process. Withdrawal stops future comparisons; information already received by an application may remain.