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.
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, re-photographed documents or screens, blur, insufficient image quality, exposure failures, crop cutoffs, masks, artificial faces, and a hand near the face.

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.