HTTP API

Introduction

The Appcues API provides an HTTP endpoint for recording user events and profile information to the Appcues platform. These events and profile updates, together called user activity, will become the new basis for triggering the display of Appcues content on the end user's browser.

This document describes the protocol for submitting user activity to the Appcues API.

Connecting

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

The URL to submit user activity is formed using your Appcues account ID (visible from your  Appcues account page) and the end user's ID (the first parameter to your site code's Appcues.identify()call), as follows:

https://api.appcues.net/v1/accounts/{account_id}/users/{user_id}/activity

Request Format

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

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.

Event Format

Each event is an object containing 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 (Optional) Object containing arbitrary key-value data describing details of the event.

Here is an example of a valid API request, using the Curl command-line tool:

curl https://api.appcues.com/v1/accounts/ACCOUNT_ID/users/USER_ID/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"
  }
} '

Response Format

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

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

request_id Request_id specified in the request, if any.

contents An array of content for which the user currently qualifies. Used internally by the Appcues SDK; safe for external users to ignore.