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.

Corner
agent_add

Description:

Adds an agent to your organization

This is a no-login agent, so access must be through SSO or Google Authentication

Structure:

https://zingtree.com/api/agent_add/{{apikey}}/{{agent name}}/{{agent login}}

Live Example:

Example PHP call:

zt_agent_add('6a103737e44e4aa6e1e4b6b0bcb46f83', 'Bill Zing', 'billzing@mydomain.com') ;

Example Return:

{"count":1,"agent_name":"Bill Zing","agent_login":"billzing@mydomain.com"}
agent_tag

Description:

Set or update tags for an agent in your organization. Multiple tags are separated by commas.

Structure:

https://zingtree.com/api/agent_tag/{{apikey}}/{{agent login}}/{{tags}}

Live Example:

Example PHP call:

zt_agent_tag('6a103737e44e4aa6e1e4b6b0bcb46f83', 'billzing@mydomain.com','tag1,tag2') ;

Example Return:

{
   "op": "agent_tag",
   "result": "Success",
   "agent_login": "billzing@mydomain.com"
}
agent_remove

Description:

Removes an agent from your organization

Structure:

https://zingtree.com/api/agent_remove/{{apikey}}/{{agent login}}

Live Example:

Example PHP call:

zt_agent_remove('6a103737e44e4aa6e1e4b6b0bcb46f83', 'billzing@mydomain.com') ;

Example Return:

{"count":1,"agent_login":"billzing@mydomain.com"}
agent_sessions

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:

https://zingtree.com/api/agent_sessions/{{apikey}}/{{agent}}/{{start date}}/{{end date}}

Live Example:

Example PHP call:

zt_agent_sessions('6a103737e44e4aa6e1e4b6b0bcb46f83', '*', '2020-11-27', '2020-12-04') ;

Example Return:

{"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"}}
]}
Corner
delete_file_upload

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:

https://zingtree.com/api/delete_file_upload/{{folder}}/{{file name}}

Live Example:

Example PHP call:

zt_delete_file_upload ("pdf", "Original_Document_Node-PREVIEW-734273024-1590648603-1590648630.pdf") ;

Example Return:

{  
  "result":"OK",
}
Corner
delete_form_data

Description:

Deletes any form data entered into Zingtree during a session.Structure:

Structure:

https://zingtree.com/api/session/{{session ID}}/delete_form_data

Live Example:

Example PHP call:

zt_delete_form_data ("Gallery55-14866585251316") ;

Example Return:

{
  "result":"OK",
}
Corner
event_log

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:

https://zingtree.com/api/event_log/{{apikey}}/{{start date}}/{{end date}}

Live Example:

Example PHP call:

zt_event_log('6a103737e44e4aa6e1e4b6b0bcb46f83', '2020-11-28', '2020-12-05') ;

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": "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"
       },

]
}
Corner
get_form_data

Description:

Returns a JSON structure with form variables and values entered during a session.

Structure:

https://zingtree.com/api/session/{{session ID}}/get_form_data

Live Example:

Example PHP call:

zt_get_form_data ("Gallery122-15513801703897") ;

Example Return:

{  
  "name":"Bill Zing",
  "comment":"I think Zingtree is great!"
}
Corner
get_session_data

Description:

Returns a JSON structure with details about a session.

Structure:

https://zingtree.com/api/session/{{session ID}}/get_session_data

Live Example:

Example PHP call:

zt_get_session_data ("Gallery122-15513801703897") ;

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"
       }
  ]
}
Corner
get_session_data_pure

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:

https://zingtree.com/api/session/{{session ID}}/get_session_data_pure

Live Example:

Example PHP call:

zt_get_session_data_pure ("Gallery122-15513801703897") ;

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"
       }
  ]
}
Corner
get_session_notes

Description:

Returns a JSON structure with agent-entered notes from a session.

Structure:

https://zingtree.com/api/session/{{session ID}}/get_session_notes

Live Example:

Example PHP call:

zt_get_session_notes ("Gallery122-15513801703897") ;

Example Return:

{  
  "notes":"These are sample notes entered for this session.",
}
Corner
get_tags

Description:

Returns a JSON structure with all tags used in your organization's trees.

Structure:

https://zingtree.com/api/tree/{{apikey}}/get_tags

Live Example:

Example PHP call:

zt_get_tags ("6a103737e44e4aa6e1e4b6b0bcb46f83") ;

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"
   ]
}
Corner
get_tree_structure

Description:

Returns a JSON structure with the basic content from a tree.

Structure:

https://zingtree.com/api/get_tree_structure/{{apikey}}/{{tree id}}

Live Example:

Example PHP call:

zt_get_tree_structure ("6a103737e44e4aa6e1e4b6b0bcb46f83",815089605) ;

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"
               }
           ]
       },

...

Corner
get_tree_variables

Description:

Returns a JSON structure with all the variables defined and used within a tree.

Structure:

https://zingtree.com/api/get_tree_variables/{{apikey}}/{{tree id}}

Live Example:

Example PHP call:

zt_get_tree_variables ("6a103737e44e4aa6e1e4b6b0bcb46f83",176104936) ;

Example Return:

{
   "op": "get_tree_variables",
   "tree_id": 176104936,
   "count": 9,
   "vars": [
       "State",
       "address1",
       "address2",
       "city",
       "email",
       "name",
       "phone",
       "product",
       "zip"
   ]
}
Corner
get_trees

Description:

Returns a JSON structure with information about all of an organization's trees.

Structure:

https://zingtree.com/api/tree/{{apikey}}/get_trees

Live Example:

Example PHP call:

zt_get_trees ("6a103737e44e4aa6e1e4b6b0bcb46f83") ;

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"}
]}
Corner
get_tree_tag_all

Description:

Returns a JSON structure with trees that have ALL tags in a comma delimited list.

Structure:

https://zingtree.com/api/tree/{{apikey}}/get_tree_tag_all/{{taglist}}

Live Example:

Example PHP call:

zt_get_tree_tag_all('6a103737e44e4aa6e1e4b6b0bcb46f83', 'demo,gallery') ;

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"}
]}
Corner
get_tree_tag_any

Description:

Returns a JSON structure with trees that have ANY tags in a comma delimited list.

Structure:

https://zingtree.com/api/tree/{{apikey}}/get_tree_tag_any/{{taglist}}

Live Example:

Example PHP call:

zt_get_tree_tag_any('6a103737e44e4aa6e1e4b6b0bcb46f83', 'demo,gallery') ;

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."}
]}
Corner
search_trees

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:

https://zingtree.com/api/tree/{{apikey}}/search_trees/{{search text}}

Live Example:

Example PHP call:

zt_search_trees ("6a103737e44e4aa6e1e4b6b0bcb46f83", "Demo") ;

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"}
]}
Corner
tree_sessions

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:

https://zingtree.com/api/tree_sessions/{{apikey}}/{{tree ID}}/{{start date}}/{{end date}}

Live Example:

Example PHP call:

zt_tree_sessions('6a103737e44e4aa6e1e4b6b0bcb46f83', '815089605', '2020-11-28', '2020-12-05') ;

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