Menu
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, or update an endpoint.

URI

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

HTTP Methods

DELETE

Use to delete 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

Use to update 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 MessageBody

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

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

Attributes

EndpointRequest

Attribute Type Description

Address

string

The address or token of the endpoint as provided by your push provider (e.g. DeviceToken or RegistrationId).

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

The endpoint demographic attributes.

EffectiveDate

string

The last time the endpoint was updated. Provided in ISO 8601 format.

EndpointStatus

string

The endpoint status. Can be either ACTIVE or INACTIVE. Will be set to INACTIVE if a delivery fails. Will be set to ACTIVE if the address is updated.

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 endpoint make, such as such as Apple or Samsung.

Model

string

The endpoint model, such as iPhone.

ModelVersion

string

The endpoint model version.

Platform

string

The endpoint platform, such as ios or android.

PlatformVersion

string

The endpoint platform version.

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

Country according to ISO 3166-1 Alpha-2 codes. For example, US.

Latitude

number

The latitude of the endpoint location. Rounded to one decimal (Roughly corresponding to a mile).

Longitude

number

The longitude of the endpoint location. Rounded to one decimal (Roughly corresponding to a mile).

PostalCode

string

The postal code or zip code of the endpoint.

Region

string

The region of the endpoint location. For example, corresponds to a state in US.

EndpointUser

Attribute Type Description

UserAttributes

object

Custom attributes that describe an end user 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.

UserId

string

The unique ID of the user.

MessageBody

Attribute Type Description

Message

string

The error message returned from the API.

RequestID

string

The unique message body ID.

EndpointResponse

Attribute Type Description

Address

string

The address or token of the endpoint as provided by your push provider (e.g. DeviceToken or RegistrationId).

ApplicationId

string

The ID of the application 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 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

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 last time the endpoint was created. Provided in ISO 8601 format.

Demographic

EndpointDemographic

The endpoint demographic attributes.

EffectiveDate

string

The last time the endpoint was updated. Provided in ISO 8601 format.

EndpointStatus

string

The endpoint status. Can be either ACTIVE or INACTIVE. Will be set to INACTIVE if a delivery fails. Will be set to ACTIVE if the address is updated.

Id

string

The unique ID that you assigned to the endpoint. The ID should be a globally unique identifier (GUID) to ensure that it is unique compared to all other endpoints for 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.