Custom Tokens

Why Custom Tokens Exist

System tokens cover universal call properties but cannot
represent business-specific data. If your landing page
collects loan_amount, zip_code, or lead_score,
those fields must be defined as custom tokens so the
platform knows how to store, render, and pass them
through to buyers.

Custom tokens are created automatically the first time
the platform sees a field name in a lead submission, a
webhook payload, or an API call. You can also create
them manually ahead of time.

Creating a Custom Token Manually

1. Navigate to /tokens.
2. Click New Token.
3. Fill in the Attributes section:
   • Type: Text (String) or Numeric. Numeric tokens render as numbers rather than quoted strings when posted to URLs and JSON payloads.
   • Key: the token name as it will appear in templates. Must be unique per company. Keys may contain only lowercase letters, digits, and underscores (regex \A[0-9a-z_]*\z). The field is disabled after the token is persisted; the key cannot be renamed.
   • Inherit From Previous Call: if enabled, the token's value carries forward when the same caller dials again.
   • Color and Text Color: display colors used when the token appears as a badge in the UI.
4. Optionally configure the Static Value section to have the token always emit a fixed value regardless of the call's own data.
5. Optionally configure the Prompt & Responses section to attach an IVR prompt to this token. See the "Tokens and Routing Responses" article for details. The Prompt & Responses section contains the Prompt Priority field, which controls the order in which prompts fire when multiple tokens prompt on the same call.
6. Save.

Creating Custom Tokens via Lead Submission

You do not need to pre-create custom tokens. When a lead
is submitted to POST /api/v1/leads with fields like
data[loan_amount]=500, the platform auto-creates
matching Token records for any unknown keys. This is
the usual path; manual creation is only needed when you
want to configure the type, color, or routing response
behavior before the first submission arrives.

Editing and Deleting

A custom token's key cannot be changed after creation
without breaking existing templates that reference it.
If you need a different name, create a new token and
migrate your templates. Deleting a token is a soft
delete; historical call token values remain intact for
reporting.