Amazon Pinpoint
REST API Reference

Segments

A segment designates which users receive the messages delivered by a campaign. You can use this resource to look up, create, update, or delete your segments.

You can create segments by making a POST request to the /segments URI. Your request body will include the dimensions that determine which user endpoints belong to the segment.

When you use this resource to make 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 make a POST request to the /jobs/import URI to import the endpoints that belong to the segment. For more information, see Importing Segments in the Amazon Pinpoint Developer Guide.

URI

/v1/apps/application-id/segments

HTTP Methods

GET

Used to get information about your segments.

Header

Name Required Type

accept

false

string

Path

Name Required Type

application-id

true

string

Query

Name Required Type

page-size

false

string

token

false

string

Response

Status Code Schema

200

SegmentsResponse

POST

Used to create or update a segment.

Body

Name Required Type

WriteSegmentRequest

true

WriteSegmentRequest

Header

Name Required Type

accept

false

string

Path

Name Required Type

application-id

true

string

Response

Status Code Schema

201

SegmentResponse

Errors

Errors

Status Code Schema Error Type

400

MessageBody

BadRequestException

403

MessageBody

ForbiddenException

404

MessageBody

NotFoundException

405

MessageBody

MethodNotAllowedException

429

MessageBody

TooManyRequestsException

500

MessageBody

InternalServerErrorException

Schemas

Request Schemas

Example WriteSegmentRequest

{ "Name": "string", "SegmentGroups": { "Include": "ALL|ANY|NONE", "Groups": [ { "Type": "ALL|ANY|NONE", "Dimensions": [ { "Demographic": { "Channel": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] }, "Platform": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] }, "DeviceType": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] }, "AppVersion": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] }, "Make": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] }, "Model": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] } }, "Location": { "Country": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] }, "GPSPoint": { "Coordinates": { "Latitude": 0, "Longitude": 0 }, "RangeInKilometers": 0 } }, "Behavior": { "Recency": { "RecencyType": "ACTIVE", "Duration": "HR_24" } }, "Attributes": {}, "Metrics": {}, "UserAttributes": {} } ], "SourceType": "ALL|ANY", "SourceSegments": [ { "Id": "string", "Version": 0 } ] } ] }, "Dimensions": { "Demographic": { "Channel": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] }, "Platform": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] }, "DeviceType": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] }, "AppVersion": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] }, "Make": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] }, "Model": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] } }, "Location": { "Country": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] }, "GPSPoint": { "Coordinates": { "Latitude": 0, "Longitude": 0 }, "RangeInKilometers": 0 } }, "Behavior": { "Recency": { "RecencyType": "ACTIVE", "Duration": "HR_24" } }, "Attributes": {}, "Metrics": {}, "UserAttributes": {} } }

Response Schemas

Example SegmentsResponse

{ "Item": [ { "Name": "string", "Dimensions": { "Demographic": { "Channel": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] }, "Platform": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] }, "DeviceType": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] }, "AppVersion": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] }, "Make": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] }, "Model": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] } }, "Location": { "Country": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] }, "GPSPoint": { "Coordinates": { "Latitude": 0, "Longitude": 0 }, "RangeInKilometers": 0 } }, "Behavior": { "Recency": { "RecencyType": "ACTIVE", "Duration": "HR_24" } }, "Attributes": {}, "Metrics": {}, "UserAttributes": {} }, "Id": "string", "ApplicationId": "string", "CreationDate": "string", "LastModifiedDate": "string", "Version": 0, "SegmentType": "DIMENSIONAL", "ImportDefinition": { "Size": 0, "S3Url": "string", "RoleArn": "string", "ExternalId": "string", "Format": "CSV", "ChannelCounts": {} } } ], "NextToken": "string" }

Example SegmentResponse

{ "Name": "string", "SegmentGroups": { "Include": "ALL|ANY|NONE", "Groups": [ { "Type": "ALL|ANY|NONE", "Dimensions": [ { "Demographic": { "Channel": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] }, "Platform": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] }, "DeviceType": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] }, "AppVersion": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] }, "Make": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] }, "Model": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] } }, "Location": { "Country": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] }, "GPSPoint": { "Coordinates": { "Latitude": 0, "Longitude": 0 }, "RangeInKilometers": 0 } }, "Behavior": { "Recency": { "RecencyType": "ACTIVE", "Duration": "HR_24" } }, "Attributes": {}, "Metrics": {}, "UserAttributes": {} } ], "SourceType": "ALL|ANY", "SourceSegments": [ { "Id": "string", "Version": 0 } ] } ] }, "Dimensions": { "Demographic": { "Channel": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] }, "Platform": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] }, "DeviceType": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] }, "AppVersion": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] }, "Make": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] }, "Model": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] } }, "Location": { "Country": { "DimensionType": "INCLUSIVE", "Values": [ "string" ] } }, "Behavior": { "Recency": { "RecencyType": "ACTIVE", "Duration": "HR_24" } }, "Attributes": { "additionalProp1": { "AttributeType": "INCLUSIVE", "Values": [ "string" ] }, "additionalProp2": { "AttributeType": "INCLUSIVE", "Values": [ "string" ] }, "additionalProp3": { "AttributeType": "INCLUSIVE", "Values": [ "string" ] } }, "UserAttributes": { "additionalProp1": { "AttributeType": "INCLUSIVE", "Values": [ "string" ] }, "additionalProp2": { "AttributeType": "INCLUSIVE", "Values": [ "string" ] }, "additionalProp3": { "AttributeType": "INCLUSIVE", "Values": [ "string" ] } } }, "Id": "string", "ApplicationId": "string", "CreationDate": "string", "LastModifiedDate": "string", "Version": 0, "SegmentType": "DIMENSIONAL", "ImportDefinition": { "Size": 0, "S3Url": "string", "RoleArn": "string", "ExternalId": "string", "Format": "CSV", "ChannelCounts": { "additionalProp1": 0, "additionalProp2": 0, "additionalProp3": 0 } } }

Example MessageBody

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

Attributes

WriteSegmentRequest

Attribute Type Description

Dimensions

SegmentDimensions

The segment dimensions attributes.

Name

string

The name of segment

SegmentGroups

SegmentGroupList

A segment group, which consists of zero or more source segments, plus dimensions that are applied to those source segments. Your request can only include one segment group. Your request can include either a SegmentGroups object or a Dimensions object, but not both.

SegmentDimensions

Attribute Type Description

Attributes

object

Custom segment attributes.

Behavior

SegmentBehaviors

The segment behaviors attributes.

Demographic

SegmentDemographics

The segment demographics attributes.

Location

SegmentLocation

The segment location attributes.

Metrics

object

Custom segment metrics.

UserAttributes

object

Custom segment user attributes.

AttributeDimension

Attribute Type Description

AttributeType

string

The type of dimension:

INCLUSIVE - Endpoints that match the criteria are included in the segment.

EXCLUSIVE - Endpoints that match the criteria are excluded from the segment.

Values

array

The criteria values for the segment dimension. Endpoints with matching attribute values are included or excluded from the segment, depending on the setting for Type.

SegmentBehaviors

Attribute Type Description

Recency

RecencyDimension

The recency of use.

RecencyDimension

Attribute Type Description

Duration

string

The length of time during which users have been active or inactive with your app.

Valid values: HR_24, DAY_7, DAY_14, DAY_30

RecencyType

string

The recency dimension type:

ACTIVE - Users who have used your app within the specified duration are included in the segment.

INACTIVE - Users who have not used your app within the specified duration are included in the segment.

SegmentDemographics

Attribute Type Description

AppVersion

SetDimension

The app version criteria for the segment.

Channel

SetDimension

The channel criteria for the segment.

DeviceType

SetDimension

The device type criteria for the segment.

Make

SetDimension

The device make criteria for the segment.

Model

SetDimension

The device model criteria for the segment.

Platform

SetDimension

The device platform criteria for the segment.

SetDimension

Attribute Type Description

DimensionType

string

The type of dimension:

INCLUSIVE - Endpoints that match the criteria are included in the segment.

EXCLUSIVE - Endpoints that match the criteria are excluded from the segment.

Values

array

The criteria values for the segment dimension. Endpoints with matching attribute values are included or excluded from the segment, depending on the setting for Type.

SegmentLocation

Attribute Type Description

Country

SetDimension

The country or region, in ISO 3166-1 alpha-2 format.

GPSPoint

GPSPointDimension

The GPS Point dimension.

GPSPointDimension

Attribute Type Description

Coordinates

GPSCoordinates

Coordinate to measure distance from.

RangeInKilometers

number

Range in kilometers from the coordinate.

GPSCoordinates

Attribute Type Description

Latitude

number

Latitude

Longitude

number

Longitude

MetricDimension

Attribute Type Description

ComparisonOperator

string

The operator that you're using to compare metric values. Possible values: GREATER_THAN, LESS_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN_OR_EQUAL, or EQUAL

Value

number

Value to be compared.

SegmentGroupList

Attribute Type Description

Groups

array

A set of segment criteria to evaluate.

Include

string

Specify how to handle multiple segment groups. For example, if the segment includes three segment groups, should the resulting segment include endpoints that are matched by all, any, or none of the segment groups you created. Acceptable values: ALL, ANY, or NONE.

SegmentGroup

Attribute Type Description

Dimensions

array

List of dimensions to include or exclude.

SourceSegments

array

The base segment that you build your segment on. The source segment defines the starting "universe" of endpoints. When you add dimensions to the segment, it filters the source segment based on the dimensions that you specify. You can specify more than one dimensional segment. You can only specify one imported segment.

NOTE: If you specify an imported segment for this attribute, the segment size estimate that appears in the Amazon Pinpoint console shows the size of the imported segment, without any filters applied to it.

SourceType

string

Specify how to handle multiple source segments. For example, if you specify three source segments, should the resulting segment be based on any or all of the segments? Acceptable values: ANY or ALL.

Type

string

Specify how to handle multiple segment dimensions. For example, if you specify three dimensions, should the resulting segment include endpoints that are matched by all, any, or none of the dimensions? Acceptable values: ALL, ANY, or NONE.

SegmentReference

Attribute Type Description

Id

string

A unique identifier for the segment.

Version

integer

If specified contains a specific version of the segment included.

SegmentsResponse

Attribute Type Description

Item

array

The list of segments.

NextToken

string

An identifier used to retrieve the next page of results. The token is null if no additional pages exist.

SegmentResponse

Attribute Type Description

ApplicationId

string

The ID of the application that the segment applies to.

CreationDate

string

The date and time when the segment was created.

Dimensions

SegmentDimensions

The segment dimensions attributes.

Id

string

The unique segment ID.

ImportDefinition

SegmentImportResource

The import job settings.

LastModifiedDate

string

The date and time when the segment was last modified.

Name

string

The name of the segment.

SegmentGroups

SegmentGroupList

A segment group, which consists of zero or more source segments, plus dimensions that are applied to those source segments.

SegmentType

string

The segment type: DIMENSIONAL - A dynamic segment built from selection criteria based on endpoint data reported by your app. You create this type of segment by using the segment builder in the Amazon Pinpoint console or by making a POST request to the segments resource. IMPORT - A static segment built from an imported set of endpoint definitions. You create this type of segment by importing a segment in the Amazon Pinpoint console or by making a POST request to the jobs/import resource.

Version

integer

The segment version number.

SegmentImportResource

Attribute Type Description

ChannelCounts

object

The number of channel types in the imported segment.

ExternalId

string

(Deprecated) Your AWS account ID, which you assigned to the ExternalID key in an IAM trust policy. Used by Amazon Pinpoint to assume an IAM role. This requirement is removed, and external IDs are not recommended for IAM roles assumed by Amazon Pinpoint.

Format

string

The format of the endpoint files that were imported to create this segment. Valid values: CSV, JSON

RoleArn

string

The Amazon Resource Name (ARN) of an IAM role that grants Amazon Pinpoint access to the endpoints in Amazon S3.

S3Url

string

The URL of the S3 bucket that the segment was imported from.

Size

integer

The number of endpoints that were successfully imported to create this segment.

MessageBody

Attribute Type Description

Message

string

The error message that's returned from the API.

RequestID

string

The unique message body ID.