Amazon Pinpoint
REST API Reference

Segments

A segment designates which users receive messages from a campaign, typically a group of customers that share certain attributes.

You can create a segment by sending a POST request to the Segments resource at the /apps/application-id/segments URI. The body of your request specifies the dimensions that determine which user endpoints belong to the segment.

If you use the Segments resource to create a segment, the segment type is DIMENSIONAL, which means that endpoints that belong to the segment vary over time based on user activity. If you want to create a static segment, which includes a fixed set of endpoints, you can send a POST request to the Import Jobs resource (/apps/application-id/jobs/import URI) to import the endpoints that belong to the segment. For more information, see Importing Segments in the Amazon Pinpoint Developer Guide.

You can use the Segments resource to create, retrieve information about, or update the settings for segments that are associated with an application.

URI

/v1/apps/application-id/segments

HTTP Methods

GET

Operation ID: GetSegments

Retrieves information about the configuration, dimension, and other settings for all the segments that are associated with an application.

Path Parameters

Name Type Required Description
application-id String True

The unique identifier for the application.

Header Parameters

Name Type Required Description
accept String False

Indicates which content types, expressed as MIME types, the client understands.

Query Parameters

Name Type Required Description
page-size String False

The maximum number of items to include on each page in a paginated response.

token String False

The NextToken string that specifies which page of results to return in a paginated response.

Responses

Status Code Response Model Description
200 SegmentsResponse

The request succeeded.

400 MessageBody

The request contains a syntax error (BadRequestException).

403 MessageBody

The request was denied because access to the specified resource is forbidden (ForbiddenException).

404 MessageBody

The request failed because the specified resource was not found (NotFoundException).

405 MessageBody

The request failed because the method is not allowed for the specified resource (MethodNotAllowedException).

429 MessageBody

The request failed because too many requests were sent during a certain amount of time (TooManyRequestsException).

500 MessageBody

The request failed due to an unknown internal server error, exception, or failure (InternalServerErrorException).

POST

Operation ID: CreateSegment

Creates a new segment for an application or updates the configuration, dimension, and other settings for an existing segment that's associated with an application.

Path Parameters

Name Type Required Description
application-id String True

The unique identifier for the application.

Header Parameters

Name Type Required Description
accept String False

Indicates which content types, expressed as MIME types, the client understands.

Responses

Status Code Response Model Description
201 SegmentResponse

The request succeeded and the specified resource was created.

400 MessageBody

The request contains a syntax error (BadRequestException).

403 MessageBody

The request was denied because access to the specified resource is forbidden (ForbiddenException).

404 MessageBody

The request failed because the specified resource was not found (NotFoundException).

405 MessageBody

The request failed because the method is not allowed for the specified resource (MethodNotAllowedException).

429 MessageBody

The request failed because too many requests were sent during a certain amount of time (TooManyRequestsException).

500 MessageBody

The request failed due to an unknown internal server error, exception, or failure (InternalServerErrorException).

OPTIONS

Retrieves information about the communication requirements and options that are available for the Segments resource.

Responses

Status Code Response Model Description
200 None

The request succeeded.

Schemas

Request Bodies

Example POST

{ "Name": "string", "Dimensions": { "Demographic": { "Channel": { "DimensionType": enum, "Values": [ "string" ] }, "Platform": { "DimensionType": enum, "Values": [ "string" ] }, "DeviceType": { "DimensionType": enum, "Values": [ "string" ] }, "AppVersion": { "DimensionType": enum, "Values": [ "string" ] }, "Make": { "DimensionType": enum, "Values": [ "string" ] }, "Model": { "DimensionType": enum, "Values": [ "string" ] } }, "Location": { "Country": { "DimensionType": enum, "Values": [ "string" ] }, "GPSPoint": { "Coordinates": { "Latitude": number, "Longitude": number }, "RangeInKilometers": number } }, "Behavior": { "Recency": { "RecencyType": enum, "Duration": enum } }, "Attributes": { }, "Metrics": { }, "UserAttributes": { } }, "SegmentGroups": { "Include": enum, "Groups": [ { "Type": enum, "Dimensions": [ { "Demographic": { "Channel": { "DimensionType": enum, "Values": [ "string" ] }, "Platform": { "DimensionType": enum, "Values": [ "string" ] }, "DeviceType": { "DimensionType": enum, "Values": [ "string" ] }, "AppVersion": { "DimensionType": enum, "Values": [ "string" ] }, "Make": { "DimensionType": enum, "Values": [ "string" ] }, "Model": { "DimensionType": enum, "Values": [ "string" ] } }, "Location": { "Country": { "DimensionType": enum, "Values": [ "string" ] }, "GPSPoint": { "Coordinates": { "Latitude": number, "Longitude": number }, "RangeInKilometers": number } }, "Behavior": { "Recency": { "RecencyType": enum, "Duration": enum } }, "Attributes": { }, "Metrics": { }, "UserAttributes": { } } ], "SourceType": enum, "SourceSegments": [ { "Id": "string", "Version": integer } ] } ] }, "tags": { } }

Response Bodies

Example SegmentsResponse

{ "Item": [ { "Name": "string", "Dimensions": { "Demographic": { "Channel": { "DimensionType": enum, "Values": [ "string" ] }, "Platform": { "DimensionType": enum, "Values": [ "string" ] }, "DeviceType": { "DimensionType": enum, "Values": [ "string" ] }, "AppVersion": { "DimensionType": enum, "Values": [ "string" ] }, "Make": { "DimensionType": enum, "Values": [ "string" ] }, "Model": { "DimensionType": enum, "Values": [ "string" ] } }, "Location": { "Country": { "DimensionType": enum, "Values": [ "string" ] }, "GPSPoint": { "Coordinates": { "Latitude": number, "Longitude": number }, "RangeInKilometers": number } }, "Behavior": { "Recency": { "RecencyType": enum, "Duration": enum } }, "Attributes": { }, "Metrics": { }, "UserAttributes": { } }, "SegmentGroups": { "Include": enum, "Groups": [ { "Type": enum, "Dimensions": [ { "Demographic": { "Channel": { "DimensionType": enum, "Values": [ "string" ] }, "Platform": { "DimensionType": enum, "Values": [ "string" ] }, "DeviceType": { "DimensionType": enum, "Values": [ "string" ] }, "AppVersion": { "DimensionType": enum, "Values": [ "string" ] }, "Make": { "DimensionType": enum, "Values": [ "string" ] }, "Model": { "DimensionType": enum, "Values": [ "string" ] } }, "Location": { "Country": { "DimensionType": enum, "Values": [ "string" ] }, "GPSPoint": { "Coordinates": { "Latitude": number, "Longitude": number }, "RangeInKilometers": number } }, "Behavior": { "Recency": { "RecencyType": enum, "Duration": enum } }, "Attributes": { }, "Metrics": { }, "UserAttributes": { } } ], "SourceType": enum, "SourceSegments": [ { "Id": "string", "Version": integer } ] } ] }, "Id": "string", "ApplicationId": "string", "CreationDate": "string", "LastModifiedDate": "string", "Version": integer, "SegmentType": enum, "ImportDefinition": { "Size": integer, "S3Url": "string", "RoleArn": "string", "ExternalId": "string", "Format": enum, "ChannelCounts": { } }, "Arn": "string", "tags": { } } ], "NextToken": "string" }

Example SegmentResponse

{ "Name": "string", "Dimensions": { "Demographic": { "Channel": { "DimensionType": enum, "Values": [ "string" ] }, "Platform": { "DimensionType": enum, "Values": [ "string" ] }, "DeviceType": { "DimensionType": enum, "Values": [ "string" ] }, "AppVersion": { "DimensionType": enum, "Values": [ "string" ] }, "Make": { "DimensionType": enum, "Values": [ "string" ] }, "Model": { "DimensionType": enum, "Values": [ "string" ] } }, "Location": { "Country": { "DimensionType": enum, "Values": [ "string" ] }, "GPSPoint": { "Coordinates": { "Latitude": number, "Longitude": number }, "RangeInKilometers": number } }, "Behavior": { "Recency": { "RecencyType": enum, "Duration": enum } }, "Attributes": { }, "Metrics": { }, "UserAttributes": { } }, "SegmentGroups": { "Include": enum, "Groups": [ { "Type": enum, "Dimensions": [ { "Demographic": { "Channel": { "DimensionType": enum, "Values": [ "string" ] }, "Platform": { "DimensionType": enum, "Values": [ "string" ] }, "DeviceType": { "DimensionType": enum, "Values": [ "string" ] }, "AppVersion": { "DimensionType": enum, "Values": [ "string" ] }, "Make": { "DimensionType": enum, "Values": [ "string" ] }, "Model": { "DimensionType": enum, "Values": [ "string" ] } }, "Location": { "Country": { "DimensionType": enum, "Values": [ "string" ] }, "GPSPoint": { "Coordinates": { "Latitude": number, "Longitude": number }, "RangeInKilometers": number } }, "Behavior": { "Recency": { "RecencyType": enum, "Duration": enum } }, "Attributes": { }, "Metrics": { }, "UserAttributes": { } } ], "SourceType": enum, "SourceSegments": [ { "Id": "string", "Version": integer } ] } ] }, "Id": "string", "ApplicationId": "string", "CreationDate": "string", "LastModifiedDate": "string", "Version": integer, "SegmentType": enum, "ImportDefinition": { "Size": integer, "S3Url": "string", "RoleArn": "string", "ExternalId": "string", "Format": enum, "ChannelCounts": { } }, "Arn": "string", "tags": { } }

Example MessageBody

{ "RequestID": "string", "Message": "string" }

Properties

AttributeDimension

Property Type Required Description
AttributeType

string

Values: INCLUSIVE | EXCLUSIVE

False

The type of segment dimension to use. Valid values are: INCLUSIVE, endpoints that match the criteria are included in the segment; and, EXCLUSIVE, endpoints that match the criteria are excluded from the segment.

Values

Array of type string

True

The criteria values to use for the segment dimension. Depending on the value of the AttributeType property, endpoints are included or excluded from the segment if their attribute values match the criteria values.

GPSCoordinates

Property Type Required Description
Latitude

number

True

The latitude coordinate of the location.

Longitude

number

True

The longitude coordinate of the location.

GPSPointDimension

Property Type Required Description
Coordinates

GPSCoordinates

True

The GPS coordinates to measure distance from.

RangeInKilometers

number

False

The range, in kilometers, from the GPS coordinates.

MessageBody

Property Type Required Description
RequestID

string

False

The unique identifier for the request or response.

Message

string

False

The message that's returned from the API.

MetricDimension

Property Type Required Description
ComparisonOperator

string

True

The operator to use when comparing metric values. Valid values are: GREATER_THAN, LESS_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN_OR_EQUAL, and EQUAL.

Value

number

True

The value to compare.

RecencyDimension

Property Type Required Description
RecencyType

string

Values: ACTIVE | INACTIVE

True

The type of recency dimension to use for the segment. Valid values are: ACTIVE, users who have used your app within the specified duration are included in the segment; and, INACTIVE, users who haven't used your app within the specified duration are included in the segment.

Duration

string

Values: HR_24 | DAY_7 | DAY_14 | DAY_30

True

The duration to use when determining which users have been active or inactive with your app.

SegmentBehaviors

Property Type Required Description
Recency

RecencyDimension

False

The dimension settings that derive from how recently users have used your app.

SegmentDemographics

Property Type Required Description
Channel

SetDimension

False

The channel criteria for the segment.

Platform

SetDimension

False

The device platform criteria for the segment.

DeviceType

SetDimension

False

The device type criteria for the segment.

AppVersion

SetDimension

False

The app version criteria for the segment.

Make

SetDimension

False

The device make criteria for the segment.

Model

SetDimension

False

The device model criteria for the segment.

SegmentDimensions

Property Type Required Description
Demographic

SegmentDemographics

False

The demographic-based criteria, such as device platform, for the segment.

Location

SegmentLocation

False

The location-based criteria, such as region or GPS coordinates, for the segment.

Behavior

SegmentBehaviors

False

The behavior-based criteria, such as how recently users have used your app, for the segment.

Attributes

object

False

One or more custom attributes to use as criteria for the segment.

Metrics

object

False

One or more custom metrics to use as criteria for the segment.

UserAttributes

object

False

One or more custom user attributes to use as criteria for the segment.

SegmentGroup

Property Type Required Description
Type

string

Values: ALL | ANY | NONE

True

Specifies how to handle multiple dimensions for the segment. For example, if you specify three dimensions for the segment, whether the resulting segment includes endpoints that match all, any, or none of the dimensions.

Dimensions

Array of type SegmentDimensions

True

An array that defines the dimensions to include or exclude from the segment.

SourceType

string

Values: ALL | ANY | NONE

False

Specifies how to handle multiple base segments for the segment. For example, if you specify three base segments for the segment, whether the resulting segment is based on all, any, or none of the base segments.

SourceSegments

Array of type SegmentReference

False

The base segment to build the segment on. A base segment, also referred to as a source segment, defines the initial population of endpoints for a segment. When you add dimensions to the segment, Amazon Pinpoint filters the base segment by using the dimensions that you specify.

You can specify more than one dimensional segment or only one imported segment. If you specify an imported segment, the segment size estimate that displays on the Amazon Pinpoint console indicates the size of the imported segment without any filters applied to it.

SegmentGroupList

Property Type Required Description
Include

string

Values: ALL | ANY | NONE

True

Specifies how to handle multiple segment groups for the segment. For example, if the segment includes three segment groups, whether the resulting segment includes endpoints that match all, any, or none of the segment groups.

Groups

Array of type SegmentGroup

True

An array that defines the set of segment criteria to evaluate when handling segment groups for the segment.

SegmentImportResource

Property Type Required Description
Size

integer

True

The number of endpoint definitions that were imported successfully to create the segment.

S3Url

string

True

The URL of the Amazon Simple Storage Service (Amazon S3) bucket that the endpoint definitions were imported from to create the segment.

RoleArn

string

True

The Amazon Resource Name (ARN) of the AWS Identity and Access Management (IAM) role that authorized Amazon Pinpoint to access the Amazon S3 location to import endpoint definitions from.

ExternalId

string

True

(Deprecated) Your AWS account ID, which you assigned to an external ID key in an IAM trust policy. Amazon Pinpoint previously used this value to assume an IAM role when importing endpoint definitions, but we removed this requirement. We don't recommend use of external IDs for IAM roles that are assumed by Amazon Pinpoint.

Format

string

Values: CSV | JSON

True

The format of the files that were imported to create the segment.

ChannelCounts

object

False

The number of channel types in the endpoint definitions that were imported to create the segment.

SegmentLocation

Property Type Required Description
Country

SetDimension

False

The country or region code, in ISO 3166-1 alpha-2 format, for the segment.

GPSPoint

GPSPointDimension

False

The GPS point dimension for the segment.

SegmentReference

Property Type Required Description
Id

string

True

The unique identifier for the segment.

Version

integer

False

The version number of the segment.

SegmentResponse

Property Type Required Description
Name

string

True

The name of the segment.

Dimensions

SegmentDimensions

False

The dimension settings for the segment.

SegmentGroups

SegmentGroupList

False

A list of one or more segment groups that apply to the segment. Each segment group consists of zero or more base segments and the dimensions that are applied to those base segments.

Id

string

True

The unique identifier for the segment.

ApplicationId

string

True

The unique identifier for the application that the segment is associated with.

CreationDate

string

True

The date and time when the segment was created.

LastModifiedDate

string

False

The date and time when the segment was last modified.

Version

integer

False

The version number of the segment.

SegmentType

string

Values: DIMENSIONAL | IMPORT

True

The segment type. Valid values are:

DIMENSIONAL - A dynamic segment, which is a segment that uses selection criteria that you specify and is based on endpoint data that's reported by your app. Dynamic segments can change over time.

IMPORT - A static segment, which is a segment that uses selection criteria that you specify and is based on endpoint data that you import from an Amazon Simple Storage Service (Amazon S3) bucket. Imported segments are static; they don't change over time.

ImportDefinition

SegmentImportResource

False

The settings for the import job that's associated with the segment.

Arn

string

True

The Amazon Resource Name (ARN) of the segment.

tags

object

False

A string-to-string map of key-value pairs that identifies the tags that are associated with the segment. Each tag consists of a required tag key and an associated tag value.

SegmentsResponse

Property Type Required Description
Item

Array of type SegmentResponse

True

An array of responses, one for each segment that's associated with the application (Segments resource) or each version of a segment that's associated with the application (Segment Versions resource).

NextToken

string

False

The string to use in a subsequent request to get the next page of results in a paginated response. The value is null if there are no additional pages.

SetDimension

Property Type Required Description
DimensionType

string

Values: INCLUSIVE | EXCLUSIVE

False

The type of segment dimension to use. Valid values are: INCLUSIVE, endpoints that match the criteria are included in the segment; and, EXCLUSIVE, endpoints that match the criteria are excluded from the segment.

Values

Array of type string

True

The criteria values for the segment dimension to use. Depending on the value of the DimensionType property, endpoints are included or excluded from the segment if their attribute values match the criteria values.

WriteSegmentRequest

A WriteSegmentRequest request can include either a Dimensions object or a SegmentGroups object, but not both.

Property Type Required Description
Name

string

True

The name of the segment.

Dimensions

SegmentDimensions

False

The criteria that define the dimensions for the segment.

SegmentGroups

SegmentGroupList

False

The segment group, which consists of zero or more base segments, to use and the dimensions to apply to those base segments in order to build the segment. Your request can include only one segment group.

tags

object

False

A string-to-string map of key-value pairs that defines the tags to associate with the segment. Each tag consists of a required tag key and an associated tag value.

See Also

For more information about using this API in one of the language-specific AWS SDKs and references, see the following:

GetSegments

CreateSegment