Zingtree API
Learn about Zingtree's REST API
Overview
Zingtree makes it easy to find trees, or import data from your sessions into any other system via a standard API. This is primarily for use in scheduled jobs, after the user sessions have occurred. For sending and receiving data during a decision tree session, please refer to Zingtree Webhooks instead.
Zingtree uses a RESTful API, with easy support for any language. You can also use our PHP wrapper, or this Python source code and command line interface.
If needed, your API Key is found at the bottom of the Account, Organizations and Billing page.
The following operations are available:
All results are returned in JSON format. The examples below use trees and sessions from the Zingtree Gallery.
Please Note: There is a limit of 6000 API calls per day for each organization.
Status Codes
200 (Success): The query was successful.
404 (Not Found): The session ID or API Key was not found.
500 (Server Error): The operation requested is not supported.
Description:
Adds an agent to your organization
This is a no-login agent, so access must be through SSO or Google Authentication
Structure:
Live Example:
Example PHP call:
Example Return:
Description:
Set or update tags for an agent in your organization. Multiple tags are separated by commas.
Structure:
Live Example:
Example PHP call:
Example Return:
Description:
Removes an agent from your organization
Structure:
Live Example:
Example PHP call:
Example Return:
Description:
Returns a JSON structure with session information for a particular agent and date range.
Start date and end date are in the form of YYYY-MM-DD. If blank, returns sessions for last 30 days.
If agent is *, return sessions for all agents.
Structure:
Live Example:
Example PHP call:
Example Return:
"sessions":[{
"session_id":"9f5a6cb4b1dd47c990e230abbdc5baf2","agent":"Bill","start_time":"2016-03-20 00:07:55","resolution_state":"Y","total_score":"0","tree_id":"815089605"}}, {"session_id":"23cd2c6474724190ac551223971a6f54","agent":"Tom","start_time":"2016-03-20 00:12:16","resolution_state":"N","total_score":"0","tree_id":"815089605"}},
{"session_id":"Gallery24-14584700538357","agent":"","start_time":"2016-03-20 03:34:13","resolution_state":"?","total_score":"0","tree_id":"815089605"}}
]}
Description:
Deletes an uploaded file from the Zingtree server. (The examples below would delete a file at https://uploads.zingtree.com/pdf/Original_Document_Node-PREVIEW-734273024-1590648603-1590648630.pdf)
Structure:
Live Example:
Example PHP call:
Example Return:
"result":"OK",
}
Description:
Deletes any form data entered into Zingtree during a session.Structure:
Structure:
Example PHP call:
Example Return:
"result":"OK",
}
Description:
Returns a JSON structure with the event log for your organization in a date range.
Start date and end date are in the form of YYYY-MM-DD. If blank, returns events for last 30 days. Dates are in PST.
Structure:
Live Example:
Example PHP call:
Example Return:
"op": "event_log",
"count": 3,
"results": [
{
"severity": "0",
"type": "Webhook",
"tree_id": "203643337",
"user_name": "Zingtree",
"session_id": "Gallery66-15663071273739",
"data": "https:\/\/zingtree.com\/apps\/webhook\/filters\/zippopotamus.php?zip=75013",
"details": "{\"zip\":\"75013\",\"state\":\"Texas\",\"state_abbreviation\":\"TX\",\"city\":\"Allen\"}",
"timestamp": "2019-08-20 06:18:51",
"ip": "192.2.2.2"
},
{
"severity": "0",
"type": "Tree Changed",
"tree_id": "958060817",
"user_name": "Bill Zing ",
"session_id": "",
"data": "958060817",
"details": "Designer - Add Button from Node #1 to Node #16",
"timestamp": "2019-08-22 12:41:44",
"ip": "54.1.1.1"
},
{
"severity": "0",
"type": "Email Sent",
"tree_id": "591588065",
"user_name": "Zingtree",
"session_id": "f8dca0dfb9b44477acf0b7c2dd2d1347",
"data": "[email protected]",
"details": "Auto-Sent via Email Node #5. Result: queued. Update: send.",
"timestamp": "2019-08-21 18:54:45",
"ip": "54.70.2.21"
},
]
}
Description:
Returns a JSON structure with form variables and values entered during a session.
Structure:
Example PHP call:
Example Return:
"name":"Bill Zing",
"comment":"I think Zingtree is great!"
}
Description:
Returns a JSON structure with details about a session.
Structure:
Example PHP call:
Example Return:
"op": "get_session_data",
"source": "Gallery User",
"os": "Win10",
"browser": "Chrome Generic",
"start_time_pst": "2029-03-01 13:01:00",
"start_time_utc": "2029-03-01 9:01:00",
"last_click_time_pst": "2019-03-01 15:01:00",
"last_click_time_utc": "2019-03-01 11:01:00",
"tree_id": "176104936000",
"tree_name": "Life Insurance Sales (with Form Fields & Verification)",
"total_score": "0",
"ip": "0.0.0.0",
"result": "Y",
"notes": "This is an example note",
"time_spent": "4:10",
"duration_seconds": 250,
"path": [
{
"question": "?",
"page_title": "Welcome",
"subtree": "Life Insurance Sales (with Form Fields & Verification)",
"from_node_id": "12",
"to_node_id": "1",
"source": "Gallery User",
"seq": 1,
"time": "1:02",
"seconds": 62,
"button_text": "Continue"
},
{
"question": "How long should the policy last?",
"page_title": "Welcome",
"subtree": "Life Insurance Sales (with Form Fields & Verification)",
"from_node_id": "1",
"to_node_id": "2",
"source": "Gallery User",
"seq": 2,
"time": "1:11",
"seconds": 71,
"button_text": "10 years or less"
}
]
}
Description:
Returns a JSON structure with details about a session. This is identical to get_session_data, except it eliminates the back and restart operations, returning a "pure" linear path through the tree.
Structure:
Example PHP call:
Example Return:
"op": "get_session_data",
"source": "Gallery User",
"os": "Win10",
"browser": "Chrome Generic",
"start_time_pst": "2029-03-01 13:01:00",
"start_time_utc": "2029-03-01 9:01:00",
"last_click_time_pst": "2019-03-01 15:01:00",
"last_click_time_utc": "2019-03-01 11:01:00",
"tree_id": "176104936000",
"tree_name": "Life Insurance Sales (with Form Fields & Verification)",
"total_score": "0",
"ip": "0.0.0.0",
"result": "Y",
"notes": "This is an example note",
"time_spent": "4:10",
"duration_seconds": 250,
"path": [
{
"question": "?",
"page_title": "Welcome",
"subtree": "Life Insurance Sales (with Form Fields & Verification)",
"from_node_id": "12",
"to_node_id": "1",
"source": "Gallery User",
"seq": 1,
"time": "1:02",
"seconds": 62,
"button_text": "Continue"
},
{
"question": "How long should the policy last?",
"page_title": "Welcome",
"subtree": "Life Insurance Sales (with Form Fields & Verification)",
"from_node_id": "1",
"to_node_id": "2",
"source": "Gallery User",
"seq": 2,
"time": "1:11",
"seconds": 71,
"button_text": "10 years or less"
}
]
}
Description:
Returns a JSON structure with agent-entered notes from a session.
Structure:
Example PHP call:
Example Return:
"notes":"These are sample notes entered for this session.",
}
Description:
Returns a JSON structure with all tags used in your organization's trees.
Structure:
Example PHP call:
Example Return:
"op": "get_tags",
"count": 19,
"tags": [
"astrodemo",
"astrology",
"call_center",
"demo",
"demo_agent",
"gallery",
"insurance",
"master_finder",
"medical",
"misc",
"pet_rock",
"PL_FAQ",
"retail",
"support",
"testtag",
"webhooks",
"zingtree",
"zingtree_demos",
"zinsurance"
]
}
Description:
Returns a JSON structure with the basic content from a tree.
Structure:
Example PHP call:
Example Return:
"tree_id": "815089605",
"tree_name": "Agent Script - Set Appointment",
"description": "This demo shows an example of how to script a maintenance appointment.",
"root_node_id": "1",
"nodes": [
{
"node_id": "1",
"page_title": "Welcome",
"question": "Would you like to schedule a time for a technician to come out in the next week?",
"success": "?",
"content": "This is Sheryl with Acme Water Systems. I see in my system you are due for routine maintenance for your water filtration system.<\ p="">",</\>
"keywords", "",
"tags": "",
"buttons": [
{
"button_text": "Yes",
"button_link": "2"
},
{
"button_text": "No",
"button_link": "3"
}
]
},
...
Description:
Returns a JSON structure with all the variables defined and used within a tree.
Structure:
Example PHP call:
Example Return:
"op": "get_tree_variables",
"tree_id": 176104936,
"count": 9,
"vars": [
"State",
"address1",
"address2",
"city",
"email",
"name",
"phone",
"product",
"zip"
]
}
Description:
Returns a JSON structure with information about all of an organization's trees.
Structure:
Example PHP call:
Example Return:
"op":"get_trees",
"count":3,
"trees": [
{"name":"Pet Rock Demo","description":"Zingtree demo using the Pet Rock","tree_id":"164166011", "tags":"gallery troubleshooting"},
{"name":"Intercom.io Demo","description":"Shows how to gather data and insert it into an Intercom.io chat window.","tree_id":"172041421", "tags":"gallery chat"},
{"name":"Narcissist Test","description":"Narcissism test, adapted from The Narcissist Test by Dr Craig Malkin\r\n\r\n","tree_id":"229818441", "tags":"gallery scoring"}
]}
Description:
Returns a JSON structure with trees that have ALL tags in a comma delimited list.
Structure:
Live Example:
Example PHP call:
Example Return:
"count":1,
"results":[
{"id":"14","name":"Astrology Site - Troubleshooting Demo","tags":"demo,gallery,testtag2","description":"Interactive guide to assist subscribers who have questions about their account"}
]}
Description:
Returns a JSON structure with trees that have ANY tags in a comma delimited list.
Structure:
Live Example:
Example PHP call:
Example Return:
"count":4,
"results":[
{"id":"14","name":"Astrology Site - Troubleshooting Demo","tags":"demo,gallery,testtag2","description":"Interactive guide to assist subscribers who have questions about their account"},
{"id":"120169628","name":"Zapier Demo","tags":"gallery","description":"Demonstrates how to send data from Zingtree to 500+ apps supported by Zapier."},
{"id":"164166011","name":"Pet Rock Demo","tags":"gallery","description":"Zingtree demo using the Pet Rock"},
{"id":"207620939","name":"What To Wear Demo","tags":"demo","description":"This is a tree for the \"What to Wear\" example used in the tutorials."}
]}
Description:
Returns a JSON structure with information about all of an organization's trees and nodes matching search text. The searches look for a match on any phrase in the node title, content, question and search keywords.
You can use multiple search keywords for an AND search operation. To do this, separate the search terms in the search text with ^^
Structure:
Live Example:
Example PHP call:
Example Return:
"count":6,
"results": [
{"tree_id":"225470905","name":"Form Fields and Data Entry Demo","node":"2","page_title":"Summary"},
{"tree_id":"539252574","name":"Freshdesk Integration example","node":"1","page_title":"Welcome"},
{"tree_id":"172041421","name":"Intercom.io Demo","node":"1","page_title":"Start"},
{"tree_id":"164166011","name":"Pet Rock Demo","node":"1","page_title":"The Care and Training of Your PET ROCK"},
{"tree_id":"867287049","name":"Zingtree Tour","node":"1","page_title":"Zingtree Tour"},
{"tree_id":"723996162","name":"Zopim Demo","node":"1","page_title":"Start"}
]}
Description:
Returns a JSON structure with session information for a particular tree ID and date range.
Start date and end date are in the form of YYYY-MM-DD. If blank, returns sessions for last 30 days.
You can also use date and time (PST) instead of date. These would be like YYYY-MM-DD HH:MM:SS. When calling a URL like this, replace the space character with %20.
f tree is *, return sessions for all trees.
Structure:
Live Example:
Example PHP call:
Example Return:
"op": "find_tree_sessions",
"count": 5,
"tree_id": 815089605,
"start_date": "2016-03-20 00:00:00",
"end_date": "2016-03-20 23:59:59",
"sessions": [
{
"session_id": "9f5a6cb4b1dd47c990e230abbdc5baf2",
"agent": "",
"start_time": "2016-03-20 00:07:55",
"last_click_time": "2016-03-20 00:12:11",
"resolution_state": "Y",
"total_score": "0",
"tree_id": "815089605",
"duration": 256
},
{
"session_id": "23cd2c6474724190ac551223971a6f54",
"agent": "",
"start_time": "2016-03-20 00:12:16",
"last_click_time": "2016-03-20 00:12:21",
"resolution_state": "Y",
"total_score": "0",
"tree_id": "815089605",
"duration": 5
},
{
"session_id": "Gallery53-14584801286490",
"agent": "",
"start_time": "2016-03-20 06:22:09",
"last_click_time": "2016-03-20 06:22:37",
"resolution_state": "Y",
"total_score": "0",
"tree_id": "815089605",
"duration": 28
},
{
"session_id": "Gallery53-1458502196365",
"agent": "",
"start_time": "2016-03-20 12:29:58",
"last_click_time": "2016-03-20 12:30:23",
"resolution_state": "Y",
"total_score": "0",
"tree_id": "815089605",
"duration": 25
},
{
"session_id": "Gallery53-14585149488285",
"agent": "",
"start_time": "2016-03-20 16:02:31",
"last_click_time": "2016-03-20 16:02:37",
"resolution_state": "Y",
"total_score": "0",
"tree_id": "815089605",
"duration": 6
}
]
}