Amazon Pinpoint
REST API Reference

Events

In Amazon Pinpoint, you can create events to keep track of how users interact with your app. For example, you can log interactions such as logins, account creations, and purchase attempts as events.

Use to this resource to record events for endpoints. This method creates events and creates or updates the endpoints that those events are associated with.

URI

/v1/apps/application-id/events

HTTP Methods

POST

Use to record events for endpoints. This method creates events and creates or updates the endpoints that those events are associated with.

Body

Name Required Type

EventsRequest

true

EventsRequest

Header

Name Required Type

accept

false

string

Path

Name Required Type

application-id

true

string

Response

Status Code Schema

202

EventsResponse

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 EventsRequest

{ "EventsRequest":{ "EventsBatch":{ "BatchItem":{ "EndpointId":{ "Endpoint":{ "ChannelType":"string", "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":{ "attributeKey1":[ "string" ], "attributeKey2":[ "string" ] }, "User":{ "UserId":"string", "Attributes":{ "userAttributeKey1":[ "string" ], "userAttributeKey2":[ "string" ] } } }, "Events":{ "EventId":{ "EventType":"string", "ClientSdkVersion":"string", "Timestamp":"string", "Version":"string", "Attributes":{ "eventAttributeKey1":"string", "eventAttributeKey2":"string" }, "Metrics":{ "metricName":0 }, "Session":{ "Id":"string", "Duration":0, "StartTimestamp":"string", "EndTimestamp":"string" } } } } } } } }

Response Schemas

Example EventsResponse

{ "EventsResponse":{ "Results":{ "EndpointId1":{ "EndpointItemResponse":{ "Message":"string", "StatusCode":202 }, "EventsItemResponse":{ "EventId1":{ "Message":"string", "StatusCode":202 } } }, "EndpointId2":{ "EndpointItemResponse":{ "Message":"string", "StatusCode":202 }, "EventsItemResponse":{ "EventId1":{ "Message":"string", "StatusCode":202 }, "EventId2":{ "Message":"string", "StatusCode":400 } } } } } }

Example MessageBody

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

Attributes

EventsRequest

Attribute Type Description

BatchItem

object

A batch of events to process. Each BatchItem consists of an endpoint ID as the key, and an EventsBatch object as the value.

EventsBatch

Attribute Type Description

Endpoint

PublicEndpoint

The PublicEndpoint attached to the EndpointId from the request.

Events

object

An object that contains a set of events associated with the endpoint.

PublicEndpoint

Attribute Type Description

Address

string

The unique identifier for the recipient. For example, an address could be a device token, email address, or mobile phone number.

Attributes

object

Custom attributes that your app reports to Amazon Pinpoint. You can use these attributes as selection criteria when you create a segment.

ChannelType

string

The channel type.

Valid values: APNS, GCM

Demographic

EndpointDemographic

The endpoint demographic attributes.

EffectiveDate

string

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

EndpointStatus

string

The status of the endpoint. If the update fails, the value is INACTIVE. If the endpoint is updated successfully, the value is ACTIVE.

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

A unique identifier that is generated each time the endpoint is updated.

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.

Event

Attribute Type Description

Attributes

object

Custom attributes that are associated with the event you're adding or updating.

ClientSdkVersion

string

The version of the SDK that's running on the client device.

EventType

string

The name of the custom event that you're recording.

Metrics

object

Custom metrics related to the event.

Session

Session

Information about the session in which the event occurred.

Timestamp

string

The date and time when the event occurred, in ISO 8601 format.

Session

Attribute Type Description

Duration

integer

The duration of the session, in milliseconds.

Id

string

A unique identifier for the session.

StartTimestamp

string

The date and time when the session began.

StopTimestamp

string

The date and time when the session ended.

EventsResponse

Attribute Type Description

Results

object

A map that contains a multipart response for each endpoint. Each item in this object uses the endpoint ID as the key, and the item response as the value.

If no item response exists, the value can also be one of the following: 202 (if the request was processed successfully) or 400 (if the payload was invalid, or required fields were missing).

ItemResponse

Attribute Type Description

EndpointItemResponse

EndpointItemResponse

The response received after the endpoint was accepted.

EventsItemResponse

object

A multipart response object that contains a key and value for each event ID in the request. In each object, the event ID is the key, and an EventItemResponse object is the value.

EndpointItemResponse

Attribute Type Description

Message

string

A custom message associated with the registration of an endpoint when issuing a response.

StatusCode

integer

The status code associated with the merging of an endpoint when issuing a response.

EventItemResponse

Attribute Type Description

Message

string

A custom message that is associated with the processing of an event.

StatusCode

integer

The status returned in the response as a result of processing the event.

Possible values: 400 (for invalid events) and 202 (for events that were accepted).

MessageBody

Attribute Type Description

Message

string

The error message that's returned from the API.

RequestID

string

The unique message body ID.