# 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

If you're not familiar with the Segment Specs, take a look to understand what the [Identify method](/docs/segment/connections/spec/identify/) does. An example call would look like:

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

Identify calls will be sent to Userlist as user records. If the `userId` is already known, it'll update the user record, otherwise it'll create 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

If you're not familiar with the Segment Specs, take a look to understand what the [Track method](/docs/segment/connections/spec/track/) does. An example call would look like:

```javascript
analytics.track('Project created', {
  projectName: 'Party Planning'
});
```

Track calls will be sent to Userlist as a new event. You may send additional properties to describe the event in more detail. Both the event name and additional properties will be stored with the event and normalized to snake case (`project_created` and `project_name`) automatically within Userlist.

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

```javascript
analytics.track(
  'Project created',
  {
    projectName: 'Party Planning'
  },
  {
    context: {
      groupId: 'companyId123'
    }
  }
);
```

## Group

If you're not familiar with the Segment Specs, take a look to understand what the [Group method](/docs/segment/connections/spec/group/) does. An example call would look like:

```javascript
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.        |

Group calls will be sent to Userlist as company records. If the `groupId` is already known, it'll update the company record, otherwise it'll create 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
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.

> \[!NOTE]
>
> Real-time audience syncs to Userlist  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   |
| ------- | -------------------------------------------------------------------- | -------- | ------ |
| API Key | Please enter the token available in your Userlist Push API settings. | Yes      | string |