NAV
Examples

Appcues API

Welcome! You are reading the documentation for the Appcues Public API, version 2.0.0-beta.0.

The Appcues Public API is a web API that offers access to functions within the Appcues platform. Each function is identified using an HTTP method and a URL. All API requests and responses are encoded as JSON by default. Most API endpoints also support CSV input and output.

Most URLs supported by this API include an Appcues account ID as part of the URL path. You can find your account ID on your Studio.appcues.com account page.

Warning: this is a beta release. It is possible that the API's suite of endpoints or input/output formats may change slightly during the beta period. Please refer to this document if you suspect something has changed.

Connecting

# Curl is pre-installed on Mac OS X and most Linux systems.
# Binaries for many platforms are available on http://curl.se/.

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

The Appcues API uses the encrypted HTTPS protocol, and does not respond to unencrypted HTTP requests.

In this documentation, we will provide examples using the popular Curl command-line HTTP client.

If you would like to use the Postman API client, the Appcues Public API is available as a Postman collection here:

Run in Postman

Authentication

# Curl uses the -u flag to support HTTP Basic Auth. For example:
curl https://api.appcues.com/v2/... \
  -u API_KEY:API_SECRET

All requests to the Appcues API V2 must be authenticated using an API key and secret.

API keys and secrets can be created and managed in your settings on studio.appcues.com.

The key and secret must be attached to each request using the HTTP Basic Auth standard, summarized here:

Most HTTP clients (such as Curl, in our examples) offer a feature to simplify this procedure.

Requests

# Curl uses the -H flag to add a header to a request, and -d to add a body.
# Here is an example JSON request:
curl https://api.appcues.com/v2/... \
  -u API_KEY:API_SECRET \
  -H 'Content-type: application/json' \
  -d '{ ... }'

Each request that pushes data to this API requires the appropriate Content-type request header. Accepted values for this header are as follows:

application/json
Request body is a single JSON-encoded object.
application/ndjson
Request body consists of Newline-Delimited JSON, i.e. one JSON-encoded object per line.
text/csv
Request body consists of a CSV-encoded document starting with a line of headers.
multipart/mixed
Request body consists of an uploaded file in CSV or Newline-Delimited JSON format.

In all input formats, extra whitespace (blank lines, indentation, etc) is safely ignored.

Responses

All error (4xx and 5xx) responses adhere to the standard Problem Details format, with the following fields:

{
  "error": true,
  "status": 400,
  "title": "Bad Request",
  "detail": "`widget_id` is required but missing"
}

By default, responses will be provided in JSON format (Content-type: application/json).

To receive a response encoded in CSV format instead of JSON, pass along the appropriate Accept header:

Accept: text/csv

Each response will feature one of the following status codes:

200
Success. The request succeeded.
201
Created. The request succeeded, and resulted in the creation of a new resource.
202
Accepted. The request was accepted, and is being processed offline.
400
Bad Request. The request was malformed or invalid.
401
Unauthorized. Access credentials were missing or invalid.
403
Forbidden. The given credentials do not grant access to the requested resource.
404
Not Found. The given endpoint or resource could not be located in our system.
415
Unsupported Media Type. The content type specified in the Content-type header is not supported by this API.
429
Too Many Requests. Requests from this API key are being throttled due to heavy traffic.
500
Internal Server Error. Something went wrong and it's not your fault.

Flows

The Appcues Public API provides access to your account's flows, supporting read operations and publish/unpublish actions.

List Flows

curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/flows \
  -u API_KEY:API_SECRET

The above API call returns a response like this JSON example:

[
  {
    "id": "flow1",
    "name": "Flow 1",
    "published": true,
    "frequency": "once",
    "created_at": "2021-04-05T16:21:09Z",
    "updated_at": "2021-04-05T17:00:42Z",
    "published_at": "2021-04-05T17:00:42Z",
    "created_by": "620a104f-d233-4389-a335-73b43bc36902",
    "updated_by": "e3d7a8d7-b8cd-4139-aa9d-25b493fa2e65",
    "url": "https://api.appcues.com/v2/accounts/ACCOUNT_ID/flows/flow1"
  },
  {
    "id": "flow2",
    "name": "Flow 2",
    "published": false,
    "frequency": "every_time",
    "created_at": "2021-04-05T09:18:02Z",
    "updated_at": "2021-04-05T09:18:02Z",
    "published_at": null,
    "created_by": "620a104f-d233-4389-a335-73b43bc36902",
    "updated_by": "620a104f-d233-4389-a335-73b43bc36902",
    "url": "https://api.appcues.com/v2/accounts/ACCOUNT_ID/flows/flow2"
  }
]

Or this CSV example:

id,name,published,frequency,created_at,updated_at,published_at,created_by,updated_by,url
flow1,Flow 1,true,once,2021-04-05T16:21:09Z,2021-04-05T17:00:42Z,2021-04-05T17:00:42Z,620a104f-d233-4389-a335-73b43bc36902,e3d7a8d7-b8cd-4139-aa9d-25b493fa2e65,https://api.appcues.com/v2/accounts/ACCOUNT_ID/flows/flow1
flow2,Flow 2,false,every_time,2021-04-05T09:18:02Z,2021-04-05T09:18:02Z,,620a104f-d233-4389-a335-73b43bc36902,620a104f-d233-4389-a335-73b43bc36902,https://api.appcues.com/v2/accounts/ACCOUNT_ID/flows/flow2

This endpoint returns an array of flow details objects, whose format is described in detail below.

HTTP Request

GET https://api.appcues.com/v2/accounts/{account_id}/flows

URL Parameters

Parameter Description
account_id Appcues account ID

Get Flow Details

curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/flows/FLOW_ID \
  -u API_KEY:API_SECRET

The above API call returns a response like this JSON example:

{
  "id": "flow1",
  "name": "Flow 1",
  "published": true,
  "frequency": "once",
  "created_at": "2021-04-05T16:21:09Z",
  "updated_at": "2021-04-05T17:00:42Z",
  "published_at": "2021-04-05T17:00:42Z",
  "created_by": "620a104f-d233-4389-a335-73b43bc36902",
  "updated_by": "620a104f-d233-4389-a335-73b43bc36902",
  "url": "https://api.appcues.com/v2/accounts/ACCOUNT_ID/flows/flow1"
}

Or this CSV example:

id,name,published,frequency,created_at,updated_at,published_at,created_by,updated_by,url
flow1,Flow 1,true,once,2021-04-05T16:21:09Z,2021-04-05T17:00:42Z,2021-04-05T17:00:42Z,620a104f-d233-4389-a335-73b43bc36902,e3d7a8d7-b8cd-4139-aa9d-25b493fa2e65,https://api.appcues.com/v2/accounts/ACCOUNT_ID/flows/flow1

This endpoint returns a description of a single flow, identified by its flow ID.

HTTP Request

GET https://api.appcues.com/v2/accounts/{account_id}/flows/{flow_id}

URL Parameters

Parameter Description
account_id Appcues account ID
flow_id Flow ID

Response

Field Type Description
id string Flow ID
name string Flow name
published boolean Whether flow is currently published
frequency string Frequency to show flow; e.g., once, every_time
created_at string ISO 8601 date string of creation time
updated_at string ISO 8601 date string of last update time
published_at string or null ISO 8601 date string of last publish, if any
created_by string User ID of flow creator
updated_by string User ID of last updater

Publish Flow

curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/flows/FLOW_ID/publish \
  -u API_KEY:API_SECRET \
  -d ''

The above API call returns a JSON response like this:

{"status": 200, "title": "OK"}

Or a CSV response like this:

status,title
200,OK

This endpoint is used to publish a flow. It is harmless to call this endpoint on flows that are already published.

HTTP Request

POST https://api.appcues.com/v2/accounts/{account_id}/flows/{flow_id}/publish

URL Parameters

Parameter Description
account_id Appcues account ID
flow_id Flow ID

Response

Field Type Description
status number 200
title string OK

Unpublish Flow

curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/flows/FLOW_ID/unpublish \
  -u API_KEY:API_SECRET \
  -d ''

The above API call returns a JSON response like this:

{"status": 200, "title": "OK"}

Or a CSV response like this:

status,title
200,OK

This endpoint is used to unpublish a flow. It is harmless to call this endpoint on flows that are already unpublished.

HTTP Request

POST https://api.appcues.com/v2/accounts/{account_id}/flows/{flow_id}/unpublish

URL Parameters

Parameter Description
account_id Appcues account ID
flow_id Flow ID

Response

Field Type Description
status number 200
title string OK

Segments

This API can be used to view your Appcues user segments, update or delete them, create new ones, and add or remove users to segments.

List Segments

curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/segments \
  -u API_KEY:API_SECRET

The above API call returns a response like this JSON example:

[
  {
    "created_at": "2018-11-05T22:44:37.089Z",
    "created_by": "461",
    "description": "Accounts in non-expired free trial status",
    "id": "-LQA2aYxavNXfyzm9mtP",
    "name": "Trial customers",
    "updated_at": "2019-11-26T20:14:21.345Z",
    "updated_by": "NVVD02P2Kseri4J6prKXHPOLrDw2",
    "url": "https://api.appcues.com/v2/accounts/ACCOUNT_ID/segments/-LQA2aYxavNXfyzm9mtP"
  },
  {
    "created_at": "2019-06-19T13:54:59.630Z",
    "created_by": "Nvvd02p2kSeri4J6prKXHPOLrDw2",
    "description": "Paying accounts in good standing",
    "id": "-LhK0dQeSX3hdyp2hA3G",
    "name": "Paying customers",
    "updated_at": "2019-06-19T13:54:59.630Z",
    "updated_by": "NVVD02P2Kseri4J6prKXHPOLrDw2",
    "url": "https://api.appcues.com/v2/accounts/ACCOUNT_ID/segments/-LhK0dQeSX3hdyp2hA3G"
  }
]

Or this CSV example:

id,name,description,created_at,created_by,updated_at,updated_by,url
-LQA2aYxavNXfyzm9mtP,Trial customers,Accounts in non-expired free trial status,2018-11-05T22:44:37.089Z,461,2019-11-26T20:14:21.345Z,NVVD02P2Kseri4J6prKXHPOLrDw2,https://api.appcues.com/v2/accounts/ACCOUNT_ID/segments/-LQA2aYxavNXfyzm9mtP
-LhK0dQeSX3hdyp2hA3G,Paying customers,Paying accounts in good standing,2019-06-19T13:54:59.630Z,Nvvd02p2kSeri4J6prKXHPOLrDw2,2019-06-19T13:54:59.630Z,NVVD02P2Kseri4J6prKXHPOLrDw2,https://api.appcues.com/v2/accounts/ACCOUNT_ID/segments/-LhK0dQeSX3hdyp2hA3G

This endpoint returns an array of segment details objects, whose format is described in detail below.

HTTP Request

GET https://api.appcues.com/v2/accounts/{account_id}/segments

URL Parameters

Parameter Description
account_id Appcues account ID

Response

This endpoint returns the list of user segments for the given account.

Get Segment Details

curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/segments/SEGMENT_ID \
  -u API_KEY:API_SECRET

The above API call returns a response like this JSON example:

{
  "created_at": "2018-11-05T22:44:37.089Z",
  "created_by": "461",
  "description": "Accounts in non-expired free trial status",
  "id": "-LQA2aYxavNXfyzm9mtP",
  "name": "Trial customers",
  "updated_at": "2019-11-26T20:14:21.345Z",
  "updated_by": "NVVD02P2Kseri4J6prKXHPOLrDw2",
  "url": "https://api.appcues.com/v2/accounts/ACCOUNT_ID/segments/-LQA2aYxavNXfyzm9mtP"
}

Or this CSV example:

id,name,description,created_at,created_by,updated_at,updated_by,url
-LQA2aYxavNXfyzm9mtP,Trial customers,Accounts in non-expired free trial status,2018-11-05T22:44:37.089Z,461,2019-11-26T20:14:21.345Z,NVVD02P2Kseri4J6prKXHPOLrDw2,https://api.appcues.com/v2/accounts/ACCOUNT_ID/segments/-LQA2aYxavNXfyzm9mtP

This endpoint returns the details for a single segment.

HTTP Request

GET https://api.appcues.com/v2/accounts/{account_id}/segments

URL Parameters

Parameter Description
account_id Appcues account ID
segment_id Segment ID

Response

Field Type Description
id string Segment ID
name string Segment name
description string Segment description
created_at string ISO 8601 date string of creation time
updated_at string ISO 8601 date string of last update time
created_by string User ID of flow creator
updated_by string User ID of last updater

Create Segment

curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/segments \
  -u API_KEY:API_SECRET \
  -H 'Content-type: application/json' \
  -d '
  {
    "name": "My best friends",
    "description": "A complete list of my best friends"
  }
  '

The above API call returns 201 Created, with a JSON response like this:

{
  "created_at": "2021-07-16T16:02:50.037Z",
  "created_by": "6ec53e5f-2b7a-4d9a-94ed-68a3a22cacbd-02",
  "description": "A complete list of my best friends",
  "id": "-MEK2A2q927bUIuhpIFT",
  "name": "My best friends",
  "updated_at": "2021-07-16T16:02:50.588Z",
  "updated_by": "6ec53e5f-2b7a-4d9a-94ed-68a3a22cacbd-02",
  "url": "https://api.appcues.com/v2/accounts/ACCOUNT_ID/segments/-MEK2A2q927bUIuhpIFT"
}

Or this CSV example:

id,name,description,created_at,created_by,updated_at,updated_by,url
-Mek2u2nL3r-yg0CHaZA,My best friends,A complete list of my best friends,2021-07-16T16:04:11.976Z,6ec53e5f-2b7a-4d9a-94ed-68a3a22cacbd-02,2021-07-16T16:04:12.547Z,6ec53e5f-2b7a-4d9a-94ed-68a3a22cacbd-02,https://api.appcues.com/v2/accounts/ACCOUNT_ID/segments/-MEK2A2q927bUIuhpIFT

This endpoint is used to create a segment.

The created segment is returned in the format described above.

Only JSON is accepted at this endpoint.

HTTP Request

POST https://api.appcues.com/v2/accounts/{account_id}/segments

URL Parameters

Parameter Description
account_id Appcues account ID

Body Parameters

Parameter Type Description
name string Required. Name of segment
description string Description of segment

Response

The created segment.

Update Segment Details

curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/segments/SEGMENT_ID \
  -u API_KEY:API_SECRET \
  -H 'Content-type: application/json' \
  -X PATCH \
  -d '
  {
    "description": "An incomplete list of my best friends"
  }
  '

The above API call returns a JSON response like this:

{
  "created_at": "2021-07-16T16:02:50.037Z",
  "created_by": "6ec53e5f-2b7a-4d9a-94ed-68a3a22cacbd-02",
  "description": "An incomplete list of my best friends",
  "id": "-MEK2A2q927bUIuhpIFT",
  "name": "My best friends",
  "updated_at": "2021-07-16T16:09:42.069Z",
  "updated_by": "6ec53e5f-2b7a-4d9a-94ed-68a3a22cacbd-02",
  "url": "https://api.appcues.com/v2/accounts/ACCOUNT_ID/segments/-MEK2A2q927bUIuhpIFT"
}

Or this CSV example:

id,name,description,created_at,created_by,updated_at,updated_by,url
-Mek2u2nL3r-yg0CHaZA,My best friends,An incomplete list of my best friends,2021-07-16T16:04:11.976Z,6ec53e5f-2b7a-4d9a-94ed-68a3a22cacbd-02,2021-07-16T16:09:42.069Z,6ec53e5f-2b7a-4d9a-94ed-68a3a22cacbd-02,https://api.appcues.com/v2/accounts/ACCOUNT_ID/segments/-MEK2A2q927bUIuhpIFT

This endpoint updates the name or description field of a user segment.

The updated segment is returned in the form described above.

Only JSON is accepted at this endpoint.

HTTP Request

PATCH https://api.appcues.com/v2/accounts/{account_id}/segments/SEGMENT_ID

URL Parameters

Parameter Description
account_id Appcues account ID

Body Parameters

Parameter Type Description
name string Name of segment
description string Description of segment

Response

The updated segment.

Delete Segment

curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/segments/SEGMENT_ID \
  -u API_KEY:API_SECRET \
  -X DELETE

The above API call returns a JSON response like this:

{"status": 200, "title": "OK"}

Or a CSV response like this:

status,title
200,OK

This endpoint deletes a user segment permanently.

HTTP Request

DELETE https://api.appcues.com/v2/accounts/{account_id}/segments/SEGMENT_ID

URL Parameters

Parameter Description
account_id Appcues account ID

Response

Field Type Description
status number 200
title string OK

Add User IDs to Segment

## Sending JSON in POST request:
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/segments/SEGMENT_ID/add_user_ids \
  -u API_KEY:API_SECRET \
  -H 'Content-type: application/json' \
  -d '
  {
    "user_ids": [
      "some-id-here",
      "another-user-id",
      "a-third-user"
    ]
  }
  '

## Sending Newline-Delimited JSON in POST request:
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/segments/SEGMENT_ID/add_user_ids \
  -u API_KEY:API_SECRET \
  -H 'Content-type: application/ndjson' \
  -d '
"some-id-here"
"another-user-id"
"a-third-user"
  '

## Sending CSV in POST request (equivalent to above):
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/segments/SEGMENT_ID/add_user_ids \
  -u API_KEY:API_SECRET \
  -H 'Content-type: text/csv' \
  -d '
some-id-here
another-user-id
a-third-user
  '

## Sending Newline-Delimited JSON via file upload:
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/segments/SEGMENT_ID/add_user_ids \
  -u API_KEY:API_SECRET \
  -F file=@path/to/file.ndjson

## Sending CSV via file upload:
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/segments/SEGMENT_ID/add_user_ids \
  -u API_KEY:API_SECRET \
  -F file=@path/to/file.csv

The above API call returns a JSON response like this:

{
  "job_id": "62844794-b7d9-40c8-b811-8f51c1414c74",
  "job_url": "https://api.appcues.com/v2/accounts/ACCOUNT_ID/jobs/62844794-b7d9-40c8-b811-8f51c1414c74",
  "status": 202,
  "title": "Accepted"
}

Or a CSV response like this:

status,title,job_id,job_url
202,Accepted,62844794-b7d9-40c8-b811-8f51c1414c74,https://api.appcues.com/v2/accounts/ACCOUNT_ID/jobs/62844794-b7d9-40c8-b811-8f51c1414c74

This endpoint can be used to add user IDs to a segment. These users will be matched by the segment, in addition to any users previously matched.

If uploading in the JSON or NDJSON format, each user ID must be properly enclosed in double-quotes.

If uploading in CSV format, the header line is optional, but if present, it must read user_id or userId.

It is harmless to add the same user ID(s) to a segment multiple times.

It may take a few minutes for the updates to take effect. Responses contain a job_url field that can be queried to view the status of the updates.

HTTP Request

POST https://api.appcues.com/v2/accounts/{account_id}/segments/{segment_id}/add_user_ids

URL Parameters

Parameter Description
account_id Appcues account ID

Body Parameters

Parameter Type Description
user_ids string User IDs of end users (may also be given as uploaded file)

Response

Field Type Description
status number 202
title string Accepted
job_id string Job ID
job_url string Job URL

Remove User IDs from Segment

## Sending JSON in POST request:
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/segments/SEGMENT_ID/remove_user_ids \
  -u API_KEY:API_SECRET \
  -H 'Content-type: application/json' \
  -d '
  {
    "user_ids": [
      "some-id-here",
      "another-user-id",
      "a-third-user"
    ]
  }
  '

## Sending Newline-Delimited JSON in POST request:
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/segments/SEGMENT_ID/remove_user_ids \
  -u API_KEY:API_SECRET \
  -H 'Content-type: application/ndjson' \
  -d '
"some-id-here"
"another-user-id"
"a-third-user"
  '

## Sending CSV in POST request (equivalent to above):
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/segments/SEGMENT_ID/remove_user_ids \
  -u API_KEY:API_SECRET \
  -H 'Content-type: text/csv' \
  -d '
some-id-here
another-user-id
a-third-user
  '

## Sending Newline-Delimited JSON via file upload:
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/segments/SEGMENT_ID/remove_user_ids \
  -u API_KEY:API_SECRET \
  -F file=@path/to/file.ndjson

## Sending CSV via file upload:
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/segments/SEGMENT_ID/remove_user_ids \
  -u API_KEY:API_SECRET \
  -F file=@path/to/file.csv

The above API call returns a JSON response like this:

{
  "job_id": "62844794-b7d9-40c8-b811-8f51c1414c74",
  "job_url": "https://api.appcues.com/v2/accounts/ACCOUNT_ID/jobs/62844794-b7d9-40c8-b811-8f51c1414c74",
  "status": 202,
  "title": "Accepted"
}

Or a CSV response like this:

status,title,job_id,job_url
202,Accepted,62844794-b7d9-40c8-b811-8f51c1414c74,https://api.appcues.com/v2/accounts/ACCOUNT_ID/jobs/62844794-b7d9-40c8-b811-8f51c1414c74

This endpoint removes user IDs that were previously added to a segment via the add_user_ids endpoint described above.

If uploading in the JSON or NDJSON format, each user ID must be properly enclosed in double-quotes.

If uploading in CSV format, the header line is optional, but if present, it must read user_id or userId.

It is harmless to add the remove user ID(s) from a segment multiple times.

It may take a few minutes for the updates to take effect. Responses contain a job_url field that can be queried to view the status of the updates.

HTTP Request

POST https://api.appcues.com/v2/accounts/{account_id}/segments/{segment_id}/remove_user_ids

URL Parameters

Parameter Description
account_id Appcues account ID

Body Parameters

Parameter Type Description
user_ids string User IDs of end users (may also be given as uploaded file)

Response

Field Type Description
status number 202
title string Accepted
job_id string Job ID
job_url string Job URL

End Users

The Appcues Public API provides endpoints for reading an end user's full profile and their most recent events, as well as tracking individual events and applying profile updates synchronously.

To import large amounts of profile or event data, it is recommended to use the import bulk profile data and import bulk event data endpoints listed under the API's Importing Data in Bulk section.

Get User Profile

curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/users/USER_ID/profile \
  -u API_KEY:API_SECRET

The above API call returns a JSON response like this:

{
  "first_name": "Harriet",
  "last_name": "Porber",
  "email": "harriet@bumbleborn.net"
}

Or a CSV response like this:

first_name,last_name,email
Harriet,Porber,harriet@bumbleborn.net

This endpoint returns a user's complete profile.

HTTP Request

GET https://api.appcues.com/v2/accounts/{account_id}/users/{user_id}/profile

URL Parameters

Parameter Description
account_id Appcues account ID
user_id End user ID

Response

This endpoint returns the user's full profile.

Update a User Profile

curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/users/USER_ID/profile \
  -u API_KEY:API_SECRET \
  -H 'Content-type: application/json' \
  -X PATCH \
  -d '
  {
    "first_name": "Harriet",
    "last_name": "Porber",
    "email": "harriet@bumbleborn.net"
  }
  '

The above API call returns a JSON response like this:

{"status": 200, "title": "OK"}

Or a CSV response like this:

status,title
200,OK

This endpoint makes a synchronous update to a user's profile.

The results of the profile update are immediately available for targeting and personalization of Appcues flows.

HTTP Request

PATCH https://api.appcues.com/v2/accounts/{account_id}/users/{user_id}/profile

URL Parameters

Parameter Description
account_id Appcues account ID
user_id End user ID

Body Parameters

The entire request body is used as key-value profile data.

Response

Field Type Description
status number 200
title string OK

Get User Event History

## Use default time_zone and limit
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/users/USER_ID/events \
  -u API_KEY:API_SECRET

## Customize time_zone to EDT (UTC-04:00) and limit to 50
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/users/USER_ID/events \
  -u API_KEY:API_SECRET \
  -G \
  -d 'time_zone=-04:00' \
  -d 'limit=50'

The above API call returns a JSON response like this:

[
  {
    "user_id": "abc123",
    "timestamp": "2021-07-20T12:34:56.789Z",
    "name": "appcues:page_view",
    "attributes": {
      "url": "https://example.com/index.cfm"
    }
  },
  {
    "user_id": "abc123",
    "timestamp": "2021-07-20T12:34:00.123Z",
    "name": "Clicked button",
    "attributes": {
      "button": "Go Home",
      "color": "red"
    }
  }
]

Or a CSV response like this:

user_id,timestamp,name,attributes.button,attributes.color,attributes.url
abc123,2021-07-20T12:34:56.789Z,appcues:page_view,,,https://example.com/index.cfm
abc123,2021-07-20T12:34:00.123Z,Clicked button,red,Go Home,

This endpoint returns a user's most recent events, sorted most-recent-first.

HTTP Request

GET https://api.appcues.com/v2/accounts/{account_id}/users/{user_id}/events

URL Parameters

Parameter Description
account_id Appcues account ID
user_id End user ID

Query Parameters

Parameter Description
limit Return at most this many events. Optional; default 100.
time_zone Return event timestamps in the given time zone, expressed like either -04:00 or in minutes offset from UTC (in this example, -240). Optional; default 0 (UTC).

Response

This endpoint returns a list of the user's most recent events, most recent first.

Each event will contain name (string) and timestamp (string, ISO 8601 compatible datetime) fields, and may contain an attributes field containing an object of key/value data describing the event.

Track a User Event

curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/users/USER_ID/events \
  -u API_KEY:API_SECRET \
  -H 'Content-type: application/json' \
  -d '
  {
    "name": "Verified email",
    "timestamp": "2021-08-10T09:41:53-04:00",
    "attributes": {
      "verified_from": "mobile"
    }
  }
  '

The above API call returns a JSON response like this:

{"status": 200, "title": "OK"}

Or a CSV response like this:

status,title
200,OK

This endpoint records a user event, synchronously.

The event is immediately available for targeting and personalization of Appcues flows, but will take several minutes to appear in other contexts (insights, charts, event history, etc.)

HTTP Request

POST https://api.appcues.com/v2/accounts/{account_id}/users/{user_id}/events

URL Parameters

Parameter Description
account_id Appcues account ID
user_id End user ID

Body Parameters

Parameter Type Description
name string Required. Event name
timestamp string Required. Event timestamp in ISO 8601 format
attributes object Freeform key/value data about the event

Response

Field Type Description
status number 200
title string OK

Importing Data in Bulk

This API has provisions for uploading user profile updates and event data, both in bulk or individually. The data is made available for use in flow targeting, personalization, and insights inside the Appcues platform.

The endpoints described in this section are for adding data in bulk, asynchronously. For adding data synchronously, one profile update or event at a time, please use the endpoints to update a user profile and track a user event in the API's End Users section.

The below updates are performed asynchronously (offline), so your API call returns before the updates are finished being applied. The endpoints return a 202 Accepted response instead of 200 OK upon success. Responses contain a job_url that can be queried to check on the status of the import job.

Import Bulk Profile Data

## Sending Newline-Delimited JSON in POST request:
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/import/profiles \
  -u API_KEY:API_SECRET \
  -H 'Content-type: application/ndjson' \
  -d '
{"user_id": "some-id-here", "email": "harriet@example.com"}
{"user_id": "another-user-id", "first_name": "Snabe"}
{"user_id": "a-third-user", "email": "bumbleborn@example.com", isAdmin: true}
  '

## Sending CSV in POST request (equivalent to above):
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/import/profiles \
  -u API_KEY:API_SECRET \
  -H 'Content-type: text/csv' \
  -d '
user_id,email,first_name,is_admin
some-id-here,harriet@example.com,,,
another-user-id,,Snabe,
a-third-user,bumbleborn@example.com,,true
  '

## Sending Newline-Delimited JSON via file upload:
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/import/profiles \
  -u API_KEY:API_SECRET \
  -F file=@path/to/file.ndjson

## Sending CSV via file upload:
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/import/profiles \
  -u API_KEY:API_SECRET \
  -F file=@path/to/file.csv

The above API call returns a JSON response like this:

{
  "job_id": "62844794-b7d9-40c8-b811-8f51c1414c74",
  "job_url": "https://api.appcues.com/v2/accounts/ACCOUNT_ID/jobs/62844794-b7d9-40c8-b811-8f51c1414c74",
  "status": 202,
  "title": "Accepted"
}

Or a CSV response like this:

status,title,job_id,job_url
202,Accepted,62844794-b7d9-40c8-b811-8f51c1414c74,https://api.appcues.com/v2/accounts/ACCOUNT_ID/jobs/62844794-b7d9-40c8-b811-8f51c1414c74

This endpoint imports user profile data in bulk. Input can be provided in CSV or Newline-Delimited JSON format, either as a traditional POST request (20MB limit per request) or as a file upload (200MB limit per file).

Each row requires a user_id or userId field. All other fields in the row are treated as user profile attributes to be assigned to the given user.

HTTP Request

POST https://api.appcues.com/v2/accounts/{account_id}/import/profiles

URL Parameters

Parameter Description
account_id Appcues account ID

Body Parameters

Parameter Type Description
user_id string User ID of end user.

Response

Field Type Description
status number 202
title string Accepted
job_id string Job ID
job_url string Job URL

Import Bulk Event Data

## Sending Newline-Delimited JSON in POST request:
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/import/events \
  -u API_KEY:API_SECRET \
  -H 'Content-type: application/ndjson' \
  -d '
{"user_id": "some-id-here", "name": "Clicked thing", "timestamp": "2021-07-14T12:34:56Z", "color": "red"}
{"user_id": "another-user-id", "name": "Made purchase", "timestamp": "2021-07-14T13:57:22Z", "attributes": {"method": "visa"}} '

## Sending CSV in POST request (equivalent to above):
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/import/events \
  -u API_KEY:API_SECRET \
  -H 'Content-type: text/csv' \
  -d '
user_id,name,timestamp,color,method
some-id-here,Clicked thing,2021-07-14T12:34:56Z,red,
another-user-id,Made purchase,2021-07-14T13:57:22Z,,visa
  '

## Sending Newline-Delimited JSON via file upload:
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/import/events \
  -u API_KEY:API_SECRET \
  -F file=@path/to/file.ndjson

## Sending CSV via file upload:
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/import/events \
  -u API_KEY:API_SECRET \
  -F file=@path/to/file.csv

The above API call returns a JSON response like this:

{
  "job_id": "62844794-b7d9-40c8-b811-8f51c1414c74",
  "job_url": "https://api.appcues.com/v2/accounts/ACCOUNT_ID/jobs/62844794-b7d9-40c8-b811-8f51c1414c74",
  "status": 202,
  "title": "Accepted"
}

Or a CSV response like this:

status,title,job_id,job_url
202,Accepted,62844794-b7d9-40c8-b811-8f51c1414c74,https://api.appcues.com/v2/accounts/ACCOUNT_ID/jobs/62844794-b7d9-40c8-b811-8f51c1414c74

This endpoint imports user event data in bulk. Input can be provided in CSV or Newline-Delimited JSON format, either as a traditional POST request (20MB limit per request) or as a file upload (200MB limit per file).

Each row requires a user_id or userId field, a name field carrying the event name, and a timestamp field bearing the ISO 8601-formatted datetime of the event. All other fields in the row are treated as event attributes. (Event attributes can be passed in a attributes key also, as shown in the first Curl example.)

HTTP Request

POST https://api.appcues.com/v2/accounts/{account_id}/import/events

URL Parameters

Parameter Description
account_id Appcues account ID

Body Parameters

Each event in the import must adhere to this specification:

Parameter Type Description
user_id string Required. User ID of end user
name string Required. Event name
timestamp string Required. Event timestamp in ISO 8601 format
attributes object Freeform key/value data about the event

Response

Field Type Description
status number 202
title string Accepted
job_id string Job ID
job_url string Job URL

Exporting Data in Bulk

The Appcues Public API allows you to export CSV- or JSON-formatted batches of user events matching a given timeframe and conditions.

The exports are prepared offline (asynchronously), and upon completion, a link to the export is sent via email.

Like other offline jobs in this API, the response will contain a job_url field that can be queried for progress updates.

Export Bulk Event Data

curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/export/events \
  -u API_KEY:API_SECRET \
  -H 'content-type: application/json' \
  -d '
  {
    "email": "harriet@example.com",
    "format": "json",
    "conditions": [
      ["flow_id", "==", "df6b6ce8-9666-4e54-bbff-b0607af5b597"]
    ],
    "start_time": "2021-08-11",
    "end_time": "2021-08-18",
    "time_zone": "-04:00"
  }
  '

The above API call returns a JSON response like this:

{
  "job_id": "62844794-b7d9-40c8-b811-8f51c1414c74",
  "job_url": "https://api.appcues.com/v2/accounts/ACCOUNT_ID/jobs/62844794-b7d9-40c8-b811-8f51c1414c74",
  "status": 202,
  "title": "Accepted"
}

Or a CSV response like this:

status,title,job_id,job_url
202,Accepted,62844794-b7d9-40c8-b811-8f51c1414c74,https://api.appcues.com/v2/accounts/ACCOUNT_ID/jobs/62844794-b7d9-40c8-b811-8f51c1414c74

This endpoint initiates an asynchronous export of event data matching the given conditions, start_time, and end_time (optional).

Set the format parameter to either "json" or "csv" to specify output encoding.

Other parameters are described below.

In JSON-encoded exports, there are four top-level fields in each event object: name, timestamp, user_id, and attributes, which is an object with all other data pertaining to the event.

In CSV-encoded exports, the attributes field has been flattened into many shallow columns. For example, the flowId field in the event's attributes object will be in a column entitled attributes.flowId.

Upon completion, a link to the exported data will be sent via email to the address(es) in the email parameter. This is a secure link that expires in one week.

HTTP Request

POST https://api.appcues.com/v2/accounts/ACCOUNT_ID/export/events

URL Parameters

Parameter Description
account_id Appcues account ID

Body Parameters

Parameter Type Description
email string or array of strings Required. Email address(es) to which results should be sent
format string Required. "csv" or "json"
conditions array of arrays Required. Conditions that determine which events are exported. See below.
start_time string or number Required. Beginning of time range for export, in ISO 8601 format (string) or milliseconds since 1970 (number)
end_time string or number End of time range for export, in ISO 8601 format (string) or milliseconds since 1970 (number)
time_zone string or number Time zone for export timestamps, in +HH:MM/-HH:MM format (string) or minutes offset from UTC (number)
limit number Maximum number of events to export. No more than 10 million events can be exported in a single export.
offset number Number of rows to skip in the export results. Use offset and limit together if you require paginated results.

Conditions

Example conditions:

Export all events for a certain flow:

[
  ["flow_id", "==", "3c2105c4-1e23-4be3-90a7-b17ff504c986"]
]

Export all events for a certain flow or a certain checklist:

[
  [
    "or",
    ["checklist_id", "==", "df31e2c7-7ac7-4eda-bcee-efceb72913fa"],
    ["flow_id", "==", "3c2105c4-1e23-4be3-90a7-b17ff504c986"]
  ]
]

Export all Appcues events for users in a certain segment:

[
  ["user_segment_id", "==", "155500d3-8f28-41ca-be2f-6b3f2a859ce7"],
  ["name", "like", "appcues%"]
]

Export non-empty NPS feedback events:

[
  ["nps_feedback", "is not null"]
]

Export Appcues internal events:

[
  ["name", "like", "appcues:%"]
]

Export Appcues Click-to-Track events:

[
  ["name", "like", "appcues_custom:%"]
]

Export all types of events:

[]

The conditions field contains a specification of the conditions that each event must match in order to be included in the export. It's an array of arrays that look like this:

[field, operator, value]

or

[conjunction, conditions1, conditions2, ...]

If there are multiple items in the top-level conditions array, each condition must pass (i.e., the conditions are joined with an implicit "and".

Fields

The following fields are able to appear in conditions:

All events

Flows

Checklists

NPS

Operators

Here are the operators that are supported in export requests:

Conjunctions

The following conjunction conditions are accepted:

Offline Jobs

Appcues tracks the progress of any offline jobs you create, such as importing data. Use these functions to check on long-running tasks.

List Jobs

curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/jobs \
  -u API_KEY:API_SECRET

The above API call returns a JSON response like this:

[
  {
    "id": "fee890bf-8984-4502-ad47-14f1074e831c",
    "name": "Import Profiles",
    "started_at": "2021-07-28T22:11:58",
    "status": "IN_PROGRESS",
    "url": "https://api.appcues.com/v2/accounts/ACCOUNT_ID/jobs/fee890bf-8984-4502-ad47-14f1074e831c"
  },
  {
    "id": "75d59048-7961-419b-95e2-018c708bdfe5",
    "name": "Import Profiles",
    "started_at": "2021-07-29T17:23:48",
    "status": "COMPLETED",
    "url": "https://api.appcues.com/v2/accounts/ACCOUNT_ID/jobs/75d59048-7961-419b-95e2-018c708bdfe5"
  }
]

Or a CSV response like this:

id,name,status,started_at,url
fee890bf-8984-4502-ad47-14f1074e831c,Import Profiles,IN_PROGRESS,2021-07-28T22:11:58,https://api.appcues.com/v2/accounts/ACCOUNT_ID/jobs/777b0a52-a5ae-4c55-9f92-e4c12f02617e
75d59048-7961-419b-95e2-018c708bdfe5,Import Profiles,COMPLETED,2021-07-29T17:23:48,https://api.appcues.com/v2/accounts/ACCOUNT_ID/jobs/75d59048-7961-419b-95e2-018c708bdfe5

This endpoint returns a list of all recent jobs for the given Appcues account.

HTTP Request

GET https://api.appcues.com/v2/accounts/{account_id}/jobs

URL Paramaters

Parameter Description
account_id Appcues account ID

Response

Each item in the response array will take the following form:

Field Type Description
id string Job ID
name string Job name
started_at string ISO 8601 date string of job creation time
status string IN_PROGRESS, COMPLETED, or FAILED
url string The URL of this job

Get Job Status

curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/jobs/JOB_ID \
  -u API_KEY:API_SECRET

The above API call returns a JSON response like this:

{
  "events": [
    {
      "attributes": {},
      "name": "Ingesting",
      "timestamp": "2021-07-29T17:24:35"
    },
    {
      "attributes": {
        "ingestions_completed": 22,
        "ingestions_failed": 0,
        "requests_failed": 0,
        "runtime_ms": 3198
      },
      "name": "Completed",
      "timestamp": "2021-07-29T17:24:36"
    }
  ],
  "id": "75d59048-7961-419b-95e2-018c708bdfe5",
  "name": "Import Profiles",
  "started_at": "2021-07-29T17:23:48",
  "status": "COMPLETED",
  "url": "https://api.appcues.com/v2/accounts/ACCOUNT_ID/jobs/75d59048-7961-419b-95e2-018c708bdfe5"
}

Or a CSV response like this, which is missing the events field:

id,name,status,started_at,url
75d59048-7961-419b-95e2-018c708bdfe5,Import Profiles,COMPLETED,2021-07-29T17:23:48,https://api.appcues.com/v2/accounts/ACCOUNT_ID/jobs/75d59048-7961-419b-95e2-018c708bdfe5

This endpoint returns the status information for a particular offline job.

HTTP Request

GET https://api.appcues.com/v2/accounts/{account_id}/jobs/{job_id}

URL Parameters

Parameter Description
account_id Appcues account ID
job_id Job ID

Response

The response matches the format described above, with the addition of an events field, whose contents are an array of objects that take the following form:

Field Type Description
name string Event name
timestamp string Event timestamp in ISO 8601 format
attributes object Freeform key/value data about the event