Choose the right workflow

Most integrations have two phases: trigger capture, then retrieve and delete the processed photo. Pick the trigger based on where the portrait starts.

Web application with a Deeplink

Use a signed Deeplink when an authenticated web user should move into Photo Collect, complete the guided capture, and return to your application.

1. Generate a signed Deeplink with a unique salt and an expiry_date.
2. Present it as an Upload photo button, QR code, link, or embedded iFrame.
3. Set config.collect_redirect_uri to return the user to your application. For embedded flows, follow the iFrame integration guide to observe progress and resize the frame.
4. Without manual quality control, retrieve the result with GET /export and remove it with DELETE /export.
5. With manual quality control, show a pending-review state and optionally poll GET /search for photo_status and qc_status.

Do not treat invitation_key ↔ customer_no as a permanent mapping. Kiosk and app uploads can close an initial invitation and create a new key. Search by customer_no when the business record is the stable identifier.

Process an existing image

Use POST /photo when your mobile app, HR system, or document workflow already has an image.

• Set set_received=1 for a stateless processing flow where the photo should be removed immediately after it is returned. This is available only when manual quality control is disabled.
• customer_no is optional. Keep it when you need later tracking or export.
• Validate and persist the returned image immediately.

Poll for approved photos

Use GET /export without customer or site filters to retrieve newly approved photos. The oldest exports are returned first.

• Poll every 1–5 minutes, depending on volume and latency needs.
• Process each page in order and avoid increasing page_size unnecessarily; each record contains Base64 image data.
• customer_no is not unique. If it appears more than once, use the latest uploaded_at value.
• Delete each successfully persisted image through DELETE /export.

Operational recommendations

• Prefer static API keys for server-to-server integrations.
• Use dynamic user tokens only when acting explicitly for a signed-in Photo Collect user.
• Implement bounded retries for network failures and 5xx responses. Do not blindly retry validation errors.
• Log request IDs, endpoint, HTTP status, and duration—but never API keys or Base64 photo content.
• Treat all portrait and signature data as sensitive personal data.