Amazon Pinpoint
REST API Reference

Endpoint

An endpoint uniquely identifies a mobile device, email address, or phone number that can receive a message. You can use this resource to look up, create, update, or delete an endpoint.

URI

/v1/apps/application-id/endpoints/endpoint-id

HTTP Methods

DELETE

Deletes an endpoint.

Header

Name Required Type

accept

false

string

Path

Name Required Type

application-id

true

string

endpoint-id

true

string

Response

Status Code Schema

202

EndpointResponse

GET

Returns information about an endpoint.

Header

Name Required Type

accept

false

string

Path

Name Required Type

application-id

true

string

endpoint-id

true

string

Response

Status Code Schema

200

EndpointResponse

PUT

Creates or updates an endpoint.

Body

Name Required Type

EndpointRequest

true

EndpointRequest

Header

Name Required Type

accept

false

string

Path

Name Required Type

application-id

true

string

endpoint-id

true

string

Response

Status Code Schema

202

MessageBody

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 EndpointRequest

{ "ChannelType": "GCM", "Address": "string", "EndpointStatus": "string", "OptOut": "string", "RequestId": "string", "Location": { "Latitude": 0, "Longitude": 0, "PostalCode": "string", "City": "string", "Region": "string", "Country": "string" }, "Demographic": { "Make": "string", "Model": "string", "ModelVersion": "string", "Timezone": "string", "Locale": "string", "AppVersion": "string", "Platform": "string", "PlatformVersion": "string" }, "EffectiveDate": "string", "Attributes": { "additionalProp1": [ "string" ], "additionalProp2": [ "string" ], "additionalProp3": [ "string" ] }, "Metrics": { "additionalProp1": 0, "additionalProp2": 0, "additionalProp3": 0 }, "User": { "UserId": "string", "UserAttributes": { "additionalProp1": [ "string" ], "additionalProp2": [ "string" ], "additionalProp3": [ "string" ] } } }

Response Schemas

Example EndpointResponse

{ "ChannelType": "GCM", "Address": "string", "EndpointStatus": "string", "OptOut": "string", "RequestId": "string", "Location": { "Latitude": 0, "Longitude": 0, "PostalCode": "string", "City": "string", "Region": "string", "Country": "string" }, "Demographic": { "Make": "string", "Model": "string", "ModelVersion": "string", "Timezone": "string", "Locale": "string", "AppVersion": "string", "Platform": "string", "PlatformVersion": "string" }, "EffectiveDate": "string", "Attributes": { "additionalProp1": [ "string" ], "additionalProp2": [ "string" ], "additionalProp3": [ "string" ] }, "Metrics": { "additionalProp1": 0, "additionalProp2": 0, "additionalProp3": 0 }, "User": { "UserId": "string", "UserAttributes": { "additionalProp1": [ "string" ], "additionalProp2": [ "string" ], "additionalProp3": [ "string" ] } }, "ApplicationId": "string", "Id": "string", "CohortId": "string", "CreationDate": "string" }

Example MessageBody

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

Attributes

EndpointRequest

Attribute Type Description

Address

string

The destination for messages that you send to this endpoint. The address varies by channel. For mobile push channels, use the token provided by the push notification service, such as the APNs device token or the FCM registration token. For the SMS channel, use a phone number in E.164 format, such as +12065550100. For the email channel, use an email address.

Attributes

object

Custom attributes that describe the endpoint by associating a name with an array of values. For example, an attribute named "interests" might have the values ["science", "politics", "travel"]. You can use these attributes as selection criteria when you create a segment of users to engage with a messaging campaign.

The following characters are not recommended in attribute names: # : ? \ /. The Amazon Pinpoint console does not display attributes that include these characters in the name. This limitation does not apply to attribute values.

ChannelType

string

The channel type.

Valid values: GCM | APNS | APNS_SANDBOX | APNS_VOIP | APNS_VOIP_SANDBOX | ADM | SMS | EMAIL | BAIDU

Demographic

EndpointDemographic

Demographic attributes for the endpoint.

EffectiveDate

string

The date and time when the endpoint was updated, shown in ISO 8601 format.

EndpointStatus

string

Unused.

Location

EndpointLocation

The endpoint location attributes.

Metrics

object

Custom metrics that your app reports to Amazon Pinpoint.

OptOut

string

Indicates whether a user has opted out of receiving messages with one of the following values:

ALL - User has opted out of all messages.

NONE - Users has not opted out and receives all messages.

RequestId

string

The unique ID for the most recent request to update the endpoint.

User

EndpointUser

Custom user-specific attributes that your app reports to Amazon Pinpoint.

EndpointDemographic

Attribute Type Description

AppVersion

string

The version of the application associated with the endpoint.

Locale

string

The endpoint locale in the following format: The ISO 639-1 alpha-2 code, followed by an underscore, followed by an ISO 3166-1 alpha-2 value.

Make

string

The manufacturer of the endpoint device, such as Apple or Samsung.

Model

string

The model name or number of the endpoint device, such as iPhone.

ModelVersion

string

The model version of the endpoint device.

Platform

string

The platform of the endpoint device, such as iOS or Android.

PlatformVersion

string

The platform version of the endpoint device.

Timezone

string

The timezone of the endpoint. Specified as a tz database value, such as Americas/Los_Angeles.

EndpointLocation

Attribute Type Description

City

string

The city where the endpoint is located.

Country

string

The two-letter code for the country or region of the endpoint. Specified as an ISO 3166-1 alpha-2 code, such as "US" for the United States.

Latitude

number

The latitude of the endpoint location, rounded to one decimal place.

Longitude

number

The longitude of the endpoint location, rounded to one decimal place.

PostalCode

string

The postal code or zip code of the endpoint.

Region

string

The region of the endpoint location. For example, in the United States, this corresponds to a state.

EndpointUser

Attribute Type Description

UserAttributes

object

Custom attributes that describe the user by associating a name with an array of values. For example, an attribute named "interests" might have the following values: ["science", "politics", "travel"]. You can use these attributes as selection criteria when you create segments.

The Amazon Pinpoint console can't display attribute names that include the following characters: hash/pound sign (#), colon (:), question mark (?), backslash (\), and forward slash (/). For this reason, you should avoid using these characters in the names of custom attributes.

UserId

string

The unique ID of the user.

EndpointResponse

Attribute Type Description

Address

string

The address of the endpoint as provided by your push provider. For example, the DeviceToken or RegistrationId.

ApplicationId

string

The ID of the application that is associated with the endpoint.

Attributes

object

Custom attributes that describe the endpoint by associating a name with an array of values. For example, an attribute named "interests" might have the following values: ["science", "politics", "travel"]. You can use these attributes as selection criteria when you create segments.

The Amazon Pinpoint console can't display attribute names that include the following characters: hash/pound sign (#), colon (:), question mark (?), backslash (\), and forward slash (/). For this reason, you should avoid using these characters in the names of custom attributes.

ChannelType

string

The channel type.

Valid values: GCM | APNS | APNS_SANDBOX | APNS_VOIP | APNS_VOIP_SANDBOX | ADM | SMS | EMAIL | BAIDU

CohortId

string

A number from 0-99 that represents the cohort the endpoint is assigned to. Endpoints are grouped into cohorts randomly, and each cohort contains approximately 1 percent of the endpoints for an app. Amazon Pinpoint assigns cohorts to the holdout or treatment allocations for a campaign.

CreationDate

string

The date and time when the endpoint was created, shown in ISO 8601 format.

Demographic

EndpointDemographic

The endpoint demographic attributes.

EffectiveDate

string

The date and time when the endpoint was last updated, shown in ISO 8601 format.

EndpointStatus

string

Unused.

Id

string

The unique ID that you assigned to the endpoint. The ID should be a globally unique identifier (GUID) to ensure that it doesn't conflict with other endpoint IDs associated with the application.

Location

EndpointLocation

The endpoint location attributes.

Metrics

object

Custom metrics that your app reports to Amazon Pinpoint.

OptOut

string

Indicates whether a user has opted out of receiving messages with one of the following values:

ALL - User has opted out of all messages.

NONE - Users has not opted out and receives all messages.

RequestId

string

The unique ID for the most recent request to update the endpoint.

User

EndpointUser

Custom user-specific attributes that your app reports to Amazon Pinpoint.

MessageBody

Attribute Type Description

Message

string

The error message that's returned from the API.

RequestID

string

The unique message body ID.