***

title: Use the X-EI SIP header
subtitle: null
slug: x-ei-sip-header
description: null
-----------------

<Warning>
  The `X-EI` header still works, but Synthflow now accepts any custom `X-*` SIP header on inbound calls. For most use cases, [arbitrary X-headers](/sip-x-headers-in-prompts) are simpler and more flexible.
</Warning>

The `X-EI` SIP header lets you pass downstream call metadata from your SBC, PBX, or carrier into Synthflow so agents, analytics, and post-call workflows immediately inherit that context. Use it any time you need to correlate distributed call legs or identify where a transfer originated.

## When to use X-EI

* Preserve a platform-native call ID (`Twilio CallSid`, carrier GUID, etc.) for every leg of a transfer so custom actions can cross-reference it without re-mapping IDs.
* Carry your own external call identifiers from PBXs or CRMs to keep reporting aligned between Synthflow and legacy systems.
* Track diversion chains even when carriers strip the standard Diversion header—Synthflow can reconstruct it through `X-EI`.

## Header format

`X-EI` expects a semicolon-delimited list of tokens. Each token begins with one of three prefixes followed by a dot and the value:

```
(S|E|O).([^\;]+);
```

You can send any subset of tokens in any order. All combinations are valid.

| Token             | Purpose                                                                                                                 | Example           |
| :---------------- | :---------------------------------------------------------------------------------------------------------------------- | :---------------- |
| `S.<call_id>`     | Synthflow's Call ID.                                                                                                    | `S.abc123;`       |
| `E.<external_id>` | Your own call ID from a PBX, CRM, or ticketing system so every leg of the call maps back to your records.               | `E.crm456;`       |
| `O.<diversion>`   | Original caller or diversion history. Synthflow proxies fall back to `X-Diversion` if the Diversion header is stripped. | `O.+15551234567;` |

```
X-EI: S.abc123;E.crm456;O.+15551234567;
```

<Note>
  Avoid semicolons in the token values. Each token ends with `;`, so additional semicolons break parsing.
</Note>

## Using the values in Synthflow

Once the INVITE reaches Synthflow, the platform maps the token values to reusable placeholders for prompts, actions, and post-call workflows:

| Placeholder     | Source token      |
| :-------------- | :---------------- |
| `<call_id>`     | `S.<call_id>`     |
| `<external_id>` | `E.<external_id>` |
| `<diversion>`   | `O.<diversion>`   |

You can call these placeholders inside before-the-call or during-the-call custom actions without additional setup. The `E.` token also surfaces as `call.external_id` in the [post-call webhook response](/webhooks).

## Example: Passing external\_id via Twilio Dial SIP

![Configuration](https://files.buildwithfern.com/synthflow.docs.buildwithfern.com/d8725a1eff85baa9d23d067258c8b0db0252a1ffa895312dc0635ad09a069be7/docs/assets/screenshots/x-ei-sip-header.png)

```
TwiML snippet

voice.dial().sip(
  f"sip:{CURRENT_CUSTOM_NUMBER}@{CFG.termination}?X-EI=S.{synthflow_call_id};E.someExternalID;"
)
```

In this example, we are passing E.someExternalID inside the Dial().sip(...) URI.

## Deployment notes

* Combine any tokens you need—`S + E`, `S + O`, or all three.
* Keep values short to avoid SIP header size limits, especially on UDP trunks.
* If upstream carriers remove Diversion, Synthflow merges the contents of `X-Diversion` into the `O.` token automatically.
* Ensure the header remains URL-encoded if you add it to a query string inside your SIP target URI.

## Troubleshooting checklist

* Header missing? Verify your SBC forwards custom SIP headers end-to-end.
* Wrong `external_id` in webhooks? Confirm the `E.` token matches the format `E.<your_id>;` and isn’t URL-escaped twice.
* Diversion chain incomplete? Check whether the carrier strips Diversion—Synthflow only reconstructs it if `X-Diversion` is present.