Contact Us

If you still have questions or prefer to get help directly from an agent, please submit a request.
We’ll get back to you as soon as possible.

Please fill out the contact form below and we will reply as soon as possible.

  • Contact Us
  • Home
  • Installation & Developers
  • API & Data

HTTP API (Developer)

Updated at December 20th, 2022

Contact Us

If you still have questions or prefer to get help directly from an agent, please submit a request.
We’ll get back to you as soon as possible.

Please fill out the contact form below and we will reply as soon as possible.

  • Installation & Developers
    Installing Appcues Installing Appcues Mobile API & Data Troubleshooting Extras
  • User Experiences
    Web Experiences Building Web Experiences Building Mobile Experiences Customization & Styling Targeting Studio Troubleshooting Use Cases FAQ
  • Mobile
    Installation & Overview Building Mobile Experiences Mobile Analytics Troubleshooting
  • Account Management
    Subscription Users & Data
  • Analytics
    Experience and Event Analytics Data
  • Best Practices
    Use Cases Pro Tips PLG FAQ
  • Integrations
    Integration Documents Use Cases Resources
  • Post-mortem
    System Incidents
+ More

Table of Contents

Base URL Making Requests Sending events Sending user profile properties Example request Response format Error Handling

Note: although the methods in this documentation are still valid, we recommend utilizing our new public API for any bulk importing and exporting of data you'd like to do.

 

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.

Was this article helpful?

Yes
No
Give feedback about this article

Related Articles

  • Welcome and Getting Started
  • Appcues Installation Overview
  • Javascript API (Developer)
  • Installation Overview (for Developers)
Appcues logo

Product

Why Appcues
How it works
Integrations
Security
Pricing
What's new

Use cases

User Onboarding Software
Feature Adoption Software
NPS & Surveys
Announcements
Insights
Mobile Adoption

Company

About
Careers
we're Hiring

Support

Developer Docs
Contact

Resources

The Appcues Blog
Product Adoption Academy
GoodUX
Case studies
Webinar Series
Made with Appcues
Appcues University

Follow us

Facebook iconTwitter icon greyLinkedin iconInstagram icon
© 2022 Appcues. All rights reserved.
SecurityTerms of ServicePrivacy Policy
Expand