Menu
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

Copy
{ "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" ] } }, "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" ] } } } }

Response Schemas

Example SegmentResponse

Copy
{ "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" ] } }, "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 SegmentsResponse

Copy
{ "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" ] } }, "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 } } } ], "NextToken": "string" }

Example MessageBody

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

Attributes

WriteSegmentRequest

Attribute Type Description

Dimensions

SegmentDimensions

The segment dimensions attributes.

Name

string

The name of segment

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.

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 filter according to ISO 3166-1 Alpha-2 codes.

SegmentResponse

Attribute Type Description

ApplicationId

string

The ID of the application to which the segment applies.

CreationDate

string

The date the segment was created in ISO 8601 format.

Dimensions

SegmentDimensions

The segment dimensions attributes.

Id

string

The unique segment ID.

ImportDefinition

SegmentImportResource

The import job settings.

LastModifiedDate

string

The date the segment was last updated in ISO 8601 format.

Name

string

The name of segment

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

Channel type counts

ExternalId

string

A unique, custom ID assigned to the IAM role that restricts who can assume the role.

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

A URL that points to the Amazon S3 location from which the endpoints for this segment were imported.

Size

integer

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

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.

MessageBody

Attribute Type Description

Message

string

The error message returned from the API.

RequestID

string

The unique message body ID.