> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coval.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Simulation Wrappers (Beta)

> Fetch data before each simulation and use the response in test case inputs.

<Info>
  **Beta.** API simulation wrappers are a beta feature and may change.
</Info>

An **API simulation wrapper** calls an HTTP endpoint before each simulation in a test set. Values from the JSON response become available as template variables in the test case's **Simulation Input**.

Use an API simulation wrapper when a scenario needs fresh data at runtime, such as a test customer, account identifier, quote, reservation, or session.

The wrapper is configured once for the test set. Saving the test set applies the same configuration to every test case in it, while the endpoint is called separately before each simulation.

## Configure an API call

<Steps>
  <Step title="Open a test set">
    Open **Test Sets**, then select the test set you want to configure.
  </Step>

  <Step title="Select the API wrapper">
    In **Simulation setup**, select **API** and click **Add Pre-Simulation API Call**.
  </Step>

  <Step title="Configure the request">
    Enter the endpoint URL, HTTP method, timeout, and any optional JSON request body or headers.
  </Step>

  <Step title="Reference the response">
    Add `{{sim_wrapper.api.*}}` variables to your test case inputs using the response examples below.
  </Step>

  <Step title="Save the test set">
    Save to apply the configuration to every test case in the test set.
  </Step>
</Steps>

## Request settings

| Setting          | Required | Description                                                                |
| ---------------- | -------- | -------------------------------------------------------------------------- |
| **API URL**      | Yes      | The full URL Coval calls before the simulation.                            |
| **Method**       | Yes      | `GET`, `POST`, `PUT`, or `DELETE`. Defaults to `GET`.                      |
| **Timeout**      | Yes      | How long to wait for the endpoint, in seconds. Defaults to `30`.           |
| **Request Body** | No       | A JSON request body for `POST` or `PUT` requests.                          |
| **Headers**      | No       | A JSON object containing request headers, such as an authorization header. |

<Warning>
  Use test data and scoped credentials. Do not place production secrets or real sensitive customer data in test set configuration or endpoint responses.
</Warning>

## Use an object response

For a JSON object response, fields are available directly under `sim_wrapper.api`.

For example, if the endpoint returns:

```json theme={null}
{
  "customer": {
    "firstName": "John",
    "phoneNumber": "3034186858"
  }
}
```

Use these values in a scenario:

```text theme={null}
You are {{sim_wrapper.api.customer.firstName}}, a customer calling for help.
Your phone number is {{sim_wrapper.api.customer.phoneNumber}}.
```

## Use an array response

For a JSON array response, the complete array is available under `sim_wrapper.api.response`. Use bracket notation to select an item.

For example, if the endpoint returns:

```json theme={null}
[
  [
    { "phoneNumber": "3034186858" },
    { "firstName": "John" }
  ]
]
```

Use the nested values in a scenario:

```text theme={null}
You are a customer. Your phone number is {{sim_wrapper.api.response[0][0].phoneNumber}}.
Your first name is {{sim_wrapper.api.response[0][1].firstName}}.
```

Property names are case-sensitive and must match the JSON response exactly. For example, `phoneNumber` and `phone_number` are different properties.

## Troubleshooting

* Confirm the endpoint is publicly reachable from Coval and returns a successful HTTP status.
* Confirm the response body is valid JSON.
* Check that every property name and array index in the template matches the response.
* Increase the timeout if the endpoint regularly needs more than 30 seconds.
* Test the endpoint with non-sensitive sample data before running the full test set.

If a referenced value is unavailable, the template cannot be resolved in the simulation input.