Submit Article Requests

Do you have a suggestion for an article you would like to see created?
Feel free to submit this form and add your suggestions to our document board.

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

  • Appcues Certifications & Training
  • Contact Us
  • Docs home
  • Installation & Developers
  • API & Data

HTTP API (Developer)

Updated at May 16th, 2023

Submit Article Requests

Do you have a suggestion for an article you would like to see created?
Feel free to submit this form and add your suggestions to our document board.

Please fill out the contact form with the details about the help content you'd like to see.

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

Table of Contents

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

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.

Note: Use our Public API for any bulk importing and exporting of user data.

 

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.

developers http api

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