Light Blue Software - API documentation

The Light Blue API

For all of our customers who are subscribed to our online services, or trialling them, we offer an API which will allow you to send data directly into your Light Blue account. This incoming data appears in the Inbox in the Mac OS X and Windows versions of Light Blue 5. For example, you could set up the contact form on your website to post messages directly into Light Blue's Inbox, from which you can create new enquiries and contact records without needing to retype anything. Wedding & corporate photographers could use our API to capture extra information from their clients in a special form on their website (e.g. a list of shoot requests, or contact details) and you can use this information to update the relevant shoot record in Light Blue directly from the Inbox.

The Light Blue API is being used by photographers all over the world, but anything related to the web is always evolving so it's entirely possible that bugs could appear when something outside of our control is changed. If you find any oddities in the Light Blue API, please let us know!

Contents

Overview

Using the Light Blue API with ProPhoto 5 sites

Using the Light Blue API plugin for WordPress / GravityForms

Using the Light Blue API with MachForm

Sending data directly to the Light Blue API via HTTP POST

HTTP POST result

HTTP POST example

Data types

Supported parameters

Importing multiple contacts in a single API call

Combining miscellaneous values

Overview

The Light Blue API lets you send data from web forms into Light Blue. The information will come into your Inbox in Light Blue, from where you can either convert it into a new Shoot or Contact record, or update an existing record.

The API currently allows you to send information about shoots and contacts to Light Blue. Other types of information are not currently supported, but if you run a service where our mutual customers would benefit from having information from your system appear automatically in Light Blue (e.g. orders placed via your web gallery shopping carts, or invoices that you send to photographers from your lab) then we would love to hear from you.

Currently, there are two different methods that you can use to send data to the Light Blue API:

Using the Light Blue API plugin for ProPhoto 5 sites

Using the ProPhoto theme for WordPress is one of the most popular ways of setting up a professional photography website, and ProPhoto 5 includes a flexible contact form that can be customised to suit your requirements (e.g. by asking your clients to specify the type of shoot they're interested in, their wedding date, etc). We've written a WordPress plugin that lets you link up your ProPhoto 5 contact form to your Light Blue account without needing to write any special code.

Requirements

To use the Light Blue API plugin for ProPhoto, you need to be hosting your own WordPress site (e.g. websites hosted on WordPress.com cannot use plugins) and have the ProPhoto 5 theme installed and activated.

Installation

You can download the plugin from the WordPress Plugins Directory. You need to un-zip the file and copy the folder called 'prophoto-light-blue' to your WordPress plugins directory. This is usually located at wp-content/plugins/ in your WordPress directory. Alternatively, you can use the 'Add New' section of the Plugins settings page in your WordPress admin console to search the WordPress Plugins Directory for "light blue" and install the plugin from there.

To set up the Light Blue API plugin for ProPhoto, first go to the Plugins section of your WordPress admin page and activate it. Next, click the Settings link for the plugin.

In the plugin settings page, you'll need to fill in your Light Blue API key. You can find your API key by logging into the My Account section of our website.

Linking the fields on your ProPhoto contact form to the Light Blue API

Once you've installed the Light Blue API plugin for ProPhoto, you need to associate the fields in your forms with parameters that the Light Blue API recognises.

To do this, you need to select your contact form fields from the menus in the 'Field Mappings' section in the plugin settings page, and enter the Light Blue API parameter that you want to send it to into the field next to it. The menu will list all of the fields from your contact form apart from 'Headline text' fields, and the field numbers correspond to those that appear in the 'Form Fields' section of the ProPhoto theme's Contact Form customisation page.

You can find a list of the parameters that the Light Blue API recognises further down on this page. Any fields in your forms that have not had a Light Blue parameter set up for them, or have a parameter that doesn't match a valid Light Blue API paramater, will be ignored but stored in the ProPhoto contact form database as usual.

The next few sections of this documentation aren't relevant to using the Light Blue API plugin for ProPhoto, so you can skip ahead to the list of data types and parameters supported by the Light Blue API.

Using the Light Blue API plugin for WordPress / GravityForms

Many professional photographers have websites that have been built on top of WordPress, and the most popular way of creating contact forms (as well as other forms for gathering data) is to use the GravityForms plugin. We've written a WordPress plugin that lets you link up GravityForms to the Light Blue API without you needing to write any special code.

Requirements

To use the Light Blue API plugin for WordPress / GravityForms, you need to be hosting your own WordPress site (e.g. websites hosted on WordPress.com cannot use plugins) and have GravityForms 1.6 or later installed. You need a current licence for GravityForms, but any of their licences will do.

Installation

You can download the plugin from the WordPress Plugins Directory. You need to un-zip the file and copy the folder called 'gravity-forms-light-blue' to your WordPress plugins directory. This is usually located at wp-content/plugins/ in your WordPress directory. Alternatively, you can use the 'Add New' section of the Plugins settings page in your WordPress admin console to search the WordPress Plugins Directory for "light blue" and install the plugin from there.

To set up the Light Blue API plugin for WordPress, first go to the Plugins section of your WordPress admin page and activate it. Next, click the Settings link for the GravityForms plugin, then 'Light Blue API'.

In the plugin settings page, you'll need to fill in your Light Blue API key. You can find your API key by logging into the My Account section of our website.

If you want to change any of the default settings, such as the date format, you can also do that on the plugin settings page.

Linking GravityForms forms to the Light Blue API

Once you've installed the Light Blue API plugin for WordPress / GravityForms, you need to associate the fields in your forms with parameters that the Light Blue API recognises.

To do this, you need to set the 'Parameter Name' for each field on your forms. You can find the 'Parameter Name' in the form editor, by clicking the 'Edit' button for a field, going to the 'Advanced' tab, checking the 'Allow field to be populated dynamically' box.

You can find a list of the parameters that the Light Blue API recognises further down on this page. Any fields in your forms that do not have their 'Parameter Name' set, or have a 'Parameter Name' that doesn't match a valid Light Blue API paramater, will be ignored but stored in the Gravity Forms entries database as usual.

The next few sections of this documentation aren't relevant to using the Light Blue API plugin for WordPress / GravityForms, so you can skip ahead to the list of data types and parameters supported by the Light Blue API.

Using the Light Blue API with MachForm

Another popular contact form provider is MachForm, and they've linked with the Light Blue API. As with our ProPhoto and Gravity Forms plugins, you don't need to write any special code yourself.

Requirements

You'll need to be using MachForm.

Installation

There's nothing special you need to do!

Linking MachForm forms to the Light Blue API

There are full instructions on how to connect your MachForm form on their website.

You can find a list of the parameters that the Light Blue API recognises further down on this page. Any fields in your forms that do not have their 'value' set, or have a 'value' that doesn't match a valid Light Blue API paramater, will be ignored but processed by MachForm as usual.

The next few sections of this documentation aren't relevant to using the Light Blue API with MachForm, so you can skip ahead to the list of data types and parameters supported by the Light Blue API.

Sending data directly to the Light Blue API via HTTP POST

HEALTH WARNING: This method is designed to be used only by customers who are confident with web scripting languages such as PHP, because you need to write some simple code that will gather information from an HTML form that you've created and send it to our API. If you're not confident that you can do this yourself, you can send your website developer to this page to read this guide.

Information is sent to the Light Blue API using an HTTP POST request to https://online.lightbluesoftware.com/api.php .

The POST request must contain the following key-value pairs:

Text encoding

The Light Blue API expects data to be sent as UTF-8. Data sent using other text encodings is likely to cause problems or require manual tidying when its imported into Light Blue.

HTTP POST result

The Light Blue API will return a status code and, if an error occurred, a summary of that error. The list of status codes will be expanded as the API evolves.

HTTP POST Example

The following PHP sample code uses curl to send a contact name, shoot date, enquiry source and shoot notes to the Light Blue API. Using cURL requires PHP 4.0.2 or later, and PHP needs to have been compiled with the libcurl package. In our experience, most web hosts that offer PHP support include curl.

<?php
	// Build an array of the key-value pairs to be sent to the Light Blue API
	$data = array(
		"Key" => "<YOUR API KEY>",  // You must supply the API key displayed on your account page
		"Type" => "contact form",  // You must supply an API request type
		"DateFormat" => "dd/mm/yyyy",  // If you want to use US-style dates, specify mm/dd/yyyy
		"ContactNameFull" => "Andrew Sample",
		"ShootDate" => "01/01/2014",
		"ShootEnquirySource" => "Advert in What Photographer magazine",
		"Message" => "We're looking for a photographer."
		);
 
	// Set up curl
	$curl_connection = curl_init("https://online.lightbluesoftware.com/api.php");
	curl_setopt($curl_connection, CURLOPT_CONNECTTIMEOUT, 30);
	curl_setopt($curl_connection, CURLOPT_RETURNTRANSFER, True);
	curl_setopt($curl_connection, CURLOPT_SSL_VERIFYPEER, True);
	curl_setopt($curl_connection, CURLOPT_FOLLOWLOCATION, 1);
 
	// Use curl to send the array to the Light Blue API
	curl_setopt($curl_connection, CURLOPT_POSTFIELDS, $data);
	$result = curl_exec($curl_connection);
	curl_close($curl_connection);
?>

Data types

The values that you send in an API call each have one of the following data types. Any data that doesn't match the specified data type will either be ignored or converted by our API to comply with the data type.

Supported parameters

The full list of parameters which are supported is as follows. This list will be expanded as the API evolves.

Key Maps to Type Notes
Message - Text Long This message is displayed in the Inbox, and when you link it to a record in Light Blue it will appear in that record's Activity panel. If your contact form includes a message field, you should map it to this parameter.
ContactNameFull Contact First Name and Contact Last Name Text Split into first name (the first word) and last name (all subsequent words); used to populated Contact First Name and Contact Last Name.
ContactNameFirst Contact First Name Text  
ContactNameLast Contact Last Name Text  
ContactRole Contact Link Role Text  
ContactTitle Contact Title Text  
ContactDateOfBirth Contact Date of Birth Date  
ContactSource Contact Source Text  
ContactEmail Contact Email Text When you import this from your Inbox into Light Blue, the label for this email will be your default label.
ContactPhoneHome Contact Phone Text When you import this from your Inbox into Light Blue, the label for this phone number will always be 'Home', regardless of your default.
ContactPhoneWork Contact Phone Text When you import this from your Inbox into Light Blue, the label for this phone number will always be 'Work', regardless of your default.
ContactPhoneMobile Contact Phone Text When you import this from your Inbox into Light Blue, the label for this phone number will always be 'Mobile', regardless of your default.
ContactAddress1 Address 1 Text When you import this from your Inbox into Light Blue, the label for this address will be set to your default address type.
ContactAddress2 Address 2 Text When you import this from your Inbox into Light Blue, the label for this address will be set to your default address type.
ContactAddress3 Address 3 Text When you import this from your Inbox into Light Blue, the label for this address will be set to your default address type.
ContactAddressCity Address City Text When you import this from your Inbox into Light Blue, the label for this address will be set to your default address type.
ContactAddressCounty Address County Text ContactAddressCounty and ContactAddressState are interchangeable. When you import this from your Inbox into Light Blue, the label for this address will be set to your default address type.
ContactAddressState Address State Text ContactAddressCounty and ContactAddressState are interchangeable. When you import this from your Inbox into Light Blue, the label for this address will be set to your default address type.
ContactAddressPostCode Address Post Code Text ContactAddressPostCode and ContactAddressZIPCode are interchangeable. When you import this from your Inbox into Light Blue, the label for this address will be set to your default address type.
ContactAddressZIPCode Address ZIP Code Text ContactAddressPostCode and ContactAddressZIPCode are interchangeable. When you import this from your Inbox into Light Blue, the label for this address will be set to your default address type.
ContactAddressCountry Address Country Text When you import this from your Inbox into Light Blue, the label for this address will be set to your default address type.
ContactNotes Contact Notes Text Long  
ContactCustomTextX Contact Custom Text X Text X is 1 through 10 (eg ContactCustomText1) and maps to the matching custom field in Light Blue.
ContactCustomDateX Contact Custom Date X Date X is 1 through 5 (eg ContactCustomDate1) and maps to the matching custom field in Light Blue.
ContactCustomAmountX Contact Custom Amount X Currency X is 1 through 5 (eg ContactCustomAmount1) and maps to the matching custom field in Light Blue.
GroupContacts - Boolean If your API request includes multiple contacts (see below), setting GroupContacts to False prevents Light Blue from automatically grouping the contacts for you. GroupContacts defaults to True.
ShootTitle Shoot Title Text  
ShootType Shoot Type Text Must precisely match an existing shoot type name, or it will be ignored when importing from the Inbox into Light Blue.
ShootDate Session Date Date  
ShootTimeStart Session Start Time Time  
ShootTimeEnd Session End Time Time  
ShootLocation Shoot Location Text  
ShootEnquirySource Shoot Enquiry Source Text  
ShootReferralSource Shoot Referral Source Text The Shoot Referral Source field is only displayed in Light Blue if the Shoot Enquiry Source field is set to "referral", so you should make sure that you specify ShootEnquirySource in the same API call as one that uses ShootReferralSource.
ShootRequests Shoot Requests Text Long When importing, this will be split on end of line characters, with one request created for each line. Blank lines are ignored.
ShootNotes Shoot Notes Text Long  
ShootCustomTextX Shoot Custom Text X Text X is 1 through 10 (eg ShootCustomText1) and maps to the matching custom field in Light Blue.
ShootCustomDateX Shoot Custom Date X Date X is 1 through 5 (eg ShootCustomDate1) and maps to the matching custom field in Light Blue.
ShootCustomAmountX Shoot Custom Amount X Currency X is 1 through 5 (eg ShootCustomAmount1) and maps to the matching custom field in Light Blue.

Importing multiple contacts

The Light Blue API allows you to send multiple contacts in a single API call. This can be particularly useful when gathering information from clients about a shoot that involves several people. For example, a wedding photographer could use a form to ask clients for the best man's details, those of the chief bridesmaid, etc.

To send multiple contacts in the same API call, you need to prefix the contact parameters with a number identifying which contact each belongs to. For example:

When you choose to import data with multiple contacts into the desktop version of Light Blue, it will automatically create separate contact records for each of them and link them to the shoot record you're updating. The contacts will automatically be grouped together for you, with the first contact being made the head of the group, unless you supply the optional GroupContacts parameter and give it a value of "False".

Combining miscellaneous values

If your form contains fields that don't fit into the parameters provided by the Light Blue API, we've provided a method for combing multiple form fields into the Message parameter. To do this, prefix each instance of the Message parameter in your form with a unique number and a colon. For example: