Appcues API

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

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

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

Connecting

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

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

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

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

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

Authentication

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

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

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

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

Join the key and secret with a single colon character (:), for example API_KEY:API_SECRET.
Encode this string using Base64. In this example, the encoded value is TVlLRVk6TVlTRUNSRVQ=.
Provide this value in a request header like:
Authorization: Basic TVlLRVk6TVlTRUNSRVQ=

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

Requests

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

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

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

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

Responses

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

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

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

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

Accept: text/csv

Each response will feature one of the following status codes:

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

Flows

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

List Flows

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

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

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

Or this CSV example:

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

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

HTTP Request

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

URL Parameters

Parameter	Description
account_id	Appcues account ID

Get Flow Details

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

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

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

Or this CSV example:

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

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

HTTP Request

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

URL Parameters

Parameter	Description
account_id	Appcues account ID
flow_id	Flow ID

Response

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

Publish Flow

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

The above API call returns a JSON response like this:

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

Or a CSV response like this:

status,title
200,OK

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

HTTP Request

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

URL Parameters

Parameter	Description
account_id	Appcues account ID
flow_id	Flow ID

Response

Field	Type	Description
status	number	200
title	string	OK

Unpublish Flow

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

The above API call returns a JSON response like this:

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

Or a CSV response like this:

status,title
200,OK

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

HTTP Request

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

URL Parameters

Parameter	Description
account_id	Appcues account ID
flow_id	Flow ID

Response

Field	Type	Description
status	number	200
title	string	OK

Segments

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

List Segments

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

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

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

Or this CSV example:

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

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

HTTP Request

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

URL Parameters

Parameter	Description
account_id	Appcues account ID

Response

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

Get Segment Details

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

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

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

Or this CSV example:

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

This endpoint returns the details for a single segment.

HTTP Request

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

URL Parameters

Parameter	Description
account_id	Appcues account ID
segment_id	Segment ID

Response

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

Create Segment

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

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

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

Or this CSV example:

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

This endpoint is used to create a segment.

The created segment is returned in the format described above.

Only JSON is accepted at this endpoint.

HTTP Request

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

URL Parameters

Parameter	Description
account_id	Appcues account ID

Body Parameters

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

Response

The created segment.

Update Segment Details

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

The above API call returns a JSON response like this:

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

Or this CSV example:

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

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

The updated segment is returned in the form described above.

Only JSON is accepted at this endpoint.

HTTP Request

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

URL Parameters

Parameter	Description
account_id	Appcues account ID

Body Parameters

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

Response

The updated segment.

Delete Segment

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

The above API call returns a JSON response like this:

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

Or a CSV response like this:

status,title
200,OK

This endpoint deletes a user segment permanently.

HTTP Request

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

URL Parameters

Parameter	Description
account_id	Appcues account ID

Response

Field	Type	Description
status	number	200
title	string	OK

Add User IDs to Segment

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

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

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

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

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

The above API call returns a JSON response like this:

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

Or a CSV response like this:

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

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

If uploading in the 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

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

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"
    }
  }
  '

The above API call returns a JSON response like this:

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

Or a CSV response like this:

status,title
200,OK

This endpoint records a user event, synchronously.

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

HTTP Request

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

URL Parameters

Parameter	Description
account_id	Appcues account ID
user_id	End user ID

Body Parameters

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

Response

Field	Type	Description
status	number	200
title	string	OK

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 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]

[conjunction, conditions1, conditions2, ...]

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

Fields

The following fields are able to appear in conditions:

All events

user_id
user_segment_id Must appear at top level of conditions array.
name Event name.
a:field Use this syntax to access attributes["field"] in an event's attributes.

Flows

flow_id
step_id
step_child_id

Checklists

checklist_id
checklist_item_id

NPS

nps_id
nps_raw_score
nps_feedback

Operators

Here are the operators that are supported in export requests:

[field, "is null"]
[field, "is not null"]
[field, "==", value]
[field, "!=", value]
[field, "<", value]
[field, "<=", value]
[field, ">", value]
[field, ">=", value]
[field, "like", value] (uses SQL's case-sensitive LIKE operator)
[field, "not like", value]
[field, "ilike", value] (uses SQL's case-insensitive ILIKE operator)
[field, "not ilike", value]
[field, "in", [value1, value2, ...]]
[field, "not in", [value1, value2, ...]]
[field, "between", low_value, high_value] (checks if low_value <= field <= high_value)

Conjunctions

The following conjunction conditions are accepted:

["or", condition1, condition2, ...] (if any condition is true, returns true)
["and", condition1, condition2, ...] (if any condition is false, return false)
["not", condition1, condition2, ...] (if any condition is true, returns false)

Offline Jobs

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

List Jobs

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

The above API call returns a JSON response like this:

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

Or a CSV response like this:

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

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

HTTP Request

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

URL Paramaters

Parameter	Description
account_id	Appcues account ID

Response

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

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

Get Job Status

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

The above API call returns a JSON response like this:

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

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

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

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

HTTP Request

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

URL Parameters

Parameter	Description
account_id	Appcues account ID
job_id	Job ID

Response

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

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

Pins

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

List Pins

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

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

[
  {
    "account_id": "17401",
    "app_id": "2d9d13ed-d21d-4d41-9e95-d401a55f7f26",
    "created_at": 1649463890602,
    "created_by": "620a104f-d233-4389-a335-73b43bc36902",
    "frequency": "every_time",
    "id": "57dd16d1-3095-4b47-a017-816390cbbc63",
    "locked_for_localization": false,
    "name": "creating experience with events",
    "platform": "web",
    "preview_url": "https://appcues.github.io/flow-testbench/index.html",
    "published": false,
    "published_at": 1660063445953,
    "state": "DRAFT",
    "steps": [
        {
            "actions": { ... },
            "children": [],
            "content": { ... },
            "contentType": "text/html",
            "createdAt": 1649465705448,
            "createdBy": "620a104f-d233-4389-a335-73b43bc36902",
            "id": "2fdf0311-277c-4bd7-bd22-bde12b55cb24",
            "index": 0,
            "name": "Pin 1",
            "parentId": null,
            "rows": [ ... ],
            "traits": [ ... ],
            "type": "tooltip",
            "updatedAt": 1649465711542,
            "updatedBy": "620a104f-d233-4389-a335-73b43bc36902"
        }
    ],
    "tag_ids": [],
    "tags": {},
    "theme": "THEME_UUID",
    "traits": [ ... ],
    "type": "persistent",
    "updated_at": 1660063804176,
    "updated_by": "620a104f-d233-4389-a335-73b43bc36902",
    "url": "https://api.appcues.com/v2/accounts/17401/pins/57dd16d1-3095-4b47-a017-816390cbbc63"
  }
]

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

HTTP Request

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

URL Parameters

Parameter	Description
account_id	Appcues account ID

Get Pin Details

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

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

  {
    "account_id": "17401",
    "app_id": "2d9d13ed-d21d-4d41-9e95-d401a55f7f26",
    "created_at": 1649463890602,
    "created_by": "620a104f-d233-4389-a335-73b43bc36902",
    "frequency": "every_time",
    "id": "57dd16d1-3095-4b47-a017-816390cbbc63",
    "locked_for_localization": false,
    "name": "creating experience with events",
    "platform": "web",
    "preview_url": "https://appcues.github.io/flow-testbench/index.html",
    "published": false,
    "published_at": 1660063445953,
    "state": "DRAFT",
    "steps": [
        {
            "actions": { ... },
            "children": [],
            "content": { ... },
            "contentType": "text/html",
            "createdAt": 1649465705448,
            "createdBy": "620a104f-d233-4389-a335-73b43bc36902",
            "id": "2fdf0311-277c-4bd7-bd22-bde12b55cb24",
            "index": 0,
            "name": "Pin 1",
            "parentId": null,
            "rows": [ ... ],
            "traits": [ ... ],
            "type": "tooltip",
            "updatedAt": 1649465711542,
            "updatedBy": "620a104f-d233-4389-a335-73b43bc36902"
        }
    ],
    "tag_ids": [],
    "tags": {},
    "theme": "THEME_UUID",
    "traits": [ ... ],
    "type": "persistent",
    "updated_at": 1660063804176,
    "updated_by": "620a104f-d233-4389-a335-73b43bc36902",
    "url": "https://api.appcues.com/v2/accounts/17401/pins/57dd16d1-3095-4b47-a017-816390cbbc63"
  }

HTTP Request

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

URL Parameters

Parameter	Description
account_id	Appcues account ID
pin_id	Pin ID

Response

Field	Type	Description
id	string	Pin ID
name	string	Pin name
published	boolean	Whether pin is currently published
published_at	string or null	ISO 8601 date string of last publish, if any
steps	[Object]	List of steps inside pin experience
frequency	string	Frequency to show pin; e.g., `once`, `every_time`
created_at	string	ISO 8601 date string of creation time
updated_at	string	ISO 8601 date string of last update time
created_by	string	User ID of pin creator
updated_by	string	User ID of last updater

Publish Pin

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

The above API call returns a JSON response like this:

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

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

HTTP Request

POST https://api.appcues.com/v2/accounts/{account_id}/pins/{pin_id}/publish

URL Parameters

Parameter	Description
account_id	Appcues account ID
pin_id	Pin ID

Response

Field	Type	Description
status	number	200
title	string	OK

Unpublish Pin

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

The above API call returns a JSON response like this:

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

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

HTTP Request

POST https://api.appcues.com/v2/accounts/{account_id}/pins/{pin_id}/unpublish

URL Parameters

Parameter	Description
account_id	Appcues account ID
pin_id	Pin ID

Response

Field	Type	Description
status	number	200
title	string	OK

Mobile Experiences

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

List Mobile Experiences

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

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

[
  {
    "account_id": "17434",
    "app_id": "012aa63d-b959-4804-a89b-3bfe4dd456db",
    "created_at": 1659968020284,
    "created_by": "ebfdec1b-21d3-4b93-9659-69d4eb31ec53",
    "frequency": "once",
    "id": "e3d8130a-6115-4e2f-a17c-256f2e5b125b",
    "locked_for_localization": false,
    "name": "DnD",
    "platform": "ios",
    "preview_url": null,
    "published": false,
    "published_at": null,
    "state": "DRAFT",
    "steps": [
        {
            "actions": {},
            "children": [...],
            "content": null,
            "contentType": null,
            "createdAt": 1660249958796,
            "createdBy": "ebfdec1b-21d3-4b93-9659-69d4eb31ec53",
            "id": "42e570ed-5f45-43d5-b599-7fc811b7f438",
            "index": 0,
            "name": null,
            "parentId": null,
            "rows": [],
            "traits": [...],
            "type": "group",
            "updatedAt": 1660249958796,
            "updatedBy": "ebfdec1b-21d3-4b93-9659-69d4eb31ec53"
        }
    ],
    "tag_ids": [],
    "tags": {},
    "theme": null,
    "traits": [],
    "type": "mobile",
    "updated_at": 1660249958803,
    "updated_by": "ebfdec1b-21d3-4b93-9659-69d4eb31ec53",
    "url": "https://api.appcues.com/v2/accounts/17434/mobile/e3d8130a-6115-4e2f-a17c-256f2e5b125b"
  }
]

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

HTTP Request

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

URL Parameters

Parameter	Description
account_id	Appcues account ID

Get Mobile Experience Details

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

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

{
    "account_id": "17434",
    "app_id": "012aa63d-b959-4804-a89b-3bfe4dd456db",
    "created_at": 1659968020284,
    "created_by": "ebfdec1b-21d3-4b93-9659-69d4eb31ec53",
    "frequency": "once",
    "id": "e3d8130a-6115-4e2f-a17c-256f2e5b125b",
    "locked_for_localization": false,
    "name": "DnD",
    "platform": "ios",
    "preview_url": null,
    "published": false,
    "published_at": null,
    "state": "DRAFT",
    "steps": [
        {
            "actions": {},
            "children": [...],
            "content": null,
            "contentType": null,
            "createdAt": 1660249958796,
            "createdBy": "ebfdec1b-21d3-4b93-9659-69d4eb31ec53",
            "id": "42e570ed-5f45-43d5-b599-7fc811b7f438",
            "index": 0,
            "name": null,
            "parentId": null,
            "rows": [],
            "traits": [...],
            "type": "group",
            "updatedAt": 1660249958796,
            "updatedBy": "ebfdec1b-21d3-4b93-9659-69d4eb31ec53"
        }
    ],
    "tag_ids": [],
    "tags": {},
    "theme": null,
    "traits": [],
    "type": "mobile",
    "updated_at": 1660249958803,
    "updated_by": "ebfdec1b-21d3-4b93-9659-69d4eb31ec53",
    "url": "https://api.appcues.com/v2/accounts/17434/mobile/e3d8130a-6115-4e2f-a17c-256f2e5b125b"
}

HTTP Request

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

URL Parameters

Parameter	Description
account_id	Appcues account ID
mobile_id	Mobile Experience ID

Response

Field	Type	Description
id	string	Mobile Experience ID
name	string	Mobile Experience name
published	boolean	Whether mobile experience is currently published
published_at	string or null	ISO 8601 date string of last publish, if any
steps	[Object]	List of steps inside mobile experience
frequency	string	Frequency to show mobile experience; e.g., `once`, `every_time`
created_at	string	ISO 8601 date string of creation time
updated_at	string	ISO 8601 date string of last update time
created_by	string	User ID of mobile experience creator
updated_by	string	User ID of last updater

Publish Mobile Experience

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

The above API call returns a JSON response like this:

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

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

HTTP Request

POST https://api.appcues.com/v2/accounts/{account_id}/mobile/{mobile_id}/publish

URL Parameters

Parameter	Description
account_id	Appcues account ID
mobile_id	Mobile Experience ID

Response

Field	Type	Description
status	number	200
title	string	OK

Unpublish Mobile Experience

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

The above API call returns a JSON response like this:

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

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

HTTP Request

POST https://api.appcues.com/v2/accounts/{account_id}/mobile/{mobile_id}/unpublish

URL Parameters

Parameter	Description
account_id	Appcues account ID
mobile_id	Mobile Experience ID

Response

Field	Type	Description
status	number	200
title	string	OK

Ingestion Filtering Rules

Ingestion filtering rules are global per account, so the whole account is in either “allow mode”, where the list represents names that are permitted, or “deny mode”, where the list represents names that are dropped.

Get Ingestion Filtering Rules

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

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

{
  "account_id": "17434",
  "type": "allow",
  "profile_rules": ["email"],
  "event_rules": ["appcues:some"],
  "group_rules": ["company:appcues"]
}

and 404 in case there isn't any ingestion rule created

This endpoint returns a single object representing all the ingestion rules you have added, whose format is described in detail below.

NOTE: Ingestion Filtering Rule is either to only allow the specified attrs or event names to deny them, can't do both.

HTTP Request

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

URL Parameters

Parameter	Description
account_id	Appcues account ID

Response

Field	Type	Description
account_id	string	Appcues account ID
type	either "allow" or "deny"	specify the action we should perform on the following rules, either deny them or only allow them
profile_rules	list of strings	a list of profile attribute names you want to either deny or allow
event_rules	list of strings	a list of event names you want to either deny or allow
group_rules	list of strings	a list of group attribute names you want to either deny or allow

Create or Update an Ingestion Filtering Rule

To create or override an existing ingestion filtering rule:

## Sending Newline-Delimited JSON in POST request:

curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/ingestion_filtering_rules/allow \
  -u API_KEY:API_SECRET \
  -h "Content-Type: application/ndjson" \
  -d '
  {"type": "profile", "value": "email"}
  {"type": "profile", "value": "password"}
  {"type": "profile", "value": "account_number"}
  {"type": "profile", "value": "ssn"}
  {"type": "group", "value": "company"}
  {"type": "group", "value": "something"}
  {"type": "group", "value": "else"}
  {"type": "event", "value": "purchase"}
  {"type": "event", "value": "should no see it"}
  {"type": "event", "value": "appcues:payment"}
  '

## Sending Newline-Delimited JSON via file upload:

curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/ingestion_filtering_rules/allow \
  -u API_KEY:API_SECRET \
  -h "Content-Type: application/ndjson" \
  -F file=@path/to/file.ndjson

## Sending CSV with columns for "type" and "value" via file upload:

curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/ingestion_filtering_rules/deny \
  -u API_KEY:API_SECRET \
  -F file=@path/to/file.csv

Example CSV file format.

type,value
profile,ssn
profile,password
profile,secret
group,other
group,secret
event,something
event,non_important

The above API call returns a JSON response like this:

{
  "account_id": "17434",
  "type": "allow",
  "event_rules": ["appcues:payment", "should no see it", "purchase"],
  "group_rules": ["else", "something", "company"],
  "profile_rules": ["ssn", "account_number", "password", "email"]
}

This endpoint is used to create or update ingestion filtering rules for your account. Ingestion filtering rules allow you to specify lists of profile attribute names, event names, and group attribute names that you wish to either allow or deny storing and using in Appcues.

NOTE: Updating rules will override the previous set of rules. Take this into account so you include the existing rules that you don't want to override.

HTTP Request

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

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

URL Parameters

Parameter	Description
account_id	Appcues account ID

Body Parameters

The request body must be new line delimited json objects with the following paramters.

Parameter	Type	Description
type	string	Required. The type of item to filter. Valid values are `profile`, `event`, and `group`
value	string	Required. The name of the profile attribute, event, or group attribute to filter

Response

Field	Type	Description
account_id	string	Appcues account ID
type	either "allow" or "deny"	specify the action we should perform on the following rules, either deny them or only allow them
profile_rules	[string]	a list of profile attribute names you want to either deny or allow
event_rules	[string]	a list of event names you want to either deny or allow
group_rules	[string]	a list of group attribute names you want to either deny or allow

SDK Authentication Keys

The Appcues Public API provides operations for managing the SDK authentication keys. To enable authentication for SDK messages/requests vis SDK Keys, you have to enable the enforcement mode.

For more information on SDK Keys and how or why you should use them, refer to our documentation on Identity Verification

NOTE: There is a limit of 5 SDK Keys per account. We recommend using the tag field to track what your SDK Keys are used for, and revoke any that are no longer in use.

Scenarios:

If enforcement mode is disabled and no authentication data is provided (for an HTTP request the auth data is given via the Authorization header), the authentication is bypassed.
If enforcement mode is disabled and the authentication data is provided (e.g.: via the Authorization header), the given token is validated, hence, if validation fails, 401 is returned.
If enforcement mode is enabled and no authentication data is provided (e.g.: via the Authorization header), the request is rejected and 401 is returned.
If enforcement mode is enabled and the authentication data is provided (e.g.: via the Authorization header), the given token validated, hence, if validation fails, 401 is returned.

SDK Key Parameters

These are the parameters for the SDK Key object:

Field	Type	Description
id	string	SDK key ID
account_id	string	Account's ID
key	string	Created key
tag	string	(Optional) Use this field to track what your SDK keys are used for
inserted_at	string	Timestamp when the SDK key was created for the first time
updated_at	string	Last time the SDK key was updated

Create a new SDK key for a given account

curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/sdk_keys \
  -u API_KEY:API_SECRET
  -d '{"tag": "my sdk key"}'

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

{
  "id": "2d9d13ed-d21d-4d41-9e95-d401a55f7f26",
  "account_id": "3d9d13ed-d21d-4d41-9e95-d401a55f7f26",
  "key": "v27fQ5sb4ChSHGqgrjNtOhYGRlMiAoqq",
  "tag": "my sdk key",
  "inserted_at": "2023-03-20T14:58:41.166949Z",
  "updated_at": "2023-03-20T14:58:41.166949Z"
}

422 is returned if there are invalid parameteres.

NOTE: There is a limit of 5 SDK Keys per account. We recommend using the tag field to track what your SDK Keys are used for, and revoke any that are no longer in use.

Path Parameters

Parameter	Description
account_id	Appcues account ID

Body Parameters (Optional)

Note: You can exclude the body parameters entirely and submit an empty request body. If you do, the key's tag will be null. You can update a key's tag later by issuing a PATCH request.

Parameter	Description
tag	(Optional) An arbitrary string that you can use to track what your SDK keys are used for.

Response

In case of success, the created SDK Key object is returned. See SDK Key Parameters.

List the SDK keys for a given account

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

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

[
  {
    "id": "2d9d13ed-d21d-4d41-9e95-d401a55f7f26",
    "account_id": "3d9d13ed-d21d-4d41-9e95-d401a55f7f26",
    "inserted_at": "2023-03-20T14:58:41.166949Z",
    "updated_at": "2023-03-20T14:58:41.166949Z"
  }
]

Path Parameters

Parameter	Description
account_id	Appcues account ID

Response

The response is a list with the SDK keys that belong to the given account. See SDK Key Parameters.

Change the `tag` field for an SDK key

curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/sdk_keys/SDK_KEY_ID \
  -X PATCH
  -u API_KEY:API_SECRET
  -d '{"tag": "my sdk key"}'

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

{
  "id": "2d9d13ed-d21d-4d41-9e95-d401a55f7f26",
  "account_id": "3d9d13ed-d21d-4d41-9e95-d401a55f7f26",
  "key": "v27fQ5sb4ChSHGqgrjNtOhYGRlMiAoqq",
  "tag": "my sdk key",
  "inserted_at": "2023-03-20T14:58:41.166949Z",
  "updated_at": "2023-03-20T14:58:41.166949Z"
}

422 is returned if there are invalid parameteres.

Path Parameters

Parameter	Description
account_id	Appcues account ID
sdk_key_id	The ID of the SDK key that you wish to update

Body Parameters

Parameter	Description
tag	An arbitrary string that you can use to track what your SDK keys are used for.

Response

In case of success, the created SDK Key object is returned. See SDK Key Parameters.

List the SDK keys for a given account

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

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

[
  {
    "id": "2d9d13ed-d21d-4d41-9e95-d401a55f7f26",
    "account_id": "3d9d13ed-d21d-4d41-9e95-d401a55f7f26",
    "inserted_at": "2023-03-20T14:58:41.166949Z",
    "updated_at": "2023-03-20T14:58:41.166949Z"
  }
]

Path Parameters

Parameter	Description
account_id	Appcues account ID

Response

The response is a list with the SDK keys that belong to the given account. See SDK Key Parameters.

Delete an existing SDK key for a given account

curl -x DELETE https://api.appcues.com/v2/accounts/ACCOUNT_ID/sdk_keys/SDK_KEY_ID \
  -u API_KEY:API_SECRET

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

{
  "id": "2d9d13ed-d21d-4d41-9e95-d401a55f7f26",
  "account_id": "3d9d13ed-d21d-4d41-9e95-d401a55f7f26",
  "inserted_at": "2023-03-20T14:58:41.166949Z",
  "updated_at": "2023-03-20T14:58:41.166949Z"
}

Path Parameters

Parameter	Description
account_id	Appcues account ID

Response

In case of success, the deleted SDK Key object is returned. See SDK Key Parameters.

Enable enforcement mode

curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/enforcement_mode/enable \
  -u API_KEY:API_SECRET \
  -d ''

The above API call replies 204 in case of success.

HTTP Request

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

Path Parameters

Parameter	Description
account_id	Appcues account ID

Disable enforcement mode

curl https://api.appcues.com/v2/accounts/ACCOUNT_ID/enforcement_mode/disable \
  -u API_KEY:API_SECRET \
  -d ''

The above API call replies 204 in case of success.

HTTP Request

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

Path Parameters

Parameter	Description
account_id	Appcues account ID