POST /events/{stream-id}

Use the POST /events/{stream-id} endpoint to send a real-time event to an event stream. Events are the primary way to update profiles in a profile collection in real time.

Note

This endpoint is part of the Real-time API, an unstable API that may change without advance notice of breaking changes.

Note

In the Amperity user interface an event stream is shown on the Events > Event streams page. The value for {stream-id} is shown as the Endpoint ID for that event stream.

Prerequisites

1. Add an API key.

2. Generate an access token.

3. An event stream must be configured for your tenant. Before creating a profile collection or an event stream, you must contact your Amperity representative to enable real-time product features.

Note

The access token must be granted the profile-events:write (or streaming-ingest-api:write) permission.

Request URL

Direct all requests to the POST /events/{stream-id} endpoint to the request URL. The request URL uses the base URL with the endpoint path appended.

Amazon AWS

https://app.amperity.com/prof/events/{stream-id}

Microsoft Azure

https://{tenant-id}.amperity.com/prof/events/{stream-id}

You can find the tenant ID from the Amperity user interface. From the Settings page and select the Security tab. Under API keys, in the row for an API key, open the menu and select Copy tenant ID.

Rate limit

A rate limit is the number of requests that may be made to the Amperity API in a given time period.

Requests

A request to the POST /events/{stream-id} endpoint sends a single JSON event object to the stream. The request body must be a JSON object and must not exceed 64 KB. A Content-Length header is required.

curl --request POST \
       'https://app.amperity.com/prof/events/{stream-id}' \
     --header 'amperity-tenant: {tenant-id}' \
     --header 'Authorization: Bearer {token}' \
     --header 'Content-Type: application/json' \
     --data '{ "email": "customer@example.com", "event_type": "purchase", "order_total": 42.00 }'

This example is formatted for readability in a narrow page layout.

Request parameters

The following table describes the parameters that may be used with the POST /events/{stream-id} endpoint.

Parameter	Description
stream-id	String. Required. The ID of the event stream to which the event is sent. This value is shown as the Endpoint ID for an event stream in the Amperity user interface.
request body	JSON object. Required. The event payload, sent as a single JSON object. The shape of the payload depends on how the event stream is configured. The payload must not exceed 64 KB.

Responses

A response from the POST /events/{stream-id} endpoint will match an HTTP status code.

Status	Description
202	The event was accepted and published to the stream.
204	The event was accepted, but the stream is configured to drop events. No event was published.
400	The request body is missing, malformed, or is not a JSON object.
404	No event stream with the given {stream-id} exists for the tenant.
409	The event stream is not currently accepting events.
411	The Content-Length header is missing.
413	The request body exceeds the 64 KB limit.
415	The request Content-Type is not application/json.
503	The event could not be published because of a temporary downstream error. Retry the request.