Common Information

Introduction

API Endpoint

https://app.pendo.io

Welcome to Pendo’s API documentation! Whether you’re looking to access Pendo data with our v1 API, or interact programatically with our Agent API, you’ve come to the right place.

Don’t have access to our API but still want to try things out? Each of the read-only examples below contain a sample integration key that can be used to query mock data. If you already have access and are looking for some sample aggregations, click the button below to load up a collection of requests that can be used against the aggregation endpoint. If you have questions or want to learn more about gaining access to our API, we recommend reaching out to your customer success manager or help@pendo.io and we’ll get you in touch with the right person.

Run in Postman

The Pendo v1 API is a RESTful API used to query, update, and reset Pendo data. All request and response bodies, including errors, are encoded in JSON unless otherwise noted in the examples. We do not currently rate limit calls against the v1 API.

Our Agent API, the JS library that lives inside of your application, allows developers to programmatically interact with Pendo’s agent. In 95% of cases, there’s really no need to use this API as the default installation snippet should be all that is needed to effectively capture events and deliver guides to end-users. If however, you’re looking to leverage advanced functionality, we’ve got you covered. Lastly, it’s important to note that any non-documented functionality found in the agent should be considered either internal and/or experimental, and more than likely is subject to change in the future. In other words, if it’s not documented here, we don’t recommend using it.

Authentication

Example request

curl -X GET \
  https://app.pendo.io/api/v1/report \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: 63bd1cda-db5a-4a2b-633b-37b8b0c54'
import requests
url = "https://app.pendo.io/api/v1/report"
headers = {
    'x-pendo-integration-key': "63bd1cda-db5a-4a2b-633b-37b8b0c5462c",
    'content-type': "application/json"
}
response = requests.get(url, headers = headers)

A sample integration key is included in all of the read-only examples so you can test any of them right away. When you’re ready to test requests against your own subscription, simply replace the sample key with your actual integration key.

Authentication of requests is handled by an integration key. When enabled for the subscription, admins can create and manage those keys here.

Integration keys should be kept secret! It is how you securely access and update information about your users and accounts in Pendo. Do not share them in client-side javascript, publicly accessible code repositories, etc.

To create an Integration Key:

  1. Login to the Pendo Application as an Admin user.
  2. Visit the Settings section in the Pendo App, and then click on Integration Keys.
  3. Click on the Add Integration Key button at the top right-hand side of the screen.
  4. Give your new key an appropriate description.
  5. If a read-write key is needed, tick the box marked Allow Write Access.
  6. Click on Create to finish.

The Integration Key is the UUID that is in the Key column of the table.

Status Codes

HTTP status code summary

200 - OK Everything worked as expected.
400 - Bad Request The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized No valid integration key provided.
402 - Request Failed The parameters were valid but the request failed.
404 - Not Found The requested resource doesn’t exist.
422 - Unprocessable Entity The request could not process the payload. The syntax may be correct, but may be semantically wrong
429 - Too Many Requests Too many requests hit the API too quickly. Slow down.
500, 502, 503, 504 - Server Errors It’s not you, it’s us. We’re sorry.

We use conventional HTTP response codes to indicate the success or failure of an API request.

In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a resource was not able to be found or updated, etc.). The various HTTP status codes we might return are listed below.

v1 API

All request and response bodies, including errors, are encoded in JSON. We do not currently rate limit calls against the v1 API.

Account

Account endpoint

https://app.pendo.io/api/v1/account

The account endpoint allows you to retrieve account specific details by supplying an account ID as part of your request. The {accountId} referenced below can be found on the accounts list page or at the end of the url when viewing an account details page.

The account object

Example response

[{
    "id": "Zeta and Sons",
    "metadata": {
        "agent": {},
        "auto": {
            "firstvisit": 1506349414089,
            "id": "Zeta and Sons",
            "idhash": 1129480058,
            "lastupdated": 1506349414757,
            "lastvisit": 1506349414089
        }
    }
}]
Attributes
id
string
Unique identifier for the account.
metadata
string
Displays various metadata for the specified account. agent, auto, custom, salesforce, and segmentio.

Get an account by ID

Definition

GET https://app.pendo.io/api/v1/account/{accountId}
requests.get("https://app.pendo.io/api/v1/account/{accountId}")

Example request

curl -X GET \
  https://app.pendo.io/api/v1/account/Zeta%20and%20Sons \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: 63bd1cda-db5a-4a2b-633b-37b8b0c5462c'
import requests
headers = {
    'content-type': 'application/json',
    'x-pendo-integration-key': '63bd1cda-db5a-4a2b-633b-37b8b0c5462c',
}
requests.get('https://app.pendo.io/api/v1/account/Zeta%20and%20Sons', headers = headers)

Example response

[{
    "id": "Zeta and Sons",
    "metadata": {
        "agent": {},
        "auto": {
            "firstvisit": 1506349414089,
            "id": "Zeta and Sons",
            "idhash": 1129480058,
            "lastupdated": 1506349414757,
            "lastvisit": 1506349414089
        }
    }
}]

Gets an account object using an account ID.

Details
Method GET
URI /api/v1/account/{accountId}
Parameters accountId - URL encoded account id or b64_XXXX, where XXXX is a URL-safe base64 encoded account Id
Request Headers content-type: application/json
x-pendo-integration-key: <PENDO_INTEGRATION_KEY>
Status Codes 200: Response is sent as body

Aggregation

Aggregation endpoint

https://app.pendo.io/api/v1/aggregation

Aggregations are a query language for accessing and processing Pendo data. They take sources of Pendo data and apply operators to do computations. They run in the context of a given Pendo subscription and are written in JSON.

It is worth noting, the aggregations endpoint is not intended to be a bulk export feature, so breaking up aggregations by different time ranges may be necessary if you hit sizing or timeout limits.

Helpful Links:

Run in Postman

Data querying is performed using a flexible aggregation pipeline modeled after MongoDB. Each step of the pipeline takes rows as its input and output zero or more rows. The basic unit is a row which contains named fields (possible nested) fields. At a high level, an aggregation consists of

  • A row source and time specification
  • A pipeline for row processing

All input data rows for the specified time period are fed into the aggregation pipeline. The rows which those pipeline yields are the result of the aggregation; a pipeline may result in no rows or in many rows depending on the pipeline and the input.

If the time specification expands into 24 separate time periods (one for each hour of a day, perhaps) then 24 independent pipelines are run, and the aggregation will have 24 sets of results. Each of those results in independent of the others.

Nested Fields

Example structure

{
    "name": {
        "first": "bugs",
        "last": "bunny"
    }
}

Wherever a field name is needed, a dotted list of field names can be used to specify nested objects.

Nested specifiers can be used to create new fields as well; any missing intermediate objects will be initialized.

In the example to the right, the field name.last has the value bunny.

Data Stores

Data Stores
Visitors General information on all visitors Pendo has ever seen.
Accounts General information on all accounts Pendo has ever seen.
Events Each interaction with your application by a visitor. This includes click, page load, metadata, and guide events. The definitions of pages, features, and guides.

Expressions

A number of pipeline operators support expressions. Expressions follow basic C expression syntax along with function calls. Supported operators are ==, !=, &&, ||, <, >, <=, >=, +, -, /, *, %, and !.

All numeric value are converted to float’s for computational purposes, and C order of operation is used.

Parenthesis () may be used for grouping expressions.

The comparison operators can be used to compare strings, the logical operators and comparison work on boolean values, and the equality operators can compare two lists.

For the || and && operators, null is treated equivalently to false.

The == and != operators treat null as a distinct value (so null == null but null != false) and any other operator which has null as a parameter returns null as its value (so 1 + null == null)

Values may be extracted from list by using normal JavaScript style indexes such as listField[index]; sublists can be created using JavaScript style slices such as listField[start:end]. Additionally negative indexes can be used to look up items from the end; listField[-2] will return the next to last item in the list. This follows Python style syntax.

Arrays of values are supported, such as ["a","b","c"] or [1,1+2,sum(a)]. All array elements must be of the same type. You may select an element from the array using normal Javascript style indexes (i.e. ["a","b","c"][2]) as defined in the preceding paragraph.

Expression primitives are numbers (with or without a decimal point), strings enclosed in double quotation marks, true, false, and field names (using dotted notation to specify nested fields). The currently supported functions are listed below.

Functions
ceil(val) returns the ceiling of numeric value val
null if val == null
error if val is non-numeric/non-null
childAccountId(accountId) returns the child account id for the specified accountId
null if the accountId is not found
contains(listValue, item) returns true if item is in the specified list
contains(haystackString, needleString) returns true if the needle is contained in the haystack (both as strings)
floor(val) returns the floor of numeric value val
null if val == null
error if val is non-numeric/non-null
formatTime(goFormatString, timeInMillis) formats the given time using the go-style go format string examples.
hash(string) returns a 32 bit hash value for the given string
if(testExpression, ifTrue, [ifFalse]) returns the ifTrue value if testExpression is true
returns the ifFalse value if testExpression is false
isNull(fieldName) returns true if the fieldName exists in the row and is not null
returns false otherwise
len(listField) returns the length of the specified list
list(field1, field2, field3) returns a list containing the named fields
listInRange(listField, minValue, maxValue) returns a list containing the elements in listField which are between minValue and maxValue (inclusive)
map() explained in greater detail below
now() returns the current time in milliseconds past the epoch
parentAccountId(accountId) returns the parent account id for the specified accountId
returns the accountId itself if there is no child
reverse(list) returns the specified list, reversed
round(val) returns the the numeric value val rounded to the nearest integer
returns null if val == null
returns error if val is non-numeric/non-null
split(s, sep) splits the string s into a list of strings using string sep as the field separator
startOfPeriod(periodName, timeStamp) returns the first timestamp in the period which includes the passed timestamp
period can be one of "hourly", "daily", "weekly", or "monthly"
startsWith(haystack, needle) returns true if the string haystack begins with the string needle
returns false if haystack is nil
sum(listValue) returns the sum of the items in the specified list, ignoring non-numeric elements

The map() function

Two parameter function

map(users, users.name)

When applied to the row

{
    "users": [{
        "id": 5,
        "name": "mickey"
    }, {
        "id": "2",
        "name": "minnie"
    }]
}

Example response

["mickey", "minnie"]

The map() function comes in two variants, which take either two or three parameters. The simpler form is map(listField, expression), and it applies the given expression to each item in the specified list, and returns a list of the results.

The listField must specify a list of objects. This means a list of integers will not work.

Three parameter function

map(x, names, len(x))

When applied to the row

{
"names": ["bugs", "daffy"]
}

Example response

[ 4, 5 ]

The three parameter form of map() is more general and works on lists of any type. While it works on any type, it’s important to note that it processes lists of objects slower than the two parameter form.

The first parameter is an identifier which the third parameter (the expression) can use to reference the particular value being mapped.

Both versions will return null if the list parameter is null.

Source specification

Definition

{
    "source": {
        "sourceType": {SOURCE PARAMS}
    },
    "timeSeries": {
        "first": timeInMsOrExpression,
        "count": numberOfPeriods,
        "period": periodName
    }
}

The source key must be specified as the first step in the pipeline unless spawn is used; then no source can exist. This tells the aggregation what data to feed into the pipeline.

Details
sourceType Source of data for the aggregation.

Row source specification

Think of row sources as tables, to borrow a term from relational databases. Once you understand what’s available in the row sources, you’ll be well on your way to knowing what’s possible overall.

When you return row source data, you can slice and dice it in a number of ways.

The short answer to “what can we access with the Pendo API” is: all the major entities, day/hour summaries for feature and page usage, and event level data for guide activity and polls.

The sourceType specifies what kind of data is being aggregated. Each specific type has specific parameters. If no parameters are provided, the empty {} can be replaced with null.

Row sources specify what types of rows should go into the pipeline, and are normally parameterized. The time period for the rows is not specified here; it is part of the time series specification instead.

Sources
accounts All accounts with their metadata. For customers using subaccounts, only the subaccounts are returned unless { "parentAccounts" : true } is specified, in which case only the parent accounts are returned.
accountTags Parameter may be { "tagId" : tagId } to limit results to a single accountTag. Returns { "accountId" : accountId , "accountTags": { tagId : true , ... }} for each account with the requested tag (listing only the requested tag), or if none specified, any currently valid accountTag (listing all tags on each).
events Returns summary data for all events on the system in a time period. Accepts an event class or list of event classes { "eventClass" : "web"|"ios"|["web","ios"] } to return, "web" by default.
featureEvents Covers all features unless featureId is provided to narrow the results to a single featureId. Returns results for requested time period. Accepts an event class or list of event classes { "eventClass" : "web"|"ios"|["web","ios"] } to return, "web" by default.
guideEvents Returns all guide events (guideSeen/dismissed/advanced) for requested time period. Can be limited by guideId or guideId and guideStepId.
guidesSeen Returns firstSeenAt, lastSeenAt, lastState, and seenCount for each visitor that saw the requested guide(s) in a time period. Parameter must be { "guideId" : guideId, "guideStepId" : guideStepId }; leaving out guide (blank/null/unsupplied) shows rows for all steps on all guides, and leaving out step shows all steps on the requested guide.
pageEvents Covers all pages unless pageId is provided to narrow the results to a single pageId. Returns results for requested time period. Accepts an event class or list of event classes { "eventClass" : "web"|"ios"|["web","ios"] } to return, "web" by default.
pollEvents Returns all poll responses for requested time period. Can be limited by guideId or guideId and pollId.
pollsSeen Returns poll responses in a time period. If visitor has multiple responses to the same poll, only the most recent is returned. Parameter must be { "guideId" : guideId, "pollId" : pollId }
visitors All visitors with their metadata. Parameter may be { "identified" : true } to eliminate anonymous visitors
visitorTags Parameter may be { "tagId" : tagId } to limit results to a single visitorTag. Returns { "visitorId" : visitorId , "visitorTags": { tagId : true , ... }} for each visitor with the requested tag (listing only the requested tag), or if none specified, any currently valid visitorTag (listing all tags on each).

Blacklist Parameter

Definition (page events used as example)

{
    "source": {
        "pageEvents": {
            "pageId": "{pageId}",
            "blacklist": "ignore"
        }
    }
}

Example request

curl -X POST \
  https://app.pendo.io/api/v1/aggregation \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: 63bd1cda-db5a-4a2b-633b-37b8b0c5462c' \
  -d '{"response":{"mimeType":"application/json"},"request":{"pipeline":[{"source":{"pageEvents":{"pageId":"aJ0KOADQZVL5h9zQhiQ0q26PNTM","blacklist":"ignore"},"timeSeries":{"first":"1506977216000","count":-5,"period":"dayRange"}}}]}}'
import requests
url = "https://app.pendo.io/api/v1/aggregation"
data = "{\"response\":{\"mimeType\":\"application/json\"},\"request\":{\"pipeline\":[{\"source\":{\"pageEvents\":{\"pageId\":\"aJ0KOADQZVL5h9zQhiQ0q26PNTM\",\"blacklist\":\"ignore\"},\"timeSeries\":{\"first\":\"1506977216000\",\"count\":-5,\"period\":\"dayRange\"}}}]}}"
headers = {
    'x-pendo-integration-key': "63bd1cda-db5a-4a2b-633b-37b8b0c5462c",
    'content-type': "application/json",
}
response = requests.post(url, data = data, headers = headers)

Example response

{
    "results": [{
            "accountId": "Kappa Trust",
            "visitorId": "59",
            "numEvents": 1,
            "numMinutes": 1,
            "server": "www.pendosandbox.com",
            "remoteIp": "59.89.251.103",
            "parameters": null,
            "userAgent": "Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/61.0.3163.100 Safari/537.36",
            "day": 1506830400000,
            "pageId": "aJ0KOADQZVL5h9zQhiQ0q26PNTM"
        }
    ]
}

All row sources take an optional blacklist parameter in addition to any listed above. For example, on the right you’ll see an example where we examine all of the page events for a particular pageId, ignoring blacklist.

Details
apply Default everywhere, and filters output according to blacklist rules
only Outputs only those rows that match the blacklist
ignore Returns all rows, ignoring the blacklist

Time Series

Example time series for July 10, 2015 through July 12, 2015

{
    "timeSeries": {
        "period": "dayRange",
        "first": 1436553419000,
        "count": 3
    }
}

Example time series for three hours ago to (and including) the current hour.

{
    "timeSeries": {
        "period": "hourRange",
        "first": "now() - 3 * 60*60*1000",
        "last": "now()"
    }
}

The timeSeries consists of the length of each time period and a timestamp for the first period in milliseconds since the epoch. If first is a string it will be evaluated as an expression to derive a timestamp.

It also requires either a count of the number of periods to include in the aggregation or an expression which evaluates to the last time period to include in the aggregation.

Details
period dayRange or hourRange
first The timestamp in milliseconds after the epoch for the start of period.
count Number of periods to include in the aggregation

Full time periods are always evaluated. Even if the first time does not coincide with the beginning of a period, all of the data for the period which contains time first will be used.

For the dayRange period, the day aligns with the time zone for that pendo account. This does mean that there will occasionally by dayRange periods which include 23 or 25 hours of data because of the switch to and from daylight savings time. If this is undesirable, hourRange may be used, though there will be a significant performance impact when large amounts of data are being evaluated.

Events - grouped

The following row sources require a date range (relative or absolute) and period (day or hour). They return a row of data for each unique combination of day/hour, visitorId, accountId, server name, and IP address.

Attributes
events All recorded click and pageview events (tagged or untagged)
featureEvents All recorded click events matching tagged features
pageEvents All recorded pageviews matching tagged pages

The events row source

Definition

{
    "source": {
        "events": null,
        "timeSeries": {
            "first": "{timeInMsOrExpression}",
            "count": "{numberOfPeriods}",
            "period": "{periodName}"
        }
    }
}

Example request

curl -X POST \
  https://app.pendo.io/api/v1/aggregation \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: 63bd1cda-db5a-4a2b-633b-37b8b0c5462c' \
  -d '{"response":{"mimeType":"application/json"},"request":{"pipeline":[{"source":{"events":null,"timeSeries":{"first":"1506977216000","count":-30,"period":"dayRange"}}}]}}'
import requests
url = "https://app.pendo.io/api/v1/aggregation"
data = "{\"response\":{\"mimeType\":\"application/json\"},\"request\":{\"pipeline\":[{\"source\":{\"events\":null,\"timeSeries\":{\"first\":\"1506977216000\",\"count\":-30,\"period\":\"dayRange\"}}}]}}"
headers = {
    'x-pendo-integration-key': "63bd1cda-db5a-4a2b-633b-37b8b0c5462c",
    'content-type': "application/json"
}
response = requests.post(url, data = data, headers = headers)

Example response

{
    "results": [{
        "accountId": "Kappa Trust",
        "visitorId": "59",
        "numEvents": 12,
        "numMinutes": 1,
        "server": "www.pendosandbox.com",
        "remoteIp": "59.89.251.103",
        "parameters": null,
        "userAgent": "Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/61.0.3163.100 Safari/537.36",
        "day": 1506830400000,
        "pageId": "allevents"
    }],
    "startTime": 1504324800000
}
  • Returns a row for each unique combination of day/hour, visitorId, accountId, server name, IP address, and user agent.
  • Encompasses all events, whether tagged or untagged (note the pageId “allevents”)
  • Useful for measuring total time, days active, etc.
  • Optionally pass an eventClass of web or iOS to specify which event bucket to return.

The featureEvents row source

Definition

{
    "source": {
        "featureEvents": {
            "featureId": "{featureId}"
        },
    "timeSeries": {
            "first": "{timeInMsOrExpression}",
            "count": "{numberOfPeriods}",
            "period": "{periodName}"
        }
    }
}

Example request

curl -X POST \
  https://app.pendo.io/api/v1/aggregation \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: 63bd1cda-db5a-4a2b-633b-37b8b0c5462c' \
  -d '{"response":{"mimeType":"application/json"},"request":{"pipeline":[{"source":{"featureEvents":{"featureId":"OFjRasLtgMG8_74hpiXdzVD7PH8"},"timeSeries":{"first":"1506977216000","count":-30,"period":"dayRange"}}}]}}'
import requests
url = "https://app.pendo.io/api/v1/aggregation"
data = "{\"response\":{\"mimeType\":\"application/json\"},\"request\":{\"pipeline\":[{\"source\":{\"featureEvents\":{\"featureId\":\"OFjRasLtgMG8_74hpiXdzVD7PH8\"},\"timeSeries\":{\"first\":\"1506977216000\",\"count\":-30,\"period\":\"dayRange\"}}}]}}"
headers = {
    'x-pendo-integration-key': "63bd1cda-db5a-4a2b-633b-37b8b0c5462c",
    'content-type': "application/json"
}
response = requests.post(url, data = data, headers = headers)

Example response

{
    "results": [{
            "accountId": "Delta Inc",
            "visitorId": "3",
            "numEvents": 1,
            "numMinutes": 1,
            "server": "www.pendosandbox.com",
            "remoteIp": "103.63.15.48",
            "parameters": null,
            "userAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/61.0.3163.100 Safari/537.36",
            "day": 1506571200000,
            "featureId": "OFjRasLtgMG8_74hpiXdzVD7PH8"
        }
    ]
}
  • Includes events which can be matched to tagged feature rules
  • Returns a row for each unique combination of feature ID, day/hour, visitorId, accountId, server name, IP address, and user agent.
  • Accepted parameters are null for all feature data or featureId:FEATURE_ID for a specific feature.
  • Remember expand if you need additional feature data

The pageEvents row source

Definition

{
    "source": {
        "pageEvents": {
            "pageId": "{pageId}"
        },
    "timeSeries": {
            "first": "{timeInMsOrExpression}",
            "count": "{numberOfPeriods}",
            "period": "{periodName}"
        }
    }
}

Example request

curl -X POST \
  https://app.pendo.io/api/v1/aggregation \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: 63bd1cda-db5a-4a2b-633b-37b8b0c5462c' \
  -d '{"response":{"mimeType":"application/json"},"request":{"pipeline":[{"source":{"pageEvents":{"pageId":"aJ0KOADQZVL5h9zQhiQ0q26PNTM"},"timeSeries":{"first":"1506977216000","count":-30,"period":"dayRange"}}}]}}'
import requests
url = "https://app.pendo.io/api/v1/aggregation"
data = "{\"response\":{\"mimeType\":\"application/json\"},\"request\":{\"pipeline\":[{\"source\":{\"pageEvents\":{\"pageId\":\"aJ0KOADQZVL5h9zQhiQ0q26PNTM\"},\"timeSeries\":{\"first\":\"1506977216000\",\"count\":-30,\"period\":\"dayRange\"}}}]}}"
headers = {
    'x-pendo-integration-key': "63bd1cda-db5a-4a2b-633b-37b8b0c5462c",
    'content-type': "application/json"
}
response = requests.post(url, data = data, headers = headers)

Example response

{
    "results": [{
            "accountId": "Acme Corp",
            "visitorId": "10",
            "numEvents": 1,
            "numMinutes": 1,
            "server": "www.pendosandbox.com",
            "remoteIp": "110.227.245.175",
            "parameters": null,
            "userAgent": "Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.113 Safari/537.36",
            "day": 1506484800000,
            "pageId": "aJ0KOADQZVL5h9zQhiQ0q26PNTM"
        }
    ]
}
  • Includes events which can be matched to tagged page rules
  • Returns a row for each unique combination of page ID, day/hour, visitorId, accountId, server name, IP address, and user agent.
  • Accepted parameters are null for all page data or pageId:PAGE_ID for a specific page.
  • Remember expand if you need additional page data

Events - ungrouped

For some events, we expose ungrouped events. These are visible for a specified time period.

Sources
guideEvents Interactions your visitors have with guides
guidesSeen Summary of when visitors see guides
guidesSeenEver Summary of when visitors see guides
pollEvents Interactions your visitors have with polls
pollsSeen Summary of when and how visitors respond to polls
pollsSeenEver Summary of when and how visitors respond to polls

The guideEvents row source

Definition

{
    "source": {
        "guideEvents": null,
    "timeSeries": {
            "first": "{timeInMsOrExpression}",
            "count": "{numberOfPeriods}",
            "period": "{periodName}"
        }
    }
}

Example request

curl -X POST \
  https://app.pendo.io/api/v1/aggregation \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: 63bd1cda-db5a-4a2b-633b-37b8b0c5462c' \
  -d '{"response":{"mimeType":"application/json"},"request":{"pipeline":[{"source":{"guideEvents":null,"timeSeries":{"first":"1506977216000","count":-10,"period":"dayRange"}}}]}}'
import requests
url = "https://app.pendo.io/api/v1/aggregation"
data = "{\"response\":{\"mimeType\":\"application/json\"},\"request\":{\"pipeline\":[{\"source\":{\"guideEvents\":null,\"timeSeries\":{\"first\":\"1506977216000\",\"count\":-10,\"period\":\"dayRange\"}}}]}}"
headers = {
    'x-pendo-integration-key': "63bd1cda-db5a-4a2b-633b-37b8b0c5462c",
    'content-type': "application/json"
}
response = requests.post(url, data = data, headers = headers)

Example response

{
    "accountIds": [
        "Acme"
    ],
    "browserTime": 1462796392383,
    "country": "US",
    "type": "guideAdvanced",
    "guideId": "He3BLNt44i0xwO5AEJVIijEswro",
    "guideStepId": "4TaMV6TLY1JmKIFkprqOcQllU8k",
    "latitude": 35.823483,
    "loadTime": 0,
    "longitude": -78.825562,
    "region": "nc",
    "remoteIp": "209.136.209.34",
    "serverName": "your.app.com",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/601.5.17 (KHTML, like Gecko) Version/9.1 Safari/601.5.17",
    "visitorId": "johndoe@acme.com",
    "accountId": "Acme"
}
  • Returns one event row for every guide event that occurs. This is not a summary or bucket structure like previous examples.
  • Type field values include guideAdvanced, guideSeen, and guideDismissed
  • Accepted parameters include guideId and guideStepId to drill down into a specific guide or step.
  • pollEvents behaves similiarly and provides one row for every poll response that occurs. You can specify pollId as a parameter to that source.

The guideSeen row source

Definition

{
    "source": {
        "guidesSeen": {
            "guideId": "{guideId}",
            "guideStepId": "{guideStepId}"
        },
    "timeSeries": {
            "first": "{timeInMsOrExpression}",
            "count": "{numberOfPeriods}",
            "period": "{periodName}"
        }
    }
}

Exmaple request

curl -X POST \
  https://app.pendo.io/api/v1/aggregation \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: 63bd1cda-db5a-4a2b-633b-37b8b0c5462c' \
  -d '{"response":{"mimeType":"application/json"},"request":{"pipeline":[{"source":{"guidesSeen":{"guideId":"nWtgylnMqWeB4DynO5duF9ako-M","guideStepId":"mHO55y6WJvJ0CnsmUgAtiGtgobA"},"timeSeries":{"first":"1506977216000","count":-10,"period":"dayRange"}}}]}}'
import requests
url = "https://app.pendo.io/api/v1/aggregation"
data = "{\"response\":{\"mimeType\":\"application/json\"},\"request\":{\"pipeline\":[{\"source\":{\"guidesSeen\":{\"guideId\":\"nWtgylnMqWeB4DynO5duF9ako-M\",\"guideStepId\":\"mHO55y6WJvJ0CnsmUgAtiGtgobA\"},\"timeSeries\":{\"first\":\"1506977216000\",\"count\":-10,\"period\":\"dayRange\"}}}]}}"
headers = {
    'x-pendo-integration-key': "63bd1cda-db5a-4a2b-633b-37b8b0c5462c",
    'content-type': "application/json"
}
response = requests.post(url, data = data, headers = headers)

Example response

{
    "firstSeenAt": 1489673759222,
    "guideId": "nWtgylnMqWeB4DynO5duF9ako-M",
    "guideStepId": "mHO55y6WJvJ0CnsmUgAtiGtgobA",
    "lastAdvancedAutoAt": 0,
    "lastDismissedAutoAt": 0,
    "lastSeenAt": 1489674347693,
    "lastState": "advanced",
    "seenCount": 5,
    "visitorId": "avery"
}
  • Returns a row for each unique combination of Visitor ID, guide ID, and step ID
  • You can additionally supply guideId and guideStepId to drill into a specific guide or step.
  • The guidesSeenEver row source can also be used for the same output, but is time insensitive and does not require a timeSeries.

The pollEvents row source

Definition

{
    "source": {
        "pollEvents": null,
    "timeSeries": {
            "first": "{timeInMsOrExpression}",
            "count": "{numberOfPeriods}",
            "period": "{periodName}"
        }
    }
}

Example request

curl -X POST \
  https://app.pendo.io/api/v1/aggregation \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: 63bd1cda-db5a-4a2b-633b-37b8b0c5462c' \
  -d '{"response":{"mimeType":"application/json"},"request":{"pipeline":[{"source":{"pollEvents":null,"timeSeries":{"first":"1506977216000","count":-10,"period":"dayRange"}}}]}}'
import requests
url = "https://app.pendo.io/api/v1/aggregation"
data = "{\"response\":{\"mimeType\":\"application/json\"},\"request\":{\"pipeline\":[{\"source\":{\"pollEvents\":null,\"timeSeries\":{\"first\":\"1506977216000\",\"count\":-10,\"period\":\"dayRange\"}}}]}}"
headers = {
    'x-pendo-integration-key': "63bd1cda-db5a-4a2b-633b-37b8b0c5462c",
    'content-type': "application/json"
}
response = requests.post(url, data = data, headers = headers)

Example response

{
    "accountIds": [
        "Acme"
    ],
    "browserTime": 1462796392383,
    "country": "US",
    "type": "pollResponse",
    "guideId": "He3BLNt44i0xwO5A201IijEswro",
    "latitude": 35.823483,
    "loadTime": 0,
    "longitude": -78.825562,
    "pollId": "z7y94y62v3c",
    "region": "nc",
    "remoteIp": "209.136.209.34",
    "serverName": "your.app.com",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/61.0.3163.100 Safari/537.36",
    "visitorId": "user@acme.com",
    "accountId": "Acme",
    "pollResponse": "You guys rock!"
}
  • Returns one row for every poll response that occurs.
  • Accepted parameters include guideId and pollId to drill down into a specific poll.

The pollsSeen row source

Definition

{
    "source": {
        "pollsSeen": {
            "guideId": "{guideId}",
            "pollId": "{pollId}"
        },
    "timeSeries": {
            "first": "{timeInMsOrExpression}",
            "count": "{numberOfPeriods}",
            "period": "{periodName}"
        }
    }
}

Example request

curl -X POST \
  https://app.pendo.io/api/v1/aggregation \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: 63bd1cda-db5a-4a2b-633b-37b8b0c5462c' \
  -d '{"response":{"mimeType":"application/json"},"request":{"pipeline":[{"source":{"pollsSeen":{"guideId":"1wz09ZEAFp-HVl78Iw8oxpwbRZA","pollId":"3isny1qp7t2"},"timeSeries":{"first":"1506977216000","count":-10,"period":"dayRange"}}}]}}'
import requests
url = "https://app.pendo.io/api/v1/aggregation"
data = "{\"response\":{\"mimeType\":\"application/json\"},\"request\":{\"pipeline\":[{\"source\":{\"pollsSeen\":{\"guideId\":\"1wz09ZEAFp-HVl78Iw8oxpwbRZA\",\"pollId\":\"3isny1qp7t2\"},\"timeSeries\":{\"first\":\"1506977216000\",\"count\":-10,\"period\":\"dayRange\"}}}]}}"
headers = {
    'x-pendo-integration-key': "63bd1cda-db5a-4a2b-633b-37b8b0c5462c",
    'content-type': "application/json"
}
response = requests.post(url, data = data, headers = headers)

Example response

{
    "accountId": "1",
    "guideId": "1wz09ZEAFp-HVl78Iw8oxpwbRZA",
    "pollId": "3isny1qp7t2",
    "response": 0,
    "time": 1500305598629,
    "visitorId": "1"
}
  • Returns poll responses in a time period
  • Only the most recent poll response for a visitor is displayed i.e. if a visitor has responded to the same poll multiple times, pollsSeen will only return most recent response. To return all responses, use pollEvents.
  • You must supply guideId and pollId as parameters to drill into specific poll events
  • The pollsSeenEver row source can also be used for the same output, but is time insensitive and does not require a timeSeries.

Entities

Entities are the nouns of Pendo. They appear in the left-nav of our UI.

Entities
accounts The accounts your users belong to (in most cases your customers)
features Sets of rules that identify individual product features (defined by a DOM rule)
guides In-app messages you show your visitors
pages Sets of rules that identify individual pages in your product (defined by a URL rule)
visitors Your product’s users (including internal users who access customer accounts)

The accounts row source

Definition syntax

{
    "source": {
        "accounts": null
    }
}

Example request

curl -X POST \
  https://app.pendo.io/api/v1/aggregation \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: 63bd1cda-db5a-4a2b-633b-37b8b0c5462c' \
  -d '{"response":{"mimeType":"application/json"},"request":{"pipeline":[{"source":{"accounts":null}}]}}'
import requests
url = "https://app.pendo.io/api/v1/aggregation"
data = "{\"response\":{\"mimeType\":\"application/json\"},\"request\":{\"pipeline\":[{\"source\":{\"accounts\":null}}]}}"
headers = {
    'x-pendo-integration-key': "63bd1cda-db5a-4a2b-633b-37b8b0c5462c",
    'content-type': "application/json"
}
response = requests.post(url, data = data, headers = headers)

Example response

{
    "results": [{
            "accountId": "Iota Partners",
            "metadata": {
                "agent": {},
                "auto": {
                    "firstvisit": 1506520495929,
                    "id": "Iota Partners",
                    "idhash": 3996782207,
                    "lastupdated": 1506969364496,
                    "lastvisit": 1506969364036
                }
            }
        }
    ]
}

The accounts source is the analogue of the visitors source. It returns one row per account ever seen and has various metadata on the account. Each account has a unique accountId defined by you through the installation snippet.

For customers using subaccounts, only the subaccounts are returned unless { "parentAccounts" : true } is specified as a parameter, in which case only the parent accounts are returned.

Definition using expand

[{
        "source": {
            "accounts": null
        }

    },
    {
        "expand": {
            "account": {
                "account": "accountId"
            }
        }
    }
]

Account data can also be accessed using the expand pipeline map operator. This is handy for including account data when using other sources (e.g. featureEvents and pageEvents sources).

The features row source

Definition

{
    "source": {
        "features": null
    }
}

Example request

curl -X POST \
  https://app.pendo.io/api/v1/aggregation \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: 63bd1cda-db5a-4a2b-633b-37b8b0c5462c' \
  -d '{"response":{"mimeType":"application/json"},"request":{"pipeline":[{"source":{"features":null}}]}}'
import requests
url = "https://app.pendo.io/api/v1/aggregation"
data = "{\"response\":{\"mimeType\":\"application/json\"},\"request\":{\"pipeline\":[{\"source\":{\"features\":null}}]}}"
headers = {
    'x-pendo-integration-key': "63bd1cda-db5a-4a2b-633b-37b8b0c5462c",
    'content-type': "application/json"
}
response = requests.post(url, data = data, headers = headers)

Example response

{
    "results": [{
            "color": "gray",
            "createdAt": 1505938327432,
            "createdByUser": {
                "first": "Adam",
                "id": "5197072786522112",
                "last": "Lohner",
                "role": 8,
                "username": "adamlohner@pendo.io"
            },
            "dirty": false,
            "elementPathRules": [
                "a:contains('Data Presentation')"
            ],
            "group": {
                "color": ".groupColor01",
                "createdAt": 1505937447295,
                "createdByUser": {
                    "first": "",
                    "id": "",
                    "last": "",
                    "role": 0,
                    "username": ""
                },
                "description": "",
                "id": "_PENDO_DEFAULTGROUP_01_",
                "items": [],
                "lastUpdatedAt": 1505938327653,
                "lastUpdatedByUser": {
                    "first": "Adam",
                    "id": "5197072786522112",
                    "last": "Lohner",
                    "role": 8,
                    "username": "adamlohner@pendo.io"
                },
                "length": 6,
                "name": "Dashboard"
            },
            "id": "UB9RTn0B9esKqPW_NcfB25n3QAc",
            "kind": "Feature",
            "lastUpdatedAt": 1505938327432,
            "lastUpdatedByUser": {
                "first": "Adam",
                "id": "5197072786522112",
                "last": "Lohner",
                "role": 8,
                "username": "adamlohner@pendo.io"
            },
            "name": "Data Presentation Toggle Dropdown",
            "pageId": "aJ0KOADQZVL5h9zQhiQ0q26PNTM",
            "rootVersionId": "UB9RTn0B9esKqPW_NcfB25n3QAc",
            "stableVersionId": "UB9RTn0B9esKqPW_NcfB25n3QAc-20170920201207.432160413",
            "validThrough": 1506974400000
        }
    ]
}

Tagged features. Returns one row for each tagged feature.

Definition using expand

[{
        "source": {
            "accounts": null
        }

    },
  {
    "expand": {
      "feature": {
        "feature": "featureId"
      }
    }
  }
]

Although features can be accessed directly as a source, for convenience we recommend accessing feature entity data using the expand pipeline map operator. This is handy for including additional feature data when using other sources (like featureEvents).

The guides row source

Definition

{
    "source": {
        "guides": null
    }
}

Example request

curl -X POST \
  https://app.pendo.io/api/v1/aggregation \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: 63bd1cda-db5a-4a2b-633b-37b8b0c5462c' \
  -d '{"response":{"mimeType":"application/json"},"request":{"pipeline":[{"source":{"guides":null}}]}}'
import requests
url = "https://app.pendo.io/api/v1/aggregation"
data = "{\"response\":{\"mimeType\":\"application/json\"},\"request\":{\"pipeline\":[{\"source\":{\"guides\":null}}]}}"
headers = {
    'x-pendo-integration-key': "63bd1cda-db5a-4a2b-633b-37b8b0c5462c",
    'content-type': "application/json"
}
response = requests.post(url, data = data, headers = headers)

Example response

{
    "attributes": { ... },
    "audience": [ ... ],
    "createdAt": 1440449676899,
    "createdByUser": {
        "first": "Someone",
        "id": "5269565705551872",
        "last": "Lastname",
        "role": 8,
        "username": "someone@yourcompany.com"
    },
    "expiresAfter": 1440472740000,
    "id": "BF_p40WvYWC2o81pvsdt1kjcIkI",
    "isMultiStep": false,
    "lastUpdatedAt": 1460734696429,
    "lastUpdatedByUser": {
        "first": "",
        "id": "4985730428305408",
        "last": "",
        "role": 8,
        "username": "someone@yourcompany.com"
    },
    "launchMethod": "auto",
    "name": "2015-08-24 - Maintenance tonight.",
    "state": "disabled",
    "stateHistory": [ ... ],
    "steps": [{
        "advanceMethod": "button",
        "attributes": {
            "height": 395,
            "width": 440
        },
        "content": "",
        "createdByUser": {
            "first": "Someone",
            "id": "5269565705551872",
            "last": "Lastname",
            "role": 8,
            "username": "someone@yourcompany.com"
        },
        "elementPathRule": "",
        "guideId": "BF_p40WvYWC2o81pvsdt1kjcIkI",
        "id": "Itfe6aDRNtgx9J1XisQwaCxDS-A",
        "lastUpdatedAt": 1460734696429,
        "lastUpdatedByUser": {
            "first": "",
            "id": "4985730428305408",
            "last": "",
            "role": 8,
            "username": "someone@yourcompany.com"
        },
        "name": "",
        "rank": 5000000,
        "resetAt": 0,
        "thumbnailUrls": [
            "https://storage.googleapis.com/pendo-static-5668600916475904/b4fab315-ab24-4e95-6ffe-fcbb19267fdd"
        ],
        "type": "lightbox"
    }]
}

steps include a single item for lightboxes, tooltips, banners, etc. and multiple items for walkthroughs.

The pages row source

Definition

{
    "source": {
        "pages": null
    }
}

Example request

curl -X POST \
  https://app.pendo.io/api/v1/aggregation \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: 63bd1cda-db5a-4a2b-633b-37b8b0c5462c' \
  -d '{"response":{"mimeType":"application/json"},"request":{"pipeline":[{"source":{"pages":null}}]}}'
import requests
url = "https://app.pendo.io/api/v1/aggregation"
data = "{\"response\":{\"mimeType\":\"application/json\"},\"request\":{\"pipeline\":[{\"source\":{\"pages\":null}}]}}"
headers = {
    'x-pendo-integration-key': "63bd1cda-db5a-4a2b-633b-37b8b0c5462c",
    'content-type': "application/json"
}
response = requests.post(url, data = data, headers = headers)

Example response

{
    "results": [{
        "color": "gray",
        "createdAt": 1505938241596,
        "createdByUser": {
            "first": "Adam",
            "id": "5197072786522112",
            "last": "Lohner",
            "role": 8,
            "username": "adamlohner@pendo.io"
        },
        "dirty": false,
        "group": {
            "color": ".groupColor01",
            "createdAt": 1505937447295,
            "createdByUser": {
                "first": "",
                "id": "",
                "last": "",
                "role": 0,
                "username": ""
            },
            "description": "",
            "id": "_PENDO_DEFAULTGROUP_01_",
            "items": [],
            "lastUpdatedAt": 1505938327653,
            "lastUpdatedByUser": {
                "first": "Adam",
                "id": "5197072786522112",
                "last": "Lohner",
                "role": 8,
                "username": "adamlohner@pendo.io"
            },
            "length": 6,
            "name": "Dashboard"
        },
        "id": "aJ0KOADQZVL5h9zQhiQ0q26PNTM",
        "kind": "Page",
        "lastUpdatedAt": 1505938241596,
        "lastUpdatedByUser": {
            "first": "Adam",
            "id": "5197072786522112",
            "last": "Lohner",
            "role": 8,
            "username": "adamlohner@pendo.io"
        },
        "name": "Dashboard",
        "rootVersionId": "aJ0KOADQZVL5h9zQhiQ0q26PNTM",
        "rules": [{
            "designerHint": "http://pendosandbox.com/",
            "parsedRule": "^https?://[^/]*/?(?:;[^#]*)?(?:\\?[^#]*)?(?:#.*)?$",
            "rule": "//*"
        }],
        "rulesjson": "",
        "stableVersionId": "aJ0KOADQZVL5h9zQhiQ0q26PNTM-20170920201041.596687476",
        "validThrough": 1506981600000
    }]
}

Tagged features. Returns one row for each tagged feature.

Definition using expand

[{
        "source": {
            "pages": null
        }
    },
    {
        "expand": {
            "page": {
                "page": "pageId"
            }
        }
    }
]

Although pages can be accessed directly as a source, for convenience we recommend accessing page entity data using the expand pipeline map operator. This is handy for including page data when using other sources (like pageEvents).

Visitors

Definition

{
    "source": {
        "visitors": null
    }
}

Example request

curl -X POST \
  https://app.pendo.io/api/v1/aggregation \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: 63bd1cda-db5a-4a2b-633b-37b8b0c5462c' \
  -d '{"response":{"mimeType":"application/json"},"request":{"pipeline":[{"source":{"visitors":null}}]}}'
import requests
url = "https://app.pendo.io/api/v1/aggregation"
data = "{\"response\":{\"mimeType\":\"application/json\"},\"request\":{\"pipeline\":[{\"source\":{\"visitors\":null}}]}}"
headers = {
    'x-pendo-integration-key': "63bd1cda-db5a-4a2b-633b-37b8b0c5462c",
    'content-type': "application/json"
}
response = requests.post(url, data = data, headers = headers)

Example response

{
    "results": [{
        "metadata": {
            "agent": {
                "email": "ac@Cras.co.uk",
                "ipaddress": "184.169.45.4",
                "language": "en_US"
            },
            "auto": {
                "accountid": "Epsilon united",
                "accountids": [
                    "Epsilon united"
                ],
                "firstvisit": 1506965912312,
                "id": "84",
                "idhash": 2012371633,
                "lastbrowsername": "Chrome",
                "lastbrowserversion": "61.0.3163",
                "lastoperatingsystem": "Mac OS X",
                "lastservername": "pendosandbox.com",
                "lastupdated": 1506976690418,
                "lastuseragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/61.0.3163.100 Safari/537.36",
                "lastvisit": 1506976690112,
                "nid": 84
            }
        },
        "visitorId": "84"
    }]
}

The visitors source returns one row per visitor ever seen and contains various metadata about the visitor. Each visitor has a unique visitorId that is defined by you and passed to Pendo through your installation snippet.

A visitor may be identified (a visitor ID is passed through the installation snippet) or anonymous (an ID is not passed to Pendo so we generate one for the visitor that is prepended with _PENDO_T_).

Accepted parameters are null or {"identified":true} to eliminate anonymous visitors.

Metadata
agent data supplied by the Pendo javascript widget
auto data automatically calculated, and summarized by Pendo
custom custom field data
salesforce data synced from Salesforce
segment data synced from Segment

Definition using expand

[{
        "source": {
            "pages": null
        }
    },
    {
        "expand": {
            "visitor": {
                "visitor": "visitorId"
            }
        }
    }
]

Visitor data can also be accessed using the expand pipeline map operator. This is handy for including visitor data when using other sources (e.g. featureEvents and pageEvents sources).

Pipeline

Example sytnax #1

{
    "cat": null
}

Example sytnax #2

{
    "field": "firstName",
    "operator": "==",
    "value": "John"
}

Each step is of the form { "name" : parameterObject }.

The source rows are transformed into result rows by the pipeline; the final rows are the result of the aggregation step. Pipelines can be arbitrarily long, and are represented as an ordered list of individual steps.

Operators

Operators
cat Takes no parameters, and returns each row without changing it.
count Counts the number of input rows and returns a single row of the form { "count" : 456 }
accumulate Keeps a running total of more than one field, and includes the current value of the total in each row. Parameters are of the forum { "totalField1" : "sourceField1" }
eval Inserts new fields based on one or more expressions. Format is an { "fieldName1" : "expression" }
identified Eliminates rows whose named field looks like an anonymous visitorId { "identified" : "visitorId" } where visitorId is the field name to check.
limit Returns the first N rows and discards the rest { "limit" : 5 }
select Builds a new row (while discarding the old one) containing one or more fields. Format is an { "fieldName1" : "expression" }
set Sets fields to constant values { "set" : { "field1" : 5, "field2.nested" : 20 } }
sort Sorts the rows by the specified field list { "sort" : [ "fieldName", "anotherFieldName" ] } Prepend a - to the front of a field name to reverse sort by that field.
unmarshal Expands an embedded JSON string into sub-objects.
useragent Expands a user agent string into a parsed set of strings.

The spawn operation

Definition

{
    "spawn": [
        [{
                "source": {
                    "events": null,
                    "timeSeries ": {
                        "period": "dayRange",
                        "first": 1404745200000,
                        "count": 7
                    }
                }
            },
            {
                "cat": null
            }
        ],
        [{
                "source": {
                    "events": null,
                    "timeSeries ": {
                        "period": "month",
                        "first": 1404745200000,
                        "count": 7
                    }
                }
            },
            {
                "count": null
            }
        ]
    ]
}

The spawn operator behaves like form, but each nested pipeline must specify its own source. This allows multiple sources to be used to create a single stream of rows which are processed by the remainder of the pipe.

Only sources which cause a single pipeline to be instantiated may be used; this means dayRange, hourRange, or any source whose count is 1 is available.

The timeSeries for the source is part of the source specification for the spawn pipeline.

The switch operation

Definition

{
    "switch": {
        "newField": {
            "existingField": [{
                    "value": "small",
                    "<": 10
                },
                {
                    "value": "medium",
                    ">=": 10,
                    "<": 20
                },
                {
                    "value": "large",
                    ">=": 20,
                    "<": 50
                }
            ]
        }
    }
}

The switch operation allows a field to checked against any number of conditions, and have a new field set in the row based on which condition the original field matches.

For each row the existingField will be checked to see which set of conditions its value matches.

It must match all of the conditions for newField to be set to the value indicated. If no conditions match, or if existingField is not set at all, the row is skipped.

For the above input, the row { "existingField" : 15 } will become { "existingField" : 15, "newField" : "medium" }

The filter operation

Definition

{
    "filter": "fieldName == 5 || len(anotherField) > 3"
}

The filter pipeline operator evaluates an expression and eliminates rows that for which the expression is false.

The fork operation

The following calculates the total time for each accountId and visitorId

{
    "fork": [
        [{
            "group": {
                "group": [
                    "visitorId"
                ],
                "fields": [{
                    "time": {
                        "sum": "numMinutes"
                    }
                }]
            }
        }],
        [{
            "group": {
                "group": [
                    "accountId"
                ],
                "fields": [{
                    "time": {
                        "sum": "numMinutes"
                    }
                }]
            }
        }]
    ]
}

The fork operator allows the pipeline to be split into multiple pipelines, with each of the child pipelines receiving all of the rows for that step.

Note that the same row is sent to all of the child pipelines; it is not a copy of the row and any changes to the row made in one pipeline will be visible in all pipelines.

The rows which result from each pipeline are all sent through the remainder of the parent pipeline. Forks may be nested, however this has not been well-tested (aka - no promises).

Empty pipelines (which would pass through the rows without modifying them) are not permitted, but a pipeline with a single cat operation performs identically.

The join operation

Definition

{
    "join": {
        "fields": [
            "firstName",
            "lastNme"
        ],
        "width": 3
    }
}

The join operator merges multiple rows together based on one or more keys. If there are field conflicts, the values from rows encountered later in the join will win. The optional width argument allows the user to tell join how many rows are expected to make up the final result. Once that many rows with the same join key have been seen, the merged row is passed to the next operation in the pipeline. If more rows are later seen with that join key, they are treated as a new join operation. Any join keys which have had less than width rows are processed once all input rows have been seen.

The group operation

Example request to calculate how much time each identified visitor has spent on the site over 30 days

{
    "requestId": "last30daysVisitorTime",
    "timeSeries": {
        "period": "dayRange",
        "count": 30,
        "first": 1404745200000
    },
    "source": {
        "events": null
    },
    "pipeline": [{
            "identified": "visitorId"
        },
        {
            "group": {
                "group": [
                    "visitorId"
                ],
                "fields": [{
                    "minutes": {
                        "sum": "numMinutes"
                    }
                }]
            }
        }
    ]
}

NOTE: The count value of 180 has to be a long enough period to cover the entire time the guide has been in existence.

The group operator supports flexible grouping (similar to GROUP BY in SQL) and simple aggregations of fields. It supports the following parameters:

Parameters
group List of fields whose values match in each grouping
fields Set of fields whose values are aggregated across the group
stringSort Result rows will be sorted by the group key. The group key is treated as a string for sort purposes (so "2" > "10"). This provides a stable ordering for the result.

Each resulting row consists of all of the fields specified by both the group and fields specification.

Aggregation fields consist of field name to use in the output row, an aggregation name, and a field name from the input row. For example, to count the rows in a group use { "outputField" : { "count" : "inputField" } } will count the number of rows which match (here the field name must be specified, but is irrelevant). The following row aggregators are supported:

Aggregators
count Counts the number of rows in the group. If a field name is it counts the unique occurrences of that field.
listAverage Average the individual values in a list arguement and return a list of those averages.
max Returns the largest value of the specified (numeric) field.
min Returns the smallest value of the specified (numeric) field.
sum Adds up the values of the specified field.
first Returns the first value of the specified field (note: "first" is only defined as deterministically as the input order is).

Count the number of unique visitorIds use the following pipeline:

[{
        "group": {
            "group": [
                "visitorId"
            ]
        }
    },
    {
        "visitorCount": {
            "count": null
        }
    }
]

To get the number of events for each visitorIduse:

[{
    "group": {
        "group": [
            "visitorId"
        ],
        "fields": {
            "eventCount": {
                "count": "event"
            }
        }
    }
}]

The reduce operation

Count the number of rows and add up the minutes fields in the rows:

[{
    "reduce": {
        "eventCount": {
            "count": null
        },
        "totalMinutes": {
            "sum": "numMinutes"
        }
    }
}]

The reduce operator collects all rows into a single row, and performs aggregations on fields. The aggregators and format are identical to the fields parameter for the group pipeline operation.

Example request to calculate the total number of events and the total number of minutes for a thirty day period.

{
    "requestId": "last30DaysEventAndMinuteTotals",
    "timeSeries": {
        "period": "dayRange",
        "count": 30,
        "first": 1404745200000
    },
    "source": {
        "events": null
    },
    "pipeline": [{
        "reduce": [{
                "events": {
                    "sum": "numEvents"
                }
            },
            {
                "minutes": {
                    "sum": "numMinutes"
                }
            }
        ]
    }]
}

Count the number of unique visitors and accounts in a dataset

{
    "requestId": "numberOfUniqueAccountsAndVisitors",
    "timeSeries": {
        "period": "dayRange",
        "count": 30,
        "first": 1404745200000
    },
    "source": {
        "events": null
    },
    "pipeline": [{
        "reduce": [{
            "reduce": {
                "visitors": {
                    "count": "visitorId"
                },
                "accounts": {
                    "count": "accountId"
                }
            }
        }]
    }]
}

Example request using group and reduce to count the number of visitors in a set of events and the total number of minutes used by those visitor:

{
    "requestId": "lastDaysEventAndMinuteTotals",
    "timeSeries": {
        "period": "dayRange",
        "count": 30,
        "first": 1404745200000
    },
    "source": {
        "events": null
    },
    "pipeline": [{
        "group": {
            "group": [
                "visitorId"
            ],
            "fields": {
                "visitorMinutes": {
                    "sum": "numMinutes"
                }
            }
        },
        "reduce": {
            "visitorCount": {
                "count": "numVisitors"
            },
            "totalMinutes": {
                "sum": "visitorMinutes"
            }
        }
    }]
}

The segment operation

Definition

{
    "segment": {
        "id": "id"
    }
}

Segments are used to preselect groups of visitors or accounts. Preexisting segments filter rows via the segment operator.

An input row is passed if the accountId and visitorId in the input row match an item in the segment. Some segments may specify only visitors or accounts; in those cases the segment operator will only match against the appropriate field from the input row.

The expand operation

Expand visitors into a subdocument called info

{
    "expand": {
        "info": {
            "visitor": "visitorId"
        }
    }
}

NOTE: The implementation of expand is not well optimized and should not be used for large numbers of expansions. See bulkExpand below. The expand operator does as its name implies - it expands fields into subdocuments based on an id. The step is of the following form: { expand : { outputFieldName : { dataType : idFieldName } } }.

The following data types support expand: page, feature, account, and visitor.

The bulkExpand operation

The bulkExpand operator behaves identically to expand, but is optimized for large numbers of visitors and accounts.

The following data types support expand: account and visitor.

The unwind operation

To unwind the following:

{
    "name": "fred",
    "items": [{
            "v": "first"
        },
        {
            "v": "second"
        },
        {
            "v": "third"
        }
    ]
}

Try:

{
    "unwind": {
        "field": "items",
        "index": "itemIndex"
    }
}

Response would yield:

{
    "name": "fred",
    "items": {
        "v": "first"
    },
    "itemIndex": 0
} {
    "name": "fred",
    "items": {
        "v": "second"
    },
    "itemIndex": 1
} {
    "name": "fred",
    "items": {
        "v": "third"
    },
    "itemIndex": 2
}

The unwind operator expands a list of items into separate rows. All other items are preserved, and an index may optionally be added.

Add "prefix" : true and you will get:

[{
    "name": "fred",
    "items": [{
        "v": "first"
    }],
    "itemIndex": 0
}, {
    "name": "fred",
    "items": [{
        "v": "first"
    }, {
        "v": "second"
    }],
    "itemIndex": 1
}, {
    "name": "fred",
    "items": [{
        "v": "first"
    }, {
        "v": "second"
    }, {
        "v": "third"
    }],
    "itemIndex": 2
}]

Alternatively, if everything to the left of each items is important, unwind can preserve those items.

If the list to unwind is empty then no rows will be emitted unless { "keepEmpty" : true } is specified, in which case the original row will be preserved.

The useragent operation

Definition

{
    "useragent": {
        "output": "input"
    }
}

The useragent operation parses the user agent string in the field input and renders it into a object in output.

Output
name the browser’s name (e.g. "MSIE", "Chrome", etc.)
version the version of the browser
os the operating system (e.g. "Windows", "Mac OS X", "GNU/Linux", etc.)
type the type of user agent (e.g. "Browser", "Crawler", etc.)

Feature

Feature endpoint

https://app.pendo.io/api/v1/feature

The {featureId} referenced below can be found at the end of the URL when viewing details for a specific feature within the app. You can view a comprehensive list of all tagged features here.

The feature object

Example response

[{
        "createdByUser": {
            "id": "5197072786522112",
            "username": "adamlohner@pendo.io",
            "first": "Adam",
            "last": "Lohner",
            "role": 8
        },
        "createdAt": 1505938327432,
        "lastUpdatedByUser": {
            "id": "5197072786522112",
            "username": "adamlohner@pendo.io",
            "first": "Adam",
            "last": "Lohner",
            "role": 8
        },
        "lastUpdatedAt": 1505938327432,
        "kind": "Feature",
        "rootVersionId": "UB9RTn0B9esKqPW_NcfB25n3QAc",
        "stableVersionId": "UB9RTn0B9esKqPW_NcfB25n3QAc-20170920201207.432160413",
        "id": "UB9RTn0B9esKqPW_NcfB25n3QAc",
        "name": "Data Presentation Toggle Dropdown",
        "color": "gray",
        "group": {
            "id": "_PENDO_DEFAULTGROUP_01_",
            "name": "Dashboard",
            "description": "",
            "color": ".groupColor01",
            "length": 6,
            "items": [],
            "createdByUser": {
                "id": "",
                "username": "",
                "first": "",
                "last": "",
                "role": 0
            },
            "createdAt": 1505937447295,
            "lastUpdatedByUser": {
                "id": "5197072786522112",
                "username": "adamlohner@pendo.io",
                "first": "Adam",
                "last": "Lohner",
                "role": 8
            },
            "lastUpdatedAt": 1505938327653
        },
        "dirty": false,
        "pageId": "aJ0KOADQZVL5h9zQhiQ0q26PNTM",
        "elementPathRules": [
            "a:contains('Data Presentation')"
        ]
    },
    { feature #2 ... },
    { feature #3 ... }
]
Attributes
createdByUser
user
The user that created the feature.
createdAt
timestamp
The timestamp in milliseconds after the epoch when the feature was created.
lastUpdatedByUser
user
The user that last updated the feature.
lastUpdatedAt
timestamp
The timestamp in milliseconds after the epoch when the feature was last updated.
kind
string
Returns the type of object. Feature for example.
rootVersionId
string
The unique identifier of the root entity, which nominally matches the public id field of the feature.
stableVersionId
string
The unique identifier for the current version of the feature.
id
string
The unique identifier for the feature.
name
string
Display name for the feature.
color
string
Color value associated with the Feature. For visualization in Paths and Funnels.
group
array[object]
Object containing information related to associated group for the feature.
dirty
boolean
Boolean value returned if feature is processing at the time of request.
elementPathRules
array[object]
The element path that indicates where the feature can be found (blank if not applicable).

Return list of all features

Definition

GET https://app.pendo.io/api/v1/feature
requests.get('https://app.pendo.io/api/v1/feature')

Example request

curl -X GET \
  https://app.pendo.io/api/v1/feature \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: 63bd1cda-db5a-4a2b-633b-37b8b0c5462c'
import requests
headers = {
    'content-type': 'application/json',
    'x-pendo-integration-key': '63bd1cda-db5a-4a2b-633b-37b8b0c5462c',
}
requests.get('https://app.pendo.io/api/v1/feature', headers = headers)

Example response

[{
        "createdByUser": {
            "id": "5197072786522112",
            "username": "adamlohner@pendo.io",
            "first": "Adam",
            "last": "Lohner",
            "role": 8
        },
        "createdAt": 1505938327432,
        "lastUpdatedByUser": {
            "id": "5197072786522112",
            "username": "adamlohner@pendo.io",
            "first": "Adam",
            "last": "Lohner",
            "role": 8
        },
        "lastUpdatedAt": 1505938327432,
        "kind": "Feature",
        "rootVersionId": "UB9RTn0B9esKqPW_NcfB25n3QAc",
        "stableVersionId": "UB9RTn0B9esKqPW_NcfB25n3QAc-20170920201207.432160413",
        "id": "UB9RTn0B9esKqPW_NcfB25n3QAc",
        "name": "Data Presentation Toggle Dropdown",
        "color": "gray",
        "group": {
            "id": "_PENDO_DEFAULTGROUP_01_",
            "name": "Dashboard",
            "description": "",
            "color": ".groupColor01",
            "length": 6,
            "items": [],
            "createdByUser": {
                "id": "",
                "username": "",
                "first": "",
                "last": "",
                "role": 0
            },
            "createdAt": 1505937447295,
            "lastUpdatedByUser": {
                "id": "5197072786522112",
                "username": "adamlohner@pendo.io",
                "first": "Adam",
                "last": "Lohner",
                "role": 8
            },
            "lastUpdatedAt": 1505938327653
        },
        "dirty": false,
        "pageId": "aJ0KOADQZVL5h9zQhiQ0q26PNTM",
        "elementPathRules": [
            "a:contains('Data Presentation')"
        ]
    },
    { feature #2 ... },
    { feature #3 ... }
]

Returns full list of features

Details
Method GET
URI /api/v1/feature
Request Headers content-type: application/json
x-pendo-integration-key: <PENDO_INTEGRATION_KEY>
Status Codes 200: Response is sent as body

Return a specific feature

Definition

GET https://app.pendo.io/api/v1/feature?id={featureId}
requests.get("https://app.pendo.io/api/v1/feature", params = "{featureId}")

Example request

curl -X GET \
  https://app.pendo.io/api/v1/feature?id=UB9RTn0B9esKqPW_NcfB25n3QAc \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: 63bd1cda-db5a-4a2b-633b-37b8b0c5462c'
import requests
url = "https://app.pendo.io/api/v1/feature"
params = {
    "id": "UB9RTn0B9esKqPW_NcfB25n3QAc"
}
headers = {
    'x-pendo-integration-key': "63bd1cda-db5a-4a2b-633b-37b8b0c5462c",
    'content-type': "application/json"
}
response = requests.get(url, headers = headers, params = params)

Example response

[{
    "createdByUser": {
        "id": "5197072786522112",
        "username": "adamlohner@pendo.io",
        "first": "Adam",
        "last": "Lohner",
        "role": 8
    },
    "createdAt": 1505938327432,
    "lastUpdatedByUser": {
        "id": "5197072786522112",
        "username": "adamlohner@pendo.io",
        "first": "Adam",
        "last": "Lohner",
        "role": 8
    },
    "lastUpdatedAt": 1505938327432,
    "kind": "Feature",
    "rootVersionId": "UB9RTn0B9esKqPW_NcfB25n3QAc",
    "stableVersionId": "UB9RTn0B9esKqPW_NcfB25n3QAc-20170920201207.432160413",
    "id": "UB9RTn0B9esKqPW_NcfB25n3QAc",
    "name": "Data Presentation Toggle Dropdown",
    "color": "gray",
    "group": {
        "id": "_PENDO_DEFAULTGROUP_01_",
        "name": "Dashboard",
        "description": "",
        "color": ".groupColor01",
        "length": 6,
        "items": [],
        "createdByUser": {
            "id": "",
            "username": "",
            "first": "",
            "last": "",
            "role": 0
        },
        "createdAt": 1505937447295,
        "lastUpdatedByUser": {
            "id": "5197072786522112",
            "username": "adamlohner@pendo.io",
            "first": "Adam",
            "last": "Lohner",
            "role": 8
        },
        "lastUpdatedAt": 1505938327653
    },
    "dirty": false,
    "pageId": "aJ0KOADQZVL5h9zQhiQ0q26PNTM",
    "elementPathRules": [
        "a:contains('Data Presentation')"
    ]
}]

Instead of returning all features, you can specify a singular feature you’d like returned by adding a {featureId} to the request.

Details
Method GET
URI /api/v1/feature?id={featureId}
Parameters {featureId} - id of the feature to return
Request Headers content-type: application/json
x-pendo-integration-key: <PENDO_INTEGRATION_KEY>
Status Codes 200: Response is sent as body

Return list of specific features

Definition

GET https://app.pendo.io/api/v1/feature?id={featureId_1},{featureId_2},{featureId_3}
requests.get("https://app.pendo.io/api/v1/feature", params = "{featureId}")

Example request

curl -X GET \
  https://app.pendo.io/api/v1/feature?id=UB9RTn0B9esKqPW_NcfB25n3QAc,x29i5gWvIXAVoCt3ShlUYx5lgpQ \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: 63bd1cda-db5a-4a2b-633b-37b8b0c5462c'
import requests
url = "https://app.pendo.io/api/v1/feature"
params = {
    "id": "UB9RTn0B9esKqPW_NcfB25n3QAc,x29i5gWvIXAVoCt3ShlUYx5lgpQ"
}
headers = {
    'x-pendo-integration-key': "63bd1cda-db5a-4a2b-633b-37b8b0c5462c",
    'content-type': "application/json"
}
response = requests.get(url, headers = headers, params = params)

Example response

 [
  { featureId_1 details },
  { featureId_2 details },
  { ... }
]

Returns JSON array of comma separated featureIds specified in the request.

Details
Method GET
URI /api/v1/feature?id={featureId_1},{featureId_2},{featureId_3}
Parameters {featureId} - id(s) of the feature to return
Request Headers content-type: application/json
x-pendo-integration-key: <PENDO_INTEGRATION_KEY>
Status Codes 200: Response is sent as body

Guide

Guide endpoint

https://app.pendo.io/api/v1/guide

The {guideId} referenced below can be found at the end of the URL when viewing an individual guide details page. You can access that page by going to the guides list and then clicking into any guide.

The guide object

Example response

[{
    "createdByUser": {
        "id": "5197072786522112",
        "username": "adamlohner@pendo.io",
        "first": "Adam",
        "last": "Lohner",
        "role": 8
    },
    "createdAt": 1506358424254,
    "lastUpdatedByUser": {
        "id": "5197072786522112",
        "username": "adamlohner@pendo.io",
        "first": "Adam",
        "last": "Lohner",
        "role": 8
    },
    "lastUpdatedAt": 1506358852110,
    "kind": "Guide",
    "rootVersionId": "T6v10_CxHlvAkROQODuKYD2nzJ8",
    "stableVersionId": "T6v10_CxHlvAkROQODuKYD2nzJ8-20170925170052.110513720",
    "id": "T6v10_CxHlvAkROQODuKYD2nzJ8",
    "name": "API Documentation Guide",
    "state": "staged",
    "launchMethod": "auto",
    "isMultiStep": false,
    "steps": [{ step object }],
    "attributes": { ... },
    "audience": [{
            "source": {
                "visitors": null
            }
        },
        {
            "select": {
                "visitorId": "visitorId"
            }
        },
        {
            "identified": "visitorId"
        }
    ],
    "audienceUiHint": {
        "filters": []
    },
    "resetAt": 0,
    "publishedAt": 0
}]
Attributes
createdByUser
user
The user that created the guide.
createdAt
timestamp
The timestamp in milliseconds after the epoch when the guide was created.
lastUpdatedByUser
user
The user that last updated the guide.
lastUpdatedAt
timestamp
The timestamp in milliseconds after the epoch when the guide was last updated.
kind
string
Returns the type of object. Guide for example.
rootVersionId
string
The unique identifier of the root entity, which nominally matches the public id field of the guide.
stableVersionId
string
The unique identifier for the current version of the guide.
id
string
The unique identifier for the guide.
name
string
Display name for the guide.
state
string
The current state of the guide. published, staged, draft, and disabled.
launchMethod
string
Also referred to as the “activation” method. api, automatic, badge, dom, and launcher.
isMultiStep
boolean
Returnstrue if guide has multiple steps (walkthrough).
steps
array[GuideStep]
Array of objects, one for each step of a multi-step walkthrough guide.
attributes
array[attributes]
Data used for the agent’s handling of the guide.
audience
array[Pipeline]
Object representing the targeted segment rules.
audienceUiHint
array[Filter]
Internal values to build audience rules.
resetAt
timestamp
The timestamp in milliseconds when the guide’s data was last reset.
publishedAt
timestamp
The timestamp in milliseconds when the guide state was last set to public.

The step object

Example response

[{
    "id": "TGgwmKNkUBKIyHbrpbNmpEzS7mU",
    "guideId": "T6v10_CxHlvAkROQODuKYD2nzJ8",
    "type": "lightbox",
    "pageId": "aJ0KOADQZVL5h9zQhiQ0q26PNTM",
    "regexUrlRule": "^https?://[^/]*/?(?:;[^#]*)?(?:\\?[^#]*)?(?:#.*)?$",
    "elementPathRule": "",
    "contentType": "text/html; charset=utf-8",
    "contentUrl": "https://pendo-static-5335432811773952.storage.googleapis.com/guide-content/T6v10_CxHlvAkROQODuKYD2nzJ8/TGgwmKNkUBKIyHbrpbNmpEzS7mU/ORZOI2Ynpl0qDCiohWyhj48flZQ",
    "contentUrlCss": "https://pendo-static-5335432811773952.storage.googleapis.com/guide-content/T6v10_CxHlvAkROQODuKYD2nzJ8/TGgwmKNkUBKIyHbrpbNmpEzS7mU/Z9yGnCH1bZIPNqYOk8x_KPB-FI4.guide.css",
    "contentUrlJs": "https://pendo-static-5335432811773952.storage.googleapis.com/guide-content/T6v10_CxHlvAkROQODuKYD2nzJ8/TGgwmKNkUBKIyHbrpbNmpEzS7mU/vzsZ7wh2C-uB56euYUiYPJKtK80.guide.js",
    "rank": 5000000,
    "advanceMethod": "button",
    "attributes": {
        "height": 500,
        "width": 500,
        "autoHeight": true,
        "css": "/* --- Selectors from Global CSS --- */\n._pendo-guide-container_ {\n    /* Guide border, shadow, background, etc. */\n    background-color: white;\n    padding: 40px;\n    color: #333;\n    line-height: 140%;\n}\n._pendo-guide-container_ ._pendo-guide-content_ {\n    /* Content area: use for font attributes, padding, etc. */\n    text-align: left;\n    padding: 0\n}\n._pendo-guide-container_ ._pendo-close-guide_ {\n    /* Close guide icon */\n    display: inline;\n    font-size: 32px;\n    font-weight: 100;\n    top: 6px;\n    right: 15px;\n    color: #ccc;\n}\n._pendo-guide-container_ ._pendo-close-guide_:hover {\n    /* Close guide icon hover effects*/\n    color: #999;\n}.guide-header-text { font-weight: bold; font-size: 36px;}"
    },
    "lastUpdatedAt": 1506358426018,
    "resetAt": 0
}]
Attributes
id
string
Unique identifier for the step.
guideId
string
ID of the parent guide.
type
string
The type of guide step (Lightbox, Banner, Tooltip, etc.)
elementPathRule
string
The element path that indicates where the tooltip or badge “points” to (blank if not applicable).
contentType
string
The MIME type text/html or application/javascript of the content of this guide step.
contentUrl
string
URL for the step html content.
contentUrlCss
string
URL for the step css content.
contentUrlJs
string
URL for the step JS content.
rank
number
The rank order of this guide step among the other guide steps.
advanceMethod
string
Returns the steps advance method - button, programatic, or element.
thumbnailUrls
string
Thumbnail URLS used for the screenshots.
attributes
array[string]
Data used for the agent’s handling of the guide step. Contains step properties such as the height, width, autoHeight, position, css, and variables.
lastUpdatedAt
timestamp
The timestamp in milliseconds when the guide step was last updated.
resetAt
timestamp
The timestamp in milliseconds when the guide data was last reset.

The attributes object

Example response

{
    "type": "lightbox",
    "device": {
        "type": "desktop"
    },
    "badge": {
        "position": "top-right",
        "color": "#6a6c75",
        "name": "empty-i",
        "offsets": {
            "top": 0,
            "right": 0,
            "left": 0
        },
        "showOnEvent": "always",
        "useHover": "no",
        "isOnlyShowOnce": false,
        "canChangeBadgeColor": true,
        "imageUrl": "https://pendo-static-5335432811773952.storage.googleapis.com/empty-i_6a6c75",
        "width": 13,
        "height": 13
    },
    "priority": 0,
    "launcher": {
        "keywords": []
    }
}
Attributes
type
string
Unique identifier for the step.
device
boolean or string
The current state of the guide.
desktop (boolean)
mobile (boolean)
type: desktop (string)
badge
array
Attributes related to the badge activation type.
priority
number
Position of the Guide as it appears in the launcher/guide center.
launcher
array[string]
Returns an array of keywords used to search from within the launcher/guide center.

Return list of all guides

Definition

GET https://app.pendo.io/api/v1/guide
requests.get("https://app.pendo.io/api/v1/guide")

Example request

curl -X GET \
  https://app.pendo.io/api/v1/guide \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: 63bd1cda-db5a-4a2b-633b-37b8b0c5462c'
import requests
url = "https://app.pendo.io/api/v1/guide"
headers = {
    'x-pendo-integration-key': "63bd1cda-db5a-4a2b-633b-37b8b0c5462c",
    'content-type': "application/json"
}
response = requests.get(url, headers = headers)

Example response

[{
        "createdByUser": { ... },
        "createdAt": 1506358424254,
        "lastUpdatedByUser": { ... },
        "lastUpdatedAt": 1506358852110,
        "kind": "Guide",
        "rootVersionId": "T6v10_CxHlvAkROQODuKYD2nzJ8",
        "stableVersionId": "T6v10_CxHlvAkROQODuKYD2nzJ8-20170925170052.110513720",
        "id": "T6v10_CxHlvAkROQODuKYD2nzJ8",
        "name": "API Documentation Guide",
        "state": "staged",
        "launchMethod": "auto",
        "isMultiStep": false,
        "steps": [{
            "id": "TGgwmKNkUBKIyHbrpbNmpEzS7mU",
            "guideId": "T6v10_CxHlvAkROQODuKYD2nzJ8",
            "type": "lightbox",
            "pageId": "aJ0KOADQZVL5h9zQhiQ0q26PNTM",
            "regexUrlRule": "^https?://[^/]*/?(?:;[^#]*)?(?:\\?[^#]*)?(?:#.*)?$",
            "elementPathRule": "",
            "contentType": "text/html; charset=utf-8",
            "contentUrl": "https://pendo-static-5335432811773952.storage.googleapis.com/guide-content/T6v10_CxHlvAkROQODuKYD2nzJ8/TGgwmKNkUBKIyHbrpbNmpEzS7mU/ORZOI2Ynpl0qDCiohWyhj48flZQ",
            "contentUrlCss": "https://pendo-static-5335432811773952.storage.googleapis.com/guide-content/T6v10_CxHlvAkROQODuKYD2nzJ8/TGgwmKNkUBKIyHbrpbNmpEzS7mU/Z9yGnCH1bZIPNqYOk8x_KPB-FI4.guide.css",
            "contentUrlJs": "https://pendo-static-5335432811773952.storage.googleapis.com/guide-content/T6v10_CxHlvAkROQODuKYD2nzJ8/TGgwmKNkUBKIyHbrpbNmpEzS7mU/vzsZ7wh2C-uB56euYUiYPJKtK80.guide.js",
            "rank": 5000000,
            "advanceMethod": "button",
            "attributes": {
                "height": 500,
                "width": 500,
                "autoHeight": true,
                "css": "/* --- Selectors from Global CSS --- */\n._pendo-guide-container_ {\n    /* Guide border, shadow, background, etc. */\n    background-color: white;\n    padding: 40px;\n    color: #333;\n    line-height: 140%;\n}\n._pendo-guide-container_ ._pendo-guide-content_ {\n    /* Content area: use for font attributes, padding, etc. */\n    text-align: left;\n    padding: 0\n}\n._pendo-guide-container_ ._pendo-close-guide_ {\n    /* Close guide icon */\n    display: inline;\n    font-size: 32px;\n    font-weight: 100;\n    top: 6px;\n    right: 15px;\n    color: #ccc;\n}\n._pendo-guide-container_ ._pendo-close-guide_:hover {\n    /* Close guide icon hover effects*/\n    color: #999;\n}.guide-header-text { font-weight: bold; font-size: 36px;}"
            },
            "lastUpdatedAt": 1506358426018,
            "resetAt": 0
        }],
        "attributes": {
            "type": "lightbox",
            "device": {
                "type": "desktop"
            },
            "badge": {
                "position": "top-right",
                "color": "#6a6c75",
                "name": "empty-i",
                "offsets": {
                    "top": 0,
                    "right": 0,
                    "left": 0
                },
                "showOnEvent": "always",
                "useHover": "no",
                "isOnlyShowOnce": false,
                "canChangeBadgeColor": true,
                "imageUrl": "https://pendo-static-5335432811773952.storage.googleapis.com/empty-i_6a6c75",
                "width": 13,
                "height": 13
            },
            "priority": 0,
            "launcher": {
                "keywords": []
            }
        },
        "audience": [{
                "source": {
                    "visitors": null
                }
            },
            {
                "select": {
                    "visitorId": "visitorId"
                }
            },
            {
                "identified": "visitorId"
            }
        ],
        "audienceUiHint": {
            "filters": []
        },
        "resetAt": 0,
        "publishedAt": 0
    },
    { guide #2 },
    { guide #3 }
]

Returns a JSON list of all guides for a subscription.

Details
Method GET
URI /api/v1/guide
Request Headers content-type: application/json
x-pendo-integration-key: <PENDO_INTEGRATION_KEY>
Status Codes 200: Response is sent as body

Return a specific guide

Definition

GET https://app.pendo.io/api/v1/guide?id={guideId}
requests.get("https://app.pendo.io/api/v1/guide", params = "{guideId}")

Example request

curl -X GET \
  https://app.pendo.io/api/v1/guide?id=T6v10_CxHlvAkROQODuKYD2nzJ8 \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: 63bd1cda-db5a-4a2b-633b-37b8b0c5462c'
url = "https://app.pendo.io/api/v1/guide"
params = {
    "id": "T6v10_CxHlvAkROQODuKYD2nzJ8"
}
headers = {
    'x-pendo-integration-key': "63bd1cda-db5a-4a2b-633b-37b8b0c5462c",
    'content-type': "application/json"
}
response = requests.get(url, headers = headers, params = params)

Example response

[{
    "createdByUser": {},
    "createdAt": 1506358424254,
    "lastUpdatedByUser": {},
    "lastUpdatedAt": 1506358852110,
    "kind": "Guide",
    "rootVersionId": "T6v10_CxHlvAkROQODuKYD2nzJ8",
    "stableVersionId": "T6v10_CxHlvAkROQODuKYD2nzJ8-20170925170052.110513720",
    "id": "T6v10_CxHlvAkROQODuKYD2nzJ8",
    "name": "API Documentation Guide",
    "state": "staged",
    "launchMethod": "auto",
    "isMultiStep": false,
    "steps": [{ ... }],
    "attributes": { ... },
    "audience": [{ ... }],
    "audienceUiHint": {
        "filters": []
    },
    "resetAt": 0,
    "publishedAt": 0
}]

Instead of returning all guides, you can specify a singular guide you’d like returned by adding a {guideId} to the request. Comma separated values are allowed. For example, if you wanted to return multiple guides but not the entire list, follow the format: guide?id={guideId_1},{guideId_2},{guideId_3}

Details
Method GET
URI /api/v1/guide?={guideId}
Parameters guideId - the ID of the guide requested
Request Headers content-type: application/json
x-pendo-integration-key: <PENDO_INTEGRATION_KEY>
Status Codes 200: Response is sent as body

Retrieve change history for a guide

Definition

GET https://app.pendo.io/api/v1/guide/{guideId}/history
requests.get("https://app.pendo.io/api/v1/guide/{guideId}/history")

Example request

curl -X GET \
https://app.pendo.io/api/v1/guide/T6v10_CxHlvAkROQODuKYD2nzJ8/history \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: 63bd1cda-db5a-4a2b-633b-37b8b0c5462c'
import requests
url = "https://app.pendo.io/api/v1/guide/T6v10_CxHlvAkROQODuKYD2nzJ8/history"
headers = {
    'x-pendo-integration-key': "63bd1cda-db5a-4a2b-633b-37b8b0c5462c",
    'content-type': "application/json"
}
response = requests.get(url, headers = headers)

Example response

[{
        "createdByUser": { ... },
        "createdAt": 1506358424254,
        "lastUpdatedByUser": { ... },
        "lastUpdatedAt": 1506358426018,
        "kind": "Guide",
        "rootVersionId": "T6v10_CxHlvAkROQODuKYD2nzJ8",
        "stableVersionId": "T6v10_CxHlvAkROQODuKYD2nzJ8-20170925165346.018238252",
        "id": "T6v10_CxHlvAkROQODuKYD2nzJ8",
        "name": "API Documentation Guide",
        "state": "draft",
        "launchMethod": "auto",
        "isMultiStep": false,
        "steps": [{ ... }],
        "attributes": { ... },
        "audience": [{ ... }],
        "audienceUiHint": {
            "filters": []
        },
        "resetAt": 0,
        "publishedAt": 0
    },
    { next oldest version (if applicable) },
  { ... }
]

Returns a JSON list of all versions of a guide, from current to oldest. Changes to guides through the Pendo user interface often result in multiple individual updates, each of which will be independently reflected in the history.

Details
Method GET
URI /api/v1/guide/{guideId}/history
Parameters guideId - the ID of the guide whose history is needed
Request Headers content-type: application/json
x-pendo-integration-key: <PENDO_INTEGRATION_KEY>
Status Codes 200: guide was located and history found.
404: guide in question was not found.

Reset guide seen for specific visitor

Definition

POST https://app.pendo.io/api/v1/guide/{guideId}/visitor/{visitorId}/reset
requests.post("https://app.pendo.io/api/v1/guide/{guideId}/visitor/{visitorId}/reset")

Example request

curl -X POST \
 https://app.pendo.io/api/v1/guide/T6v10_CxHlvAkROQODuKYD2nzJ8/visitor/4/reset \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: <PENDO_INTEGRATION_KEY>' \
  -d ''
import requests
url = "https://app.pendo.io/api/v1/guide/T6v10_CxHlvAkROQODuKYD2nzJ8/visitor/4/reset"
headers = {
    'x-pendo-integration-key': "<PENDO_INTEGRATION_KEY>",
    'content-type': "application/json"
}
response = requests.post(url, headers = headers)

Reset the guide seen records for a guide with ID {guideId} for a particular visitor with ID {visitorId}. The guide can be in any state.

Details
Method POST
URI /api/v1/guide/{guideId}/visitor/{visitorId}/reset
Parameters guideId - ID of the guide to be reset
visitorId - ID of the visitor whose record of having seen the guide should be removed.
Request Headers content-type: application/json
x-pendo-integration-key: <PENDO_INTEGRATION_KEY>
Status Codes 200: guide was reset as requested.
404: The guide in question was not found.

Reset guide seen for specific visitor for all guides

Definition

POST https://app.pendo.io/api/v1/guide/all/visitor/{visitorId}/reset
requests.post("https://app.pendo.io/api/v1/guide/all/visitor/{visitorId}/reset")

Example request

curl -X POST \
https://app.pendo.io/api/v1/guide/all/visitor/4/reset \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: <PENDO_INTEGRATION_KEY>' \
  -d ''
import requests
url = "https://app.pendo.io/api/v1/guide/all/visitor/4/reset"
headers = {
    'x-pendo-integration-key': "<PENDO_INTEGRATION_KEY>",
    'content-type': "application/json"
}
response = requests.post(url, headers = headers)

Reset the guide seen records for a particular visitor with ID {visitorId}. All seen data will be removed across all guides for that visitor.

Details
Method POST
URI /api/v1/guide/all/visitor/{visitorId}/reset
Parameters visitorId - ID of the visitor whose record of having seen all guides should be removed.
Request Headers content-type: application/json
x-pendo-integration-key: <PENDO_INTEGRATION_KEY>
Status Codes 200: guide was reset as requested.

Reset individual staged guide

Definition

POST https://app.pendo.io/api/v1/guide/{guideId}/reset
requests.post("https://app.pendo.io/api/v1/guide/{guideId}/reset")

Example request

curl -X POST \
https://app.pendo.io/api/v1/guide/T6v10_CxHlvAkROQODuKYD2nzJ8/reset \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: <PENDO_INTEGRATION_KEY>' \
  -d ''
import requests
url = "https://app.pendo.io/api/v1/guide/T6v10_CxHlvAkROQODuKYD2nzJ8/reset"
headers = {
    'x-pendo-integration-key': "<PENDO_INTEGRATION_KEY>",
    'content-type': "application/json"
}
response = requests.post(url, headers = headers)

Reset an individual staged guide with ID guideId. All visitors that have seen the guide previously will be eligible to see it again as if it were a newly created guide. All previous guide data will be deleted for this guide, including any poll response data.

Details
Method POST
URI /api/v1/guide/{guideId}/reset
Parameters guideId - ID of the guide to be reset.
Request Headers content-type: application/json
x-pendo-integration-key: <PENDO_INTEGRATION_KEY>
Status Codes 200: guide was reset as requested.
400: The guide could not be reset (e.g. it’s not a staged guide).
404: The guide in question was not found.

Reset all staged guides

Definition

POST https://app.pendo.io/api/v1/guide/staged/reset
requests.post("https://app.pendo.io/api/v1/guide/staged/reset")

Example request

curl -X POST \
 https://app.pendo.io/api/v1/guide/staged/reset \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: <PENDO_INTEGRATION_KEY>' \
  -d ''
import requests
url = "https://app.pendo.io/api/v1/guide/staged/reset"
headers = {
    'x-pendo-integration-key': "<PENDO_INTEGRATION_KEY>",
    'content-type': "application/json"
}
response = requests.post(url, headers = headers)

Reset all staged guides. All visitors that have seen guides previously will be eligible to them again as if they were newly created guides. All previous guide data will be deleted, including any poll response data.

Details
Method POST
URI /api/v1/guide/staged/reset
Request Headers content-type: application/json
x-pendo-integration-key: <PENDO_INTEGRATION_KEY>
Status Codes 200: All guides were reset as requested.

Metadata

The metadata object

Example response

{
    "agent": { ... },
    "auto": { ... },
    "custom": { ... },
    "pendo": {
      "blacklistguides": true
    }
}
Attributes
agent
array
Metadata type passed through the installation snippet.
auto
string
Automatically generated by Pendo.
custom
array
Custom “Pendo only” fields to help analyze aspects of your data.
pendo
string
Metadata representing the current blacklistguides setting for the visitor.

Automatically generated metadata

Example visitor "auto" object

{
    "accountid": "Epsilon united",
    "accountids": [
        "Epsilon united"
    ],
    "firstvisit": 1506351511034,
    "id": "4",
    "idhash": 4088798008,
    "lastbrowsername": "Chrome",
    "lastbrowserversion": "60.0.3112",
    "lastoperatingsystem": "Mac OS X",
    "lastservername": "pendosandbox.com",
    "lastupdated": 1506358391050,
    "lastuseragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.113 Safari/537.36",
    "lastvisit": 1506358390891,
    "nid": 4
}
Visitor Attributes
accountid
string
Unique identifier for the account the visitor belongs to.
accountids
array
Array of unique accountIds the visitor belongs to.
firstvisit
timestamp
The timestamp in milliseconds after the epoch when an event was first captured for the visitor.
id
string
Unique identifier for the visitor.
idhash
number
Hash of visitor Id.
lastbrowsername
string
Most recent browser name.
lastbrowserversion
string
Most recent browser version.
lastoperatingsystem
string
Most recent operating system.
lastservername
string
Most recent server name.
lastupdated
timestamp
The timestamp in milliseconds after the epoch when the visitor was last updated.
lastuseragent
string
Most recent user agent (unparsed).
lastvisit
timestamp
The timestamp in milliseconds after the epoch when we last recorded an event for the visitor.
nid
number
Numeric id for the visitor.

Example account "auto" object

{
    "firstvisit": 1506349414089,
    "id": "Zeta and Sons",
    "idhash": 1129480058,
    "lastupdated": 1506349414757,
    "lastvisit": 1506349414089
}
Account Attributes
firstvisit
timestamp
The timestamp in milliseconds after the epoch when the account or visitor was created.
id
string
Unique identifier for the visitor or account.
idhash
number
Hash of account Id.
lastupdated
timestamp
The timestamp in milliseconds after the epoch when the account was last updated.
lastvisit
timestamp
The timestamp in milliseconds after the epoch when we last recorded an event for the account.

Get a metadata schema

Definition

GET https://app.pendo.io/api/v1/metadata/schema/{kind}
requests.get("https://app.pendo.io/api/v1/metadata/schema/{kind}")

Example request

curl -X GET \
  https://app.pendo.io/api/v1/metadata/schema/account \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: 63bd1cda-db5a-4a2b-633b-37b8b0c5462c'
import requests
url = "https://app.pendo.io/api/v1/metadata/schema/account"
headers = {
    'x-pendo-integration-key': "63bd1cda-db5a-4a2b-633b-37b8b0c5462c",
    'content-type': "application/json"
}
response = requests.get(url, headers = headers)

Example response

{
    "auto": {
        "firstvisit": {
            "Type": "time",
            "DisplayName": "First Visit",
            "ElementType": "",
            "ElementFormat": "milliseconds",
            "Dirty": false,
            "isHidden": false,
            "isDeleted": false,
            "isCalculated": false,
            "neverIndex": false
        },
        "id": {
            "Type": "string",
            "DisplayName": "Account ID",
            "ElementType": "",
            "ElementFormat": "",
            "Dirty": false,
            "isHidden": false,
            "isDeleted": false,
            "isCalculated": false,
            "neverIndex": false
        },
        "lastvisit": {
            "Type": "time",
            "DisplayName": "Last Visit",
            "ElementType": "",
            "ElementFormat": "milliseconds",
            "Dirty": false,
            "isHidden": false,
            "isDeleted": false,
            "isCalculated": false,
            "neverIndex": false
        }
    }
}

Gets the metadata schema for a single kind of metadata (visitor or account).

Details
Method GET
URI /api/v1/metadata/schema/{kind}
Parameters kind - "visitor" or "account".
Data JSON encoded metadata value
Request Headers content-type: application/json
x-pendo-integration-key: <PENDO_INTEGRATION_KEY>
Status Codes 200: The metadata value was updated
404: Check to make sure the custom field exists in Data Mappings and that the visitor or account ID is valid

Get value of a metadata field

Definition

GET https://app.pendo.io/api/v1/metadata/{kind}/{group}/value/{id}/{fieldName}
requests.get("https://app.pendo.io/api/v1/metadata/{kind}/{group}/value/{id}/{fieldName}")

Example request

curl -X GET \
https://app.pendo.io/api/v1/metadata/visitor/agent/value/4/email \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: 63bd1cda-db5a-4a2b-633b-37b8b0c5462c'
import requests
url = "https://app.pendo.io/api/v1/metadata/visitor/agent/value/4/email"
headers = {
    'x-pendo-integration-key': "63bd1cda-db5a-4a2b-633b-37b8b0c5462c",
    'content-type': "application/json"
}
response = requests.get(url, headers = headers)

Example response

"quam.quis@eratvolutpat.edu"

Gets the value of metadata field for an account or visitor

Details
Method GET
URI /api/v1/metadata/{kind}/{group}/value/{id}/{fieldName}
Parameters kind - "visitor" or "account"
id - ID of the visitor or account being updated
fieldName - name of the metadata field being updated
Data JSON encoded metadata value
Request Headers content-type: application/json
x-pendo-integration-key: <PENDO_INTEGRATION_KEY>
Status Codes 200: The metadata value was updated
404: Check to make sure the custom field exists in Data Mappings and that the visitor or account ID is valid

Opt-out a visitor or account from all guides

Definition

PUT https://app.pendo.io/api/v1/metadata/{kind}/pendo/value/{id}/blacklistguides
requests.put("https://app.pendo.io/api/v1/metadata/{kind}/pendo/value/{id}/blacklistguides", data = "{boolean}")

Example request

curl -X PUT \
  https://app.pendo.io/api/v1/metadata/visitor/pendo/value/4/blacklistguides \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: <PENDO_INTEGRATION_KEY>' \
  -d true
import requests
url = "https://app.pendo.io/api/v1/metadata/visitor/pendo/value/4/blacklistguides"
data = "true"
headers = {
    'x-pendo-integration-key': "<PENDO_INTEGRATION_KEY>",
    'content-type': "application/json"
}
response = requests.put(url, data = data, headers = headers)

Use ‘Pendo’ metadata to turn guides off or on for a visitor or an account. This provides an opt-out capability for visitors and accounts.

Details
Method PUT
URI /api/v1/metadata/{kind}/pendo/value/{id}/blacklistguides
Parameters kind - "visitor" or "account"
id - ID of the visitor or account being updated
Data true to disable guides
false to re-enable guides
Request Headers content-type: application/json
x-pendo-integration-key: <PENDO_INTEGRATION_KEY>
Status Codes 200: The metadata value was updated

Set value for an agent or custom field

Definition

PUT https://app.pendo.io/api/v1/metadata/{kind}/{group}/value/{id}/{fieldName}
requests.put("https://app.pendo.io/api/v1/metadata/{kind}/{group}/value/{id}/{fieldName}", data = "{value}")

Example request

curl -X PUT \
  https://app.pendo.io/api/v1/metadata/visitor/custom/value/4/location \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: <PENDO_INTEGRATION_KEY>' \
  -d '"Alaska"'
import requests
url = "https://app.pendo.io/api/v1/metadata/visitor/custom/value/4/location"
data = "\"Alaska\""
headers = {
    'x-pendo-integration-key': "<PENDO_INTEGRATION_KEY>",
    'content-type': "application/json"
}
response = requests.put(url, data = data, headers = headers)

Sets the value of an agent or custom metadata field on an account or visitor. If setting value for a custom field, the field must already have been created in the Data Mappings.

Details
Method PUT
URI /api/v1/metadata/{kind}/{group}/value/{id}/{fieldName}
Parameters kind - "visitor" or "account"
group - type of metadata field: agent or custom
id - id of the visitor or account being updated
fieldName - name of the metadata field being updated
Data JSON encoded metadata value
Request Headers content-type: application/json
x-pendo-integration-key: <PENDO_INTEGRATION_KEY>
Status Codes 200: The metadata value was updated
404: Check to make sure the custom field exists in Data Mappings

Set value for a set of agent or custom fields

Definition

POST https://app.pendo.io/api/v1/metadata/{kind}/{group}/value
requests.post("https://app.pendo.io/api/v1/metadata/{kind}/{group}/value", data = "JSON array")

The contents of the POST must be a JSON array:

[ object1, object2, ..., objectN ]

Each object in the array is of the form:

{
  "visitorId": "4",
  "values": {
    "firstname": "Quam",
    "lastname": "Quis"
  }
}

Example request

curl -X POST \
https://app.pendo.io/api/v1/metadata/visitor/agent/value \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: <PENDO_INTEGRATION_KEY>' \
  -d '[{"visitorId":"4","values":{"firstname":"Quam","lastname":"Quis"}},{"visitorId":"45","values":{"firstname":"Vel","lastname":"Quam"}},{"visitorId":"63","values":{"firstname":"Eros","lastname":"Nam"}}]'
import requests
url = "https://app.pendo.io/api/v1/metadata/visitor/agent/value"
data = "[{\"visitorId\":\"4\",\"values\":{\"firstname\":\"Quam\",\"lastname\":\"Quis\"}},{\"visitorId\":\"45\",\"values\":{\"firstname\":\"Vel\",\"lastname\":\"Quam\"}},{\"visitorId\":\"63\",\"values\":{\"firstname\":\"Eros\",\"lastname\":\"Nam\"}}]"
headers = {
    'x-pendo-integration-key': "<PENDO_INTEGRATION_KEY>",
    'content-type': "application/json",
}
response = requests.post(url, data = data, headers = headers)

Sets the value of multiple metadata fields on set of accounts or visitors. If setting custom fields, the fields must already have been created in the Data Mappings.

Any number of records may be submitted for update, but the call is limited to five (5) minutes. Any calls that takes longer will timeout with a 408 Request Timeout.

Details
Method POST
URI /api/v1/metadata/{kind}/{group}/value
Parameters kind - "visitor" or "account"
group - type of metadata field: agent or custom
Data JSON array (see example format)
Request Headers content-type: application/json
x-pendo-integration-key: <PENDO_INTEGRATION_KEY>
Status Codes 200: The bulk update completed.
400: The format is unacceptable due to malformed JSON or missing field mappings.
408: The call took too long and timed out.
Response

Example response

{
    "total": 3,
    "updated": 3,
    "failed": 0,
    "missing": [],
    "errors": []
}
Attributes
total
number
Sum of updated + failed.
failed
number
Sum of length(missing) + length(errors).

Accepted Date Formats

When attempting to update Date fields, please be sure to only use accepted formats. Sending unaccepted date format data into a date field can have unexpected consequences for any data entries or edits.

  • 1136232245 (s)
  • 1136232245426 (ms)
  • Mon Jan 02 2006
  • Mon Jan 02 2006 15:04:05 MST-0700
  • 01/02/2006 03:04pm
  • ISO8601 W3C, ex: 2006-01-02T115:04:05.999-05:00
  • 2006-01-02T15:04:05-0700
  • 2006-01-02T15:04:05-07:00
  • 2006-01-02T15:04:05.999-07:00
  • 2006-01-02T15:04:05Z07:00
  • 2006-01-02T15:04:05.99Z
  • 2006-01-02T15:04:05
  • 2006-01-02 15:04:05 -0700
  • 2006-01-02 15:04:05 MST
  • 2006-01-02 15:04:05

Page

Page Endpoint

https://app.pendo.io/api/v1/page

The {pageId} referenced below can be found at the end of the URL when viewing details for a specific page within the app. You can view your list of available pages here.

The page object

Example response

[{
    "createdByUser": {
        "id": "5197072786522112",
        "username": "adamlohner@pendo.io",
        "first": "Adam",
        "last": "Lohner",
        "role": 8
    },
    "createdAt": 1505938241596,
    "lastUpdatedByUser": {
        "id": "5197072786522112",
        "username": "adamlohner@pendo.io",
        "first": "Adam",
        "last": "Lohner",
        "role": 8
    },
    "lastUpdatedAt": 1505938241596,
    "kind": "Page",
    "rootVersionId": "aJ0KOADQZVL5h9zQhiQ0q26PNTM",
    "stableVersionId": "aJ0KOADQZVL5h9zQhiQ0q26PNTM-20170920201041.596687476",
    "id": "aJ0KOADQZVL5h9zQhiQ0q26PNTM",
    "name": "Dashboard",
    "color": "gray",
    "group": { ... },
    "dirty": false,
    "rules": [{
        "rule": "//*",
        "designerHint": "http://pendosandbox.com/",
        "parsedRule": "^https?://[^/]*/?(?:;[^#]*)?(?:\\?[^#]*)?(?:#.*)?$"
    }]
}]
Attributes
createdByUser
user
The user that created the page.
createdAt
timestamp
The timestamp in milliseconds after the epoch when the page was created.
lastUpdatedByUser
user
The user that last updated the page.
lastUpdatedAt
timestamp
The timestamp in milliseconds after the epoch when the page was last updated.
kind
string
Returns the type of object. Page for example.
rootVersionId
string
The unique identifier of the root entity, which nominally matches the public id field of the page.
stableVersionId
string
The unique identifier for the current version of the page.
id
string
Unique identifier for the page.
name
string
Display name for the page.
group
array[object]
Group object containing information related to associated group for the page.
dirty
boolean
Boolean value returned if page is processing at the time of request.
rules
array[rules]
URL rules for the page.

Return list of all pages

Definition

GET https://app.pendo.io/api/v1/page
requests.get("https://app.pendo.io/api/v1/page")

Example request

curl -X GET \
  https://app.pendo.io/api/v1/page \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: 63bd1cda-db5a-4a2b-633b-37b8b0c5462c'
import requests
url = "https://app.pendo.io/api/v1/page"
headers = {
    'x-pendo-integration-key': "63bd1cda-db5a-4a2b-633b-37b8b0c5462c",
    'content-type': "application/json"
}
response = requests.get(url, headers = headers)

Example response

[{
        "createdByUser": {
            "id": "5197072786522112",
            "username": "adamlohner@pendo.io",
            "first": "Adam",
            "last": "Lohner",
            "role": 8
        },
        "createdAt": 1505938241596,
        "lastUpdatedByUser": {
            "id": "5197072786522112",
            "username": "adamlohner@pendo.io",
            "first": "Adam",
            "last": "Lohner",
            "role": 8
        },
        "lastUpdatedAt": 1505938241596,
        "kind": "Page",
        "rootVersionId": "aJ0KOADQZVL5h9zQhiQ0q26PNTM",
        "stableVersionId": "aJ0KOADQZVL5h9zQhiQ0q26PNTM-20170920201041.596687476",
        "id": "aJ0KOADQZVL5h9zQhiQ0q26PNTM",
        "name": "Dashboard",
        "color": "gray",
        "group": {
            "id": "_PENDO_DEFAULTGROUP_01_",
            "name": "Dashboard",
            "description": "",
            "color": ".groupColor01",
            "length": 6,
            "items": [],
            "createdByUser": {
                "id": "",
                "username": "",
                "first": "",
                "last": "",
                "role": 0
            },
            "createdAt": 1505937447295,
            "lastUpdatedByUser": {
                "id": "5197072786522112",
                "username": "adamlohner@pendo.io",
                "first": "Adam",
                "last": "Lohner",
                "role": 8
            },
            "lastUpdatedAt": 1505938327653
        },
        "dirty": false,
        "rules": [{
            "rule": "//*",
            "designerHint": "http://pendosandbox.com/",
            "parsedRule": "^https?://[^/]*/?(?:;[^#]*)?(?:\\?[^#]*)?(?:#.*)?$"
        }]
    },
    { page #2 },
    { page #3 }
]

Returns full list of pages

Details
Method GET
URI /api/v1/page
Request Headers content-type: application/json
x-pendo-integration-key: <PENDO_INTEGRATION_KEY>
Status Codes 200: Response is sent as body

Return list of specific pages

Definition

GET https://app.pendo.io/api/v1/page?={pageId_1},{pageId_2},{...}
requests.get("https://app.pendo.io/api/v1/page", params = "{pageId_1},{pageId_2},{...}")

Example request

curl -X GET \
  https://app.pendo.io/api/v1/page?id=aJ0KOADQZVL5h9zQhiQ0q26PNTM \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: 63bd1cda-db5a-4a2b-633b-37b8b0c5462c'
import requests
url = "https://app.pendo.io/api/v1/page"
params = {
    "id": "aJ0KOADQZVL5h9zQhiQ0q26PNTM"
}
headers = {
    'x-pendo-integration-key': "63bd1cda-db5a-4a2b-633b-37b8b0c5462c",
    'content-type': "application/json"
}
response = requests.get(url, headers = headers, params = params)

Example response

 [
  { page #1 details },
  { page #2 details },
  { ... }
]

Instead of returning all pages, you can specify which pages you’d like returned by adding the page Id to the request.

Details
Method GET
URI /api/v1/page/{pageId}
Parameters {pageId} - id of the page to return. Multiple comma separated ids may be used.
Request Headers content-type: application/json
x-pendo-integration-key: <PENDO_INTEGRATION_KEY>
Status Codes 200: Response is sent as body

Report

Report endpoint

https://app.pendo.io/api/v1/report

NOTE: The Reports API output is not a stable endpoint at this time. We are committed to making the results stable as soon as possible. The aggregations API is considered stable and can be used as an alternative.

The reports API works with Visitor or Account reports that have been created in your subscription. The {reportId} referenced below can be found at the end of the URL when viewing a report within the app: https://app.pendo.io/visitorlist/{reportId}. Visitor and Account reports can managed from the Visitor or Account report tabs.

The report object

Example response

[{
    "createdByUser": {
        "id": "5197072786522112",
        "username": "adamlohner@pendo.io",
        "first": "Adam",
        "last": "Lohner",
        "role": 8
    },
    "createdAt": 1506362416386,
    "lastUpdatedByUser": {
        "id": "5197072786522112",
        "username": "adamlohner@pendo.io",
        "first": "Adam",
        "last": "Lohner",
        "role": 8
    },
    "lastUpdatedAt": 1506362423556,
    "kind": "Report",
    "rootVersionId": "Gcs71tkJQe88CwiBKVQ9zd8sG1U",
    "stableVersionId": "Gcs71tkJQe88CwiBKVQ9zd8sG1U-20170925180023.556531973",
    "id": "Gcs71tkJQe88CwiBKVQ9zd8sG1U",
    "type": "",
    "name": "API Documentation Report",
    "shared": true,
    "definition": { ... },
    "aggregation": { ... },
    "lastRunAt": 1506363386484
}]
Attributes
createdByUser
user
The user that created the report.
createdAt
timestamp
The timestamp in milliseconds after the epoch when the report was created.
lastUpdatedByUser
user
The user that last updated the report.
lastUpdatedAt
timestamp
The timestamp in milliseconds after the epoch when the report was last updated.
kind
string
Returns the type of object. Report for example.
rootVersionId
string
The unique identifier of the root entity, which nominally matches the public id field of the report.
stableVersionId
string
The unique identifier for the current version of the report.
id
string
Unique identifier for the report.
name
string
Display name for the report.
shared
boolean
Returns true or false dependent on the reports visibility setting.
definition
array[definition]
Structure of the report, e.g., which columns were selected, which segment was applied, etc.
aggregation
array[aggregation]
See aggregation object definition.

The definition object

Example response

[{
  "config": {
    "columns": [],
    "segmentId": "everyone",
    "filters": [],
    "segments": []
  },
  "generator": "visitorList",
  "kind": "visitor",
  "timeSeries": {
    "type": "Last 30 Days",
    "start": "2017-08-01",
    "end": "2017-08-31"
  },
  "type": "List"
}]
Attributes
config
array
Returns the configuration options for the report such as the columns included, and any segment related information present.
generator
string
visitorList or accountList.
kind
string
Returns visitor or account dependent on the report kind.
timeSeries
array
The set timeSeries for the current report.
type
string
The type of report. Values include List, Funnel or Path.

Return a list of public reports

Definition

GET https://app.pendo.io/api/v1/report
requests.get("https://app.pendo.io/api/v1/report")

Example request

curl -X GET \
  https://app.pendo.io/api/v1/report \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: 63bd1cda-db5a-4a2b-633b-37b8b0c5462c'
import requests
url = "https://app.pendo.io/api/v1/report"
headers = {
    'x-pendo-integration-key': "63bd1cda-db5a-4a2b-633b-37b8b0c5462c",
    'content-type': "application/json"
}
response = requests.get(url, headers = headers)

Example response

[{
        "createdByUser": {
            "id": "5197072786522112",
            "username": "adamlohner@pendo.io",
            "first": "Adam",
            "last": "Lohner",
            "role": 8
        },
        "createdAt": 1506362416386,
        "lastUpdatedByUser": {
            "id": "5197072786522112",
            "username": "adamlohner@pendo.io",
            "first": "Adam",
            "last": "Lohner",
            "role": 8
        },
        "lastUpdatedAt": 1506362423556,
        "kind": "Report",
        "rootVersionId": "Gcs71tkJQe88CwiBKVQ9zd8sG1U",
        "stableVersionId": "Gcs71tkJQe88CwiBKVQ9zd8sG1U-20170925180023.556531973",
        "id": "Gcs71tkJQe88CwiBKVQ9zd8sG1U",
        "type": "",
        "name": "API Documentation Report",
        "shared": true,
        "definition": {
            "config": {
                "columns": [],
                "segmentId": "everyone",
                "filters": [],
                "segments": []
            },
            "generator": "visitorList",
            "history": [],
            "kind": "visitor",
            "timeSeries": {
                "type": "Today"
            },
            "type": "List"
        },
        "aggregation": {
            "fields": [{
                "type": "string",
                "title": "Visitor ID",
                "field": "visitorId"
            }],
            "pipeline": [{
                    "source": {
                        "events": null,
                        "timeSeries": {
                            "period": "dayRange",
                            "first": "now()",
                            "last": "now()"
                        }
                    }
                },
                {
                    "identified": "visitorId"
                },
                {
                    "group": {
                        "group": [
                            "visitorId"
                        ]
                    }
                },
                {
                    "select": {
                        "visitorId": "visitorId"
                    }
                }
            ]
        },
        "lastRunAt": 1506362423429
    },
    {},
    {}
]

Returns an array of JSON objects representing all public reports for a subscription.

Details
Method GET
URI /api/v1/report
Request Headers content-type: application/json
x-pendo-integration-key: <PENDO_INTEGRATION_KEY>
Status Codes 200: Response is sent as body

Return report contents as array of JSON objects

Definition

GET https://app.pendo.io/api/v1/report/{reportId}/results.json
requests.get("https://app.pendo.io/api/v1/report/{reportId}/results.json")

Example request

curl -X GET \
https://app.pendo.io/api/v1/report/Gcs71tkJQe88CwiBKVQ9zd8sG1U/results.json \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: 63bd1cda-db5a-4a2b-633b-37b8b0c5462c'
import requests
url = "https://app.pendo.io/api/v1/report/Gcs71tkJQe88CwiBKVQ9zd8sG1U/results.json"
headers = {
    'x-pendo-integration-key': "63bd1cda-db5a-4a2b-633b-37b8b0c5462c",
    'content-type': "application/json"
}
response = requests.get(url, headers = headers)

Example response

[{
        "visitorId": "12"
    },
    {
        "visitorId": "4"
    },
    {
        "visitorId": "45"
    },
    {
        "visitorId": "63"
    },
    {
        "visitorId": "NaN"
    }
]

Returns a list of JSON objects.

Details
Method GET
URI /api/v1/report/{reportId}/results.json
Parameters reportId - ID of the report
Request Headers content-type: application/json
x-pendo-integration-key: <PENDO_INTEGRATION_KEY>
Status Codes 200: Response is sent as body
404: The report in question was not found.

Return report contents as csv

Definition

GET https://app.pendo.io/api/v1/report/{reportId}/results.csv
requests.get("https://app.pendo.io/api/v1/report/{reportId}/results.csv")

Example request

curl -X GET \
https://app.pendo.io/api/v1/report/8JsdfvwlY_Fx2uAHUsdfqOsYVXE/results.csv \
  -H 'content-type: text/csv' \
  -H 'x-pendo-integration-key: 63bd1cda-db5a-4a2b-633b-37b8b0c5462c'
import requests
url = "https://app.pendo.io/api/v1/report/Gcs71tkJQe88CwiBKVQ9zd8sG1U/results.csv"
headers = {
    'x-pendo-integration-key': "63bd1cda-db5a-4a2b-633b-37b8b0c5462c",
    'content-type': "text/csv"
}
response = requests.get(url, headers = headers)

Example response

Visitor ID
12
4
45
63
NaN
Details
Method GET
URI /api/v1/report/{reportId}/results.csv
Parameters reportId - ID of the report
Request Headers content-type: text/csv
x-pendo-integration-key: <PENDO_INTEGRATION_KEY>
Status Codes 200: Response is sent as body
404: The report in question was not found.

Visitor

Visitor endpoint

https://app.pendo.io/api/v1/visitor

The visitor endpoint allows you to retrieve visitor specific details by supplying a visitor ID as part of your request. The {visitorId} referenced below can be found on the visitors list page or at the end of the url when viewing a visitor details page.

The visitor object

Example response

{
    "id": "4",
    "email": "",
    "accountIds": [
        "Epsilon united"
    ],
    "metadata": {
        "agent": {
            "email": "quam.quis@eratvolutpat.edu",
            "ipaddress": "204.16.137.138",
            "language": "en_US"
        },
        "auto": {
            "accountid": "Epsilon united",
            "accountids": [
                "Epsilon united"
            ],
            "firstvisit": 1506351511034,
            "id": "4",
            "idhash": 4088798008,
            "lastbrowsername": "Chrome",
            "lastbrowserversion": "60.0.3112",
            "lastoperatingsystem": "Mac OS X",
            "lastservername": "pendosandbox.com",
            "lastupdated": 1506358391050,
            "lastuseragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.113 Safari/537.36",
            "lastvisit": 1506358390891,
            "nid": 4
        }
    },
    "accountId": "Epsilon united"
}
Attributes
id
string
Unique identifier for the visitor.
accountIds
string
All Account ID associations for the visitor.
accountId
string
The Account ID last associated with the visitor.

Get visitor by ID

Definition

GET https://app.pendo.io/api/v1/visitor/{visitorId}
requests.get("https://app.pendo.io/api/v1/visitor/{visitorId}")

Example request

curl -X GET \
  https://app.pendo.io/api/v1/visitor/4 \
  -H 'content-type: application/json' \
  -H 'x-pendo-integration-key: 63bd1cda-db5a-4a2b-633b-37b8b0c5462c'
import requests
url = "https://app.pendo.io/api/v1/visitor/4"
headers = {
    'x-pendo-integration-key': "63bd1cda-db5a-4a2b-633b-37b8b0c5462c",
    'content-type': "application/json"
}
response = requests.get(url, headers = headers)

Example response

{
    "id": "4",
    "email": "",
    "accountIds": [
        "Epsilon united"
    ],
    "metadata": {
        "agent": {
            "email": "quam.quis@eratvolutpat.edu",
            "ipaddress": "204.16.137.138",
            "language": "en_US"
        },
        "auto": {
            "accountid": "Epsilon united",
            "accountids": [
                "Epsilon united"
            ],
            "firstvisit": 1506351511034,
            "id": "4",
            "idhash": 4088798008,
            "lastbrowsername": "Chrome",
            "lastbrowserversion": "60.0.3112",
            "lastoperatingsystem": "Mac OS X",
            "lastservername": "pendosandbox.com",
            "lastupdated": 1506358391050,
            "lastuseragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.113 Safari/537.36",
            "lastvisit": 1506358390891,
            "nid": 4
        }
    },
    "accountId": "Epsilon united"
}

Gets a visitor object using an Visitor ID.

Details
Method GET
URI /api/v1/visitor/{visitorId}
Parameters visitorId - URL encoded visitor id or b64_XXXX, where XXXX is a URL-safe base64 encoded visitor Id
Request Headers content-type: application/json
x-pendo-integration-key: <PENDO_INTEGRATION_KEY>
Status Codes 200: Response is sent as body
404: Error while getting visitor, no such entity found

Get visitor history for a time period

Definition

GET https://app.pendo.io/api/v1/visitor/{id}/history?starttime={starttime}
requests.get("https://app.pendo.io/api/v1/visitor/{visitorId}/history", params = "starttime={starttime}")

Example request

curl -X GET \
  https://app.pendo.io/api/v1/visitor/4/history?starttime=1506341326000 \
  -H 'content-type: application/x-www-form-urlencoded' \
  -H 'x-pendo-integration-key: 63bd1cda-db5a-4a2b-633b-37b8b0c5462c'
import requests
url = "https://app.pendo.io/api/v1/visitor/4/history"
params = {
    "starttime": "1506341326000"
}
headers = {
    'x-pendo-integration-key': "63bd1cda-db5a-4a2b-633b-37b8b0c5462c",
    'content-type': "application/x-www-form-urlencoded"
}
response = requests.get(url, headers = headers, params = params)

Example response

[{
        "type": "untagged",
        "ts": 1506351480000,
        "parsedUserAgent": {
            "name": "Chrome",
            "version": "60.0.3112",
            "os": "Mac OS X"
        },
        "duration": 120000,
        "lastTs": 1506351600000,
        "untaggedUrl": "http://pendosandbox.com/index.html"
    },
    {
        "type": "feature",
        "ts": 1506351551911,
        "uri": "://app.pendo.io/api/s/5335432811773952/feature/OFjRasLtgMG8_74hpiXdzVD7PH8",
        "parsedUserAgent": {
            "name": "Chrome",
            "version": "60.0.3112",
            "os": "Mac OS X"
        },
        "featureId": "OFjRasLtgMG8_74hpiXdzVD7PH8"
    },
    {
        "type": "feature",
        "ts": 1506351555327,
        "uri": "://app.pendo.io/api/s/5335432811773952/feature/DZc-w_WWNR_ia-SgtnF9yLntPds",
        "parsedUserAgent": {
            "name": "Chrome",
            "version": "60.0.3112",
            "os": "Mac OS X"
        },
        "featureId": "DZc-w_WWNR_ia-SgtnF9yLntPds"
    },
    {
        "type": "page",
        "ts": 1506353640000,
        "uri": "://app.pendo.io/api/s/5335432811773952/page/aJ0KOADQZVL5h9zQhiQ0q26PNTM",
        "parsedUserAgent": {
            "name": "Chrome",
            "version": "60.0.3112",
            "os": "Mac OS X"
        },
        "duration": 60000,
        "lastTs": 1506353700000,
        "pageId": "aJ0KOADQZVL5h9zQhiQ0q26PNTM"
    },
    {
        "type": "page",
        "ts": 1506358380000,
        "uri": "://app.pendo.io/api/s/5335432811773952/page/aJ0KOADQZVL5h9zQhiQ0q26PNTM",
        "parsedUserAgent": {
            "name": "Chrome",
            "version": "60.0.3112",
            "os": "Mac OS X"
        },
        "duration": 60000,
        "lastTs": 1506358440000,
        "pageId": "aJ0KOADQZVL5h9zQhiQ0q26PNTM"
    }
]

Returns a summary of visitor activity for a 24 hour time period.

Details
Method GET
URI /api/v1/visitor/{id}/history?starttime={starttime}
Parameters id - URL encoded visitor id or b64_XXXX, where XXXX is a URL-safe base64 encoded visitor Id
starttime - Start time for historical data, in milliseconds since the epoch
Request Headers content-type: application/x-www-form-urlencoded
x-pendo-integration-key: <PENDO_INTEGRATION_KEY>
Status Codes 200: The visitor history is returned in the body as a JSON list of objects. An empty list means there was no activity in that time period
404: The visitor is unknown
Response

Page views

{
    "type": "page",
    "pageId": {pageId},
    "uri": {uri},
    "ts": {ts},
    "lastTs": {lastTs}
}

Untagged page views

{
    "type": "untagged",
    "untaggedUrl": {untaggedUrl},
    "ts": {ts},
    "lastTs": {lastTs}
}

Feature usage

{
    "type": "feature",
    "featureId": {featureId},
    "uri": {uri},
    "ts": {ts}
}

Guide views

{
    "type": "guide",
    "guideId": {guideId},
    "guideStepId": {guideStepId},
    "uri": {uri},
    "ts": {ts}
}

Each historical event is a JSON object, each with its own type-dependent fields.

Attributes
type
string
The type of object. Page for example.
(object)id
string
The associated unique identifier or untaggedUrl for the returned resource.
ts
timestamp
Milliseconds after the epoch that the event occurred. For pages, this is the first time the page was seen during consecutive usage.
lastTs
timestamp
Last time in consecutive usage that a page (or untagged page) was seen.
uri
string
API call to get the type-specific object associated with this event (not applicable to untagged pages).

Agent API

As mentioned previously, our Agent API allows developers to programmatically interact with Pendo’s agent. In 95% of cases, there’s really no need to use this API as the default installation snippet should be all that is needed to effectively capture events and deliver guides to end-users. NOTE: any non-documented functionality found in the agent should be considered either internal, or experimental, and more than likely is subject to change in the future. In other words, if it’s not documented here, we don’t recommend using it.

Browser interaction

The following chart displays how the Pendo agent interacts with the browser and loads resources.

agent_browser.png

Functions

Definition

pendo.{functionName}

Example function

pendo.identify("put_visitor_id_here", "put_account_id_here");

Example object format

pendo.identify({
    visitor: {
        id: "put_visitor_id_here",
        name: "Neo",
        email: "neo@thematrix.io",
        role: "admin"
    },
    account: {
        id: "put_account_id_here",
        name: "CorpSchmorp"
    }
});
Functions
initialize() re-initialize the Pendo JavaScript code snippet. It will not reload Pendo guides. They will need to be called manually in the code with the following: pendo.loadGuides(pendo.apiKey, pendo.getVisitorId(), pendo.url.get());
identify() String visitor_id [, String account_id] or Object options. This will potentially send an identify event and a metadata event. This function accepts either a string for just the visitor id or it accepts an Object that will contain at least a visitor object with at least an id field.
isReady() Returns true when the Agent is fully loaded and has an api key.
flushNow() Force a flush of cached event objects.
updateOptions() Used after initialize has been called to update one or more metadata fields.
getVersion() Returns the string for the current Version of the Agent.
findGuideByName() Returns a guide object as JSON if found for the given name.
findGuideById() Returns a guide object as JSON if found for the given id.
showGuideByName() Activates the guide if found for the given name.
showGuideById() Activates the guide if found for the given id.
getVisitorId() Returns the id for the visitor currently being applied to any events being sent to Pendo. Will always be set either by host application or as a generated id.
getAccountId() Returns the id for the account currently being applied to any events being sent to Pendo.
getCurrentUrl() Gets the current url.
toggleLauncher() Causes the Pendo Guide Center to toggle between visible and hidden. Does nothing if the Guide Center should not be shown for the given page.
removeLauncher() Removes the Pendo Guide Center completely. A reload must happen before it will come back.
startGuides() Evaluate all currently loaded guides to see if any of them should be shown.
stopGuides() Clear any showing guides and prevent any loaded guides from rendering but does not erase the loaded guides from memory. Calling startGuides will work just fine after a stopGuides call.
enableDebugging() Extends the global pendo object to include additional access for debugging purposes.
disableDebugging() Removes the debugging extensions.
isDebuggingEnabled() Returns a string indicating debugging status. Or pass a value of true to get a boolean result.

Debugging

Definition

pendo.debugging.{functionName}

Example function

pendo.debugging.getEventCache();
Functions
getEventCache() Returns the cache of unsent event objects.
getAllGuides() Returns all guides for the visitor.
getAutoGuides() Returns all guides that are launched ‘auto’.
getBadgeGuides() Returns all guides that are launched via a Badge.
getLauncherGuides() Returns all guides that are launched via the Guide Center.

These functions will only be available once the debugging module has been enabled.

Alternatively, you can debug and troubleshoot guides with our debugging tool available to agent versions 2.10+. Open up the console and type pendo.enableDebugging() and a small bug should appear in the top left corner.

To stop debugging and remove the icon, simply type pendo.disableDebugging().

NOTE: when enabled, the debugging icon is only visible to you. None of your users will ever see it.

Events

Definition

pendo.events.{eventName}

Example function

pendo.events.guidesLoaded(function() {
    // Do something when guides load
}).guidesFailed(function() {
    // Do something when guides fail to load
});

Example snippet passing event handlers in pendo_options

window.pendo_options = {
    apiKey: '...',
    account: { /* ... */ },
    visitor: { /* ... */ },
    events: {
        ready: function() {
            // Do something when pendo is initialized
        }
    }
}
Events
ready Fired when the Pendo agent is loaded and initialized.
guidesLoaded Fired when guides have loaded successfully.
guidesFailed Fired when guides fail to load. Will only fire when pendo_options.guideTimeout is set to a numeric value (in milliseconds).

Optionally, you may also pass event handlers in your pendo_options.

Guide

Definition

pendo.{functionName}

Example function

pendo.onGuideAdvanced();

These functions are for use from DOM elements inside a guide.

Advance

    <button class='_pendo-guide-next_'>Show me more!</button>

Using your button classes from your HTML above, you can utilize the following snippet to advance to the next step of the guide:

(function wireGuideAdvanceButton(step) {
    step && step.attachEvent(step.guideElement[0], 'click', function (e) {
        var advanceButton = pendo.dom(e.target || e.srcElement).closest('._pendo-guide-next_');
        if (advanceButton.length) {
            pendo.onGuideAdvanced();
        }
    });
})(step,guide);

Advance multiple steps:

(function wireGuideAdvanceButton(step) {
    step && step.attachEvent(step.guideElement[0], 'click', function (e) {
        var advanceButton = pendo.dom(e.target || e.srcElement).closest('._pendo-guide-next_');
        if (advanceButton.length) {
            pendo.onGuideAdvanced({ steps: 2 });
        }
    });
})(step,guide);
Function
onGuideAdvanced([GuideStep step]) Proceed to the next step in a multi-step guide, and sends a guideAdvanced event.
onGuideAdvanced({ steps: count }) Advances both the currently displayed step and the step immediately following the currently displayed step.

Previous

Assumes the previous step is defined on the same page:

<a class='_pendo-guide-previous_'>Back</a>

Javascript:

(function wireGuidePreviousStepButton(step) {
    step && step.attachEvent(step.guideElement[0], 'click', function (e) {
        var previousStep = pendo.dom(e.target || e.srcElement).closest('._pendo-guide-previous_');
        if (previousStep.length) {
            pendo.onGuidePrevious();
        }
    });
})(step,guide);

Assumes the previous step is defined on another page

<a class='_pendo-guide-previous_' href='/url/to/previous/step'>Back</a>

Javascript

(function wireGuidePreviousButton(step) {
    step && step.attachEvent(step.guideElement[0], 'click', function (e) {
        var previousStep = pendo.dom(e.target || e.srcElement).closest('._pendo-guide-previous_');
        if (previousStep.length) {
            pendo.onGuidePrevious();
        }
    });
})(step,guide);
Function
onGuidePrevious([GuideStep step]) Returns the user to the previous step in a multi-step guide

Dismiss

To dismiss the currently displayed guide, add this to your HTML:

<button class='_pendo-guide-dismiss_'>No thanks</button>

Javascript:

(function wireGuideDismissButton(step) {
    step && step.attachEvent(step.guideElement[0], 'click', function (e) {
        var dismissButton = pendo.dom(e.target || e.srcElement).closest('._pendo-guide-dismiss_');
        if (dismissButton.length) {
            pendo.onGuideDismissed();
        }
    });
})(step,guide);
Function
onGuideDismissed([GuideStep step]) Hides the guide and invokes the guideDismissed event
onGuideDismissed({ until: 'reload' }) Dismiss a guide until the next page reload

Options

Options
apiKey Your API key (required)
excludeAllText Do not collect any element text. Default is false.
excludeTitle Do not collect <title> during page load events. Default is false
disablePersistence Do not use cookies to remember any visitor identifiers. This will prevent identifiers from being written to cookies, and will also ignore any identifiers already stored in cookies. Default is false.
guides.delay Guides will be loaded, but not displayed. Call pendo.startGuides() to display guides when you choose to do so. Default is false.
guides.disable Completely disables guides. Default is false.
guides.timeout How long to wait for guides to load (in milliseconds). Default is infinity (i.e. wait forever).
guides.tooltip.arrowSize The tooltip arrow size (in pixels). Default is 15.