API identifiers and coded values
The Builder uses friendly labels, while a service definition and API use stable identifiers and coded values. Understanding the distinction helps you configure templates, conditions and integrations safely, and makes programmatic updates predictable.
Use stable identifiers
An identifier is a machine-readable name, not the text people see. It may be referenced by templates, actions, conditions, data mappings, review settings and API payloads. Choose it carefully at the point of creation.
| Identifier | Purpose | Good practice |
|---|---|---|
| Field ID | Identifies a component answer. | Use a short, descriptive camelCase name such as applicantEmail. |
| Action ID | Identifies an action and its result. | Name the outcome, such as lookupAddress or sendConfirmation. |
| Condition ID | Identifies reusable conditional logic. | Name the decision, such as isEligible. |
| Selection item ID | Is the stored value for a choice item. | Keep it stable when labels are edited or translated. |
| Page ID | Identifies a page internally. | Let the platform generate it unless a supported API operation requires otherwise. |
Field IDs start with a letter or underscore, use letters, numbers and underscores, are shorter than 80 characters, and must not be reserved names or generated structural IDs. Action IDs accept alphanumeric characters, underscores and hyphens. IDs are case-sensitive.
Separate labels from stored values
For a radio, checkbox, select or autocomplete component, the person sees the selection label but the service stores the selection item ID. Conditions should compare against that ID, not the visible wording. This prevents an otherwise harmless copy change from breaking routing or an integration.
For example, a visible choice can be changed from Renew an application to Renew an existing application while its stored ID remains renewal. A condition using the selection item ID continues to work.
flowchart LR
A["Visible label: Renew an existing application"] --> B["Stored item ID: renewal"]
B --> C["Condition, action or template"]
C --> D["Reliable behaviour after wording changes"]Read API references accurately
Reference articles should use the Builder’s friendly setting name as the heading, then show the exact API property or coded value where it is useful. A UI option and its API value can differ in case or wording. For example, a storage option shown in the UI may be represented by a lower-case code in JSON.
Copy API property names and coded values exactly. Do not assume a displayed title maps mechanically to a property name. Check the current schema or API reference before writing or changing an integration payload.
Use identifiers in Liquid and actions
Field and action IDs are used in Liquid templates. For example:
{{ fields.applicantEmail }}
{{ actions.lookupAddress.data }}An assignment action can set a field using a value generated by a prior action. Configure the action order so the source result is available first. For nested data, the Builder supports dot notation in a target field path; test the resulting structure in QA before relying on it elsewhere.
Update services safely through an API
Treat an API update as a change to a working service, not as a text edit.
- Read the latest service version before constructing an update.
- Confirm the target library and service, and use non-production data while testing.
- Send an object that matches the required discriminator type for the page, component, condition or action.
- Omit transient, cached and provisioning-only values.
- Keep parallel arrays aligned where a schema pairs names with values.
- Validate Liquid syntax and identifier references before saving.
- Save a new version with a meaningful change description.
- Test the affected journey in User view and QA before deployment.
Do not use a full-service replacement as the normal editing method. A targeted update is easier to review and less likely to remove unrelated settings.
Be careful with context and query values
Some services can be configured to accept context values through query parameters. This can be useful for controlled internal links, but it can also create a security risk if it changes behaviour based on untrusted input. Do not use query context for secrets, authorisation decisions or sensitive data. Validate and test every permitted context value.
Checklist
- Use the exact ID, including its case.
- Use selection item IDs for choice comparisons.
- Keep user-facing labels meaningful and independent from codes.
- Search for all dependent templates, conditions and actions before changing an ID.
- Keep API payloads schema-valid and scoped to the intended change.
- Version, test and deploy changes through the normal service lifecycle.