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.
| Field Name | Description | Response Example - Key | Value |
| “id” | The ID Number for the person submitting the Lead. | “Id”: (Numerics), |
| “first_name” | The First Name of the person submitting the Lead. | “first_name”: “(Alphanumerics)”, |
| “last_name” | The Last Name of the person submitting the Lead. | “last_name”: “(Alphanumerics)”, |
| “company” | The Company that the person submitting the Lead is associated with. | “company”: “(Alphanumerics)”, |
| “phone_number” | The Phone Number for the person submitting the Lead. | “phone_number”: “(Alphanumerics)”, |
| “phone_number_extension” | The Extension for the Phone Number provided by the person submitting the Lead. | “phone_number_extension”: “(Alphanumerics)”, |
| “email_address” | The Email Address of the person submitting the Lead. | “email_address”: “(Alphanumerics)”, |
| “additional_information” | Any Additional Information or notes relevant to the Lead being submitted. *It is worth noting that any Non-Tripleseat fields/information would need to be mapped to this field. |
“additional_information": "(Alphanumerics)", |
| “lead_form_id” | The ID Number for the Lead Form this Lead should be attributed to. | “lead_form_id”: (Numerics), |
| “contact_preference” | The Contact Preference for the person submitting the Lead. | “contact_preference”: (Phone/Email/Text), |
| “referral_source_id” | The ID Number of the Referral Source for the person submitting the Lead. |
“referral_source_id”: (Numerics), |
| “referral_source_other” | This field is specific to when the “referral_source_id” is set to 1. This depicts a source of Other, and this field contains the text for a guest/user to provide additional context for the “Other” *This field will display as “null” for all other “referral_source_id” other than 1. |
“referral_source_other”: “(Alphanumerics)”, |
| “event_style” | The requested Event Style for the Lead being submitted. *The available Event Styles are dependent on those that are accepted for the Location in question. The values for these Event Styles are as follows: On-Premise = onpremise Full-Service Catering = catering Pick-Up Catering = pickup Drop-Off Catering = dropoff If an Event Style is not specified this field will display as “null” |
“event_style”: “(onpremise/catering/pickup/dropoff)”, |
| “converted_at” | The Date and Timestamp for when the Lead was converted. *Leads can be converted to an Account/Contact or Account/Contact/Event/Booking altogether. If “null” the Lead has yet to be converted at all and can be considered “Not Converted” within Tripleseat. |
“converted_at”: “MM/DD/YYYY HH:MM AM/PM”, |
| “created_at” | The Date and Timestamp for when the Lead was created. *Leads can be created by a Tripleseat Lead Form, via the API, or manually In-App by a User |
“created_at”: "MM/DD/YYYY HH:MM AM/PM”, |
| “updated_at” | The Date and Timestamp for when the Lead was last Updated. *Creation of the Lead will be considered the very first time a Lead was updated. If a lead has never been edited/updated, the “created_at” and “updated_at” will match. |
“updated_at”: “MM/DD/YYYY HH:MM AM/PM”, |
| “deleted_at” | The Date and Timestamp for when the Lead was deleted. *Leads can be deleted via the API or manually In-App by a User. If “null” the Lead has yet to be deleted. |
“deleted_at”: “MM/DD/YYYY HH:MM AM/PM”, |
| “customer_id” | The ID Number for the Customer that the Lead belongs to. *For additional clarity, the Customer is a collection of all Sites and their associated Locations. Customer -> Site(s) -> Location(s) -> Lead(s) |
“customer_id”: (Numerics), |
| “site_id” | The ID Number for the Site the submitted Lead’s Location belongs to. *For additional clarity, the Site is a collection of their associated Locations. Customer -> Site(s) -> Location(s) -> Lead(s) |
“site_id”: (Numerics), |
| “turned_down_at” | The Date and Timestamp for when the Lead was turned down. *Turning down a Lead can be used when either the customer or the venue will no longer move forward. If “null” the Lead has yet to be turned down. Restoring a Lead can be completed In-App, which will change this value back to “null.” |
“turned_down_at”: “MM/DD/YYYY HH:MM AM/PM”, |
| “turned_down_reason” |
The reason entered when turning down the Lead.
*This field is a text field filled out by the User in-app. |
“turned_down_reason”: “(Alphanumerics)”, |
| “booking_lead” | An indicator of if the Lead is in the Booking Lead format. | “booking_lead”: (true/false), |
| “email_opt_in” | An indicator that the person submitting the Lead opted in for mass emailing/promotions from the Venue. | “email_opt_in”: (true/false), |
| “event_description” | A description or nature of the Event that the person submitting the Lead is looking to have. *This field will become the Event Name when the lead is converted. |
“event_description”: “(Alphanumerics)”, |
| “guest_count” | The number of guests the person submitting the Lead is expecting to attend. | “guest_count”: (Numerics), |
| “event_date” | The date for the Event requested by the person submitting the Lead. | “event_date”: “MM-DD-YYYY”, |
| “campaign_name” | The value used when identifying a specific product promotion or strategic campaign. | “campaign_name”: “(Alphanumerics)”, |
| “campaign_source” | The value used when identifying a search engine, newsletter name, or another source. | “campaign_source”: “(Alphanumerics)”, |
| “campaign_medium” | The value used when identifying a medium such as an email or cost-per-click. | “campaign_medium”: “(Alphanumerics)”, |
| “campaign_term” | The value used to note the keywords for this ad. | “campaign_term”: “(Alphanumerics)”, |
| “campaign_content” | The value used to differentiate ads or links that point to the same URL. | “campaign_content”: “(Alphanumerics)”, |
| “lead_sources” | Array | An array or “collection” of IDs and Names of the Lead Sources the Lead is attributed to. *If there is a single Lead Source, it will still be displayed within an array. |
“Lead_sources”: [ { “id”: (Numerics), “name”: “(Alphanumerics)” } ], |
| “start_time” | The start time for the Event requested by the person submitting the Lead. | “start_time”: “HH:MM AM/PM”, |
| “end_time” | The end time for the Event requested by the person submitting the Lead. | “end_time”: “HH:MM AM/PM”, |
| “owner” | The User within Tripleseat that owns the Lead. |
“owner”: { “first_name”: “(Alphanumerics)”, “last_time”: “(Alphanumerics)” }, |
| "owned_by" | Used in a Lead POST to assign a User ID as the lead owner | "owned_by": (Numerics) |
| “location” | The Location for the Event requested by the person submitting the Lead. |
“location”: { “id”: (Numerics), “name”: “(Alphanumerics)”, “customer_id”: (Numerics), “site_id”: (Numerics) }, |
|
"market_segment_id"
|
The ID of the market segment dropdown options available in Tripleseat. | "market_segment_id": (numerics) |
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 “&”.
| Parameter | Value |
| query | First/Last Name, Email Address, Phone Number |
| order | first_name, last_name, company, created_at, updated_at |
| sort_direction | desc, asc |
| email_opt_in | true |
| page | (Numerics starting at 1) |
| lead_status | all (defaults to all conversion statuses with the exception of deleted), not_converted, turned_down, deleted, converted_to_account, and converted_to_booking |
| created_after | Matches Leads with a created_at greater than or equal to the parameter value. ISO8601 format | YYYY-MM-DDThh:mm:ss |
| created_before | Matches Leads with a created_at less than or equal to the parameter value. ISO8601 format | YYYY-MM-DDThh:mm:ss |
| site_id | numerics |
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',