Overview
Pendo Reseller Adopt End Users (AEUs) may want to utilize APIs in order to create segments.
Only Reseller Adopt Subscription Admins have the ability to create API keys. They can create API keys by navigating to Settings > Integrations. If the Integrations tab is unavailable, the API has not been enabled for your Subscription. Please contact your Pendo Reseller Adopt Partner to inquire about API Integration access.
Note: If you sign into your account from somewhere other than adopt.pendo.io you will need to update the endpoint URLs to match the custom hostname.
API Segment Creation
GET List All Segments
List all Segment definitions. Option to filter by segments created via API.
| https://app.pendo.io/api/v1/segment?createdByApi=true |
| Request Headers | |
| Content-Type | application/json |
| x-pendo-integration-key | <PENDO_INTEGRATION_KEY> |
| Query Params | |
| createdByApi (optional defaults to false) |
True: return only segments created via API False: return all segments |
| Response | |
| 200 OK |
[ { "createdByUser": {…}, "createdAt":<date/time>, "lastUpdatedByUser": { … }, "lastUpdatedAt":<date/time>, "kind": "Segment", "id": "<segmentId>", "name": "Test Segment 1", "createdByApi": true, "definition": { … }, "pipeline": [ … ], "dependentMetadata": [... ], "isFocusGroup": false }, { "createdByUser": {…}, "createdAt": <date/time>, "lastUpdatedByUser": { … }, "lastUpdatedAt":<date/time>, "kind": "Segment", "id": "<segmentId>", "name": "Test Segment 2", "createdByApi": false, "definition": { … }, "pipeline": [ … ], "dependentMetadata": [... ], "isFocusGroup": false }, … ] |
| 500 Internal Server Error | “Unexpected error occurred string” |
GET Segment by ID
Get a Segment definition by ID
| https://app.pendo.io/api/v1/segment/:segmentId |
| Request Headers | |
| Content-Type | application/json |
| x-pendo-integration-key | <PENDO_INTEGRATION_KEY> |
| Path variables | |
| segmentId | string |
| Response | |
| 200 OK |
{ "createdByUser": {…}, "createdAt": <date/time>, "lastUpdatedByUser": { … }, "lastUpdatedAt": <date/time>, "kind": "Segment", "id": "<segmentId>", "name": "Test Segment", "createdByApi": true, "definition": { … }, "pipeline": [ … ], "dependentMetadata": [... ], "isFocusGroup": false } |
| 404 Not Found | Segment with the ID provided was not found |
| 500 Internal Server Error | “Unexpected error occurred string” |
POST Create Segment
Create a Segment from a list of visitors.
| https://app.pendo.io/api/v1/segment/upload |
|
{ "name": "<SEGMENT NAME>", "visitors": [ "visitor1", "visitor2", "visitor3", ... "visitorN" ] } |
| Request Headers | |
| Content-Type | application/json |
| x-pendo-integration-key | <PENDO_INTEGRATION_KEY> |
| Request Body | |
| name (required) | string |
| visitors (required) |
List of visitor IDs as strings. Supports up to 10 million visitor IDs |
| Response | |
| 200 OK |
{ "segmentId": <segmentId>, "statusURL": "https://app.pendo.io/api/v1/segment/:segmentId/status” } |
| 400 Bad Request | “Error message as string” |
| 500 Internal Server Error | “Unexpected error occurred string” |
PUT Update Segment
Update a Segment
| https://app.pendo.io/api/v1/segment/:segmentId |
|
{ "name": "<SEGMENT NAME>", "visitors": [ "visitor1", "visitor2", "visitor3", ... "visitorn" ] } |
| Request Headers | |
| Content-Type | application/json |
| x-pendo-integration-key | <PENDO_INTEGRATION_KEY> |
| Path variables | |
| segmentId | string |
| Request Body | |
| Name (optional) | String |
| Visitors |
List of visitor IDs as strings. Supports up to 10 million visitor IDs. |
Note: At least one value is required. Any value provided will be updated and overwrite the previous value. Any value not provided will be left unchanged.
| Response | |
| 200 OK |
{ "segmentId": <segmentId>, "statusURL": "https://app.pendo.io/api/v1/segment/:segmentId/status" } |
| 400 Bad Request | “Error message as string” |
| 404 Not Found | Segment with the ID provided was not found |
| 500 Internal Server Error | “Unexpected error occurred string” |
DELETE Delete Segment
Delete a Segment
| https://app.pendo.io/api/v1/segment/:segmentId |
| Request Headers | |
| Content-Type | application/json |
| x-pendo-integration-key | <PENDO_INTEGRATION_KEY> |
| Path variables | |
| segmentId | string |
| Response | |
| 204 No Content | “” |
| 400 Bad Request | “Error message as string” |
| 404 Not Found | Segment with the ID provided was not found |
| 500 Internal Server Error | “Unexpected error occurred string” |
GET Segment Status
Get the status of a Segment. The Segment status will live for up to 4 hours after processing completes.
| https://app.pendo.io/api/v1/segment/:segmentId/status |
| Request Headers | |
| Content-Type | application/json |
| x-pendo-integration-key | <PENDO_INTEGRATION_KEY> |
| Path variables | |
| segmentId | string |
| Response | |
| 200 OK |
{ } |
| 400 Bad Request | “Error message as string” |
| 404 Not Found | Segment with the ID provided was not found |
| 500 Internal Server Error | “Unexpected error occurred string” |
Access
The endpoints to create, update, and delete Segments will require API access via an Integration key with write access.
Integration Keys
After granting an AEU API access the AEU subscriptions can access their integration key via the settings page.
Here is the user flow the admin of the FI subscription will go through:
- API keys are managed from Settings > Integrations
- They will generate an Integration key by providing a description. They will need to allow write access. If a token isn’t given write access, any POST/PUT/DELETE endpoint will return a 403 Forbidden.
- At that point they can copy the Integration key provided into Smart.
- They can return to this screen to add more keys or delete existing keys.
Processing
Segments are created instantly but adding visitors to the segment takes additional time.
Visitors are added to segments via an asynchronous job. Segments process one at a time (per subscription).
Zoom In
A segment will go through 3 different statuses while adding visitors.
-
Pending: The segment is waiting in queue to be processed. While in this state, the segment is still serving the previous visitor list.
-
Progress: The segment has started processing. While in this state, the segment visitor list will clear.
-
Visitor IDs are sanitized (remove leading and trailing whitespace) and normalized (if “Convert Visitor IDs to Lowercase” subscription flag is enabled, we will lowercase all visitor IDs provided).
-
If any item fails to pass validation, processing will stop and the status will change to “error” and provide an error message. The visitor list will remain empty
-
-
Finish: Processing has completed. The segment visitor list reflects the visitor list from the CSV. The eligible visitor list in the UI will only show visitors for which we’ve received data and are not on the Exclude list.
-
Error: An error occurred during processing.
Wait For It
Processing should begin almost immediately but segments only process one at a time so if multiple updates are sent at one, they will sit in the queue. Once a segment begins processing we don’t expect it to take more than 15 minutes. Processing time will vary depending on the number of visitors.
Sync Frequency
These endpoints are considered bulk create/update endpoints. They should be used for automated updates such as when a user clicks a sync button or a recurring nightly to capture updates. They should not be used for streaming updates every minute (🔜single/small batch updates coming soon!).
FAQ
What happens if the API integration key is revoked?
All APIs will return a 403 Forbidden
What happens if the API integration key isn’t given write access?
The POST/PUT/DELETE endpoints will return a 403 Forbidden
What happens if a segment is deleted and we try to perform an update?
The PUT request will return with a 404 Not Found
What happens if a CSV contains an invalid visitor IDs?
Invalid visitor IDs include strings that are too long (greater than 128 characters) or ones that contain invalid characters. The API request should fail if it receives any invalid visitor IDs. It will return a 400 status code with a descriptive error message.
What happens if an error occurs during processing?
If an unexpected error occurs during processing we will retry. If after all retries have failed, the status will return “error” and the segment will remain empty.