Lead Form API endpoint

This method is best used if you have a custom-built form and would like to programatically submit your lead information to our backend API endpoint.

Before you start, and for your own safety...

We highly, highly recommend saving lead information that is submitted to your website in some fashion (local database, text file, email, etc.) before sending it to our API endpoint in case something goes haywire with our servers or yours to prevent leads from getting lost. Several of our customers use the GravityForms plugin for Wordpress sites to handle this.

Get the API Endpoint URL

The first thing you need is to obtain is the correct API endpoint URL. You'll have to get this from Settings -> Lead Forms -> View Setup Codes -> API Endpoint. If you don't have a login to Tripleseat, you'll need to contact your customer and have them provide the URL for you.

The API endpoint URL should look something like:

http://api.tripleseat.com/v1/leads/create.js?public_key=9abe42f759038eab352976e0ba0ad1512asdfasdf

Lead Fields

With the API endpoint URL, now you just need to submit your lead information in the appropriate format. The data must be submitted in XML or JSON format with the following fields:

  • first_name (required)
  • last_name (required)
  • email_address (required)
  • phone_number (required)
  • contact_preference - This can only be "Email" or "Phone"
  • company - Business or company
  • event_description - e.g., Birthday Party or Business Dinner
  • location_id - ID of the location for this event - only necessary if there are multiple locations
  • event_date - Date of the event, e.g., 12/12/2013
  • start_time - e.g., 12pm
  • end_time
  • guest_count
  • additional_information - Any additional details or notes
  • lead_form_id - the lead_form to which this lead belongs
  • email_opt_in - boolean for email opt in (defaults to true)
  • lead_source_id - lead_source_id for this lead (see sites API)

How to get your Location ID's (if you have multiple)
You can pull your installations location ID's by going to following URL:

http://api.tripleseat.com/v1/locations.xml?public_key=[your public key]

How to get your Lead Form ID's
You can pull your installations lead_form ID's by going to following URL:

http://api.tripleseat.com/v1/lead_forms.xml?public_key=[your public key]

How to get your Lead Source ID's
You can pull your installations lead_source ID's by going to following URL:

http://api.tripleseat.com/v1/sites.xml?public_key=[your public key]

Submitting Data via Javascript

The following is an example of how to asynchronously submit data to our endpoint using jQuery.

Please note that in order to send this data cross-domain, we're using JSONP.

Setup the data to be submitted

var data = { 
lead: {
first_name: 'Kevin',
last_name: 'Zink',
phone_number: '123-123-1234',
email_address: 'kevin@tripleseat.com'
},
lead_form_id: 123
}

Submit the data via a JSONP request

$.ajax('http://api.tripleseat.com/v1/leads/create.js?public_key=9abe42f759038eab352976e0ba0ad1512dec53bf', 
{ data: data,
dataType:'JSONP',
crossDomain:true,
success: function(data) {
if (data.errors != undefined) {
// handle errors
} else {
// show data.success_message
}
}
});

Handling a successful response
If the lead data is submitted and no errors are returned, an object will be returned with a success message, which you can then display on screen or ignore.

Handling errors
If the lead data is submitted and there are errors, they will be available in the returned object in a collection called "errors." You can iterate over these errors and display them on screen in whatever fashion you prefer.

Submitting Data via PHP (Wordpress)
The following is an example of how to submit data to our endpoint using Wordpress / PHP.

This method uses Wordpress' wp_remote_post function.

<?php 
$url = 'http://api.tripleseat.com/v1/leads/create.js?public_key={your public key}'; $lead = array(
'lead[first_name]' => 'kevin',
'lead[last_name]' => 'zink',
'lead[email_address]' => 'kevin@tripleseat.com',
'lead[phone_number]' => '123-123-1234',
'lead[company]' => 'tripleseat',
'lead[event_description]' => 'the event desc',
'lead[event_date]' => '1/2/2016',
'lead[start_time]' => '3pm',
'lead[end_time]' => '5pm',
'lead[guest_count]' => 50,
'lead[additional_information]' => 'some more info',
); $response = wp_remote_post( $url, array(
'method' => 'POST',
'timeout' => 45,
'redirection' => 5,
'httpversion' => '1.0',
'blocking' => true,
'headers' => array(),
'body' => $lead,
'cookies' => array()
)
);
?>

Handling a successful response
If the lead data is submitted and no errors are returned, $response will have a body object that will contain a success message.

Handling errors

If the lead data is submitted and there are errors, the response will contain a collection of errors. Example as follows:

{"errors":
{
"First Name":["can't be blank"],
"Last Name":["can't be blank"],
"Email Address":["can't be blank"],
"Phone Number":["can't be blank"]
}
}

Validate Only Request
If you want to submit a request without actually creating a new lead. Add validate_only=true to your request parameters. If the request is valid, you'll receive back a response of "Validation Successful". Otherwise, you'll receive back a list of errors.

Simpler Error Formatting
The default error collection structure might be a bit much for your implementation. So, if you want just a simple list of errors, add the following parameter to your POST data:

simple_error_messages: true

With this parameter, the error collection will come back as follows:

{"errors":
[
"First name can't be blank",
"Last name can't be blank",
"Email address can't be blank",
"Phone number can't be blank"
]
}

Other programming languages

If you want to submit data to our API from something other than javascript (PHP, ruby, C#, etc.), you'll have to bundle the data into a JSON object and submit it in a similar fashion as above. If you need assistance in doing this, feel free to contact kevin@tripleseat.com or our support line directly.

Have more questions? Submit a request

Comments