Create an invitation

Photo Collect invitations contain a personalized link and can be delivered to the end user by email or SMS. If customer_to is omitted, Photo Collect creates a registration and returns its URL for your system to deliver.

Request parameters

Parameter	Required	Description
site_code	Yes	Site receiving the invitation. Use a value returned by GET /token.
customer_no	Yes	Your customer or case identifier.
customer_to	No	Email address or phone number in international + format.
locale	No	Front-end and message locale available in the setup theme.
language_interface	No	Response language: en, de, fr, or it.
upload_channel	No	Set registration to suppress the initial invitation message.
unique_id	No	Prevents duplicate creation during unstable network retries.
config	No	Invitation-specific behavior and image processing overrides.

Invitation configuration

Use the optional config object to override the site's configuration for this invitation. Omitted keys retain the site-level value. Boolean values must be the JSON literals true or false, not quoted strings.

Collection behavior

Key	Format	Description
qc_enabled	Boolean	true sends the processed photo through the quality-control workflow. false skips QC and allows automatic export.
collect_signature_request	Boolean	Shows the signature step when signature collection is enabled for the theme.
collect_signature_required	Boolean	true prevents the user from skipping the signature step. This setting only applies when collect_signature_request is true.
collect_customerto_request	Boolean	Asks the user for missing contact information when customer_to was not supplied.
collect_customerto_required	Boolean	true prevents the user from skipping the contact-information step. This setting only applies when collect_customerto_request is true.
collect_verification_required	Boolean	Requires the user to complete the configured identity-verification step. This setting only applies when verification is enabled for the theme.
collect_redirect_uri	HTTP(S) URL or an empty string	Opens this URL after collection is complete. Set it to "" to disable the site-level redirect for this invitation. Supported placeholders are described below.

First-gate checks

First-gate checks validate a photo before it enters the remaining processing workflow. Set a check to true to reject photos that match that condition, or to false to allow them. The following invitation-level controls are available:

Key	Format	Description
firstgate_checks_enabled	Boolean	Master switch for first-gate validation. When false, the individual settings below are ignored. The theme must support first-gate checks for this override to take effect.
firstgate_check_smile	Boolean	Rejects photos in which the person is smiling instead of showing a neutral expression.
firstgate_check_blackwhite	Boolean	Checks that the photo is in color and rejects black-and-white photos.
firstgate_check_sunglasses	Boolean	Checks whether the person is wearing sunglasses.
firstgate_check_heavyframes	Boolean	Checks for heavy eyeglass frames covering the eyes.
firstgate_check_shoulderpose	Boolean	Checks that the shoulders are in the correct frontal pose.

These switches control only the listed checks. Other first-gate checks configured by the theme are not available as invitation-level overrides.

{
  "customer_no": "12345678",
  "site_code": "example",
  "config": {
    "firstgate_check_sunglasses": false,
    "firstgate_check_heavyframes": false,
    "firstgate_check_shoulderpose": true,
    "firstgate_check_blackwhite": true
  }
}

Image output and face crop

Key	Format and allowed values	Description
image_output_size_w	Positive integer, in pixels	Width of the processed output image. For example, 600.
image_output_size_h	Positive integer, in pixels	Height of the processed output image. For example, 800.
image_background_color	Hex color: #RGB or #RRGGBB	Background color applied during image processing. For example, "#F2F2F2" produces a light-gray background.
face_zoomfactor	Number: -1 or between 1.0 and 3.0	Controls the crop around the detected face. 1.0 is a tight crop; 1.5 the passphoto default; larger values include more surrounding area.
face_pupils_percentage_from_bottom	Integer from 0 to 100	Positions the pupils vertically as a percentage of the cropped image height, measured from the bottom. For example, 54.

{
  "config": {
    "image_output_size_w": 600,
    "image_output_size_h": 800,
    "image_background_color": "#F2F2F2",
    "face_zoomfactor": 1.5,
    "face_pupils_percentage_from_bottom": 54
  }
}

collect_redirect_uri

config.collect_redirect_uri defines the URL to open after the collection process is complete. It supports these literal, case-sensitive placeholders:

Placeholder	Replaced with
[CUSTOMER_NO]	The URL-encoded customer number.
[SITE_CODE]	The URL-encoded site code.

{
  "config": {
    "collect_redirect_uri": "https://example.com/complete?customer=[CUSTOMER_NO]&site=[SITE_CODE]"
  }
}

Site-level collect_redirect_uri values support the same placeholders.

If the same customer_no, customer_to, site_code, and locale arrive within a short period, the server may return the existing invitation with is_duplicate: true.

curl --request POST "https://demo.photocollect.io/apiv1/invitation" \
  --header "Authorization: Custom <API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "site_code": "your-site-code",
    "customer_no": "12345678",
    "customer_to": "user@example.com",
    "locale": "en_US"
  }'

Response

{
  "invitation_key": "abcd12345",
  "invitation_url": "https://demo.photocollect.io/c/abcd12345"
}

On failure, HTTP 400 returns error and errorcode, for example CREATE_INVITATION_FAILED.