Importing segments

With Amazon Pinpoint, you can define a user segment by importing a file that contains information about the users who belong to the segment. Importing segments is useful if you define user segments outside of Amazon Pinpoint but you want to engage your users with Amazon Pinpoint campaigns.

Unlike the dynamic segments that you create with the segment builder in the console, an imported segment is an unchanging set of endpoints or user IDs:

An imported segment consists of endpoints, user IDs, or a combination of both. When you use Amazon Pinpoint to send a message to the segment, the potential destinations include:

When you create a new segment, you can use an imported segment as the base segment. You can then apply filters to the base segment to refine it according to your needs.

Imported segment considerations

Consider the following factors when you create imported segments:

Segment files

You define the endpoints or user IDs that belong to your segment in a comma-separated values (CSV) or JSON file. Then, you import the file into Amazon Pinpoint to create the segment.

When you import a segment, remember the following:

Example segment files

The example files in this section are based on the following data:

Each row in this table represents an individual endpoint. Note that the user IDs example-user-id-2 and example-user-id-3 are assigned to two endpoints each.

Importing a segment

There are two ways to import segments into Amazon Pinpoint: you can upload files directly from your computer, or you can import files that are stored in an Amazon Simple Storage Service (Amazon S3) bucket.

We recommend that you upload files from your computer, especially if you already have the customer data on your computer. However, you can import only 10 files at a time, and you can only upload files that are smaller than 1 gigabyte (GB).

If you need to import more than 10 files at once, or if you need to upload files that are larger than 1 GB, then you should import files from Amazon S3. The Amazon S3 import option is also useful if you already have processes that send customer data files to Amazon S3 for storage.

This section includes procedures for importing segments by using both of these methods.

Supported attributes

The table in this section lists and describes the attributes that you can specify, in endpoint definitions, that you import into Amazon Pinpoint. If you import segments by using CSV files, the headers in the file should match the names shown in the Attribute column.

For JSON files, a period in the attribute name indicates that the name following the period is an object that's nested in a parent object with a name that's equal to the value preceding the period. For example, a JSON file that contains the Demographic.Make and Demographic.Model attributes has the following structure:

{
...
"Demographic": {
  ...
  "Make":"Apple",
  "Model":"iPhone"
  ...
  }
...
}

The full JSON structure closely resembles the example endpoint request in the Amazon Pinpoint API Reference. However, not all attributes in the Endpoint request schema are supported when you import segments, including EndpointStatus and EffectiveDate.

For a custom field to have multiple values in CSV, you must replicate the header and keep one value per header. For example:

...,User.UserId, User.UserAttributes.new_multi_field,User.UserAttributes.new_multi_field
...,example-user-id-2,test10,test20

You can replace attribute names that are shown as custom_attribute with any value. For example, if you want to store users' first and last names in attributes named FirstName and LastName, you can create custom attributes named User.UserAttributes.FirstName and User.UserAttributes.LastName, respectively. An attribute name can contain up to 50 characters. An attribute value can contain up to 100 characters. Attribute names are case sensitive.

In JSON, the custom attribute must be formatted at "Attributes":{"Ride":["Bus"]}.

You can create as many as 250 custom attributes for endpoints and users in each project. For more information, see Amazon Pinpoint quotas in the Amazon Pinpoint Developer Guide.