# Batch (Actions) Destination

## Destination Info

* Accepts [Page](/docs/segment/connections/spec/page), [Alias](/docs/segment/connections/spec/alias), [Group](/docs/segment/connections/spec/group), [Identify](/docs/segment/connections/spec/identify), [Track](/docs/segment/connections/spec/track) calls.
* Refer to it as **Batch (Actions)** in the [Integrations object.](/docs/segment/guides/filtering-data/#filtering-with-the-integrations-object)
* This integration is **partner owned.** Please reach out to the partner's support for any issues.
* This destination is **Beta.**

[Batch](https://batch.com/?utm_source=segmentio\&utm_medium=docs\&utm_campaign=partners) is a customer engagement platform for personalized, timely notifications and messages that boost retention and drive growth.

This destination is maintained by Batch. For any issues, [contact Batch Support](mailto:support@batch.com).

## Getting started

1. From your workspace's [destinations catalog](https://app.segment.com/goto-my-workspace/destinations/catalog), search for **Batch**.
2. Select **Batch (Actions)** and click **Add Destination**.
3. Choose the **source** you want to connect to **Batch (Actions)**.
4. In the [Batch dashboard](https://dashboard.batch.com/), copy your **Project Key** and **REST API Key**.
5. Paste the **Project Key** and **REST API Key** into the Batch destination settings in Segment.
6. Toggle **Enable Destination**. Segment will start sending data to Batch according to your **Mappings**.

![The Braze destination Basic Settings page in the Segment app.](https://docs-resources.prod.twilio.com/7d481d11812ef3cd24bf34a22869f228e2f94bdcff6a8315125483d7d037322c.png)

## Destination Settings

| Field        | Description                                                                 | Required | Type     |
| ------------ | --------------------------------------------------------------------------- | -------- | -------- |
| REST API Key | Token used to authorize sending data to the Destination platform            | Yes      | password |
| Project Key  | The unique project key identifying your project in the Destination platform | Yes      | string   |

## Available Presets

Batch (Actions) has the following presets

| Preset Name    | Trigger                                        | Default Action      |
| -------------- | ---------------------------------------------- | ------------------- |
| Update Profile | Event type = "identify", Event  type = "track" | Update User Profile |

## Available Actions

Build your own Mappings. Combine supported [triggers](/docs/segment/connections/destinations/actions/#components-of-a-destination-action) with the following Batch-supported actions:

> \[!NOTE]
>
> Individual destination instances have support a maximum of 50 mappings.

* [Update User Profile](#update-user-profile-2)

### Update User Profile

Sends user events or creates and updates user profiles in Batch.

Update User Profile is a **Cloud** action. The default Trigger is `type = "identify" or type = "track"`

| Field              | Description                                                                     | Required | Type   |
| ------------------ | ------------------------------------------------------------------------------- | -------- | ------ |
| Identifiers        | User identifiers                                                                | Yes      | OBJECT |
| Profile attributes | Attributes for the user profile. Batch can accept up to 50 attributes per user. | No       | OBJECT |
| Event Name         | The name of the event.                                                          | No       | STRING |
| Event Attributes   | An object containining the event's attributes                                   | No       | OBJECT |

## Profile attributes mapping

> \[!NOTE]
>
> If you're new to the Identify call, see the [Segment spec](/docs/segment/connections/spec/identify/) for more details.

When you call **Identify**, Segment maps `userId` to **`identifiers.custom_id`** and writes traits into **`attributes`**.

### Example Identify call (Segment input)

```js
analytics.identify("97980cfea0067", {
  name: "Peter Gibbons",
  email: "peter@example.com",
  phone: "+33600000000",
  email_marketing: "subscribed",
  sms_marketing: "unsubscribed",
  plan: "premium",
  logins: 5
}, {
  context: {
    timezone: "Europe/Paris",
    locale: "fr-FR"
  }
});
```

### Auto-mapped fields (native)

| Segment field                                     | Batch field                   |
| ------------------------------------------------- | ----------------------------- |
| `userId`                                          | `identifiers.custom_id`       |
| `traits.email`                                    | `attributes.$email_address`   |
| `traits.phone`                                    | `attributes.$phone_number`    |
| `traits.email_marketing`                          | `attributes.$email_marketing` |
| `traits.sms_marketing`                            | `attributes.$sms_marketing`   |
| `context.timezone`                                | `attributes.$timezone`        |
| `context.locale` → language *(for example: `fr`)* | `attributes.$language`        |
| `context.locale` → region *(for example: `FR`)*   | `attributes.$region`          |

**Notes**

* `$email_marketing` / `$sms_marketing`: use `subscribed` / `unsubscribed`.
* A locale like `fr-FR` is split into **language** (`fr`) and **region** (`FR`).
* All other non‑reserved fields become **custom attributes** under `attributes` (strings, numbers, booleans, arrays of strings). Avoid arbitrary nested objects.

> \[!NOTE]
>
> For more details on the fields to be included, refer to the Batch [API Profile documentation](https://doc.batch.com/developer/api/cep/profiles/update).

### Resulting Batch profile payload (output)

```json
{
  "identifiers": {
    "custom_id": "97980cfea0067"
  },
  "attributes": {
    "$email_address": "peter@example.com",
    "$phone_number": "+33600000000",
    "$email_marketing": "subscribed",
    "$sms_marketing": "unsubscribed",
    "$language": "fr",
    "$region": "FR",
    "$timezone": "Europe/Paris",

    "name": "Peter Gibbons",
    "plan": "premium",
    "logins": 5
  }
}
```

### Add custom mappings

To map additional traits into Batch profile attributes:

1. Open your destination → **Mappings** → **Edit Mapping**.
2. Go to **Profile attributes** → **Add Mapping Field**.
3. Choose a **source** (for example, `traits.plan`) and set a **target** under `attributes` (for example, `attributes.plan`).

   ![Segment UI mapping dialog for marketing consent key-value pair.](https://docs-resources.prod.twilio.com/ca3e74e7556033779718a01a4747ec2f77e3d7ce15719ea91ffb57c8d4ad5175.png)
4. In **Step 4 – Send test record**, you can test your mapping before saving.

   ![Send test record screen showing test event configuration and API call result.](https://docs-resources.prod.twilio.com/d56406c3f152e849400ebf833dd769dd10ab152caa7ba2fa307bd0b260c62fe5.png)
5. **Save** and enable the mapping.

> \[!NOTE]
>
> Strings, numbers, booleans, arrays of strings are supported.
> Avoid arbitrary nested objects.

## Historical backfill request

If you want to integrate your entire Segment userbase into Batch using the **Identify** method, you can request a historical backfill from Segment.

To do this:

1. **Contact Segment Support** at [friends@segment.com](mailto:friends@segment.com).
2. **Request a historical replay** of your data.
3. Provide Segment with the following details:
   * **Start date and time**
   * **End date and time** (usually "now")
   * **Source**: the Segment source you want to replay
   * **Destination**: **Batch (Actions)**
   * **Events**: `Identify`

Segment will then replay your historical data so Batch can import your full userbase.

## Profile events mapping

When you call **Track**, Segment uses your `userId` as Batch's **`identifiers.custom_id`**. A **userId is required** to attribute the event to a profile.

> \[!NOTE]
>
> For more details on the Track call, see the [Track spec](/docs/segment/connections/spec/track).

### Example Track call (Segment input)

```js
analytics.track("User Registered", {
  plan: "Pro Annual",
  accountType: "Facebook"
}, {
  userId: "97980cfea0067"
});
```

### How Segment maps to Batch

| Segment        | Batch                   |
| -------------- | ----------------------- |
| `userId`       | `identifiers.custom_id` |
| `event`        | `event.name`            |
| `properties.*` | `event.attributes.*`    |

### Resulting Batch event payload (output)

```json
{
  "identifiers": {
    "custom_id": "97980cfea0067"
  },
  "event": {
    "name": "User Registered",
    "attributes": {
      "plan": "Pro Annual",
      "accountType": "Facebook"
    }
  }
}
```

Events are sent to Batch in near real time according to your destination mappings, and all event `properties` are included under `event.attributes`.

![Partial screenshot of event mappings settings in the Segment app.](https://docs-resources.prod.twilio.com/03eba91a457c87e6be33bdaafeddac800c4b5919989cb005eaff8f846b931ca0.png)

## Validation checklist

* Always send a stable `userId` → becomes `identifiers.custom_id`.
* Place native profile fields under `attributes`: `$email_address`, `$email_marketing`, `$phone_number`, `$sms_marketing`, `$language`, `$region`, `$timezone`.
* Put everything else under **custom attributes** in `attributes`.
* Format dates using **ISO‑8601 UTC** (for example: `1989-07-20T00:00:00Z`).
* Configure additional mappings in **Mappings → Edit Mapping**.
* Test with a read-back or export to verify types, encodings, and timezones.

## Integrating a computed trait

> \[!NOTE]
>
> For more details on computed traits, see the [Segment spec](/docs/segment/unify/traits/computed-traits).

To integrate a computed trait with Batch:

1. Go to your **Segment workspace**.
2. Open the **Engage** tab → **Destinations**.
   * If your Batch destination is already listed, skip this step.
   * Otherwise, click **Add destination** and select **Batch (Actions)**.
3. Open the **Engage** tab → **Audiences** → **Computed traits**.
4. Click **Create computed trait**.
5. Configure your **calculation method** (for example: count, aggregation, last value).
6. Click **Preview**, then **Next**.
7. Select your **Batch destination**.
8. Choose how to send the data:
   * For an attribute → enable **Send Identify** in the connection settings.
   * For an event → enable **Send Track**.
9. Give your computed trait a **clear name**.

Segment will then automatically update and forward your computed trait data to Batch.

## Engage

You can send computed traits and audiences generated using [Engage](/docs/segment/engage) to this destination as a **user property**. To learn more about Engage, schedule a [demo](https://segment.com/contact/demo).

For user-property destinations, an [identify](/docs/segment/connections/spec/identify/) call is sent to the destination for each user being added and removed. The property name is the snake\_cased version of the audience name, with a true/false value to indicate membership. For example, when a user first completes an order in the last 30 days, Engage sends an Identify call with the property `order_completed_last_30days: true`. When the user no longer satisfies this condition (for example, it's been more than 30 days since their last order), Engage sets that value to `false`.

When you first create an audience, Engage sends an Identify call for every user in that audience. Later audience syncs only send updates for users whose membership has changed since the last sync.

> \[!NOTE]
>
> Real-time audience syncs to Batch (Actions)  may take six or more hours for the initial sync to complete. Upon completion, a sync frequency of two to three hours is expected.

## Settings

Segment lets you change these destination settings from the Segment app without having to touch any code.

| Field        | Description                                                                 | Required | Type     |
| ------------ | --------------------------------------------------------------------------- | -------- | -------- |
| REST API Key | Token used to authorize sending data to the Destination platform            | Yes      | password |
| Project Key  | The unique project key identifying your project in the Destination platform | Yes      | string   |