Capture templates and languages

Choose the shots and the texts the person sees, in their own language.

What is a template

A capture template tells the capture page what to ask: the list of shots to take (a name and an instruction for each, required or not) and the welcome and completion texts. You create it once with the API and use it by its id (tpl_…). Test and live are separate: a template created with a test key does not exist in live, and the other way round.

Create a template

The answer carries its id, tpl_…: that is how you refer to the template from now on. The name is only a label to recognise it in a list. Each text can be a plain string, or one string per language.

$ curl -X POST https://api.tryvidimus.com/v1/capture-templates \
    -H "Authorization: Bearer $TRYVIDIMUS_API_KEY" \
    -H "Content-Type: application/json" \
    -d @template.json

{
  "name": "pickup_car",
  "default_locale": "en",
  "welcome": {
    "title": { "en": "Welcome", "fr": "Bienvenue", "de": "Willkommen" }
  },
  "steps": [
    {
      "id": "front",
      "label": { "en": "Front", "fr": "Face avant", "de": "Vorderseite" },
      "instruction": { "en": "Stand back", "fr": "Reculez", "de": "Gehen Sie zurück" }
    }
  ]
}

Use it in a capture session

Give its id as template_id and the language of the person as locale. Without template_id, the active template that matches stage and category is used, if there is one; a template with neither stage nor category is only used when you name it.

$ curl -X POST https://api.tryvidimus.com/v1/capture-sessions \
    -H "Authorization: Bearer $TRYVIDIMUS_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $(uuidgen)" \
    -d '{"external_reference":"booking_4471","party":"provider","template_id":"tpl_01m4akapdbe8e8qq3er9r5qwyj","locale":"de"}'

Languages

A language is a BCP 47 tag: en, fr, es, de, but also pt-BR, es-419 or zh-Hans. A text given as a plain string is used for every language. When a language is missing, the page uses the base language (pt for pt-BR), then the default language of the template (default_locale), then English. A text given for several languages must include the default language, and a template holds 20 languages at most.

Look of the capture page: themes

A theme is the look of the capture page: a name, a main color, a language and a logo. You can have several, for example one per brand, and choose one per template with theme_id. Your first theme becomes the default one, used by the templates that do not name another. Themes are the same in test and live.

$ curl -X POST https://api.tryvidimus.com/v1/capture-themes \
    -H "Authorization: Bearer $TRYVIDIMUS_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"name":"Gîte du Lac","primary_color":"#1f6b52","locale":"fr"}'

{
  "id": "thm_01m4akapdbe8e8qq3er9r5qwyj",
  "name": "Gîte du Lac",
  "primary_color": "#1f6b52",
  "locale": "fr",
  "has_logo": false,
  "is_default": true
}

Choose a theme in a template

Give the id of a theme (thm_…) as theme_id when you create or edit a template, and null to go back to your default theme. A theme used by a template cannot be archived.

$ curl -X PATCH https://api.tryvidimus.com/v1/capture-templates/tpl_01m4akapdbe8e8qq3er9r5qwyj \
    -H "Authorization: Bearer $TRYVIDIMUS_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"theme_id":"thm_01m4akapdbe8e8qq3er9r5qwyj"}'

The capture page itself

The buttons and messages of the page, which are not your texts, are translated by us. The capture page is being built: it is planned in English, French, Spanish and German first, and other languages will follow.

Changing a template

Changing a template never changes a link that was already sent: each capture session keeps its own copy. In production, a template that sessions have been created from is frozen, like a price once it has been used: to change it, duplicate it, change the copy, and use the id of the copy. Deleting is archiving: an archived template no longer starts sessions, and the proofs already made keep it. In test mode, templates stay editable.

$ curl -X POST https://api.tryvidimus.com/v1/capture-templates/tpl_01m4akapdbe8e8qq3er9r5qwyj/duplicate \
    -H "Authorization: Bearer $TRYVIDIMUS_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"name":"pickup_car_v2"}'

{
  "id": "tpl_01m4akapdc2nz8w9vbyx5qk3tq",
  "name": "pickup_car_v2",
  "stage": null,
  "category": null,
  "in_use": false,
  "archived_at": null
}

These routes need a key with the manage_templates scope.

Read the API reference