NAV
Examples

Appcues API

Welcome! You are reading the documentation for the Appcues Public API, version 2.32.0+71076a3d.

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:

Run in Postman

Authentication

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

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

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

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

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

Requests

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

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

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

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

Responses

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

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

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

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

Accept: text/csv

Each response will feature one of the following status codes:

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

Flows

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

List Flows

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

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

[
  {
    "id": "flow1",
    "name": "Flow 1",
    "published": true,
    "frequency": "once",
    "created_at": "2021-04-05T16:21:09Z",
    "updated_at": "2021-04-05T17:00:42Z",
    "published_at": "2021-04-05T17:00:42Z",
    "created_by": "620a104f-d233-4389-a335-73b43bc36902",
    "updated_by": "e3d7a8d7-b8cd-4139-aa9d-25b493fa2e65",
    "url": "https://api.appcues.com/v2/accounts/ACCOUNT_ID/flows/flow1",
    "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
email string or array of strings Required. Email address(es) to which results should be sent
format string Required. "csv" or "json"
conditions array of arrays Required. Conditions that determine which events are exported. See below.
start_time string or number Required. Beginning of time range for export, in ISO 8601 format (string) or milliseconds since 1970 (number)
end_time string or number End of time range for export, in ISO 8601 format (string) or milliseconds since 1970 (number)
time_zone string or number Time zone for export timestamps, in +HH:MM/-HH:MM format (string) or minutes offset from UTC (number)
limit number Maximum number of events to export. No more than 10 million events can be exported in a single export.
offset number Number of rows to skip in the export results. Use offset and limit together if you require paginated results.

Conditions

Example conditions:

Export all events for a certain flow:

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

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

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

Export all Appcues events for users in a certain segment:

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

Export non-empty NPS feedback events:

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

Export Appcues internal events:

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

Export Appcues Click-to-Track events:

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

Export all types of events:

[]

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

[field, operator, value]

or

[conjunction, conditions1, conditions2, ...]

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

Fields

The following fields are able to appear in conditions:

All events

Flows

Checklists

NPS

Operators

Here are the operators that are supported in export requests:

Conjunctions

The following conjunction conditions are accepted:

Offline Jobs

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

List Jobs

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

The above API call returns a JSON response like this:

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

Or a CSV response like this:

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

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

HTTP Request

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

URL Paramaters

Parameter Description
account_id Appcues account ID

Response

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

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

Get Job Status

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

The above API call returns a JSON response like this:

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

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

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

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

HTTP Request

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

URL Parameters

Parameter Description
account_id Appcues account ID
job_id Job ID

Response

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

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

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:

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