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. Please note: this will differ between Standard and Dynamic Lead forms. 

Lead Form Endpoint URL example:

https://api.tripleseat.com/v1/leads/create.js?public_key=[your public key]

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:

Fields 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) 

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

https://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:

https://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:

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

Lead Forms

This section will cover how to submit Leads to Tripleseat using the /leads endpoint. This will allow you to connect leads submitted via the API to a Standard Tripleseat Lead Form ID for tracking if desired. With the release of Dynamic Forms, v1/leads/create now allows you to pass values to existing custom fields on the Lead Object in Tripleseat. To create a lead custom field in-app, head to Settings > Custom Fields > Event Fields > New Field. Here, you have the option to create the desired field, and check off 'add to lead object' for use in the Leads API. 

Example Post URL

https://api.tripleseat.com/v1/leads/create.js?public_key=[your public key]&lead[first_name]=Kevin&lead[last_name]=Zink...

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('https://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
   }
 } 
});

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 = 'https://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()
  )
 );
?>

JSON Body Example:

{
"lead":{
"first_name": "String",
"last_name": "String",
"email_address": "String",
"phone_number": "String",
"location_id": 1111,
"event_style": "String",
"offsite_address_attributes": {
"address1": "String",
"address2": "String",
"zip_code": 11111,
"city": "String",
"state": "String"
}
}
}

Here is how this might look in a program like PostMan

Custom Fields

With the release of Dynamic Forms, v1/leads/create now allows you to pass values to existing custom fields on the Lead Object in Tripleseat. To create a lead custom field in-app, head to Settings > Custom Fields > Event Fields > New Field. Here, you have the option to create the desired field, and check off 'add to lead object' for use in the Leads API. (See Step 1 of this article)

To include custom fields in your submission, add the custom_field_values_attributes object to your payload, for example:

{
  "lead": {
      "first_name": "String",
      "last_name": "String",
      "email_address": "String",
      "phone_number": "String",
      "custom_field_values_attributes": [{
        "id": "",
        "custom_field_id": integer,
        "value": "string"
      }]
}
}

In the example above, we include the custom_field_id, which is the unique ID for that Lead Custom Field (See Sites API), and the value is the data you would like submitted to the field in-app. Note: the value in the payload must match the accepted data type defined in-app. ID is the ID of the field on the lead record being created/updated, but must be left blank for POST requests. Only needed for PUT/PATCH requests. 

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.

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

GDPR

Depending on where your venue is located and local Privacy Regulations, your form may have a required GDPR Consent checkbox. This primarily impacts venues in California, Canada and Europe. To account for this in the API, you must include this field on your custom form, and map it to the gdpr_consent_granted parameter with the passed value as '1'. This will allow the lead to populate in Tripleseat for venues where this is required. 

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

Using Captcha on your Lead Form
You will want to ensure that the setting 'Enable Spam Detection on Embedded Forms' is Unchecked as there is no endpoint for Captcha in our API.  You can add this to your own server, and if a site visitor passed the Captcha and field requirements, the lead request can be passed on to Tripleseat.
This checkbox is found in Settings>Lead Forms and hit the Edit button on the specific lead form.

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 support@tripleseat.com.