URI HTTP methods Schemas Properties See also

Segment

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

You can create a segment by sending a PUT request to the Segment resource. In the body of the request, you specify the dimensions that determine which endpoints belong to the segment. If you use the Segment 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 to import the endpoints that belong to the segment. For more information, see Importing Segments in the Amazon Pinpoint Developer Guide.

If you create a new segment that's based on an existing segment (by using a SourceSegments array) and the base segment was imported, the Amazon Pinpoint console displays an inaccurate estimate of the segment size. In this case, the segment size that's displayed on the console equals the size of the imported segment, without any additional filters applied to it.

You can use the Segment resource to create, retrieve information about, update, or delete a segment that's associated with an application.

Note: If you delete a segment that's used by an active campaign, the campaign will fail and stop running. Similarly, if you delete a segment that's used by an active journey, the journey might fail and stop running. If the journey does continue to run, any participants who were part of the segment might be removed from the journey prematurely.

URI

/v1/apps/application-id/segments/segment-id

HTTP methods

GET

Operation ID: GetSegment

Retrieves information about the configuration, dimension, and other settings for a specific segment that's associated with an application.

Path parameters
Name	Type	Required	Description
`segment-id`	String	True	The unique identifier for the segment.
`application-id`	String	True	The unique identifier for the application. This identifier is displayed as the Project ID on the Amazon Pinpoint console.

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
`200`	`SegmentResponse`	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).
`413`	`MessageBody`	The request failed because the payload for the body of the request is too large (RequestEntityTooLargeException).
`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).

PUT

Operation ID: UpdateSegment

Updates the configuration, dimension, and other settings for an existing segment.

Path parameters
Name	Type	Required	Description
`segment-id`	String	True	The unique identifier for the segment.
`application-id`	String	True	The unique identifier for the application. This identifier is displayed as the Project ID on the Amazon Pinpoint console.

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
`200`	`SegmentResponse`	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).
`413`	`MessageBody`	The request failed because the payload for the body of the request is too large (RequestEntityTooLargeException).
`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).

DELETE

Operation ID: DeleteSegment

Deletes a segment from an application.

Path parameters
Name	Type	Required	Description
`segment-id`	String	True	The unique identifier for the segment.
`application-id`	String	True	The unique identifier for the application. This identifier is displayed as the Project ID on the Amazon Pinpoint console.

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
`200`	`SegmentResponse`	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).
`413`	`MessageBody`	The request failed because the payload for the body of the request is too large (RequestEntityTooLargeException).
`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 Segment resource.

Path parameters
Name	Type	Required	Description
`segment-id`	String	True	The unique identifier for the segment.
`application-id`	String	True	The unique identifier for the application. This identifier is displayed as the Project ID on the Amazon Pinpoint console.

Responses
Status code	Response model	Description
`200`	None	The request succeeded.

Schemas

Request bodies


{
  "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


{
  "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": {
  }
}


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

Properties

AttributeDimension

Specifies attribute-based criteria for including or excluding endpoints from a segment.

Property Type Required Description

Property	Type	Required	Description
`AttributeType`	string Values: `INCLUSIVE \| EXCLUSIVE \| CONTAINS \| BEFORE \| AFTER \| BETWEEN \| NOT_BETWEEN \| ON`	False	The type of segment dimension to use. Valid values are: `INCLUSIVE` – endpoints that have attributes matching the values are included in the segment. `EXCLUSIVE` – endpoints that have attributes matching the values are excluded from the segment. `CONTAINS` – endpoints that have attributes' substrings match the values are included in the segment. `BEFORE` – endpoints with attributes read as ISO_INSTANT datetimes before the value are included in the segment. `AFTER` – endpoints with attributes read as ISO_INSTANT datetimes after the value are included in the segment. `BETWEEN` – endpoints with attributes read as ISO_INSTANT datetimes between the values are included in the segment. `ON` – endpoints with attributes read as ISO_INSTANT dates on the value are included in the segment. Time is ignored in this comparison.
`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.

AttributeType

string

False

The type of segment dimension to use. Valid values are:

INCLUSIVE – endpoints that have attributes matching the values are included in the segment.
EXCLUSIVE – endpoints that have attributes matching the values are excluded from the segment.
CONTAINS – endpoints that have attributes' substrings match the values are included in the segment.
BEFORE – endpoints with attributes read as ISO_INSTANT datetimes before the value are included in the segment.
AFTER – endpoints with attributes read as ISO_INSTANT datetimes after the value are included in the segment.
BETWEEN – endpoints with attributes read as ISO_INSTANT datetimes between the values are included in the segment.
ON – endpoints with attributes read as ISO_INSTANT dates on the value are included in the segment. Time is ignored in this comparison.

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

Specifies the GPS coordinates of a location.

Property	Type	Required	Description
`Latitude`	number	True	The latitude coordinate of the location.
`Longitude`	number	True	The longitude coordinate of the location.

GPSPointDimension

Specifies GPS-based criteria for including or excluding endpoints from a segment.

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

Provides information about an API request or response.

Property	Type	Required	Description
`Message`	string	False	The message that's returned from the API.
`RequestID`	string	False	The unique identifier for the request or response.

MetricDimension

Specifies metric-based criteria for including or excluding endpoints from a segment. These criteria derive from custom metrics that you define for endpoints.

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

Specifies criteria for including or excluding endpoints from a segment based on how recently an endpoint was active.

Property Type Required Description

Property	Type	Required	Description
`Duration`	string Values: `HR_24 \| DAY_7 \| DAY_14 \| DAY_30`	True	The duration to use when determining whether an endpoint is active or inactive.
`RecencyType`	string Values: `ACTIVE \| INACTIVE`	True	The type of recency dimension to use for the segment. Valid values are: `ACTIVE`, endpoints that were active within the specified duration are included in the segment; and, `INACTIVE`, endpoints that weren't active 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 whether an endpoint is active or inactive.

RecencyType

string

Values: ACTIVE | INACTIVE

True

The type of recency dimension to use for the segment. Valid values are: ACTIVE, endpoints that were active within the specified duration are included in the segment; and, INACTIVE, endpoints that weren't active within the specified duration are included in the segment.

SegmentBehaviors

Specifies dimension settings for including or excluding endpoints from a segment based on how recently an endpoint was active.

Property	Type	Required	Description
`Recency`	RecencyDimension	False	The dimension settings that are based on how recently an endpoint was active.

SegmentDemographics

Specifies demographic-based dimension settings for including or excluding endpoints from a segment. These settings derive from characteristics of endpoint devices, such as platform, make, and model.

Property	Type	Required	Description
`AppVersion`	SetDimension	False	The app version criteria for the segment.
`Channel`	SetDimension	False	The channel criteria for the segment.
`DeviceType`	SetDimension	False	The device type criteria for the segment.
`Make`	SetDimension	False	The device make criteria for the segment.
`Model`	SetDimension	False	The device model criteria for the segment.
`Platform`	SetDimension	False	The device platform criteria for the segment.

SegmentDimensions

Specifies the dimension settings for a segment.

Property	Type	Required	Description
`Attributes`	object	False	One or more custom attributes to use as criteria for the segment. For more information see AttributeDimension
`Behavior`	SegmentBehaviors	False	The behavior-based criteria, such as how recently users have used your app, for the segment.
`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.
`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

Specifies the base segments and dimensions for a segment, and the relationships between these base segments and dimensions.

Property	Type	Required	Description
`Dimensions`	Array of type SegmentDimensions	False	An array that defines the dimensions for the segment.
`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 a 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 Amazon Pinpoint console displays a segment size estimate that indicates the size of the imported segment without any filters applied to it.
`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.
`Type`	string Values: `ALL \| ANY \| NONE`	False	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.

SegmentGroupList

Specifies the settings that define the relationships between segment groups for a segment.

Property Type Required Description

Property	Type	Required	Description
`Groups`	Array of type SegmentGroup	False	An array that defines the set of segment criteria to evaluate when handling segment groups for the segment.
`Include`	string Values: `ALL \| ANY \| NONE`	False	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

False

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

Include

string

Values: ALL | ANY | NONE

False

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.

SegmentImportResource

Provides information about the import job that created a segment. An import job is a job that creates a user segment by importing endpoint definitions.

Property	Type	Required	Description
`ChannelCounts`	object	False	The number of channel types in the endpoint definitions that were imported to create the segment.
`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. Valid values are: `CSV`, for comma-separated values format; and, `JSON`, for newline-delimited JSON format.
`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.
`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.
`Size`	integer	True	The number of endpoint definitions that were imported successfully to create the segment.

SegmentLocation

Specifies geographical dimension settings for a segment.

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 location and range for the segment.

SegmentReference

Specifies the segment identifier and version of a segment.

Property	Type	Required	Description
`Id`	string	True	The unique identifier for the segment.
`Version`	integer	False	The version number of the segment.

SegmentResponse

Provides information about the configuration, dimension, and other settings for a segment.

Property	Type	Required	Description
`ApplicationId`	string	True	The unique identifier for the application that the segment is associated with.
`Arn`	string	True	The Amazon Resource Name (ARN) of the segment.
`CreationDate`	string	True	The date and time when the segment was created.
`Dimensions`	SegmentDimensions	False	The dimension settings for the segment.
`Id`	string	True	The unique identifier for the segment.
`ImportDefinition`	SegmentImportResource	False	The settings for the import job that's associated with the segment.
`LastModifiedDate`	string	False	The date and time when the segment was last modified.
`Name`	string	False	The name of 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.
`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 definitions that you import from a file. Imported segments are static; they don't change over time.
`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.
`Version`	integer	False	The version number of the segment.

SetDimension

Specifies the dimension type and values for a segment dimension.

Property Type Required Description

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 to use for the segment dimension. Depending on the value of the `DimensionType` property, endpoints are included or excluded from the segment if their values match the criteria values.

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 to use for the segment dimension. Depending on the value of the DimensionType property, endpoints are included or excluded from the segment if their values match the criteria values.

WriteSegmentRequest

Specifies the configuration, dimension, and other settings for a segment. A WriteSegmentRequest object can include a Dimensions object or a SegmentGroups object, but not both.

Property	Type	Required	Description
`Dimensions`	SegmentDimensions	False	The criteria that define the dimensions for the segment. If no values are provided, then all endpoints are included in the segment.
`Name`	string	False	The name of the segment. Note A segment must have a name otherwise it will not appear in the Amazon Pinpoint console.
`SegmentGroups`	SegmentGroupList	False	The segment group to use and the dimensions to apply to the group's base segments in order to build the segment. A segment group can consist of zero or more base segments. Your request can include only one segment group.
`tags`	object	False	Note As of 22-05-2023 the PUT UpdateSegment tags attribute has been deprecated. After this date any value in the tags attribute is not processed and will not generate an error code. Use the Tags resource to add or modify tags. (Deprecated) 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.