---
"@context": https://schema.org
"@type": TechArticle
"@id": https://www.twilio.com/docs/segment/connections/destinations/catalog/userlist#article
headline: Userlist Destination
description: Connect Segment to Userlist to send Identify, Track, and Group data as user records, events, and company records for behavior-based SaaS messaging.
url: https://www.twilio.com/docs/segment/connections/destinations/catalog/userlist
inLanguage: en
dateModified: 2026-06-09T16:30:18.000Z
author:
  "@type": Organization
  name: Twilio Developer Education Team
publisher:
  "@type": Organization
  name: Twilio
---

# Userlist Destination

## Destination Info

* Accepts [Identify](/docs/segment/connections/spec/identify), [Track](/docs/segment/connections/spec/track) calls.
* Refer to it as **Userlist** 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.

[Userlist](https://userlist.com/?utm_source=segmentio\&utm_medium=docs\&utm_campaign=partners) allows you to send behavior-based messages to your SaaS users. It's great for onboarding users as well as nurturing them throughout their journey.

This destination is maintained by Userlist. For any issues with the destination, [contact the Userlist Support team](mailto:support@userlist.com).

## Getting Started

1. From the Segment web app, click **Catalog**.
2. Search for "Userlist" in the Catalog, select it, and choose which of your sources to connect the destination to.
3. In the Userlist Segment destination settings, enter your Userlist "Push API Key". You can find this key in your [Userlist Push API settings](https://app.userlist.com/settings/push).

> \[!NOTE]
>
> **NOTE:** The Userlist Destination does not support tracking anonymous users, and returns a 400 error if you send `track` or `group` call for unidentified users. To prevent this, make sure you make an Identify call before you make Track or Group calls. You can also disregard this error if you sent calls you do not intend Userlist to process.

## Identify

Segment sends Identify calls to Userlist as user records. See the [Identify method](/docs/segment/connections/spec/identify/) in the Segment Spec for details. An example call looks like:

```javascript title="Identify call example"
analytics.identify('userId123', {
  email: 'john.doe@example.com',
  name: 'John Doe',
  role: 'Owner',
  createdAt: '2019-03-21T12:12:54.735+01:00'
});
```

If the `userId` is already known, Userlist updates the user record; otherwise, it creates a new one.

Here's how Segment fields map to Userlist users:

| Segment field      | Userlist field | Description                                |
| ------------------ | -------------- | ------------------------------------------ |
| `userId`           | `identifier`   | The unique identifier for this user.       |
| `traits`           | `properties`   | Additional properties describing the user. |
| `traits.email`     | `email`        | The user's email address.                  |
| `traits.createdAt` | `signed_up_at` | The time when the user was created.        |

## Track

Segment sends Track calls to Userlist as new events. See the [Track method](/docs/segment/connections/spec/track/) in the Segment Spec for details. An example call looks like:

```javascript title="Track call example"
analytics.track('Project created', {
  projectName: 'Party Planning'
});
```

You can send additional properties to describe the event in more detail. Userlist stores both the event name and additional properties with the event and normalizes them to snake case (`project_created` and `project_name`) automatically.

To associate an event with both a user and a company, include the company's identifier as `context.groupId` on the Track call:

```javascript title="Track call with company association"
analytics.track(
  'Project created',
  {
    projectName: 'Party Planning'
  },
  {
    context: {
      groupId: 'companyId123'
    }
  }
);
```

## Group

Segment sends Group calls to Userlist as company records. See the [Group method](/docs/segment/connections/spec/group/) in the Segment Spec for details. An example call looks like:

```javascript title="Group call example"
analytics.group('companyId123', {
  name: 'Segment'
});
```

| Segment field      | Userlist field | Description                                |
| ------------------ | -------------- | ------------------------------------------ |
| `groupId`          | `identifier`   | The unique identifier for this company.    |
| `traits`           | `properties`   | Additional properties describing the user. |
| `traits.name`      | `name`         | The company's name.                        |
| `traits.createdAt` | `signed_up_at` | The time when the user was created.        |

If the `groupId` is already known, Userlist updates the company record; otherwise, it creates a new one.

Userlist supports custom properties to describe the relationship between users and groups (such as the user's role in a company). You can pass relationship properties in a Group call by using Userlist-specific extensions.

```javascript title="Group call with relationship properties"
analytics.group(
  'companyId123',
  {
    name: 'Segment'
  },
  {
    integrations: {
      Userlist: {
        extensions: {
          relationship: {
            properties: {
              role: 'owner'
            }
          }
        }
      }
    }
  }
);
```

## 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.

## Settings

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

| Field   | Description                                                          | Required | Type   |
| ------- | -------------------------------------------------------------------- | -------- | ------ |
| API Key | Please enter the token available in your Userlist Push API settings. | Yes      | string |