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

# Pre-Call Data Fetch

> Fetch customer data from your CRM or ERP before the call starts, so your voice agent can greet callers by name and reference their account details.

Pre-Call Data Fetch allows you to enrich the call context with external data before the voice agent starts speaking. Configure it on the [**Start Call**](/voice-agent/start-call) node for every call or inbound calls only. While the response is loading, the caller hears a ring-back tone. Once the data arrives, it is merged into the call's [initial context](/core-concepts/context-and-variables#initial_context) and becomes available as template variables in your prompts and greetings.

## How It Works

1. A call arrives.
2. Tig.ai sends a **POST** request to your configured endpoint with a standardized payload.
3. The caller hears a ring-back tone while waiting for the response.
4. Your API responds with a JSON object containing an `initial_context` object.
5. The variables are merged into the call's initial context.
6. The voice agent starts with full access to the fetched data via `{{variable_name}}` syntax.

## Configuration

Open the [**Start Call**](/voice-agent/start-call) node editor and expand **Advanced Settings**. Choose a **Pre-Call Data Fetch** mode and configure the endpoint when the mode is not disabled:

| Field                   | Description                                                                                                        |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Pre-Call Data Fetch** | **Disabled**, **Always**, or **Inbound calls only**.                                                               |
| **Endpoint URL**        | The URL Tig.ai will send the POST request to.                                                                      |
| **Authentication**      | Optional credential for authenticating the request. Supports API key, bearer token, basic auth, and custom header. |

## Request Format

Tig.ai sends a `POST` request with the following JSON payload:

```json theme={null}
{
  "event": "call_inbound",
  "call_inbound": {
    "agent_id": 123,
    "from_number": "+12137771234",
    "to_number": "+12137771235"
  }
}
```

| Field                      | Description                                                       |
| -------------------------- | ----------------------------------------------------------------- |
| `event`                    | Always `"call_inbound"`.                                          |
| `call_inbound.agent_id`    | The workflow (agent) ID.                                          |
| `call_inbound.from_number` | The caller's phone number (`caller_number` from initial context). |
| `call_inbound.to_number`   | The called phone number (`called_number` from initial context).   |

The `Content-Type` header is set to `application/json`. If you configured a credential, the corresponding authentication header is included.

## Expected Response Format

Your API should return a **JSON object** with a `2xx` status code. The variables to inject into the call context should be placed inside the `initial_context` key:

```json theme={null}
{
  "call_inbound": {
    "initial_context": {
      "customer_name": "Jane Doe",
      "account_status": "active",
      "loyalty_tier": "gold",
      "open_tickets": 2
    }
  }
}
```

You can also place `initial_context` at the top level:

```json theme={null}
{
  "initial_context": {
    "customer_name": "Jane Doe",
    "account_status": "active"
  }
}
```

<Note>
  The legacy `dynamic_variables` key is still accepted as a drop-in alias for `initial_context`, so existing integrations keep working without any changes. Use `initial_context` for new integrations. If a response contains both keys, `initial_context` takes precedence.
</Note>

After the response is received, you can reference these values anywhere template variables are supported:

* **Greeting**: `Hello {{customer_name}}, thank you for calling!`
* **Prompt**: `The customer is a {{loyalty_tier}} member with {{open_tickets}} open support tickets.`

<Note>
  If the response is not a valid JSON object, does not contain `initial_context` (or the legacy `dynamic_variables`), or the request fails or times out, the call proceeds normally without the additional context. The pre-call fetch never blocks or fails a call.
</Note>

## Nested Variables

If your `initial_context` contains nested objects, you can access them using dot notation:

```json theme={null}
{
  "call_inbound": {
    "initial_context": {
      "customer": {
        "name": "Jane Doe",
        "address": {
          "city": "Los Angeles"
        }
      }
    }
  }
}
```

Access in prompts as `{{customer.name}}` and `{{customer.address.city}}`.

## Timeout

The request has a **10-second timeout**. If your API does not respond within this window, the call proceeds without the fetched data. Design your endpoint to respond as quickly as possible to minimize the ring-back tone duration.

## Testing with Test Calls

When a real phone call comes in, the `caller_number` and `called_number` context variables are automatically set by the telephony provider and included in the pre-call data fetch request as `from_number` and `to_number`. However, when you make a test call — either a **web call** (WebRTC) or a **phone test call** from the workflow editor — these variables are not available by default.

To simulate telephony data during testing:

1. Open your workflow and go to **Settings**.
2. Under **Context Variables**, add the following variables:
   * `caller_number` — set to a phone number you want to simulate as the caller (e.g., `+12137771234`).
   * `called_number` — set to the number that would be dialed (e.g., `+12137771235`).
3. Save the settings.

Now when you make a test call (web or phone), these values will be sent in the pre-call data fetch request to your endpoint, allowing you to test the full flow as if a real inbound call were coming in.

<Note>
  These context variables are only used during test calls from the workflow editor. On production inbound calls, the actual telephony data is used and these values are ignored.
</Note>

## Example Integration

A simple Node.js endpoint that looks up a customer by phone number:

```javascript theme={null}
app.post("/tig/pre-call", async (req, res) => {
  const { call_inbound } = req.body;

  const customer = await db.customers.findOne({
    phone: call_inbound.from_number,
  });

  if (!customer) {
    return res.json({});
  }

  res.json({
    call_inbound: {
      initial_context: {
        customer_name: customer.name,
        account_status: customer.status,
        loyalty_tier: customer.tier,
      },
    },
  });
});
```