API | Leads Endpoint

A Lead represents a potentially interested person and/or party for outreach. Leads can be converted into Accounts/Contacts and Events/Bookings within Tripleseat.

Lead Fields Overview

Below is a comprehensive list of the fields within the Leads Endpoint. The order displayed below is representative of the order in which they are displayed within a response body of a standard GET request.

GET Request Examples:

GET https://api.tripleseat.com/v1/leads.(XML | JSON)

This request will pull a paginated list of all Leads.

GET https://api.tripleseat.com/v1/leads/(Lead_ID).(XML | JSON)

This request will pull Lead information specific to the ID specified in the request URL.

Leads Search:

GET https://api.tripleseat.com/v1/leads/search.(XML | JSON)?(Search_Parameters)

This request will pull Lead information for any records that match the queried parameters. When you query multiple parameters, you can append parameters together using a “&”.

Multiple Search Parameter Example:

?page=1&sort_direction=desc&order=created_at

The above example would Search the Leads listed on Page 1, in descending order and ordered by the created_at field.

DELETE Request Example:

DELETE https://api.tripleseat.com/v1/leads/(Lead_ID).(XML | JSON)

This request will delete the Lead with the associated ID specified in the request URL.

PUT Request Example:

Leads can be updated by adding the Lead ID to your URL similarly to deletion. Parameters can be added to the URL or passed in a JSON Body, for instance, adding multiple sources to a lead:

{
"lead": {
    "selected_lead_sources":[
      {
      "lead_source_id": 48666 
      },
      {
      "lead_source_id": 72198 
      }
      ] 
    }
}

POST Request Example:

Creating Leads via the API can be done by modifying the Leads Endpoint slightly.

POST https://api.tripleseat.com/v1/leads/create.(XML | JSON)?public_key=(Public_Key)

Now that the URL for the Leads Endpoint has been modified slightly to include /create.(XML | JSON)?public_key=(Public_Key), you can continue to create or submit a Lead by either:

Appending the Lead information to the end of the URL. This would look similar to the following.

POST https://api.tripleseat.com/v1/leads/create.(XML | JSON)?public_key=(Public_Key)&lead[first_name]=Mark&lead[last_name]=Lawrence&etc…

Including the Lead information in the Body of the Request. The following is the URL and the Body, which is in the JSON format.
POST https://api.tripleseat.com/v1/leads/create.(XML | JSON)?public_key=(Public_Key)

{
    "lead":{
        "first_name": "Mark",
        "last_name": "Lawrence",
       etc…
    }
}

Pro-Tips

• The following fields are used for UTM/Analytics tracking (these fields are hidden in Tripleseat until the information is passed along to them; then, the values submitted will appear on the Lead details page)
  • “campaign_name”
  • “campaign_source”
  • “campaign_medium”
  • “campaign_term”
  • “campaign_content”
    
     
• When creating Leads via the API, the most common mistake is forgetting to modify the URL of the request. If the URL is not formatted to include /create.(XML | JSON)?public_key=(Public_Key), you will receive a 404 Not Found status code.
   
• If your Site has more than one Location, you will need to specify which Location the Lead is intended for by including “location_id: (Numerics) in either the Body or the URL as shown above under the header “POST Request Example.” Failing to include the Location ID will result in an error message indicating that the Location ID can not be blank.
   
• If you would like the Lead that is being submitted to be attributed to a specific Lead Form within Tripleseat, you will want to include “lead_form_id”: (Numerics) in either the Body or the URL as shown above under the header “POST Request Example.” Failing to include the Lead Form ID will result in the Lead being submitted with a 200 OK status code; however, no Lead Form will be attributed to Tripleseat.

Adding tasks to a lead

POST api.tripleseat.com/v1/leads/{lead_id}/tasks.json

All the following key/value pairs are required to create a task on a lead, example payload below:

{
    "body": "This is a test task",
    "due_date": "String", // Date/time in ISO 8601 format,
    "priority": integer, // (1 = Low, 2 = Medium, 3 = High)
    "task_type_id": integer, // unique ID for the desired task type (See Sites API)
    "assignee_ids": [], // array containing comma separated User IDs that should be assigned the task (See Users API)
    "site_id": integer, // unique ID for the site the event belongs to
}

Please note: At this time, there is no way to retrieve or update tasks associated to a lead via GET/PUT. 
 

Leads Call Rate Limits

There is a rate limit of 10 requests per second for the following endpoints:

'/v1/leads',
'/v1/leads.json',
'/v1/leads.xml',
'/v1/leads/search',
'/v1/leads/search.xml',
'/v1/leads/search.json',