The Appcues API provides an HTTP endpoint for recording user events and profile information to the Appcues platform. These events and profile updates (or "user activity"), are used for targeting the right content to the right end users.

Base URL

The root URL for the Appcues API is https://api.appcues.com/

Making Requests

The user activity endpoint accepts POST requests, JSON-formatted, which must contain a  Content-Type: application/json header.

Submission URL
Submissions must include:

• your Appcues account ID (from the account page)
• the end user's ID (the first parameter to your Appcues.identify() call).
• A `Content-Type: application/json` header.

Note: If the end user ID submitted does not exist in Appcues, a new user will be created with that ID.

When complete, the URL should look like this:

https://api.appcues.com/v1/accounts/{account id}/users/{user id}/activity

Request body

The request body must be a JSON-formatted object, containing one or both of the following parameters:

• events Array of event objects, defined below.
• profile_update Object containing arbitrary key-value data to update in the user's stored profile.
• request_id (Optional) Arbitrary string which can be used to identify this request. The request_id will be returned in the response.

Sending events

Each event you send is an object included in an events array. Each event object should contain the following parameters:

• name Event name. This is the main mechanism for grouping and targeting on specific events. Max 127 characters.
• timestamp Time at which the event occurred, in either integer format (as Unix time) or string format (as ISO 8601 compliant date, e.g. 2016-01-13T13:05:22.000Z).
• attributes Object containing arbitrary key-value data describing details of the event. Optional

"events": [
    {
      "name": "clicked widget",
      "timestamp": 1452854179,
      "attributes": {
        "widget_color": "blue",
        "ab_group": "a"
      }
    },
    {
      "name": "purchased a plan",
      "timestamp": 1452855000,
      "attributes": {
        "plan_tier": "Enterprise",
      }
    }
]

Note on reserved event names: Appcues reserves events with names beginning with appcues: for internal use.

Sending user profile properties

Each profile update you send is a key value pair in the profile_update object, with no required parameters.

"profile_update": {
  "team": "Product",
  "tier": "Beginner"
}

Example request

Here is an example of a valid API request, including both events and profile updates, with the account ID 123 and user ID 456:

curl https://api.appcues.com/v1/accounts/123/users/456/activity \
  -X POST -H "Content-Type: application/json" -d '
{
  "request_id": "abc123",
  "events": [
    {
      "name": "clicked widget",
      "timestamp": 1452854179,
      "attributes": {
        "widget_color": "blue",
        "ab_group": "a"
      }
    }
  ],
  "profile_update": {
    "favorite team": "Red Sox",
    "favorite boat type": "Duck"
  }

Response format

A successful user activity submission will result in a response with status code 200, and a response body including:

• request_id Request ID for the submission (if provided).
• contents An array of content for which the user currently qualifies.

{"request_id":"abc123","contents":[]}

Error Handling

The response codes that will be returned for each submission:

• 202: Successful submission
• 400: Update failed, likely malformed JSON
• 502: Activity ingestion failed, please retry

We recommend building retry logic into your data uploader to handle potential 502 responses.