The Appcues API provides an HTTP endpoint for adding individual user events and profiles to your Appcues account. These events and profile updates or “user activity”, can be 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.

Note on timestamps: If you are interested in using the example above for a test event, we recommend using an updated timestamp. Events with older timestamps may not appear in Studio lists. 

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 of true:

{"ok":true}

Error Handling

An unsuccessful request will have a response containing information about the error that occurred:

{"error":true,"message":{"description":"no route found for POST /v1/accounts/users/K/activity (ApiWeb.Router)","title":"no route found for POST /v1/accounts/users/K/activity (ApiWeb.Router)","type":"error"},"status_code":404}

We recommend building retry logic to handle potential errors.