> For the complete documentation index, see [llms.txt](https://docs.chord.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.chord.co/activate/event-streaming/destinations/email-and-marketing/insider/insider-one.md).

# Insider One

This destination sends events to Insider One using the server-side Upsert API, so it is not affected by ad blockers or browser restrictions. See [Insider](/activate/event-streaming/destinations/email-and-marketing/insider.md) for how it fits with the [Insider Pixel](/activate/event-streaming/destinations/email-and-marketing/insider/insider-pixel.md) version.

## Getting started

Get your account name and API key from Insider One. The account name is in **InOne Panel > Settings > Inone Settings > Account Preferences**. The API key is in **InOne Panel > Settings > Preferences > Integration Settings**.

## Settings

* **Destination Name** (required): a name to tell this destination apart.
* **Account Name** (required): your Insider One account name.
* **API Key** (required): your Insider One API key.
* **Treat Email as Identifier** (optional): if on, the user's email address is sent as an Insider One identifier in addition to the user ID. Off by default.
* **Treat Phone Number as Identifier** (optional): if on, the user's phone number is sent as an Insider One identifier. Off by default.
* **Consent Requirements** (optional): the consent categories a visitor must accept before Chord sends data to this destination. See [Consent](/activate/event-streaming/consent.md).

## Connect

Add **Insider One** from the destination catalog, using the settings above. See [Connect a destination](/activate/event-streaming/connect-a-destination.md) for the full steps.

## Event mapping

| Chord event | Insider One event          | Notes                                                            |
| ----------- | -------------------------- | ---------------------------------------------------------------- |
| `identify`  | `POST /api/user/v1/upsert` | Updates user attributes and identifiers; no event recorded       |
| `track`     | `POST /api/user/v1/upsert` | Sends one or more events; user attributes updated simultaneously |
| `page`      | `POST /api/user/v1/upsert` | Sent as a `page_view` event                                      |

Unsupported event types (e.g. `group`, `alias`) are silently dropped.

## Ecommerce event name mapping

Chord ecommerce track event names are translated to Insider One's reserved event names:

| Chord event            | Insider One event          | Notes |
| ---------------------- | -------------------------- | ----- |
| `Product Viewed`       | `product_detail_page_view` |       |
| `Product List Viewed`  | `listing_page_view`        |       |
| `Product Added`        | `item_added_to_cart`       |       |
| `Product Removed`      | `item_removed_from_cart`   |       |
| `Cart Viewed`          | `cart_page_view`           |       |
| `Order Completed`      | `confirmation_page_view`   |       |
| `Checkout Started`     | `checkout_page_view`       |       |
| `Checkout Step Viewed` | `checkout_page_view`       |       |
| `User Registered`      | `sign_up_confirmation`     |       |

All other event names are lowercased and spaces are replaced with underscores (e.g. `Button Clicked` → `button_clicked`). Note: camelCase names are not converted — `myCustomEvent` becomes `mycustomevent`, not `my_custom_event`.

## Identify events

Identify events update user attributes in Insider One. No event entry is recorded.

| Chord source (priority order)                                                                        | Insider One field                         | Notes                                                                                                                                                             |
| ---------------------------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `userId`                                                                                             | `identifiers.uuid`                        | Primary user identifier                                                                                                                                           |
| `properties.email` > `traits.email` > `context.traits.email`                                         | `identifiers.email`                       | Only included if **Treat Email as Identifier** is enabled                                                                                                         |
| `properties.phone` > `traits.phone` > `context.traits.phone`, then the same order for `phone_number` | `identifiers.phone_number`                | Only included if **Treat Phone Number as Identifier** is enabled                                                                                                  |
| `anonymousId`                                                                                        | `identifiers.custom.segment_anonymous_id` | Always included as a custom identifier                                                                                                                            |
| `context.traits` merged with `traits`                                                                | `attributes.*`                            | If a trait is in both, `traits` wins. Reserved attribute names mapped directly; others placed in `attributes.custom`. See [Attribute mapping](#attribute-mapping) |

## Track events

Track events send one or more event entries to Insider One alongside updated user attributes.

| Chord source (priority order)                                                                        | Insider One field                         | Notes                                                                                                                                                             |
| ---------------------------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `userId`                                                                                             | `identifiers.uuid`                        | Primary user identifier                                                                                                                                           |
| `properties.email` > `traits.email` > `context.traits.email`                                         | `identifiers.email`                       | Only included if **Treat Email as Identifier** is enabled                                                                                                         |
| `properties.phone` > `traits.phone` > `context.traits.phone`, then the same order for `phone_number` | `identifiers.phone_number`                | Only included if **Treat Phone Number as Identifier** is enabled                                                                                                  |
| `anonymousId`                                                                                        | `identifiers.custom.segment_anonymous_id` | Always included as a custom identifier                                                                                                                            |
| `context.traits` merged with `traits`                                                                | `attributes.*`                            | If a trait is in both, `traits` wins. Reserved attribute names mapped directly; others placed in `attributes.custom`. See [Attribute mapping](#attribute-mapping) |
| `event` (translated via ecommerce map)                                                               | `events[].event_name`                     | See [Ecommerce event name mapping](#ecommerce-event-name-mapping)                                                                                                 |
| `timestamp`                                                                                          | `events[].timestamp`                      | ISO 8601 format                                                                                                                                                   |
| `properties`                                                                                         | `events[].event_params.*`                 | Reserved param names mapped directly; others placed in `event_params.custom`. See [Event parameter mapping](#event-parameter-mapping)                             |

Chord sends one event entry for each product. For `Order Completed`, `Checkout Started`, `Checkout Step Viewed`, `Cart Viewed`, `Product List Viewed` and `Payment Info Entered`, that means each item in `properties.products`. For any other event with a top-level `product_id`, `sku` or `variant`, Chord sends one entry for that product. An event with no products sends one entry built from `properties`. The product ID is `product_id` > `sku` > `id`.

Top-level properties (e.g. `currency`, `order_id`) are merged into each product's event params, except `products` and `product_id`. If a field is on both, the product's own value wins. Chord skips a `track` event that has no event name.

## Page events

Page events are sent as `page_view` events.

| Chord source (priority order)                                                                        | Insider One field                         | Notes                                                                                                                                                             |
| ---------------------------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `userId`                                                                                             | `identifiers.uuid`                        | Primary user identifier                                                                                                                                           |
| `properties.email` > `traits.email` > `context.traits.email`                                         | `identifiers.email`                       | Only included if **Treat Email as Identifier** is enabled                                                                                                         |
| `properties.phone` > `traits.phone` > `context.traits.phone`, then the same order for `phone_number` | `identifiers.phone_number`                | Only included if **Treat Phone Number as Identifier** is enabled                                                                                                  |
| `anonymousId`                                                                                        | `identifiers.custom.segment_anonymous_id` | Always included as a custom identifier                                                                                                                            |
| `context.traits` merged with `traits`                                                                | `attributes.*`                            | If a trait is in both, `traits` wins. Reserved attribute names mapped directly; others placed in `attributes.custom`. See [Attribute mapping](#attribute-mapping) |
| *(hardcoded)* `page_view`                                                                            | `events[].event_name`                     |                                                                                                                                                                   |
| `timestamp`                                                                                          | `events[].timestamp`                      | ISO 8601 format                                                                                                                                                   |
| `properties.url` > `context.page.url`                                                                | `events[].event_params.url`               |                                                                                                                                                                   |
| `properties.referrer` > `context.page.referrer`                                                      | `events[].event_params.referrer`          |                                                                                                                                                                   |
| remaining `properties`                                                                               | `events[].event_params.*`                 | Reserved params mapped directly; others in `event_params.custom`                                                                                                  |

## Attribute mapping

Chord trait names are lowercased and spaces replaced with underscores before being matched against Insider One's reserved attribute names. Note: camelCase traits are not converted to snake\_case — send reserved attributes using Insider One's expected names to have them mapped correctly. Unrecognized traits are placed in the `attributes.custom` object.

**Special-cased trait mappings:**

| Chord source (priority order) | Insider One field | Notes                                                    |
| ----------------------------- | ----------------- | -------------------------------------------------------- |
| `firstName`                   | `name`            | Renamed to match Insider's reserved field                |
| `lastName`                    | `surname`         | Renamed to match Insider's reserved field                |
| `address.city`                | `city`            | Nested trait flattened                                   |
| `address.country`             | `country`         | Nested trait flattened                                   |
| `locale`                      | `locale`          | Hyphens converted to underscores, e.g. `en-US` → `en_US` |

**Reserved attributes** (mapped directly when sent with the exact Insider field name):

| Insider One attribute | Notes |
| --------------------- | ----- |
| `email`               |       |
| `phone_number`        |       |
| `age`                 |       |
| `birthday`            |       |
| `name`                |       |
| `gender`              |       |
| `surname`             |       |
| `city`                |       |
| `country`             |       |
| `app_version`         |       |
| `idfa`                |       |
| `model`               |       |
| `last_ip`             |       |
| `carrier`             |       |
| `os_version`          |       |
| `platform`            |       |
| `timezone`            |       |
| `locale`              |       |
| `gdpr_optin`          |       |
| `email_optin`         |       |
| `sms_optin`           |       |
| `whatsapp_optin`      |       |
| `language`            |       |

Any trait not in the special-cased list or reserved attributes list is placed in `attributes.custom`.

## Event parameter mapping

Chord property names are lowercased and spaces replaced with underscores. Note: camelCase property names are not converted to snake\_case. Known property aliases are remapped to Insider One's reserved event parameter names:

**Aliased property mappings:**

| Chord source (priority order) | Insider One field   | Notes                                                                                                       |
| ----------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------- |
| `order_id` or `cart_id`       | `event_group_id`    |                                                                                                             |
| `category`                    | `taxonomy`          | Wrapped in array if not already                                                                             |
| `image_url`                   | `product_image_url` |                                                                                                             |
| `price`                       | `unit_sale_price`   | Fallback only — applied when `unit_sale_price` is not explicitly set on the product or top-level properties |

{% hint style="info" %}
Insider One requires `unit_sale_price` on ecommerce events such as `confirmation_page_view` (mapped from `Order Completed`). Because Chord Pixel sends the Segment-standard `price` on products, this destination automatically aliases `price` → `unit_sale_price` when no explicit `unit_sale_price` is provided. If you send both, the explicit `unit_sale_price` wins and `price` is placed in `event_params.custom.price`.
{% endhint %}

**Reserved event parameters** (mapped directly when sent with the exact Insider field name):

| Insider One event parameter |
| --------------------------- |
| `campaign_id`               |
| `campaign_name`             |
| `url`                       |
| `product_id`                |
| `user_agent`                |
| `taxonomy`                  |
| `name`                      |
| `variant_id`                |
| `unit_sale_price`           |
| `unit_price`                |
| `quantity`                  |
| `product_image_url`         |
| `event_group_id`            |
| `referrer`                  |
| `currency`                  |

Any property not in the aliased or reserved lists is placed in `event_params.custom`.

## Testing and validation

After connecting the destination:

1. Trigger a test event from your storefront or use the **Live Events** tab in Chord.
2. In Insider One, navigate to **InOne Panel > Audience** and verify the user profile was created or updated.
3. Check event history under the user profile to confirm events were received.
4. Review the **API Destinations & Functions Logs** tab in **Live Events** for any API errors or credential issues.

## Use cases

* **Personalize onsite experiences** using purchase history and loyalty tier attributes synced from Chord.
* **Trigger re-engagement journeys** when Chord sends a track event like `Subscription Cancelled` or `Cart Abandoned`.
* **Build high-value segments** in Insider using enriched customer attributes from Chord (e.g., LTV tier, acquisition channel).
* **Suppress messaging** by syncing opted-out users from Chord to keep Insider audiences up to date.
* **Activate post-purchase flows** by sending `Order Completed` events with product and revenue details.

## Best practices

* **Always include an identifier.** Insider needs at least one identifier (email, phone, or UUID) to match or create a profile. Events without identifiers will be dropped.
* **Use consistent user IDs.** Ensure the `userId` sent from Chord matches the UUID Insider already has on file for existing profiles.
* **Format phone numbers correctly.** Include the country code (e.g., `+14155550123`). Incorrectly formatted numbers will not match existing profiles.
* **Filter events deliberately.** Sending all track events is rarely necessary. Start with high-signal events (e.g., `Order Completed`, `Product Viewed`) and expand from there.
* **Monitor delivery logs after launch.** Check for 4xx errors in the first few days — these typically indicate a mapping or credential issue.

## Troubleshooting

### Data not sending

**Problem:** Events are not appearing in Insider One after the destination is enabled.

* Confirm the destination is enabled in Chord.
* Verify your **API Key** and **Account Name** are correct — a single character error will cause all requests to fail.
* Check the **API Destinations & Functions Logs** tab in **Live Events** for error responses (look for 401 or 403 status codes).
* Confirm that the event types you want to send (identify, track, page) are being emitted by your storefront.

### Missing attributes

**Problem:** User profiles appear in Insider One but expected attributes (e.g., custom traits) are missing.

* Custom traits not in Insider's reserved attribute list are nested under `attributes.custom`. Verify the attribute name in Insider includes the `custom.` prefix.
* Check whether the attribute exists in Insider's schema. New custom attributes may need to be created in Insider before data can be written to them.
* Confirm the trait is present on the identify event being sent from Chord by inspecting the **Live Events** payload.

### Duplicate users

**Problem:** Insider One is creating multiple profiles for the same customer.

* Confirm that identify events consistently include the same identifier (email or UUID). Inconsistent identifiers cause Insider to create separate profiles.
* If your store captures both anonymous and logged-in sessions, ensure an identify call is sent when a user logs in so Insider can merge the profiles.
* Check that phone numbers are formatted consistently — a mismatch (e.g., with and without country code) can prevent profile matching.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.chord.co/activate/event-streaming/destinations/email-and-marketing/insider/insider-one.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.