> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.simz.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.simz.com/_mcp/server.

# Dynamic Variables

> Register your own prompt variables and send a value for each lead.

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`.

```text
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:

| Setting          | Meaning                                                                                                                                                                                               |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Key              | The 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`. |
| Label            | A readable name shown in the portal.                                                                                                                                                                  |
| Type             | `text`, `number`, `date`, `phone`, or `identifier`. See [Types](#types).                                                                                                                              |
| Must or optional | Whether a call can be placed without a value. See [Must and optional variables](#must-and-optional-variables).                                                                                        |
| Sensitive        | Whether the value is kept away from the language model, logs, transcripts, and webhooks. See [Sensitive variables](#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.

```bash
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 `{` `}` `<` `>`.

| Type         | Accepted value                                                                                                                                                                 | Example                 |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------- |
| `text`       | One line of text, up to 200 characters.                                                                                                                                        | `"the downtown office"` |
| `number`     | Digits 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`     |
| `date`       | A real calendar date written as `YYYY-MM-DD`. Past and future dates are accepted.                                                                                              | `"2026-12-03"`          |
| `phone`      | An E.164 number starting with `+`, or a US number such as `(555) 123-4567` or `5551234567`.                                                                                    | `"+15551234567"`        |
| `identifier` | Up 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`.

```json
{
  "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"`:

```json
{
  "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": []
      }
    ]
  }
}
```

| Field              | Meaning                                                                                                       |
| ------------------ | ------------------------------------------------------------------------------------------------------------- |
| `code`             | `DYNAMIC_VARIABLES_INVALID` for a lead rejected by this check.                                                |
| `reason`           | A readable summary that names the keys. Its wording can change; read `code` and the three lists in your code. |
| `unknownVariables` | Keys that are not registered for your company.                                                                |
| `missingVariables` | Must variables that the outbound prompt refers to and that were not sent.                                     |
| `invalidVariables` | Keys 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`:

```json
{
  "invalidVariables": [
    { "key": "appointment_date", "reason": "not_a_date" }
  ]
}
```

| Reason code      | Meaning                                                                                                                                                                               |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `wrong_type`     | The value is not a JSON string, or not a string or number for `number` and `identifier`. Objects, arrays, and booleans are never accepted.                                            |
| `too_long`       | The value is longer than 200 characters, or longer than 64 for `identifier`.                                                                                                          |
| `bad_characters` | The 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_number`   | The value of a `number` variable is not a plain number, or is longer than 32 characters.                                                                                              |
| `not_a_date`     | The value of a `date` variable is not a real date written as `YYYY-MM-DD`.                                                                                                            |
| `not_a_phone`    | The value of a `phone` variable is not an E.164 or US phone number.                                                                                                                   |
| `not_an_object`  | Reported under the key `dynamicVariables`: the lead's `dynamicVariables` is not a JSON object.                                                                                        |
| `too_many_keys`  | Reported 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`:

```json
{
  "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.

```json
{
  "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](/overview/lead-receive-api/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](#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.