Import User Segments

To recruit only specific users, user segments can be imported from CSV. Note that for in-app recruitment, the Client SDK must implement identify() with data that matches the CSV, in order to determine whether to target a specific user or not.

It's important the CSV is properly formatted and contains the required data.

Which CSV column names / headers should I use?

We recommend including the following column headers: name, email, userId, and greetingName.

But, at a minimum, we require only an email or userId (both unique per user within Orbital).

Here's an example of the recommended CSV attributes:

email,userId,name,greetingName
john@doe.com,806510ed-f6ff-48a4-926e-1ed3045b1741,John Doe,john
jane@smith.com,4360b2ac-19b8-49f4-862e-bfe18e6c411f,Jane Smith,Jane
jeremy@dune.com,c07c0b9a-9534-4e29-be98-d0dd01df601e, Jeremy Dune,Jeremy
…
Here's a Google Sheet you can copy

For in-app recruitment...

In order to determine whether a user should be recruited for an active discovery, the Client SDK must identify the user's userId or email against the segment inclusion criteria. At least one of these attributes must be provided in the CSV.

  • userId is the user's unique user ID (eg. from your own user database)
  • email is only used to identify a user (if they enter a different email for scheduling, they'll receive the calendar invite to that other email)

For email recruitment...

The email attribute is always required, but we also encourage you to at least include a greetingName so that you can personalize the emails.

Are any attributes unique?

Yes, email and userId are both considered unique per user.

That means when uploading user segments with users already in Orbital, you will have the option of updating or skipping those records.

What happens if I upload the same user in multiple segments?

No problem! We will merge them based on their email or userId, and it will be a single user record that is part of both segments.

Can I skip existing users when importing?

Yes.

Can I add more users to existing segment?

Yes.

Why does my uploaded segment have less users than rows in my CSV?

Orbital validates each row during upload and skips/ignores rows with invalid data (eg. email provided is not a valid email)

Further Examples

  1. At a minimum, Orbital needs a single unique attribute provided per user:
userId
806510ed-f6ff-48a4-926e-1ed3045b1741
4360b2ac-19b8-49f4-862e-bfe18e6c411f
c07c0b9a-9534-4e29-be98-d0dd01df601e
…

which in turn can be used by the Client:

orbital('identify', '806510ed-f6ff-48a4-926e-1ed3045b1741')
  1. Alternatively, if you would rather use email to identify users:
email
john@doe.com
jane@smith.com
jeremy@dune.com
…

which in turn can be used by the Client:

orbital('identify', null, { email: 'john@doe.com' })
  1. But you can also include as many attributes as you want:
email,userId,name,greetingName
john@doe.com,806510ed-f6ff-48a4-926e-1ed3045b1741,John Doe,john
jane@smith.com,4360b2ac-19b8-49f4-862e-bfe18e6c411f,Jane Smith,Jane
jeremy@dune.com,c07c0b9a-9534-4e29-be98-d0dd01df601e, Jeremy Dune,Jeremy
…

which in turn can be used by the Client:

orbital('identify', '806510ed-f6ff-48a4-926e-1ed3045b1741', { email: 'john@doe.com' })

Please refer to the Client SDK docs for further information on client instrumentation.

Was this page helpful?