Process a new photo

Send URL-encoded form data to process a new image. customer_no is optional; keep it when the photo must remain traceable or available for later export.

By default the processed photo remains on the server for manual quality control and export. Set set_received=1 to remove it immediately after it is returned. That option only takes effect when manual QC is disabled.

Request parameters

Parameter	Required	Description
site_code	Yes	Site and processing configuration to use.
customer_no	No	Your identifier. A random internal ID is generated when omitted.
customer_to	No	Contact used for follow-up flows.
set_received	No	1 removes the image after the response when QC is disabled.
skip_firstgate_checks	No	1 accepts the image despite first-gate failures.
soften_firstgate_checks	No	1 enforces hard checks but skips soft checks.
language_interface	No	Response language. ISO locale codes such as en_US are recommended. Two-letter codes such as en are matched on a best-effort basis.
photo_b64	Yes	Base64 JPEG, WebP, or PNG. Raw-body upload is also supported outside this console.
signature_b64	No	Base64 PNG, WebP, JPEG, TIFF, or GIF.

curl --request POST "https://demo.photocollect.io/apiv1/photo" \
  --header "X-Api-Key: <API_KEY>" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "photo_b64=$(base64 -w 0 photo.jpg)" \
  --data-urlencode "site_code=your-site-code" \
  --data-urlencode "set_received=1"

For binary transfer, place the image in the raw request body and pass all other parameters in the query string. Omit photo_b64 and signature_b64 in that mode.

Response

HTTP 200 means the image was processed, even when first-gate validation returns failures. status is exported, received, or processed, depending on QC and set_received.

{
  "invitation_key": "YUDkLo1zaAVv",
  "file_type": "image/jpeg",
  "file_content": "/9j/4AAQSkZJRgABAQEA...",
  "status": "exported"
}

First-gate checks

Checks run in configured sequence and processing stops at the first check method that fails. The response therefore contains the reason or reasons from that method, not necessarily every possible issue.

Hard failures include no face, multiple faces, low resolution, face occlusion, reflective glasses, red eyes, headphones, seatbelts worn over a shoulder or across the upper torso, re-photographed documents or screens, blur, insufficient image quality, exposure failures, crop cutoffs, masks, artificial faces, and a hand near the face.

The seatbelt check runs as part of the existing LLM Vision portrait assessment when that provider is enabled. It detects a vehicle seatbelt visibly worn over a shoulder or diagonally across the upper torso and rejects scores at or above the default threshold of 0.8. A vehicle interior alone, bag straps, suspenders, scarves, or clothing seams do not establish a seatbelt failure.

As a hard check, seatbelt remains enforced with soften_firstgate_checks=1 and in kiosk processing. Setting the effective firstgate_checks_enabled configuration to false or using skip_firstgate_checks=1 still bypasses first-gate rejection. The rejection message asks the person to take a new photo outside the vehicle.

Soft failures include head pose, grayscale, sunglasses, heavy frames, closed eyes, off-gaze, weak face lighting, smile, shoulder pose, non-religious head covering, and strong makeup. Individual setups can reclassify checks.

Processing failures return HTTP 400 with UPLOAD_FAILED.