Appcues API
Welcome! You are reading the documentation for the Appcues Public API, version 2.32.0+c5c5b652.
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.
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:
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:
- Join the key and secret with a single colon character (
:
), for exampleAPI_KEY:API_SECRET
. - Encode this string using Base64.
In this example, the encoded value is
TVlLRVk6TVlTRUNSRVQ=
. - Provide this value in a request header like:
Authorization: Basic TVlLRVk6TVlTRUNSRVQ=
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",
"tag_ids": ["c96db83f-1db0-4d2c-ab51-7fa4f6eedbfb"],
"tags": {"c96db83f-1db0-4d2c-ab51-7fa4f6eedbfb": true}
},
{
"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",
"tag_ids": ["53c4e56e-9d16-40aa-8b9d-98a625788a8c"],
"tags": {"53c4e56e-9d16-40aa-8b9d-98a625788a8c": true}
}
]
Or this CSV example:
id,name,published,frequency,created_at,updated_at,published_at,created_by,updated_by,url,tag_ids,tags
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,\"[\"\"c96db83f-1db0-4d2c-ab51-7fa4f6eedbfb\"\"]\",\"%{\"\"c96db83f-1db0-4d2c-ab51-7fa4f6eedbfb\"\" => true}\"
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,\"[\"\"53c4e56e-9d16-40aa-8b9d-98a625788a8c\"\"]\",\"%{\"\"53c4e56e-9d16-40aa-8b9d-98a625788a8c\"\" => true}\"
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",
"tag_ids": ["c96db83f-1db0-4d2c-ab51-7fa4f6eedbfb"],
"tags": {"c96db83f-1db0-4d2c-ab51-7fa4f6eedbfb": true}
}
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,\"[\"\"c96db83f-1db0-4d2c-ab51-7fa4f6eedbfb\"\"]\",\"%{\"\"c96db83f-1db0-4d2c-ab51-7fa4f6eedbfb\"\" => true}\"
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 |
tag_ids | [string] | list of tag's ids |
tags | object | json object which has the tag ids as keys |
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 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 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 |
Tags
This API can be used to view your Appcues tags.
List Tags
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/tags \
-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",
"id": "c96db83f-1db0-4d2c-ab51-7fa4f6eedbfb",
"name": "Custom Tag",
"updated_at": "2019-11-26T20:14:21.345Z",
"updated_by": "NVVD02P2Kseri4J6prKXHPOLrDw2",
"url": "https://api.appcues.com/v2/accounts/ACCOUNT_ID/tags/c96db83f-1db0-4d2c-ab51-7fa4f6eedbfb"
}
]
Or this CSV example:
id,name,created_at,created_by,updated_at,updated_by,url
c96db83f-1db0-4d2c-ab51-7fa4f6eedbfb,Custom Tag,2018-11-05T22:44:37.089Z,461,2019-11-26T20:14:21.345Z,NVVD02P2Kseri4J6prKXHPOLrDw2,https://api.appcues.com/v2/accounts/ACCOUNT_ID/tags/c96db83f-1db0-4d2c-ab51-7fa4f6eedbfb
This endpoint returns an array of tag details objects, whose format is described in detail below.
HTTP Request
GET https://api.appcues.com/v2/accounts/{account_id}/tags
URL Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
Response
This endpoint returns the list of user tags for the given account.
Get Tag Details
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/tags/TAG_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",
"id": "c96db83f-1db0-4d2c-ab51-7fa4f6eedbfb",
"name": "Custom Tag",
"updated_at": "2019-11-26T20:14:21.345Z",
"updated_by": "NVVD02P2Kseri4J6prKXHPOLrDw2",
"url": "https://api.appcues.com/v2/accounts/ACCOUNT_ID/tags/c96db83f-1db0-4d2c-ab51-7fa4f6eedbfb"
}
Or this CSV example:
id,name,description,created_at,created_by,updated_at,updated_by,url
c96db83f-1db0-4d2c-ab51-7fa4f6eedbfb,Custom Tag,2018-11-05T22:44:37.089Z,461,2019-11-26T20:14:21.345Z,NVVD02P2Kseri4J6prKXHPOLrDw2,https://api.appcues.com/v2/accounts/ACCOUNT_ID/tags/c96db83f-1db0-4d2c-ab51-7fa4f6eedbfb
This endpoint returns the details for a single tag.
HTTP Request
GET https://api.appcues.com/v2/accounts/{account_id}/tags/{tag_id}
URL Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
tag_id | Tag ID |
Response
Field | Type | Description |
---|---|---|
id | string | Tag ID |
name | string | Tag name |
url | string | Tag URL |
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 |
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 user 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 user 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 user profile data.
Response
Field | Type | Description |
---|---|---|
status | number | 200 |
title | string | OK |
Delete 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 DELETE
The above API call returns a JSON response like this:
{
"job_id": "7a16a888-07d3-49c4-83bf-f35111f7d534",
"job_url": "https://api.appcues.com/v2/accounts/ACCOUNT_ID/jobs/7a16a888-07d3-49c4-83bf-f35111f7d534",
"status": 202,
"title": "Accepted"
}
This endpoint deletes a user's profile permanently, including all properties for targeting and personalization of Appcues flows. You can use this endpoint to retest flows that have a frequency setting of one and dismissed banners, without having to create new users or clone the experience. It will also reset the completion status of checklists.
Note that this endpoint does not remove user activity from analytics and reporting.
HTTP Request
DELETE 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
No-Body
Response
Field | Type | Description |
---|---|---|
status | number | 200 |
job_id | string | Job ID |
job_url | string | Job URL |
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 '
{
"group_id": "awesome_people",
"name": "Verified email",
"timestamp": "2021-08-10T09:41:53-04:00",
"attributes": {
"verified_from": "mobile"
}
}
'
In case you want to include context.url
and _identity
(within the
attributes), it would look like this:
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/users/USER_ID/events \
-u API_KEY:API_SECRET \
-H 'Content-type: application/json' \
-d '
{
"group_id": "awesome_people",
"name": "Verified email",
"timestamp": "2021-08-10T09:41:53-04:00",
"attributes": {
"verified_from": "mobile",
"_identity": {
"name": "test"
}
},
"context": {"url": "http://appcues.com"}
}
'
The above API calls return 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 |
Groups
The Appcues Public API provides endpoints for reading groups's full profile, as well as applying group profile updates synchronously.
To import large amounts of group profile data, it is recommended to use the import bulk group profile data endpoints listed under the API's Importing Data in Bulk section.
Get Group Profile
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/groups/GROUP_ID/profile \
-u API_KEY:API_SECRET
The above API call returns a JSON response like this:
{
"group_name": "Awesome People",
"mission": "Rock the world!",
"plan": "PRO"
}
Or a CSV response like this:
group_name,mission,plan
Awesome People,Rock the world!,PRO
This endpoint returns a group's complete profile.
HTTP Request
GET https://api.appcues.com/v2/accounts/{account_id}/groups/{group_id}/profile
URL Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
group_id | Group ID |
Response
This endpoint returns the group's full profile.
Update a Group Profile
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/groups/GROUP_ID/profile \
-u API_KEY:API_SECRET \
-H 'Content-type: application/json' \
-X PATCH \
-d '
{
"group_name": "Awesome People",
"mission": "Rock the world!",
"plan": "PRO"
}
'
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 group's profile.
The results of the group profile update are immediately available for targeting and personalization of Appcues flows.
HTTP Request
POST https://api.appcues.com/v2/accounts/{account_id}/groups/{group_id}/profile
URL Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
group_id | End group ID |
Body Parameters
The entire request body is used as key-value group profile data.
Response
Field | Type | Description |
---|---|---|
status | number | 200 |
title | string | OK |
Associate Users to a Group
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).
## Sending JSON in POST request:
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/groups/GROUP_ID/users \
-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/groups/GROUP_ID/users \
-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/groups/GROUP_ID/users \
-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/groups/GROUP_ID/users \
-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/groups/GROUP_ID/users \
-u API_KEY:API_SECRET \
-F file=@path/to/file.csv
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 request for each user's profile.
The results of the user profile update are immediately available for targeting and personalization of Appcues flows.
HTTP Request
PATCH https://api.appcues.com/v2/accounts/{account_id}/groups/{group_id}/users
URL Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
group_id | End group ID |
Body Parameters
Parameter | Type | Description |
---|---|---|
user_ids | [string] | List of User IDs of end user. |
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 user 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 if the data has been enqueued successfully for later processing or if
an error happened.
Import Bulk User 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 Group Profile Data
## Sending Newline-Delimited JSON in POST request:
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/import/groups \
-u API_KEY:API_SECRET \
-H 'Content-type: application/ndjson' \
-d '
{"group_id": "some-id-here", "subscription_name": "PRO"}
{"group_id": "another-group-id", "subscription_name": "TRIAL"}
{"group_id": "a-third-group", "subscription_name": "ENTRY"}
'
## Sending CSV in POST request (equivalent to above):
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/import/groups \
-u API_KEY:API_SECRET \
-H 'Content-type: text/csv' \
-d '
group_id,subscription_name
some-id-here,PRO
another-group-id,TRIAL
a-third-group,ENTRY
'
## Sending Newline-Delimited JSON via file upload:
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/import/groups \
-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/groups \
-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 group 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 group_id
or groupId
field. All other fields in the
row are treated as group profile attributes to be assigned to the given
group.
HTTP Request
POST https://api.appcues.com/v2/accounts/{account_id}/import/groups
URL Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
Body Parameters
Parameter | Type | Description |
---|---|---|
group_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"}}
{"group_id" "awesome_people", "name": "Plan Upgrade", "timestamp": "2021-07-14T13:57:22Z", "attributes": {"plan": "PRO"}} '
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,group_id,name,timestamp,color,method,plan
some-id-here,,Clicked thing,2021-07-14T12:34:56Z,red,,
another-user-id,,Made purchase,2021-07-14T13:57:22Z,,visa,
,awesome_people,Plan Upgrade,2021-07-14T13:57:22Z,,,PRO
'
Sending Newline-Delimited JSON in POST request adding context.url
and
_identity
(within the attributes) fields:
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/import/events \
-u API_KEY:API_SECRET \
-H 'Content-type: application/ndjson' \
-d '
{"user_id": "user1", "name": "user1", "timestamp": "2021-07-14T13:57:22Z", "attributes": {"_identity": {"name": "test"}}, "context": {"url": "http://appcues.com"}}
{"user_id": "user2", "name": "user2", "timestamp": "2021-07-14T13:57:22Z", "attributes": {"_identity": {"name": "test"}}, "context": {"url": "http://appcues.com"}}
'
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
, userId
, group_id
or groupId
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 | Either User ID or Group ID are Required. User ID of end user |
group_id | string | Either User ID or Group ID are Required. Group ID |
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.
Best Practices
Use a limited export time range so that the asynchronous export limit of 10 million events per request is not hit. Appcues generally recommends keeping the time range to less than one month.
Use the condition ["name", "not in", ["appcues:page_view", "appcues:profile_update"]]
to exclude those events unless they are specifically needed. These events are typically
the most numerous and excluding them will increase the possible export time range
without hitting the 10 million event limit.
Ensure the provided email address(es) are valid. Many exports are lost to incorrect email addresses.
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 |
---|---|---|
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
user_id
user_segment_id
Must appear at top level ofconditions
array.name
Event name.a:field
Use this syntax to accessattributes["field"]
in an event's attributes.
Flows
flow_id
step_id
step_child_id
Checklists
checklist_id
checklist_item_id
NPS
nps_id
nps_raw_score
nps_feedback
Operators
Here are the operators that are supported in export requests:
[field, "is null"]
[field, "is not null"]
[field, "==", value]
[field, "!=", value]
[field, "<", value]
[field, "<=", value]
[field, ">", value]
[field, ">=", value]
[field, "like", value]
(uses SQL's case-sensitive LIKE operator)[field, "not like", value]
[field, "ilike", value]
(uses SQL's case-insensitive ILIKE operator)[field, "not ilike", value]
[field, "in", [value1, value2, ...]]
[field, "not in", [value1, value2, ...]]
[field, "between", low_value, high_value]
(checks iflow_value <= field <= high_value
)
Conjunctions
The following conjunction conditions are accepted:
["or", condition1, condition2, ...]
(if any condition is true, returns true)["and", condition1, condition2, ...]
(if any condition is false, return false)["not", condition1, condition2, ...]
(if any condition is true, returns false)
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 |
Pins
The Appcues Public API provides access to your account's pins, supporting read operations and publish/unpublish actions.
List Pins
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/pins \
-u API_KEY:API_SECRET
The above API call returns a response like this JSON example:
[
{
"account_id": "17401",
"app_id": "2d9d13ed-d21d-4d41-9e95-d401a55f7f26",
"created_at": 1649463890602,
"created_by": "620a104f-d233-4389-a335-73b43bc36902",
"frequency": "every_time",
"id": "57dd16d1-3095-4b47-a017-816390cbbc63",
"locked_for_localization": false,
"name": "creating experience with events",
"platform": "web",
"preview_url": "https://appcues.github.io/flow-testbench/index.html",
"published": false,
"published_at": 1660063445953,
"state": "DRAFT",
"steps": [
{
"actions": { ... },
"children": [],
"content": { ... },
"contentType": "text/html",
"createdAt": 1649465705448,
"createdBy": "620a104f-d233-4389-a335-73b43bc36902",
"id": "2fdf0311-277c-4bd7-bd22-bde12b55cb24",
"index": 0,
"name": "Pin 1",
"parentId": null,
"rows": [ ... ],
"traits": [ ... ],
"type": "tooltip",
"updatedAt": 1649465711542,
"updatedBy": "620a104f-d233-4389-a335-73b43bc36902"
}
],
"tag_ids": [],
"tags": {},
"theme": "THEME_UUID",
"traits": [ ... ],
"type": "persistent",
"updated_at": 1660063804176,
"updated_by": "620a104f-d233-4389-a335-73b43bc36902",
"url": "https://api.appcues.com/v2/accounts/17401/pins/57dd16d1-3095-4b47-a017-816390cbbc63"
}
]
This endpoint returns an array of pin details objects, whose format is described in detail below.
HTTP Request
GET https://api.appcues.com/v2/accounts/{account_id}/pins
URL Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
Get Pin Details
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/pins/PIN_ID \
-u API_KEY:API_SECRET
The above API call returns a response like this JSON example:
{
"account_id": "17401",
"app_id": "2d9d13ed-d21d-4d41-9e95-d401a55f7f26",
"created_at": 1649463890602,
"created_by": "620a104f-d233-4389-a335-73b43bc36902",
"frequency": "every_time",
"id": "57dd16d1-3095-4b47-a017-816390cbbc63",
"locked_for_localization": false,
"name": "creating experience with events",
"platform": "web",
"preview_url": "https://appcues.github.io/flow-testbench/index.html",
"published": false,
"published_at": 1660063445953,
"state": "DRAFT",
"steps": [
{
"actions": { ... },
"children": [],
"content": { ... },
"contentType": "text/html",
"createdAt": 1649465705448,
"createdBy": "620a104f-d233-4389-a335-73b43bc36902",
"id": "2fdf0311-277c-4bd7-bd22-bde12b55cb24",
"index": 0,
"name": "Pin 1",
"parentId": null,
"rows": [ ... ],
"traits": [ ... ],
"type": "tooltip",
"updatedAt": 1649465711542,
"updatedBy": "620a104f-d233-4389-a335-73b43bc36902"
}
],
"tag_ids": [],
"tags": {},
"theme": "THEME_UUID",
"traits": [ ... ],
"type": "persistent",
"updated_at": 1660063804176,
"updated_by": "620a104f-d233-4389-a335-73b43bc36902",
"url": "https://api.appcues.com/v2/accounts/17401/pins/57dd16d1-3095-4b47-a017-816390cbbc63"
}
HTTP Request
GET https://api.appcues.com/v2/accounts/{account_id}/pins/{pin_id}
URL Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
pin_id | Pin ID |
Response
Field | Type | Description |
---|---|---|
id | string | Pin ID |
name | string | Pin name |
published | boolean | Whether pin is currently published |
published_at | string or null | ISO 8601 date string of last publish, if any |
steps | [Object] | List of steps inside pin experience |
frequency | string | Frequency to show pin; 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 |
created_by | string | User ID of pin creator |
updated_by | string | User ID of last updater |
Publish Pin
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/pins/PIN_ID/publish \
-u API_KEY:API_SECRET \
-d ''
The above API call returns a JSON response like this:
{ "status": 200, "title": "OK" }
This endpoint is used to publish a pin. It is harmless to call this endpoint on pins that are already published.
HTTP Request
POST https://api.appcues.com/v2/accounts/{account_id}/pins/{pin_id}/publish
URL Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
pin_id | Pin ID |
Response
Field | Type | Description |
---|---|---|
status | number | 200 |
title | string | OK |
Unpublish Pin
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/pins/PIN_ID/unpublish \
-u API_KEY:API_SECRET \
-d ''
The above API call returns a JSON response like this:
{ "status": 200, "title": "OK" }
This endpoint is used to unpublish a pin. It is harmless to call this endpoint on pins that are already unpublished.
HTTP Request
POST https://api.appcues.com/v2/accounts/{account_id}/pins/{pin_id}/unpublish
URL Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
pin_id | Pin ID |
Response
Field | Type | Description |
---|---|---|
status | number | 200 |
title | string | OK |
Mobile Experiences
The Appcues Public API provides access to your account's mobile experiences, supporting read operations and publish/unpublish actions.
List Mobile Experiences
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/mobile \
-u API_KEY:API_SECRET
The above API call returns a response like this JSON example:
[
{
"account_id": "17434",
"app_id": "012aa63d-b959-4804-a89b-3bfe4dd456db",
"created_at": 1659968020284,
"created_by": "ebfdec1b-21d3-4b93-9659-69d4eb31ec53",
"frequency": "once",
"id": "e3d8130a-6115-4e2f-a17c-256f2e5b125b",
"locked_for_localization": false,
"name": "DnD",
"platform": "ios",
"preview_url": null,
"published": false,
"published_at": null,
"state": "DRAFT",
"steps": [
{
"actions": {},
"children": [...],
"content": null,
"contentType": null,
"createdAt": 1660249958796,
"createdBy": "ebfdec1b-21d3-4b93-9659-69d4eb31ec53",
"id": "42e570ed-5f45-43d5-b599-7fc811b7f438",
"index": 0,
"name": null,
"parentId": null,
"rows": [],
"traits": [...],
"type": "group",
"updatedAt": 1660249958796,
"updatedBy": "ebfdec1b-21d3-4b93-9659-69d4eb31ec53"
}
],
"tag_ids": [],
"tags": {},
"theme": null,
"traits": [],
"type": "mobile",
"updated_at": 1660249958803,
"updated_by": "ebfdec1b-21d3-4b93-9659-69d4eb31ec53",
"url": "https://api.appcues.com/v2/accounts/17434/mobile/e3d8130a-6115-4e2f-a17c-256f2e5b125b"
}
]
This endpoint returns an array of mobile experiences details objects, whose format is described in detail below.
HTTP Request
GET https://api.appcues.com/v2/accounts/{account_id}/mobile
URL Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
Get Mobile Experience Details
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/mobile/MOBILE_ID \
-u API_KEY:API_SECRET
The above API call returns a response like this JSON example:
{
"account_id": "17434",
"app_id": "012aa63d-b959-4804-a89b-3bfe4dd456db",
"created_at": 1659968020284,
"created_by": "ebfdec1b-21d3-4b93-9659-69d4eb31ec53",
"frequency": "once",
"id": "e3d8130a-6115-4e2f-a17c-256f2e5b125b",
"locked_for_localization": false,
"name": "DnD",
"platform": "ios",
"preview_url": null,
"published": false,
"published_at": null,
"state": "DRAFT",
"steps": [
{
"actions": {},
"children": [...],
"content": null,
"contentType": null,
"createdAt": 1660249958796,
"createdBy": "ebfdec1b-21d3-4b93-9659-69d4eb31ec53",
"id": "42e570ed-5f45-43d5-b599-7fc811b7f438",
"index": 0,
"name": null,
"parentId": null,
"rows": [],
"traits": [...],
"type": "group",
"updatedAt": 1660249958796,
"updatedBy": "ebfdec1b-21d3-4b93-9659-69d4eb31ec53"
}
],
"tag_ids": [],
"tags": {},
"theme": null,
"traits": [],
"type": "mobile",
"updated_at": 1660249958803,
"updated_by": "ebfdec1b-21d3-4b93-9659-69d4eb31ec53",
"url": "https://api.appcues.com/v2/accounts/17434/mobile/e3d8130a-6115-4e2f-a17c-256f2e5b125b"
}
HTTP Request
GET https://api.appcues.com/v2/accounts/{account_id}/mobile/{mobile_id}
URL Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
mobile_id | Mobile Experience ID |
Response
Field | Type | Description |
---|---|---|
id | string | Mobile Experience ID |
name | string | Mobile Experience name |
published | boolean | Whether mobile experience is currently published |
published_at | string or null | ISO 8601 date string of last publish, if any |
steps | [Object] | List of steps inside mobile experience |
frequency | string | Frequency to show mobile experience; 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 |
created_by | string | User ID of mobile experience creator |
updated_by | string | User ID of last updater |
Publish Mobile Experience
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/mobile/MOBILE_ID/publish \
-u API_KEY:API_SECRET \
-d ''
The above API call returns a JSON response like this:
{ "status": 200, "title": "OK" }
This endpoint is used to publish a mobile experience. It is harmless to call this endpoint on mobile that are already published.
HTTP Request
POST https://api.appcues.com/v2/accounts/{account_id}/mobile/{mobile_id}/publish
URL Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
mobile_id | Mobile Experience ID |
Response
Field | Type | Description |
---|---|---|
status | number | 200 |
title | string | OK |
Unpublish Mobile Experience
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/mobile/MOBILE_ID/unpublish \
-u API_KEY:API_SECRET \
-d ''
The above API call returns a JSON response like this:
{ "status": 200, "title": "OK" }
This endpoint is used to unpublish a mobile experience. It is harmless to call this endpoint on mobile that are already unpublished.
HTTP Request
POST https://api.appcues.com/v2/accounts/{account_id}/mobile/{mobile_id}/unpublish
URL Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
mobile_id | Mobile Experience ID |
Response
Field | Type | Description |
---|---|---|
status | number | 200 |
title | string | OK |
Launchpads
The Appcues Public API provides access to your account's launchpads, supporting read operations and publish/unpublish actions.
List Launchpads
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/launchpads \
-u API_KEY:API_SECRET
The above API call returns a response like this JSON example:
[
{
"account_id": "ACCOUNT_ID",
"app_id": "2d9d13ed-d21d-4d41-9e95-d401a55f7f26",
"contains_localized_blocks": false,
"created_at": 1719276617656,
"created_by": "2048c23e-2602-4332-82c3-a74a546d37ca",
"experiment": null,
"frequency": "every_time",
"id": "dc8e7316-a74d-47b6-b399-4d36b22156df",
"locked_for_localization": false,
"name": "upload svgs",
"platform": "web",
"preview_url": null,
"public_name": null,
"published": false,
"published_at": null,
"schema_version": null,
"state": "DRAFT",
"steps": [
{
"actions": {},
"children": [],
"content": {},
"contentType": "application/json",
"createdAt": 1719276617664,
"createdBy": "2048c23e-2602-4332-82c3-a74a546d37ca",
"id": "82352069-0d66-41aa-8577-2d185cfa766a",
"index": 0,
"name": null,
"parentId": null,
"rows": [],
"traits": [],
"type": "launchpad",
"updatedAt": 1719361264487,
"updatedBy": "2048c23e-2602-4332-82c3-a74a546d37ca"
}
],
"tag_ids": [],
"tags": {},
"theme": null,
"traits": [
{
"type": "@appcues/persistent"
},
{
"type": "@appcues/coreEvents"
}
],
"type": "launchpad",
"updated_at": 1719361264511,
"updated_by": "2048c23e-2602-4332-82c3-a74a546d37ca",
"url": "https://api-main.staging.us-west-2.aws.appcues.net/v2/accounts/ACCOUNT_ID/launchpads/dc8e7316-a74d-47b6-b399-4d36b22156df"
}
]
Or this CSV example:
account_id,app_id,contains_localized_blocks,created_at,created_by,experiment,frequency,id,locked_for_localization,name,platform,preview_url,public_name,published,published_at,schema_version,state,steps,tag_ids,tags,theme,traits,type,updated_at,updated_by,url
"ACCOUNT_ID","2d9d13ed-d21d-4d41-9e95-d401a55f7f26",false,1719276617656,"2048c23e-2602-4332-82c3-a74a546d37ca",null,"every_time","dc8e7316-a74d-47b6-b399-4d36b22156df",false,"upload svgs","web",null,null,false,null,null,"DRAFT","[{\"actions\":{},\"children\":[],\"content\":{},\"contentType\":\"application/json\",\"createdAt\":1719276617664,\"createdBy\":\"2048c23e-2602-4332-82c3-a74a546d37ca\",\"id\":\"82352069-0d66-41aa-8577-2d185cfa766a\",\"index\":0,\"name\":null,\"parentId\":null,\"rows\":[],\"traits\":[],\"type\":\"launchpad\",\"updatedAt\":1719361264487,\"updatedBy\":\"2048c23e-2602-4332-82c3-a74a546d37ca\"}]","[]","{}",null,"[{\"type\":\"@appcues/persistent\"},{\"type\":\"@appcues/coreEvents\"}]","launchpad",1719361264511,"2048c23e-2602-4332-82c3-a74a546d37ca","https://api-main.staging.us-west-2.aws.appcues.net/v2/accounts/ACCOUNT_ID/launchpads/dc8e7316-a74d-47b6-b399-4d36b22156df"
This endpoint returns an array of launchpad details objects, whose format is described in detail below.
HTTP Request
GET https://api.appcues.com/v2/accounts/{account_id}/launchpads
URL Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
Get Launchpad Details
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/launchpads/LAUNCHPAD_ID \
-u API_KEY:API_SECRET
The above API call returns a response like this JSON example:
{
"account_id": "ACCOUNT_ID",
"app_id": "2d9d13ed-d21d-4d41-9e95-d401a55f7f26",
"contains_localized_blocks": false,
"created_at": 1719276617656,
"created_by": "2048c23e-2602-4332-82c3-a74a546d37ca",
"experiment": null,
"frequency": "every_time",
"id": "dc8e7316-a74d-47b6-b399-4d36b22156df",
"locked_for_localization": false,
"name": "upload svgs",
"platform": "web",
"preview_url": null,
"public_name": null,
"published": false,
"published_at": null,
"schema_version": null,
"state": "DRAFT",
"steps": [
{
"actions": {},
"children": [],
"content": {},
"contentType": "application/json",
"createdAt": 1719276617664,
"createdBy": "2048c23e-2602-4332-82c3-a74a546d37ca",
"id": "82352069-0d66-41aa-8577-2d185cfa766a",
"index": 0,
"name": null,
"parentId": null,
"rows": [],
"traits": [],
"type": "launchpad",
"updatedAt": 1719361264487,
"updatedBy": "2048c23e-2602-4332-82c3-a74a546d37ca"
}
],
"tag_ids": [],
"tags": {},
"theme": null,
"traits": [
{
"type": "@appcues/persistent"
},
{
"type": "@appcues/coreEvents"
}
],
"type": "launchpad",
"updated_at": 1719361264511,
"updated_by": "2048c23e-2602-4332-82c3-a74a546d37ca",
"url": "https://api-main.staging.us-west-2.aws.appcues.net/v2/accounts/ACCOUNT_ID/launchpads/dc8e7316-a74d-47b6-b399-4d36b22156df"
}
Or this CSV example:
account_id,app_id,contains_localized_blocks,created_at,created_by,experiment,frequency,id,locked_for_localization,name,platform,preview_url,public_name,published,published_at,schema_version,state,steps,tag_ids,tags,theme,traits,type,updated_at,updated_by,url
"ACCOUNT_ID","2d9d13ed-d21d-4d41-9e95-d401a55f7f26",false,1719276617656,"2048c23e-2602-4332-82c3-a74a546d37ca",null,"every_time","dc8e7316-a74d-47b6-b399-4d36b22156df",false,"upload svgs","web",null,null,false,null,null,"DRAFT","[{\"actions\":{},\"children\":[],\"content\":{},\"contentType\":\"application/json\",\"createdAt\":1719276617664,\"createdBy\":\"2048c23e-2602-4332-82c3-a74a546d37ca\",\"id\":\"82352069-0d66-41aa-8577-2d185cfa766a\",\"index\":0,\"name\":null,\"parentId\":null,\"rows\":[],\"traits\":[],\"type\":\"launchpad\",\"updatedAt\":1719361264487,\"updatedBy\":\"2048c23e-2602-4332-82c3-a74a546d37ca\"}]","[]","{}",null,"[{\"type\":\"@appcues/persistent\"},{\"type\":\"@appcues/coreEvents\"}]","launchpad",1719361264511,"2048c23e-2602-4332-82c3-a74a546d37ca","https://api-main.staging.us-west-2.aws.appcues.net/v2/accounts/ACCOUNT_ID/launchpads/dc8e7316-a74d-47b6-b399-4d36b22156df"
This endpoint returns a description of a single launchpad, identified by its launchpad ID.
HTTP Request
GET https://api.appcues.com/v2/accounts/{account_id}/launchpads/{launchpad_id}
URL Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
launchpad_id | Launchpad ID |
Response
Field | Type | Description |
---|---|---|
id | string | Launchpad ID |
name | string | Launchpad name |
published | boolean | Whether launchpad is currently published |
frequency | string | Frequency to show launchpad; e.g., once , every_time |
tag_ids | [string] | list of tag's ids |
tags | object | json object which has the tag ids as keys |
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 launchpad creator |
updated_by | string | User ID of last updater |
Publish Launchpad
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/launchpads/LAUNCHPAD_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 launchpad. It is harmless to call this endpoint on launchpads that are already published.
HTTP Request
POST https://api.appcues.com/v2/accounts/{account_id}/launchpads/{launchpad_id}/publish
URL Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
launchpad_id | Flow ID |
Response
Field | Type | Description |
---|---|---|
status | number | 200 |
title | string | OK |
Unpublish Launchpad
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/launchpads/LAUNCHPAD_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 launchpad. It is harmless to call this endpoint on launchpads that are already unpublished.
HTTP Request
POST https://api.appcues.com/v2/accounts/{account_id}/launchpads/{launchpad_id}/unpublish
URL Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
launchpad_id | Flow ID |
Response
Field | Type | Description |
---|---|---|
status | number | 200 |
title | string | OK |
Banners
The Appcues Public API provides access to your account's banners, supporting read operations and publish/unpublish actions.
List Banners
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/banners \
-u API_KEY:API_SECRET
The above API call returns a response like this JSON example:
[
{
"account_id": "ACCOUNT_ID",
"app_id": "2d9d13ed-d21d-4d41-9e95-d401a55f7f26",
"contains_localized_blocks": false,
"created_at": 1719276617656,
"created_by": "2048c23e-2602-4332-82c3-a74a546d37ca",
"experiment": null,
"frequency": "every_time",
"id": "dc8e7316-a74d-47b6-b399-4d36b22156df",
"locked_for_localization": false,
"name": "press release",
"platform": "web",
"preview_url": null,
"public_name": null,
"published": false,
"published_at": null,
"schema_version": null,
"state": "DRAFT",
"steps": [
{
"actions": {},
"children": [],
"content": {},
"contentType": "application/json",
"createdAt": 1719276617664,
"createdBy": "2048c23e-2602-4332-82c3-a74a546d37ca",
"id": "82352069-0d66-41aa-8577-2d185cfa766a",
"index": 0,
"name": null,
"parentId": null,
"rows": [],
"traits": [],
"type": "banner",
"updatedAt": 1719361264487,
"updatedBy": "2048c23e-2602-4332-82c3-a74a546d37ca"
}
],
"tag_ids": [],
"tags": {},
"theme": null,
"traits": [
{
"type": "@appcues/persistent"
},
{
"type": "@appcues/coreEvents"
}
],
"type": "banner",
"updated_at": 1719361264511,
"updated_by": "2048c23e-2602-4332-82c3-a74a546d37ca",
"url": "https://api-main.staging.us-west-2.aws.appcues.net/v2/accounts/ACCOUNT_ID/banners/dc8e7316-a74d-47b6-b399-4d36b22156df"
}
]
Or this CSV example:
account_id,app_id,contains_localized_blocks,created_at,created_by,experiment,frequency,id,locked_for_localization,name,platform,preview_url,public_name,published,published_at,schema_version,state,steps,tag_ids,tags,theme,traits,type,updated_at,updated_by,url
"ACCOUNT_ID","2d9d13ed-d21d-4d41-9e95-d401a55f7f26",false,1719276617656,"2048c23e-2602-4332-82c3-a74a546d37ca",null,"every_time","dc8e7316-a74d-47b6-b399-4d36b22156df",false,"press release","web",null,null,false,null,null,"DRAFT","[{\"actions\":{},\"children\":[],\"content\":{},\"contentType\":\"application/json\",\"createdAt\":1719276617664,\"createdBy\":\"2048c23e-2602-4332-82c3-a74a546d37ca\",\"id\":\"82352069-0d66-41aa-8577-2d185cfa766a\",\"index\":0,\"name\":null,\"parentId\":null,\"rows\":[],\"traits\":[],\"type\":\"banner\",\"updatedAt\":1719361264487,\"updatedBy\":\"2048c23e-2602-4332-82c3-a74a546d37ca\"}]","[]","{}",null,"[{\"type\":\"@appcues/persistent\"},{\"type\":\"@appcues/coreEvents\"}]","banner",1719361264511,"2048c23e-2602-4332-82c3-a74a546d37ca","https://api-main.staging.us-west-2.aws.appcues.net/v2/accounts/ACCOUNT_ID/banners/dc8e7316-a74d-47b6-b399-4d36b22156df"
This endpoint returns an array of banner details objects, whose format is described in detail below.
HTTP Request
GET https://api.appcues.com/v2/accounts/{account_id}/banners
URL Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
Get Banner Details
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/banners/BANNER_ID \
-u API_KEY:API_SECRET
The above API call returns a response like this JSON example:
{
"account_id": "ACCOUNT_ID",
"app_id": "2d9d13ed-d21d-4d41-9e95-d401a55f7f26",
"contains_localized_blocks": false,
"created_at": 1719276617656,
"created_by": "2048c23e-2602-4332-82c3-a74a546d37ca",
"experiment": null,
"frequency": "every_time",
"id": "dc8e7316-a74d-47b6-b399-4d36b22156df",
"locked_for_localization": false,
"name": "press release",
"platform": "web",
"preview_url": null,
"public_name": null,
"published": false,
"published_at": null,
"schema_version": null,
"state": "DRAFT",
"steps": [
{
"actions": {},
"children": [],
"content": {},
"contentType": "application/json",
"createdAt": 1719276617664,
"createdBy": "2048c23e-2602-4332-82c3-a74a546d37ca",
"id": "82352069-0d66-41aa-8577-2d185cfa766a",
"index": 0,
"name": null,
"parentId": null,
"rows": [],
"traits": [],
"type": "banner",
"updatedAt": 1719361264487,
"updatedBy": "2048c23e-2602-4332-82c3-a74a546d37ca"
}
],
"tag_ids": [],
"tags": {},
"theme": null,
"traits": [
{
"type": "@appcues/persistent"
},
{
"type": "@appcues/coreEvents"
}
],
"type": "banner",
"updated_at": 1719361264511,
"updated_by": "2048c23e-2602-4332-82c3-a74a546d37ca",
"url": "https://api-main.staging.us-west-2.aws.appcues.net/v2/accounts/ACCOUNT_ID/banners/dc8e7316-a74d-47b6-b399-4d36b22156df"
}
Or this CSV example:
account_id,app_id,contains_localized_blocks,created_at,created_by,experiment,frequency,id,locked_for_localization,name,platform,preview_url,public_name,published,published_at,schema_version,state,steps,tag_ids,tags,theme,traits,type,updated_at,updated_by,url
"ACCOUNT_ID","2d9d13ed-d21d-4d41-9e95-d401a55f7f26",false,1719276617656,"2048c23e-2602-4332-82c3-a74a546d37ca",null,"every_time","dc8e7316-a74d-47b6-b399-4d36b22156df",false,"press release","web",null,null,false,null,null,"DRAFT","[{\"actions\":{},\"children\":[],\"content\":{},\"contentType\":\"application/json\",\"createdAt\":1719276617664,\"createdBy\":\"2048c23e-2602-4332-82c3-a74a546d37ca\",\"id\":\"82352069-0d66-41aa-8577-2d185cfa766a\",\"index\":0,\"name\":null,\"parentId\":null,\"rows\":[],\"traits\":[],\"type\":\"banner\",\"updatedAt\":1719361264487,\"updatedBy\":\"2048c23e-2602-4332-82c3-a74a546d37ca\"}]","[]","{}",null,"[{\"type\":\"@appcues/persistent\"},{\"type\":\"@appcues/coreEvents\"}]","banner",1719361264511,"2048c23e-2602-4332-82c3-a74a546d37ca","https://api-main.staging.us-west-2.aws.appcues.net/v2/accounts/ACCOUNT_ID/banners/dc8e7316-a74d-47b6-b399-4d36b22156df"
This endpoint returns a description of a single banner, identified by its banner ID.
HTTP Request
GET https://api.appcues.com/v2/accounts/{account_id}/banners/{banner_id}
URL Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
banner_id | Banner ID |
Response
Field | Type | Description |
---|---|---|
id | string | Banner ID |
name | string | Banner name |
published | boolean | Whether banner is currently published |
frequency | string | Frequency to show banner; e.g., once , every_time |
tag_ids | [string] | list of tag's ids |
tags | object | json object which has the tag ids as keys |
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 banner creator |
updated_by | string | User ID of last updater |
Publish Banner
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/banners/BANNER_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 banner. It is harmless to call this endpoint on banners that are already published.
HTTP Request
POST https://api.appcues.com/v2/accounts/{account_id}/banners/{banner_id}/publish
URL Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
banner_id | Flow ID |
Response
Field | Type | Description |
---|---|---|
status | number | 200 |
title | string | OK |
Unpublish Banner
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/banners/BANNER_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 banner. It is harmless to call this endpoint on banners that are already unpublished.
HTTP Request
POST https://api.appcues.com/v2/accounts/{account_id}/banners/{banner_id}/unpublish
URL Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
banner_id | Flow ID |
Response
Field | Type | Description |
---|---|---|
status | number | 200 |
title | string | OK |
Checklists
The Appcues Public API provides access to your account's checklists, supporting read operations and publish/unpublish actions.
List Checklists
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/checklists \
-u API_KEY:API_SECRET
The above API call returns a response like this JSON example:
[
{
"cloned_by": "1f5ddcb8-7a91-4726-bc83-4eaabdf5d101",
"cloned_from": "a6426031-ceb7-4310-8f31-f00db335eb41",
"completion_flow_id": "",
"created_at": 1719845299539,
"created_by": "1f5ddcb8-7a91-4726-bc83-4eaabdf5d101",
"id": "219d1463-c66f-480e-a113-18886bf9a132",
"internal_name": "Copy of Test checklist",
"intro_flow_id": "",
"is_sequential": false,
"items": {
"c8c10c2c-e09b-470a-b14d-a2ceefdecf2d": {
"conditions": {"and": [{"event": {"event": ""}}]},
"id": "c8c10c2c-e09b-470a-b14d-a2ceefdecf2d",
"index": 0,
"label": "question 1"
},
"d062597e-c05b-4022-a639-12e814f13e38": {
"conditions": {
"and": [
{
"properties": {
"operator": "^",
"property": "",
"value": ""
}
}
]
},
"id": "d062597e-c05b-4022-a639-12e814f13e38",
"index": 1,
"label": "question 2"
}
},
"published": false,
"published_at": null,
"published_by": null,
"state": "DRAFT",
"title": "Test Flow",
"type": "checklist",
"unpublished_at": null,
"unpublished_by": null,
"updated_at": 1719845299539,
"updated_by": "1f5ddcb8-7a91-4726-bc83-4eaabdf5d101"
}
]
Or this CSV example:
cloned_by,cloned_from,completion_flow_id,created_at,created_by,id,internal_name,intro_flow_id,is_sequential,items,published,published_at,published_by,state,title,type,unpublished_at,unpublished_by,updated_at,updated_by
"1f5ddcb8-7a91-4726-bc83-4eaabdf5d101","a6426031-ceb7-4310-8f31-f00db335eb41","",1719845299539,"1f5ddcb8-7a91-4726-bc83-4eaabdf5d101","219d1463-c66f-480e-a113-18886bf9a132","Copy of Test checklist","",false,"{\"c8c10c2c-e09b-470a-b14d-a2ceefdecf2d\":{\"conditions\":{\"and\":[{\"event\":{\"event\":\"\"}}]},\"id\":\"c8c10c2c-e09b-470a-b14d-a2ceefdecf2d\",\"index\":0,\"label\":\"question 1\"},\"d062597e-c05b-4022-a639-12e814f13e38\":{\"conditions\":{\"and\":[{\"properties\":{\"operator\":\"^\",\"property\":\"\",\"value\":\"\"}}]},\"id\":\"d062597e-c05b-4022-a639-12e814f13e38\",\"index\":1,\"label\":\"question 2\"}}",false,null,null,"DRAFT","Test Flow","checklist",null,null,1719845299539,"1f5ddcb8-7a91-4726-bc83-4eaabdf5d101"
This endpoint returns an array of checklist details objects, whose format is described in detail below.
HTTP Request
GET https://api.appcues.com/v2/accounts/{account_id}/checklists
URL Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
Get Checklist Details
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/checklists/CHECKLIST_ID \
-u API_KEY:API_SECRET
The above API call returns a response like this JSON example:
{
"cloned_by": "1f5ddcb8-7a91-4726-bc83-4eaabdf5d101",
"cloned_from": "a6426031-ceb7-4310-8f31-f00db335eb41",
"completion_flow_id": "",
"created_at": 1719845299539,
"created_by": "1f5ddcb8-7a91-4726-bc83-4eaabdf5d101",
"id": "219d1463-c66f-480e-a113-18886bf9a132",
"internal_name": "Copy of Test checklist",
"intro_flow_id": "",
"is_sequential": false,
"items": {
"c8c10c2c-e09b-470a-b14d-a2ceefdecf2d": {
"conditions": {"and": [{"event": {"event": ""}}]},
"id": "c8c10c2c-e09b-470a-b14d-a2ceefdecf2d",
"index": 0,
"label": "question 1"
},
"d062597e-c05b-4022-a639-12e814f13e38": {
"conditions": {
"and": [
{
"properties": {
"operator": "^",
"property": "",
"value": ""
}
}
]
},
"id": "d062597e-c05b-4022-a639-12e814f13e38",
"index": 1,
"label": "question 2"
}
},
"published": false,
"published_at": null,
"published_by": null,
"state": "DRAFT",
"title": "Test Flow",
"type": "checklist",
"unpublished_at": null,
"unpublished_by": null,
"updated_at": 1719845299539,
"updated_by": "1f5ddcb8-7a91-4726-bc83-4eaabdf5d101"
}
Or this CSV example:
cloned_by,cloned_from,completion_flow_id,created_at,created_by,id,internal_name,intro_flow_id,is_sequential,items,published,published_at,published_by,state,title,type,unpublished_at,unpublished_by,updated_at,updated_by
"1f5ddcb8-7a91-4726-bc83-4eaabdf5d101","a6426031-ceb7-4310-8f31-f00db335eb41","",1719845299539,"1f5ddcb8-7a91-4726-bc83-4eaabdf5d101","219d1463-c66f-480e-a113-18886bf9a132","Copy of Test checklist","",false,"{\"c8c10c2c-e09b-470a-b14d-a2ceefdecf2d\":{\"conditions\":{\"and\":[{\"event\":{\"event\":\"\"}}]},\"id\":\"c8c10c2c-e09b-470a-b14d-a2ceefdecf2d\",\"index\":0,\"label\":\"question 1\"},\"d062597e-c05b-4022-a639-12e814f13e38\":{\"conditions\":{\"and\":[{\"properties\":{\"operator\":\"^\",\"property\":\"\",\"value\":\"\"}}]},\"id\":\"d062597e-c05b-4022-a639-12e814f13e38\",\"index\":1,\"label\":\"question 2\"}}",false,null,null,"DRAFT","Test Flow","checklist",null,null,1719845299539,"1f5ddcb8-7a91-4726-bc83-4eaabdf5d101"
This endpoint returns a description of a single checklist, identified by its checklist ID.
HTTP Request
GET https://api.appcues.com/v2/accounts/{account_id}/checklists/{checklist_id}
URL Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
checklist_id | Checklist ID |
Response
Field | Type | Description |
---|---|---|
id | string | Checklist ID |
title | string | Checklist public name |
internal_name | string | Checklist internal name |
published | boolean | Whether checklist is currently published |
is_sequential | boolean | Whether checklist's steps are sequential or unordered |
items | object | json object which has the conditions to complete a checklist |
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 checklist creator |
updated_by | string | User ID of last updater |
Publish Checklist
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/checklists/CHECKLIST_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 checklist. It is harmless to call this endpoint on checklists that are already published.
HTTP Request
POST https://api.appcues.com/v2/accounts/{account_id}/checklists/{checklist_id}/publish
URL Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
checklist_id | Flow ID |
Response
Field | Type | Description |
---|---|---|
status | number | 200 |
title | string | OK |
Unpublish Checklist
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/checklists/CHECKLIST_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 checklist. It is harmless to call this endpoint on checklists that are already unpublished.
HTTP Request
POST https://api.appcues.com/v2/accounts/{account_id}/checklists/{checklist_id}/unpublish
URL Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
checklist_id | Flow ID |
Response
Field | Type | Description |
---|---|---|
status | number | 200 |
title | string | OK |
Ingestion Filtering Rules
Ingestion filtering rules are global per account, so the whole account is in either “allow mode”, where the list represents names that are permitted, or “deny mode”, where the list represents names that are dropped.
Get Ingestion Filtering Rules
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/ingestion_filtering_rules \
-u API_KEY:API_SECRET
The above API call returns a response like this JSON example:
{
"account_id": "17434",
"type": "allow",
"profile_rules": ["email"],
"event_rules": ["appcues:some"],
"group_rules": ["company:appcues"]
}
and 404 in case there isn't any ingestion rule created
This endpoint returns a single object representing all the ingestion rules you have added, whose format is described in detail below.
NOTE: Ingestion Filtering Rule is either to only allow the specified attrs or event names to deny them, can't do both.
HTTP Request
GET https://api.appcues.com/v2/accounts/{account_id}/ingestion_filtering_rules
URL Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
Response
Field | Type | Description |
---|---|---|
account_id | string | Appcues account ID |
type | either "allow" or "deny" | specify the action we should perform on the following rules, either deny them or only allow them |
profile_rules | list of strings | a list of profile attribute names you want to either deny or allow |
event_rules | list of strings | a list of event names you want to either deny or allow |
group_rules | list of strings | a list of group attribute names you want to either deny or allow |
Create or Update an Ingestion Filtering Rule
To create or override an existing ingestion filtering rule:
## Sending Newline-Delimited JSON in POST request:
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/ingestion_filtering_rules/allow \
-u API_KEY:API_SECRET \
-h "Content-Type: application/ndjson" \
-d '
{"type": "profile", "value": "email"}
{"type": "profile", "value": "password"}
{"type": "profile", "value": "account_number"}
{"type": "profile", "value": "ssn"}
{"type": "group", "value": "company"}
{"type": "group", "value": "something"}
{"type": "group", "value": "else"}
{"type": "event", "value": "purchase"}
{"type": "event", "value": "should no see it"}
{"type": "event", "value": "appcues:payment"}
'
## Sending Newline-Delimited JSON via file upload:
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/ingestion_filtering_rules/allow \
-u API_KEY:API_SECRET \
-h "Content-Type: application/ndjson" \
-F file=@path/to/file.ndjson
## Sending CSV with columns for "type" and "value" via file upload:
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/ingestion_filtering_rules/deny \
-u API_KEY:API_SECRET \
-F file=@path/to/file.csv
Example CSV file format.
type,value
profile,ssn
profile,password
profile,secret
group,other
group,secret
event,something
event,non_important
The above API call returns a JSON response like this:
{
"account_id": "17434",
"type": "allow",
"event_rules": ["appcues:payment", "should no see it", "purchase"],
"group_rules": ["else", "something", "company"],
"profile_rules": ["ssn", "account_number", "password", "email"]
}
This endpoint is used to create or update ingestion filtering rules for your account. Ingestion filtering rules allow you to specify lists of profile attribute names, event names, and group attribute names that you wish to either allow or deny storing and using in Appcues.
NOTE: Updating rules will override the previous set of rules. Take this into account so you include the existing rules that you don't want to override.
HTTP Request
POST https://api.appcues.com/v2/accounts/{account_id}/ingestion_filtering_rules/deny
POST https://api.appcues.com/v2/accounts/{account_id}/ingestion_filtering_rules/allow
URL Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
Body Parameters
The request body must be new line delimited json objects with the following paramters.
Parameter | Type | Description |
---|---|---|
type | string | Required. The type of item to filter. Valid values are profile , event , and group |
value | string | Required. The name of the profile attribute, event, or group attribute to filter |
Response
Field | Type | Description |
---|---|---|
account_id | string | Appcues account ID |
type | either "allow" or "deny" | specify the action we should perform on the following rules, either deny them or only allow them |
profile_rules | [string] | a list of profile attribute names you want to either deny or allow |
event_rules | [string] | a list of event names you want to either deny or allow |
group_rules | [string] | a list of group attribute names you want to either deny or allow |
SDK Authentication Keys
The Appcues Public API provides operations for managing the SDK authentication keys. To enable authentication for SDK messages/requests vis SDK Keys, you have to enable the enforcement mode.
For more information on SDK Keys and how or why you should use them, refer to our documentation on Identity Verification
NOTE: There is a limit of 5 SDK Keys per account. We recommend using the tag
field
to track what your SDK Keys are used for, and revoke any that are no longer in use.
Scenarios:
- If enforcement mode is disabled and no authentication data is provided
(for an HTTP request the auth data is given via the
Authorization
header), the authentication is bypassed. - If enforcement mode is disabled and the authentication data is provided
(e.g.: via the
Authorization
header), the given token is validated, hence, if validation fails,401
is returned. - If enforcement mode is enabled and no authentication data is provided
(e.g.: via the
Authorization
header), the request is rejected and401
is returned. - If enforcement mode is enabled and the authentication data is provided
(e.g.: via the
Authorization
header), the given token validated, hence, if validation fails,401
is returned.
SDK Key Parameters
These are the parameters for the SDK Key object:
Field | Type | Description |
---|---|---|
id | string | SDK key ID |
account_id | string | Account's ID |
key | string | Created key |
tag | string | (Optional) Use this field to track what your SDK keys are used for |
inserted_at | string | Timestamp when the SDK key was created for the first time |
updated_at | string | Last time the SDK key was updated |
Create a new SDK key for a given account
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/sdk_keys \
-u API_KEY:API_SECRET
-d '{"tag": "my sdk key"}'
The above API call returns
200
with a response like this JSON example:
{
"id": "2d9d13ed-d21d-4d41-9e95-d401a55f7f26",
"account_id": "3d9d13ed-d21d-4d41-9e95-d401a55f7f26",
"key": "v27fQ5sb4ChSHGqgrjNtOhYGRlMiAoqq",
"tag": "my sdk key",
"inserted_at": "2023-03-20T14:58:41.166949Z",
"updated_at": "2023-03-20T14:58:41.166949Z"
}
422
is returned if there are invalid parameteres.
NOTE: There is a limit of 5 SDK Keys per account. We recommend using the tag
field
to track what your SDK Keys are used for, and revoke any that are no longer in use.
Path Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
Body Parameters (Optional)
Note: You can exclude the body parameters entirely and submit an empty request body.
If you do, the key's tag will be null.
You can update a key's tag later by issuing a PATCH
request.
Parameter | Description |
---|---|
tag | (Optional) An arbitrary string that you can use to track what your SDK keys are used for. |
Response
In case of success, the created SDK Key object is returned. See SDK Key Parameters.
List the SDK keys for a given account
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/sdk_keys \
-u API_KEY:API_SECRET
The above API call returns
200
with a response like this JSON example:
[
{
"id": "2d9d13ed-d21d-4d41-9e95-d401a55f7f26",
"account_id": "3d9d13ed-d21d-4d41-9e95-d401a55f7f26",
"inserted_at": "2023-03-20T14:58:41.166949Z",
"updated_at": "2023-03-20T14:58:41.166949Z"
}
]
Path Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
Response
The response is a list with the SDK keys that belong to the given account. See SDK Key Parameters.
Change the tag
field for an SDK key
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/sdk_keys/SDK_KEY_ID \
-X PATCH
-u API_KEY:API_SECRET
-d '{"tag": "my sdk key"}'
The above API call returns
200
with a response like this JSON example:
{
"id": "2d9d13ed-d21d-4d41-9e95-d401a55f7f26",
"account_id": "3d9d13ed-d21d-4d41-9e95-d401a55f7f26",
"key": "v27fQ5sb4ChSHGqgrjNtOhYGRlMiAoqq",
"tag": "my sdk key",
"inserted_at": "2023-03-20T14:58:41.166949Z",
"updated_at": "2023-03-20T14:58:41.166949Z"
}
422
is returned if there are invalid parameteres.
Path Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
sdk_key_id | The ID of the SDK key that you wish to update |
Body Parameters
Parameter | Description |
---|---|
tag | An arbitrary string that you can use to track what your SDK keys are used for. |
Response
In case of success, the created SDK Key object is returned. See SDK Key Parameters.
List the SDK keys for a given account
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/sdk_keys \
-u API_KEY:API_SECRET
The above API call returns
200
with a response like this JSON example:
[
{
"id": "2d9d13ed-d21d-4d41-9e95-d401a55f7f26",
"account_id": "3d9d13ed-d21d-4d41-9e95-d401a55f7f26",
"inserted_at": "2023-03-20T14:58:41.166949Z",
"updated_at": "2023-03-20T14:58:41.166949Z"
}
]
Path Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
Response
The response is a list with the SDK keys that belong to the given account. See SDK Key Parameters.
Delete an existing SDK key for a given account
curl -x DELETE https://api.appcues.com/v2/accounts/ACCOUNT_ID/sdk_keys/SDK_KEY_ID \
-u API_KEY:API_SECRET
The above API call returns
200
with a response like this JSON example:
{
"id": "2d9d13ed-d21d-4d41-9e95-d401a55f7f26",
"account_id": "3d9d13ed-d21d-4d41-9e95-d401a55f7f26",
"inserted_at": "2023-03-20T14:58:41.166949Z",
"updated_at": "2023-03-20T14:58:41.166949Z"
}
Path Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
Response
In case of success, the deleted SDK Key object is returned. See SDK Key Parameters.
Enable enforcement mode
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/enforcement_mode/enable \
-u API_KEY:API_SECRET \
-d ''
The above API call replies
204
in case of success.
HTTP Request
POST https://api.appcues.com/v2/accounts/{account_id}/enforcement_mode/enable
Path Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |
Disable enforcement mode
curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/enforcement_mode/disable \
-u API_KEY:API_SECRET \
-d ''
The above API call replies
204
in case of success.
HTTP Request
POST https://api.appcues.com/v2/accounts/{account_id}/enforcement_mode/disable
Path Parameters
Parameter | Description |
---|---|
account_id | Appcues account ID |