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. ISO locale codes such as en_US are recommended. Two-letter codes such as en are matched on a best-effort basis.
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.

Consent configuration

Use config.consent to override which consent choices are requested for this invitation. It is an object keyed by consent category, with independent enabled and mandatory flags for each category.

Category	Description
use_general	General photo use.
use_marketing	Use of the photo for marketing, communications, and the website.
enhance_genai	Enhancement or modification of the photo using generative AI.
Theme-defined key	Additional categories, such as use_linkedin or use_advertising, are accepted only when declared in the active theme's COLLECT_CONSENT. Their wording is provided by the theme's language files.

Flag	Format	Description
enabled	Boolean	true requests this consent; false hides the category and removes its consent requirement.
mandatory	Boolean	When the category is enabled, true requires acceptance before continuing; false allows the user to leave the checkbox unchecked, recording a refusal. This flag has no effect while the category is disabled.

Overrides merge by category and flag: request override → site setting → theme default → base default. Site settings can override the three base categories; custom categories use theme defaults unless overridden in the request. Omitted, null, or invalid flag values inherit. Unknown categories and extra properties are ignored. Setting only mandatory, for example, retains the category's inherited enabled value and all other categories.

{
  "site_code": "example",
  "customer_no": "12345678",
  "config": {
    "consent": {
      "use_general": {"enabled": true, "mandatory": true},
      "use_marketing": {"enabled": true, "mandatory": false},
      "enhance_genai": {"enabled": false}
    }
  }
}

To request an optional custom category declared by your theme, for example, send "config": {"consent": {"use_linkedin": {"enabled": true, "mandatory": false}}}. Supplying a new key through the API does not create a theme category.

An omitted or empty consent object retains inherited settings; it does not disable all consent. To disable a category, explicitly set its enabled flag to false.

The resolved consent settings are saved when the invitation is created. Later site or theme changes do not change that invitation's settings or add new consent categories. Older invitations created without saved consent settings use current site settings with theme inheritance. If a request returns an existing duplicate invitation, it retains its existing configuration.

Consent is collected in invitation, registration, and Deeplink flows; direct uploads do not acquire a consent step. enhance_genai consent is shown only when enhancement is available, enabled for the invitation, and has a non-empty resolved prompt. Disabling this consent category does not disable enhancement itself; use config.image_enhance_genai_enabled for that. A recorded refusal of optional GenAI consent prevents automatic and manual enhancement.

These flags configure the questions; they do not record acceptance on the user's behalf. Read recorded decisions through user_consent in GET /invitation or GET /search.

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.
post_processing_actions	Array of strings, or a single string	Applies masks to the main photo. Accepts "mask-round-hard", "mask-round-soft", or an array of these values. A single string becomes an array. Overrides the main photo’s site/theme setting; [] disables actions. Invalid values are ignored.
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",
    "post_processing_actions": ["mask-round-hard"],
    "face_zoomfactor": 1.5,
    "face_pupils_percentage_from_bottom": 54
  }
}

Post-processing runs after the theme’s processed-photo callback. For example, "post_processing_actions": "mask-round-hard" is equivalent to "post_processing_actions": ["mask-round-hard"]. Omitting the key uses the site setting, falling back to the theme’s POST_PROCESSING_ACTIONS default. Set "post_processing_actions": [] to disable actions for the main photo.

Export variants use only their own explicitly configured post_processing_actions and do not inherit the main-photo settings. Image dimensions and formats stay unchanged: JPEG flattens masked transparency onto white, while WebP preserves transparency.

Generative AI image enhancement

Key	Format	Description
image_enhance_genai_enabled	Boolean	Set to true to enable enhancement for this invitation using the custom prompt or the site's current prompt, even if enhancement is disabled for the site. Set to false to disable enhancement, even when a custom prompt is supplied. Enhancement requires a non-empty resolved prompt.
image_enhance_genai_prompt	String	A non-empty string overrides the site's prompt and automatically enables enhancement unless image_enhance_genai_enabled is explicitly false. Omitted, null, empty, or whitespace-only values retain the site's current prompt. Non-string values, including Boolean false, are ignored.

To use the site's prompt, send "config": {"image_enhance_genai_enabled": true}. To provide custom instructions, set config.image_enhance_genai_prompt as shown below; the enabled flag is optional in this case. To disable enhancement, send "config": {"image_enhance_genai_enabled": false}. Omit both parameters to use the site's current enhancement settings. If no non-empty prompt is available, enhancement stays disabled.

{
  "site_code": "example",
  "customer_no": "12345678",
  "config": {
    "image_enhance_genai_prompt": "Improve the portrait lighting while preserving the person's identity and natural appearance."
  }
}

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.