Learn about Zingtree's REST API
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 can be 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
The API will also return HTTP Status codes as follows:Adds an agent to your organization
This is a no-login agent, so access must be through SSO or Google Authentication
https://zingtree.com/api/agent_add/{{apikey}}/{{agent name}}/{{agent login}}
https://zingtree.com/api/agent_add/6a103737e44e4aa6e1e4b6b0bcb46f83/Bill%20Zing/billzing@mydomain.com
zt_agent_add('6a103737e44e4aa6e1e4b6b0bcb46f83', 'Bill Zing', 'billzing@mydomain.com');
{"count":1,"agent_name":"Bill Zing","agent_login":"billzing@mydomain.com"}
Set or update tags for an agent in your organization. Multiple tags are separated by commas.
https://zingtree.com/api/agent_tag/{{apikey}}/{{agent login}}/{{tags}}
https://zingtree.com/api/agent_tag/6a103737e44e4aa6e1e4b6b0bcb46f83/billzing@mydomain.com/tag1,tag2
zt_agent_tag('6a103737e44e4aa6e1e4b6b0bcb46f83', 'billzing@mydomain.com','tag1,tag2');
{
"op": "agent_tag",
"result": "Success",
"agent_login": "billzing@mydomain.com"
}
Removes an agent from your organization
https://zingtree.com/api/agent_remove/{{apikey}}/{{agent login}}
https://zingtree.com/api/agent_remove/6a103737e44e4aa6e1e4b6b0bcb46f83/billzing@mydomain.com
zt_agent_remove('6a103737e44e4aa6e1e4b6b0bcb46f83', 'billzing@mydomain.com');
{
"count":1,
"agent_login":"billzing@mydomain.com"
}
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.
https://zingtree.com/api/agent_sessions/{{apikey}}/{{agent}}/{{start date}}/{{end date}}
https://zingtree.com/api/agent_sessions/6a103737e44e4aa6e1e4b6b0bcb46f83/*/2024-04-11/2024-04-18
zt_agent_sessions('6a103737e44e4aa6e1e4b6b0bcb46f83', '*', '2024-04-11', '2024-04-18');
{
"op":"agent_sessions",
"count":3,
"agent":"",
"start_date":"2016-03-20",
"end_date":"2016-03-20",
"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"}}
]
}
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)
https://zingtree.com/api/delete_file_upload/{{folder}}/{{file name}}
https://zingtree.com/api/delete_file_upload/pdf/Original_Document_Node-PREVIEW-734273024-1590648603-1590648630.pdf
zt_delete_file_upload ("pdf", "Original_Document_Node-PREVIEW-734273024-1590648603-1590648630.pdf");
{ "result":"OK" }
Deletes any form data entered into Zingtree during a session.
https://zingtree.com/api/session/{{session ID}}/delete_form_data
https://zingtree.com/api/session/Gallery55-14866585251316/delete_form_data
zt_delete_form_data ("Gallery55-14866585251316");
{ "result":"OK" }
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.
https://zingtree.com/api/event_log/{{apikey}}/{{start date}}/{{end date}}
https://zingtree.com/api/event_log/6a103737e44e4aa6e1e4b6b0bcb46f83/2024-04-11/2024-04-18
zt_event_log('6a103737e44e4aa6e1e4b6b0bcb46f83', '2024-04-11', '2024-04-18');
{
"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": "bill@zingtree.com",
"details": "Auto-Sent via Email Node #5. Result: queued. Update: send.",
"timestamp": "2019-08-21 18:54:45",
"ip": "54.70.2.21"
},
]
}
Returns a JSON structure with form variables and values entered during a session.
https://zingtree.com/api/session/{{session ID}}/get_form_data
https://zingtree.com/api/session/Gallery122-15513801703897/get_form_data
zt_get_form_data ("Gallery122-15513801703897");
{
"name":"Bill Zing",
"comment":"I think Zingtree is great!"
}
Returns a JSON structure with details about a session.
https://zingtree.com/api/session/{{session ID}}/get_session_data
https://zingtree.com/api/session/Gallery122-15513801703897/get_session_data
zt_get_session_data ("Gallery122-15513801703897");
{
"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"
}
]
}
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.
https://zingtree.com/api/session/{{session ID}}/get_session_data_pure
https://zingtree.com/api/session/Gallery122-15513801703897/get_session_data_pure
zt_get_session_data_pure ("Gallery122-15513801703897");
{
"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"
}
]
}
Returns a JSON structure with agent-entered notes from a session.
https://zingtree.com/api/session/{{session ID}}/get_session_notes
https://zingtree.com/api/session/Gallery122-15513801703897/get_session_notes
zt_get_session_notes ("Gallery122-15513801703897");
{
"notes":"These are sample notes entered for this session.",
}
Returns a JSON structure with all tags used in your organization's trees.
https://zingtree.com/api/tree/{{apikey}}/get_tags
https://zingtree.com/api/tree/6a103737e44e4aa6e1e4b6b0bcb46f83/get_tags
zt_get_tags ("6a103737e44e4aa6e1e4b6b0bcb46f83");
{
"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"
]
}
Returns a JSON structure with the basic content from a tree.
https://zingtree.com/api/get_tree_structure/{{apikey}}/{{tree id}}
https://zingtree.com/api/get_tree_structure/6a103737e44e4aa6e1e4b6b0bcb46f83/815089605
zt_get_tree_structure ("6a103737e44e4aa6e1e4b6b0bcb46f83",815089605);
{
"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"
}
]
},
...
Returns a JSON structure with all the variables defined and used within a tree.
https://zingtree.com/api/get_tree_variables/{{apikey}}/{{tree id}}
https://zingtree.com/api/get_tree_variables/6a103737e44e4aa6e1e4b6b0bcb46f83/176104936
zt_get_tree_variables ("6a103737e44e4aa6e1e4b6b0bcb46f83",176104936);
{
"op": "get_tree_variables",
"tree_id": 176104936,
"count": 9,
"vars": [
"State",
"address1",
"address2",
"city",
"email",
"name",
"phone",
"product",
"zip"
]
}
Returns a JSON structure with information about all of an organization's trees.
Please note: This only shows trees not marked as hidden in the tree's Settings.
https://zingtree.com/api/tree/{{apikey}}/get_trees
https://zingtree.com/api/tree/6a103737e44e4aa6e1e4b6b0bcb46f83/get_trees
zt_get_trees ("6a103737e44e4aa6e1e4b6b0bcb46f83");
{
"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"}
]
}
Returns a JSON structure with trees that have ALL tags in a comma delimited list.
https://zingtree.com/api/tree/{{apikey}}/get_tree_tag_all/{{taglist}}
https://zingtree.com/api/tree/6a103737e44e4aa6e1e4b6b0bcb46f83/get_tree_tag_all/demo,gallery
zt_get_tree_tag_all('6a103737e44e4aa6e1e4b6b0bcb46f83', 'demo,gallery');
{
"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"}
]
}
Returns a JSON structure with trees that have ANY tags in a comma delimited list.
https://zingtree.com/api/tree/{{apikey}}/get_tree_tag_any/{{taglist}}
https://zingtree.com/api/tree/6a103737e44e4aa6e1e4b6b0bcb46f83/get_tree_tag_any/demo,gallery
zt_get_tree_tag_any('6a103737e44e4aa6e1e4b6b0bcb46f83', 'demo,gallery');
{
"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."}
]
}
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 ^^
https://zingtree.com/api/tree/{{apikey}}/search_trees/{{search text}}
https://zingtree.com/api/tree/6a103737e44e4aa6e1e4b6b0bcb46f83/search_trees/Demo https://zingtree.com/api/tree/6a103737e44e4aa6e1e4b6b0bcb46f83/search_trees/Demo^^Order
zt_search_trees ("6a103737e44e4aa6e1e4b6b0bcb46f83", "Demo");
{
"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"}
]
}
Freezes a session from being continued or shared.
A frozen session can no longer be resumed. If a session resume is attempted the user will start a new session with a new session id.
PUT https://zingtree.com/api/session_freeze
{
"session_id": "session_1234567890",
"project_id": "1234567890"
}
x-api-key: APIKEYHERE
curl --location --request PUT 'https://zingtree.com/api/session_freeze' \
--header 'x-api-key: APIKEYHERE' \
--header 'Content-Type: application/json' \
--data-raw '{
"session_id": "session_1234567890",
"project_id": "1234567890"
}'
{
"op": "session_freeze",
"result": "Session froze."
}
{
"Error": "Error processing request to freeze session. Session not found."
}
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.
If tree is *, return sessions for all trees.
https://zingtree.com/api/tree_sessions/{{apikey}}/{{tree ID}}/{{start date}}/{{end date}}
https://zingtree.com/api/tree_sessions/6a103737e44e4aa6e1e4b6b0bcb46f83/815089605/2024-04-11/2024-04-18
zt_tree_sessions('6a103737e44e4aa6e1e4b6b0bcb46f83', '815089605', '2024-04-11', '2024-04-18');
{
"op": "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
}
]
}
Just like tree_sessions, but uses the time of the last click as a date range.
https://zingtree.com/api/tree_sessions_last_clicked/{{apikey}}/{{tree ID}}/{{start date}}/{{end date}}
https://zingtree.com/api/tree_sessions_last_clicked/6a103737e44e4aa6e1e4b6b0bcb46f83/815089605/2024-04-11/2024-04-18
zt_tree_sessions_last_clicked('6a103737e44e4aa6e1e4b6b0bcb46f83', '815089605', '2024-04-11', '2024-04-18');
{
"op": "tree_sessions_last_clicked",
"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
}
]
}