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
  • Integration Hub
  • Contact Us
  • Docs home
  • Installation & Developers
  • API & Data

HTTP API (Developer)

Learn more about the HTTP API as a way to add individual user events and profiles to your Appcues account.

Updated at October 28th, 2024

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.

  • Home

  • Installation & Developers

    • Web Experiences

      • Mobile Experiences

        • Workflows

          • Analytics & Data

            • Account Management

              • Best Practices

                • Integrations

                  • System Status

                    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

                    • Appcues Installation Overview
                    • Javascript API (Developer)
                    • Installation Guide for Developers
                    • Identity Verification
                    Appcues logo

                    Product

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

                    Use cases

                    Appcues Integration Hub User Onboarding Software Feature Adoption Software NPS & Surveys Announcements Insights Mobile Adoption

                    Company

                    About
                    Careers

                    Support

                    Developer Docs Contact

                    Resources

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

                    Follow us

                    Facebook icon Twitter icon grey Linkedin icon Instagram icon
                    © 2022 Appcues. All rights reserved.
                    Security Terms of Service Privacy Policy

                    Knowledge Base Software powered by Helpjuice

                    Expand