Getting Your User Data into the System (Integration Guide)

In this article, you’ll learn how to get your customer data flowing into our system: your list of users, their properties, and information about events (activities) they’re performing inside your app.

Instead of offering a JavaScript snippet (which can be unreliable), we rely on the data your application sends to us — and that’s what your developer will need to set up.

When you sign up for a new Userlist account, your list of users is blank. User profiles will start appearing there once you start pushing data for each individual user. When that happens depends on how your developer implements the integration. For example, the Rails library has an import task that gets all users into the system at once (more about that below).

Start planning you campaigns as early as possible — this way you'll know what properties and events to track. Download these free worksheets to speed up the process.

How behavior tracking works

You can track user behavior by sending us user data as well as events.

User data (properties) represents the current state of the user and doesn’t have a temporal aspect — we only store the latest version. One of the properties might have changed in the past, but you cannot tell just by looking at it. User properties include things like their name, company role, their current payment plan, and anything else you prefer to track — like total number of created tasks (in a project management app for example).

Events are composed of an event name, a timestamp to describe when the event occured, a set of additional properties (specific to the event type), and a user that triggered that event. Events are important activities performed by the user inside your application. E.g. in a project management app, events might include things like completed a task, created a new project, etc.

In addition to custom events you send us from your application, Userlist automatically records events that happen inside our system (like when users open a message, click a link, join a segment, etc.). So you don’t have to worry about tracking these things yourself.

Setting up the integration

Integrating Userlist.io into your application is done by sending user data and events into the system via our HTTP JSON API. We also offer libraries for some frameworks and languages that help with the integration. You can find them on GitHub.

Request payloads and responses

The Push API expects payloads as JSON as well as responds with JSON. It’s recommended to set the Accept and Content-Type accordingly.

Accept: application/json
Content-Type: application/json; charset=utf-8

Timestamps are expected to be strings formatted according to ISO 8601: YYYY-MM-DDTHH:MM:SS+HH:MM. If no time zone is given, we’ll assume UTC.  

Object keys, as well as event names, will be normalized to snake_case. You’re free to use any format you like for these, just be aware that we’ll store it in snake_case way.

Authentication

To start sending data into Userlist.io, you first have to get your Push API Key. It is used to authenticate your requests to the Push API and connect the data with your account. Keep this Push API Key secure, or an attacker will be able to mess with your data and automation.

All requests to our Push API need to have the Push API Key in the Authorization header in this format:

Authorization: Push your-push-api-key-here

Errors

When things go wrong, the Push API will respond with appropriate HTTP status codes. Status codes in the 2xx range can be considered as successful. Status codes in the 4xx range indicate a problem with the initial request. Status codes in the 5xx range indicate errors on the server.

The Push API will also respond with a JSON body describing the error in more detail.

{
  "status": 422,
  "errors": ["User must exist"]
}

Tracking user data

User data can be tracked by sending POST requests to https://push.userlist.io/users. The only required parameter is identifier which is a unique identifier for that user within your application. This can either be the user’s primary key in your database, a generated tracking identifier or their email address (we don’t recommend using email address though, because it’s less reliable). Whatever you choose, make please keep in mind that it’ll be the way Userlist identifies this user moving forward.

Parameter Required Description
identifier Yes Unique identifier for this user
email No The email address that will be used to send messages to this user
signed_up_at No The time the user signed up, formatted using ISO 8601. If it is not set, Userlist will use the current time.
last_seen_at No The time the user was last seen inside your application, formatted using ISO 8601. If it is not set, Userlist will use the current time. Userlist will update this property whenever an event happens for this user.
properties No A JSON object of custom properties that further describe the user. What you store in there is totally up to you. The object’s keys will be normalized to snake_case. If they are set, we’ll use name, or first_name and last_name to represent the user inside of Userlist.

Here’s what an example request might look like:

POST /users HTTP/1.1
Accept: application/json
Authorization: Push your-push-api-key-here
Content-Type: application/json; charset=utf-8
{
  "identifier": "3d70d1d4-484a-4e72-8857-916ee525214e",
  "email": "delaney.jones@example.net",
  "properties": {
    "first_name": "Delaney",
    "last_name": "Jones"
  }
}

When successful, the Push API will respond with 202 Accepted and an empty body. Afterwards, we’ll process the data and it’ll show up inside Userlist within a few moments.

Tracking events

Similar to tracking user data, tracking events works by sending POST requests to https://push.userlist.io/events. Tracking an event requires at least two pieces of information: a name, and a user identifier. Other parameters are optional.

Parameter Required Description
name Yes The name of the event that is triggered. The name will be normalized to snake_case.
user Yes This can either be a user identifier, or a nested user object. If the identifier is not known to the system, it’ll create a new user. The same thing is true when you pass a nested user object. However, if the user already exists it’ll update it using the given information.
occured_at No The time the event occured at, formatted using ISO 8601. The system will use the current time if you don’t provide anything.
properties No A JSON object of custom properties that further describe the event. What you store in there is totally up to you. The object’s keys will be normalized to snake_case.

Here’s what an example request might look like:

POST /events HTTP/1.1
Accept: application/json
Authorization: Push your-push-api-key-here
Content-Type: application/json; charset=utf-8
{
  "name": "product_purchased",
  "user": "3d70d1d4-484a-4e72-8857-916ee525214e",
  "properties": {
    "product": "Flowers",
    "price": "$12.99"
  }
}

When successful, the Push API will respond with with 202 Accepted and an empty body. Afterwards, we’ll process the data and it’ll show up inside Userlist within a few moments.

Best practices for a successful integration

A successful integration isn’t just a matter of technical setup. It’s equally important to be strategic and consistent in your user tracking — so that the data reflects your business goals and makes sense to all team members down the road.

Before you start the integration process, you need to make the following decisions:

  1. Figure out what properties and events need to be tracked. What properties and events reflect user progress the best, and describe the milestones in your typical user journey?
  2. Choose a naming convention and use it to document these properties and events before you implement them in code.

For further reading, we recommend this article on naming conventions published by the team at Segment (a popular integration and analytics tool).

Here are some of our recommendations:

  • Use a framework for naming events (e.g. Object-Action framework)
  • Track time instead of boolean — this will enable you to segment more meaningfully and send better communications, since you know when the user performed a certain event last time (as opposed to a boolean)
  • For dates without time we recommend to use an _on suffix (e.g. next_billing_on), and for dates with time an _at suffix (e.g. trial_expires_at)
  • Be consistent with vocabulary and phrase structure. Our recommendation for event names is resource name + verb in past tense, e.g. message_sent, template_created
  • Be consistent with capitalization and characters between words — e.g., created-project vs created_project (this isn't mission-critical as we normalize it anyways, but still a good practice)

What exactly should I track?

Below you’ll find a list of sample properties and events you could be tracking. Keep in mind that events will only start appearing after you do the integration, so it’s helpful to have critical information stored as properties (such as user’s sign-up date or trial expiration date).

Group Sample properties Sample events
General user information first_name, last_name, signed_up_at, company, account_role (owner, manager, guest, etc.)
Payment information Helps trigger payment-related campaigns: trial_expires_at, plan, monthly_spend, ltv, subscription_status (trial, active, cancelled), next_billing_on, billing_interval (month, year) trial_expired, payment_succeeded, payment_failed, plan_updated, subscription_status_updated
Settings status Shows what settings the user has added or customized depending on your product, e.g. templates, custom_domains. You can send the values themselves, or merely indicators that things have been accomplished. Helps to define their onboarding progress. Depending on your product, e.g. template_created, custom_domain_created, custom_domain_verified
Current activity Shows the current state of things depending on your product, e.g. projects_active. Helps to define active/inactive users (how much value the user is receiving from the app right now). Depending on your product, e.g. project_created, notification_sent, comment_received
Lifetime activity Shows activity since the user signed up, depending on your product: e.g. total_projects_created, total_notifications_sent. Helps to define loyal customers (how much overall value the user has received).

It's hugely helpful to plan your properties and events alongside the campaigns you’re going to send. Welcome to use our free printable worksheets and consult the following article:

Still need help? Contact Us Contact Us