Skip to navigation

Dynamic Variables

View as Markdown

Dynamic variables let you pass per-call values, such as an appointment date or a reference number, into what your SimZ agent says. You register each variable once in the portal, the agent’s prompt refers to it as {{key}}, and you send the value with each lead in dynamicVariables.

Hi {{first_name}}, this is {{agent_name}} from SimZ. I'm calling about your appointment on {{appointment_date}}.

In this example first_name and agent_name are built-in variables that SimZ fills from the lead and the agent. appointment_date is a dynamic variable that your company registered and that your API request fills.

Register variables in the portal

Open Agents in the SimZ Portal and click Variables on an agent card.

  • A company has one list of variables. Every agent of the company shares it.
  • Company admins can add and edit variables. Operators can view the list but cannot change it.
  • A company can register up to 200 variables. Contact SimZ if you need a higher limit.

Each variable has these settings:

SettingMeaning
KeyThe name used in prompts as {{key}} and in API requests. Starts with a lowercase letter, followed by lowercase letters, digits, or underscores. Maximum 32 characters. Example: appointment_date.
LabelA readable name shown in the portal.
Typetext, number, date, phone, or identifier. See Types.
Must or optionalWhether a call can be placed without a value. See Must and optional variables.
SensitiveWhether the value is kept away from the language model, logs, transcripts, and webhooks. See Sensitive variables.

After a variable is created, its key, type, and sensitive setting cannot be changed. Its label and its must or optional setting can.

Reserved names

Some keys cannot be registered because SimZ already uses them:

  • the built-in variables: first_name, last_name, full_name, email, phone_number, today_date, agent_name, campaign_type
  • any key that starts with client_
  • dob, member_id, policy_number, claim_number, zip_code, customer_phone, insurance_name_being_reached, caller_demo_appointments

Pick a more specific key instead, for example customer_dob in place of dob. Built-in variables keep working in prompts as before and do not need to be registered.

Send values with a lead

Add dynamicVariables to each lead, next to customData. It is a JSON object that maps a variable key to its value.

curl -X POST "https://api.simz.com/api/lead-receive-service/agent/receiveLead/agent_123" \
-H "Content-Type: application/json" \
-H "X-Company-API-Key: sk_comp_example" \
-d '{
"leads": [
{
"phoneNumber": "+15551234567",
"firstName": "Jane",
"lastName": "Doe",
"customData": {
"leadId": "LEAD-001"
},
"dynamicVariables": {
"appointment_date": "2026-12-03",
"promo_code": "SPRING-25",
"amount_due": 49.5
}
}
]
}'
  • dynamicVariables belongs to one lead. Each lead in the request carries its own values.
  • Every key must be registered for your company. A key that is not registered rejects the lead.
  • customData stays your own metadata. Values meant for the prompt go in dynamicVariables.

Variables are not supported in the portal’s Batch Call (CSV) upload. Use the Lead Receive API to send values.

Types

Send values as JSON strings. A number or identifier value may also be sent as a JSON number. Leading and trailing spaces are ignored. No value may be longer than 200 characters or contain control characters or any of { } < >.

TypeAccepted valueExample
textOne line of text, up to 200 characters."the downtown office"
numberDigits with an optional leading minus sign and an optional decimal part, up to 32 characters. No thousands separators, currency symbols, or exponents."49.50" or 49.5
dateA real calendar date written as YYYY-MM-DD. Past and future dates are accepted."2026-12-03"
phoneAn E.164 number starting with +, or a US number such as (555) 123-4567 or 5551234567."+15551234567"
identifierUp to 64 characters in total: ASCII letters (A-Z, a-z) and digits, which a single space, -, /, ., or # may separate. It must start and end with a letter or digit."SPRING-25"

Must and optional variables

  • An optional variable may be left out. SimZ then uses the agent’s default for it, or an empty value when there is no default.
  • A must variable has to be sent by your API request. It has no default for outbound calls. If the value is missing, the lead is rejected.

A must variable is enforced only when the outbound prompt used for the call refers to it. If the prompt does not contain {{appointment_date}}, a lead without appointment_date is still accepted.

A value that is null or an empty string counts as not sent.

Defaults

Each agent can have two defaults per variable, one for inbound calls and one for outbound calls. Set them in the same Variables window.

SimZ picks the value for a call in this order:

  1. the value sent with the call
  2. the agent’s default for the direction of the call
  3. an empty value

Inbound calls use the inbound defaults only, because no API request comes with an inbound call. Must variables have no outbound default, and sensitive variables have no defaults at all.

Sensitive variables

Mark a variable as sensitive when its value should be spoken to the person on the call but not kept anywhere else.

  • The agent says the value on the call.
  • The value is never shown to the language model and never written to logs, transcripts, or webhooks.
  • SimZ keeps the value you sent only while the lead is queued, and erases it when the lead ends.
  • A sensitive variable cannot have a default. On inbound calls the agent says “not available” in its place.

Errors

SimZ checks dynamicVariables for each lead before the lead is queued. A lead is rejected when:

  • a key is not registered for your company (unknownVariables)
  • a must variable that the outbound prompt refers to has no value (missingVariables)
  • a value does not fit the type of its variable (invalidVariables)

The other leads in the request are not affected. Error responses never contain a value you sent in dynamicVariables, only key names and reason codes. Each rejected attempt is also listed in the portal under Blocked Calls.

Some leads rejected

The request below sends two leads to an agent whose outbound prompt refers to the must variable appointment_date. The second lead misspells promo_code and does not send appointment_date.

{
"leads": [
{
"phoneNumber": "+15551234567",
"firstName": "Jane",
"dynamicVariables": {
"appointment_date": "2026-12-03",
"promo_code": "SPRING-25"
}
},
{
"phoneNumber": "+15557654321",
"firstName": "John",
"dynamicVariables": {
"promo_cod": "SPRING-25"
}
}
]
}

SimZ answers 207. The rejected lead is listed in data.rejectedLeadDetails with code: "DYNAMIC_VARIABLES_INVALID":

{
"success": true,
"message": "Some leads were rejected",
"data": {
"batchId": "batch_123",
"agentId": "agent_123",
"agentName": "Spring Outreach",
"totalLeads": 2,
"acceptedLeads": 1,
"rejectedLeads": 1,
"estimatedStartTime": "2026-12-01T18:30:00Z",
"rejectedLeadDetails": [
{
"phoneNumber": "+15557654321",
"code": "DYNAMIC_VARIABLES_INVALID",
"reason": "Lead rejected: unknown variables: promo_cod; missing required: appointment_date. Create variables in the portal under Agents > Variables.",
"unknownVariables": ["promo_cod"],
"missingVariables": ["appointment_date"],
"invalidVariables": []
}
]
}
}
FieldMeaning
codeDYNAMIC_VARIABLES_INVALID for a lead rejected by this check.
reasonA readable summary that names the keys. Its wording can change; read code and the three lists in your code.
unknownVariablesKeys that are not registered for your company.
missingVariablesMust variables that the outbound prompt refers to and that were not sent.
invalidVariablesKeys whose value was not accepted, each with a reason code from the table below.

A lead that sends "appointment_date": "12/03/2026" is rejected with the key and a reason code in invalidVariables:

{
"invalidVariables": [
{ "key": "appointment_date", "reason": "not_a_date" }
]
}
Reason codeMeaning
wrong_typeThe value is not a JSON string, or not a string or number for number and identifier. Objects, arrays, and booleans are never accepted.
too_longThe value is longer than 200 characters, or longer than 64 for identifier.
bad_charactersThe value contains a control character or one of { } < >, or an identifier contains a character that is not allowed or a separator that is repeated or at the start or end.
not_a_numberThe value of a number variable is not a plain number, or is longer than 32 characters.
not_a_dateThe value of a date variable is not a real date written as YYYY-MM-DD.
not_a_phoneThe value of a phone variable is not an E.164 or US phone number.
not_an_objectReported under the key dynamicVariables: the lead’s dynamicVariables is not a JSON object.
too_many_keysReported under the key dynamicVariables: the lead’s dynamicVariables holds too many keys.

Every lead rejected

When no lead in the request is accepted, SimZ answers 400. The code is DYNAMIC_VARIABLES_INVALID when at least one lead was rejected by this check, and INVALID_REQUEST otherwise. details holds one readable line per rejected lead. When at least one lead reached this check, data.rejectedLeadDetails also lists the rejected leads in the same form as on a 207:

{
"success": false,
"error": "All leads were rejected during validation",
"code": "DYNAMIC_VARIABLES_INVALID",
"details": [
"+15557654321: Lead rejected: unknown variables: promo_cod. Create variables in the portal under Agents > Variables."
],
"data": {
"rejectedLeadDetails": [
{
"phoneNumber": "+15557654321",
"code": "DYNAMIC_VARIABLES_INVALID",
"reason": "Lead rejected: unknown variables: promo_cod. Create variables in the portal under Agents > Variables.",
"unknownVariables": ["promo_cod"],
"missingVariables": [],
"invalidVariables": []
}
]
}
}

Send a value for each key in missingVariables, correct the keys in unknownVariables or register them under Agents > Variables, and correct the values in invalidVariables. Then submit the leads again.

Check unavailable

If SimZ cannot check the variables, the request fails closed: it returns 503 with code: "DYNAMIC_VARIABLES_CHECK_FAILED" and no leads are queued.

{
"success": false,
"code": "DYNAMIC_VARIABLES_CHECK_FAILED",
"message": "Unable to check dynamic variables. Leads were not queued. Please try again shortly.",
"data": {
"agentId": "agent-id",
"companyId": "company-id"
}
}

Retry the same request later with exponential backoff.

FAQ

My lead was rejected with a key in unknownVariables, but I registered that variable. Compare the key letter by letter with the key shown under Agents > Variables. Keys are lowercase and exact: Promo_Code, promoCode, and promo_cod are not promo_code. Also check that the variable is registered in the same company that owns the API key.

Where do I put dynamicVariables? Inside each lead object, next to customData, not next to leads or inside options.

Can I send the values in customData instead? Send them in dynamicVariables. customData is for your own metadata and must be a JSON object. See Custom Data.

I sent "12/03/2026" for a date and got not_a_date. Dates are YYYY-MM-DD only, for example "2026-12-03".

I sent true or a JSON number and got wrong_type. Send values as JSON strings. Only number and identifier variables also accept a JSON number.

I set a default for a must variable, but leads without it are still rejected. A must variable has no outbound default. The API request has to send it for every lead whenever the outbound prompt refers to it. If a fallback is acceptable and the variable is not sensitive, make the variable optional and set an outbound default.

A lead without a must variable was accepted. Why? The outbound prompt used for that call does not refer to the variable, so it was not enforced.

I cannot register dob or first_name. Those keys are reserved. See Reserved names and choose a more specific key.

Does one bad lead reject the whole request? No. Only that lead is rejected, and the response is 207. The response is 400 only when no lead in the request can be accepted.

Will the error response show me the value that was wrong? No. Errors contain key names and reason codes only.

Can I upload variables in a Batch Call CSV? Not at this time. Use the Lead Receive API.