Skip to main content


The Customers area provides you with the ability to view and manage your customers, enabling you to send personalized messages to specific groups of customers.

Access it by selecting 'Customers' in the left hand sidebar.


There are three types of fields associated with each customer. The customer's unique ID is the only required field, all other fields are optional.

  1. Profile: this includes optional personal details such as name, email address, location and an external ID.
  2. Custom fields: any other fields you would like to add. E.g. a “churn risk” score, or their preferred name. This field type can accommodate either a date or a string value.
  3. Analytics fields: this includes your customer’s platform and device related information, as well as event-related data, such as when they were first and last seen and more.

Once added to Atomic, analytics fields will automatically be populated, including data such as the timezone they were last seen in, their operating system, and when they last completed a card.

Managing customers

Customers can be managed via API or manually in the Workbench via a csv upload.
It is not possible to add individual customers, but you can add test accounts for testing purposes, as explained in the Sending cards tutorial.

Add or update customers via CSV

CSV file limits

Make sure your CSV file:

  • is smaller than 128MB in size
  • has less than 100 columns

From the Customers screen, follow these steps:

  1. Click the 'Import' button in the top right. This will open the 'Upload customers from CSV file' window.
  2. Click the 'information' icon next to the title. This opens an information panel.
  3. Click the 'Download a sample csv file'. This csv file contains all of your environment's custom profile fields.


  1. Update the sample csv file with your customer data. The only required property in the CSV file is the 'id' column, but you can provide any other profile or custom fields. Where a customer already exists (with a matching user ID), the properties of that customer will be updated with the data provided by the CSV.
  2. Upload the file and check that the fields match your data correctly. If any fields do not match, you can select the correct field from the column header dropdown.


  1. You can edit the name of the tag that will be applied to all customers in this upload, or prevent it being added before uploading by toggling the 'tag records' switch off. Additionally, you have the option to select and apply one or more of the existing tags. Find out more about using tags in the Tags section below.

  2. Once you've configured the fields that will be imported and the tag(s) that will be applied, you click the 'import records' button. This will open the 'Processing your import' dialogue window, which gives you the option to go to the 'Customer data importer' to track progress of the upload, or click the X to return to the Customers screen.

Manage customers via API

Using our Users API you can add new customers, update or delete existing customers, or retrieve a list of all customers. You can find detailed information about this in the Users API guide. This is also where you can read more about passing customer data with the auth token.


Tags provide a manual way for you to group your customers. They allow you to categorize customers based on criteria you specify, for example – those who joined through a specific event or promotion, VIPs, or customers uploaded in a particular batch.

Adding or removing tags needs to be performed manually, or via API. This is unlike Segments, where customers move in and out of segments dynamically.

In the Workbench, you can create new tags directly when assigning them to a customer(s), or you can create tags in advance, to use later.

Once a tag is created, you can manually assign it to a customer in the Workbench or via API.

Create a tag

There are two ways to create tags in the Workbench. The first is via the Configuration area:

  1. Go to: Configuration → Customer profiles → Tags. Alternatively, open the command palette and type 'Tag'. Click on 'New Tag'.
  2. Give the tag a name.
  3. Select 'Save'.

The second way to create new tags is within the Customers area. This can be done while assigning a tag to a customer as explained in the next section.

Assign a tag to a customer

  1. Select the customer(s) you want to tag by selecting the checkbox(es) next to the respective customers.
  2. Click 'Tag customer(s)' located towards the top-right of the screen and select the tag(s) you want to add. Additionally, you have the option to create and assign new tags at the same time.
  3. Select 'Save'.

Customer tags can also be added, removed, or retrieved via API. See the Users API guide to find out more.


A segment is a predefined set or combination of filters that enables you to target specific customers.

Unlike tags where customers are added to the group either manually or via API, customers enter and leave a Segment dynamically based on the filter conditions being met (or not). For example, you can create segments based on:

  • the timezone a customer last logged in from
  • the customer not completing any cards in the last month
  • the customer's date of birth being in between two dates

You can create filters based on profile fields (including custom fields and activity fields), events or tags.

Create a Segment

  1. In the Customers screen, click on the + button next to the word Segments on the left side of your screen.
  2. In the 'Create a new segment' window, give the segment a name and an optional description before clicking 'Create'.

The new segment is created and opened in edit mode.

  1. Click 'add filter' to add one or more filters. When adding more than one filter, you can choose whether all these filter conditions need to be true ('match all') or whether meeting one condition ('match any') is sufficient.
  2. All customers that currently meet the segment criteria are shown on the screen, helping you decide whether the filter conditions have been set up correctly.
  3. Once the filters are configured correctly, click 'save changes'.

When customers are updated through API or CSV, customers will automatically enter the new segment if they meet the criteria specified. They will likewise leave a segment if they no longer meet the criteria.

Example segment with multiple filters


Example: let's say you want to create a segment for all customers that were 'first seen' in the year 2022.

  1. Create a segment (by clicking on the + button), give it a name 'first seen in 2022', and click 'Create'.
  2. Click 'add filter'. In the 'profile field' tab, select 'First seen' (under Activity). Select 'After' as a condition and select '1 January 2022 12:00 AM' as the date and time.
  3. Click 'Apply'. The view shows all customers that were first seen after 1 January 2022.
  4. Click 'add filter'. In the 'profile field' tab, select 'First seen' (under Activity). Now select 'Before' as a condition and select '1 January 2023 12:00 AM' as the date and time.
  5. Click 'Apply'. The view now shows all customers that match all conditions. You can change the 'match all' condition to 'match any' to see how that affects the number of customers.
  6. Click 'save changes'.

Fields for customer filtering

The table below lists all profile fields that can be used to create filters.

Field nameDescription
Atomic createdtime when customer profile was created in Atomic
Atomic IDAtomic ID; each customer is assigned one when created in Atomic
Cityoptional free text field
Countryoptional free text field
Emailoptional free text field
External IDoptional free text field
Nameoptional free text field
Phoneoptional free text field
Regionoptional free text field
Timezoneoptional free text field
User typecustomers can either be "test" or "live" depending on whether they are an internal workbench test user or not

The table below lists all profile activity fields that can be used to create filters.

Field nameDescription
First seentime when customer first interacted with any of the SDKs, based on time of first analytic event received or first successful authentication
Last seentime of last customer activity based on most recent analytics and successful authentication with the SDK
Last seen on iOStime when customer last interacted with the iOS sdk
Last seen on Androidtime when customer last interacted with the Android sdk
Last seen on Webtime when customer last interacted with the Web sdk
Last Android SDK versionversion of the Android SDK the customer last interacted with
Last Android deviceAndroid version and device model the customer used most recently
Last Android OS versionAndroid version the customer used most recently
Last Android device nameAndroid device model the customer used most recently
Last iOS SDK versionversion of the iOS SDK the customer last interacted with
Last iOS deviceiOS version and device model the customer used most recently
Last iOS OS versioniOS version the customer used most recently
Last iOS device nameiOS device model the customer used most recently
Last browserthe user agent string of the last browser used
Last browser namebrowser name of the last browser used
Last browser versionbrowser version of the last browser used
Last browser OSthe operating system the last browser used
Last browser OS versionthe operating system version the last browser used
Last web SDK versionversion of the Web SDK the customer last interacted with

The table below lists all event fields that can be used to create filters.

Field nameDescription
Card cancelledtime when customer cancelled a card
Card completedtime when customer completed a card
Card dismissedtime when customer dismissed a card
Card displayedtime when customer displayed a card
Card embargoedtime when card was embargoed
Card expiredtime when card was expired
Card publishedtime when card was sent
Card snoozedtime when customer snoozed a card
Card subview displayedtime when customer opened a subview
Card subview exitedtime when customer exited a subview
Card unsnoozedtime when card was unsnoozed
Card voted-downtime when card was voted-down
Card voted-uptime when card was voted-up
Notification receivedtime when customer received a push notification
Notification senttime when a push notification was sent
Runtime vars-updatedtime when runtime variables were updated for this customer
SDK initializedtime when any of the SDKs was initialized for this customer
Segment enteredtime when customer entered any segment
Segment exitedtime when customer exited any segment
Snooze options cancelledtime when customer cancelled the snooze options
Snooze options displayedtime when customer displayed the snooze options
Stream displayedtime when any stream was displayed for this customer
User redirectedtime when customer was redirected after clicking a link
Video completedtime when customer completed watching a card video
Video playedtime when customer started watching a card video
Timestamps for user analytics fields

Timestamps are shown in the workbench member's local timezone. When creating a segment based on time, it gets converted to UTC time in the backend. This means that even organizations with workbench members in different timezones will have consistent segments.

When a customer exits or enters a segment the 'segment-entered' or 'segment-exited' events are emitted. These events are available in the analytics data. It is also possible to configure webhooks to send the event payload data to a URL you specify when the events are emitted.

Edit a segment

  1. In the Customers area, select the segment you would like to edit. Click on its name to open its detailed view.
  2. Click on the 'Edit segment' button on the right hand side.
  3. You can now make changes to the segment name, description or filters.
  4. Click the 'save changes' button. When the segment is used as a trigger to one or more cards, you will see a warning message such as the one in the screenshot below.

  1. Confirm again by clicking 'Save changes'.

Delete a Segment

  1. In the Customers area, select the segment you would like to delete.
  2. Then click the overflow menu (3 vertical dots) next to 'Edit segment' and select 'Delete segment'.
  3. When the segment is used as a trigger to one or more cards, you will see a warning message showing what cards the segment is linked to.
  4. Confirm by clicking the 'Delete segment' button.

Custom fields (Beta)

Custom fields let you add other fields to customers' profiles not contained in user or analytics fields.

Add a Custom field

  1. Go to: Configuration > Customer profiles > Custom fields. Alternatively, open the command palette and type 'Field'. Click 'New Field'.
  2. Give the Field a label (the name will automatically be generated).
  3. Give the field a type: either text or a date.
  4. Select ‘Save’.
  5. The Field is now created, and so customer profiles can have the field updated manually or via API.

Multiple values in custom fields

A custom field of the type 'text' can have more than 1 value, separated by commas. These values can be used to filter on, and create segments.

Create a segment based on multiple values in a custom field

  1. Create a custom field as described in the custom fields section.
    Example: a custom field describing a customer's shopping interests.

  1. Update the relevant customers' profile with comma-separated values for this field.
    Example: a customer is interested in arts, music and books.

  1. Create a filter based on the custom field by using the 'contains' condition and one keyword.
    Example: a filter for all customer interested in music.

  1. If you want to include multiple keywords in your segment, you can combine multiple filters using the 'match any' or 'match all' dropdown menu.
    Example: a segment containing all customers interested in music or art.

Limitations of applying filters to multiple values custom fields
  • When you filter on a value that contains (part of) another value, both get returned. When you have two values, 'men' and 'women', filtering on 'men' will also include all values for 'women'. This happens because the text string 'men' is found within the text string 'women'.
  • If you use multiple keywords in 1 filter, the results will be limited to cutomers with those values in that exact order. A filter for 'books, art' will not return the same results as 'art, book'. Using a combination of multiple filters (as described in the section above) is the recommended approach.

Send a card

In the Customers screen, you can select one or more customers to send cards to.

Before you send a card to customers you will need to have a card configured. See creating a card template for how to do this.

The Sending cards tutorial describes in detail how to send cards, while the Sending cards advanced guide describes the different card delivery options.