devincrossman.com

Whether this is your first time developing with an API or not, you might have some trouble when you want to begin interacting with your MINDBODY data. I have created a simple guide will help you understand how the MINDBODY API works and how you can incorporate your MINDBODY business data on your own website using PHP.

How to prepare

You will need to have a web server running PHP with the SOAP extension installed and enabled. This can be a local development server setup (MAMP, WAMP) or an online server such as Digital Ocean who offer easy to manage VPS starting at $5/month.

Get your MINDBODY API credentials

Before you can start integrating your MINDBODY data you will need credentials to access the MINDBODY API. If you are just developing for a single business, follow the steps below. If you want to access the data for more than one business you will need to contact MINDBODY directly for this information.

1. Complete the sign up form at the MINDBODY Partner Program website and write down your sourcename and key.
2. This next step can be tricky. You have to make a call to the SiteService on the MINDBODY SOAP server to get an activation code. I made a form you can fill out instead. (UPDATE: MINDBODY has included this tool on the partner program website) You need the sourcename and key that you wrote down in the first step as well as your site id. If you don’t know what your site id is, log in to your MINDBODY account and check the URL. Your site id comes after “?studioid=” at the end of the URL.
3. Give the activation link and code to the person with the ‘owner’ account for the MINDBODY site you want to access the data of.

Some API methods require user credentials as well. Set up a user for your application by following these steps.

1. Log in to MINDBODY
2. Go to Toolbox -> Setup -> Staff -> Staff Management
3. Click Add New Staff Member
   

   Click on “Add New Staff Member”

4. Enter something for the first and last name. I used first name “web” last name “developer”.
5. Create a staff login with a new username and password and write these down.
   

   Create a staff log in

6. Save your new staff member.

The very basics of SOAP

SOAP is a platform independent protocol for exchanging information between websites. It’s fairly simple and easy to use once you understand how SOAP works. In your situation you want to access your data stored on MINDBODY’s servers. MINDBODY has provided a SOAP server that you can send XML formatted messages to and receive responses from over the http protocol.

Your SOAP messages are written in XML which is a markup language similar to HTML. Luckily using PHP we can abstract away the need to interact with the XML directly so it should make it a lot easier to work with.

The API Docs

You need to know where to send your SOAP requests. In SOAP jargon these destinations are known as endpoints. You can find the endpoints here http://www.mindbodyonline.com/api

Appointment Service
https://api.mindbodyonline.com/0_5/AppointmentService.asmx
Class Service:
https://api.mindbodyonline.com/0_5/ClassService.asmx
Client Service:
https://api.mindbodyonline.com/0_5/ClientService.asmx
Site Service:
https://api.mindbodyonline.com/0_5/SiteService.asmx
Sale Service:
https://api.mindbodyonline.com/0_5/SaleService.asmx
Staff Service:
https://api.mindbodyonline.com/0_5/StaffService.asmx
Data Service:
https://api.mindbodyonline.com/0_5/DataService.asmx

For the purposes of this tutorial we will be consuming the GetClasses method of the Class Service. You can browse the different service definitions and their methods here http://api.mindbodyonline.com/Doc

Creating the MINDBODY_API class

Update: I have created an updated version of this class that you can see at https://github.com/devincrossman/mindbody-php-api.

Now we’re going to create a PHP class to interface with MINDBODY that we can reuse easily in different projects. Open your code editor and create a new PHP document called MINDBODY_API_v0.5.php.

Due to a DDoS attack API requests now require a User-Agent header so the first thing we will do is set the user agent string with the following function

ini_set("user_agent", "FOOBAR");

include this at the top of the MINDBODYAPI_v0.5.php file. If you have the Zend Framework you can take advantage of it’s more robust SOAP classes but it is not a requirement for this project. If you don’t have PHP5 running I recommend using the nuSOAP library for PHP4. If you have PHP5 on your server you can use the native SoapClient class.

Now create the MINDBODY_API_v0.5 class

class MINDBODY_API {

}

Let’s also create some default properties. Inside the MINDBODY_API_v0.5 class add the following code. Substitute your source credentials and user credentials where indicated.

private $client;
private $sourceCredentials = array("SourceName"=>'{SourceName}', "Password"=>'{Password}', "SiteIDs"=>array('{SiteID}'));
private $userCredentials = array("Username"=>'{Username}', "Password"=>'{Password}', "SiteIDs"=>array('{SiteID}'));

We are defining the private variable $client at this scope level so that we can use it in some separate methods for debugging later.

Just a little more SOAP stuff

Now you need to know a little bit more about SOAP and specifically about something called the WSDL. Simply, a WSDL is an XML file that describes a web service. It lists the different methods exposed by a web service, their endpoints, and data types. All you need to know for now is that for MINDBODY the WSDL will be the endpoint url plus “?WSDL” in the query string. For example
https://api.mindbodyonline.com/0_5/ClassService.asmx?WSDL

The getClasses function

Our first attempt should be something easy so we know that our code is working. We’re going to call the GetClasses method of the Class service with no parameters (except our credentials) and it will return information on today’s classes. Understanding how to write this function will help you to write similar functions for other MINDBODY SOAP methods.

Create the following functions in the MINDBODY_API class:

function getClasses($params = array()) {
	$this->client = new SoapClient('https://api.mindbodyonline.com/0_5/ClassService.asmx?WSDL', array("soap_version"=>SOAP_1_1, 'trace'=>true));
	$request = array_merge(array("SourceCredentials"=>$this->sourceCredentials, "UserCredentials"=>$this->userCredentials),$params);
	try {
		$result = $this->client->GetClasses(array("Request"=>$request));
	} catch (SoapFault $s) {
    		echo 'ERROR: [' . $s->faultcode . '] ' . $s->faultstring;
	} catch (Exception $e) {
    		echo 'ERROR: ' . $e->getMessage();
	}
	return $result;
}

function getXMLRequest() {
	return $this->client->__getLastRequest();
}
	
function getXMLResponse() {
	return $this->client->__getLastResponse();
}

The getClasses method accepts one parameter, $params, which can be an array of options to pass to the web service method. If $params is not set it will default to an empty array. You create the SoapClient by passing the WSDL URI, and an optional array of settings. We must set the soap version to 1.1 in order for it to work with MINDBODY and setting trace to true will allow us to use the __getLastRequest() and __getLastResponse() methods.

Calling the getClasses function

You should now have the basic code you need to communicate with MINDBODY’s API. Create a new file and copy this last bit of code into it.

getClasses();
?>
<?= $mb->getXMLRequest(); ?>
<?= $mb->getXMLResponse(); ?>

When you view this page in your browser you will see a <textarea> with the XML code that was generated and sent to MINDBODY and the XML code that you received back. You can use a free XML formatting tool to clean up the formatting so it’s easier to read. This can be useful for diagnostic purposes and seeing the hierarchy of the data.

Passing options to getClasses

Instead of getting classes for today’s date, perhaps you want to get classes for a specific date. You can pass an array of options to the getClasses method. To find out what options are available you will have to check the MINDBODY API docs. For example: to get all of the classes for tomorrow you would use the following code.

$tomorrow,
		"EndDateTime"=>$tomorrow
	);
	$mbResult = $mb->getClasses($params);
?>

Targeting specific data

If you want to address specific information you can use PHP’s object access syntax. The following code lists the names of today’s classes.

foreach($mbResult->GetClassesResult->Classes->Class as $class) {
	echo $class->ClassDescription->Name.'
';
}

Using the MINDBODY API over SSL

Sometimes MINDBODY requires you to call a SOAP method over SSL. In order to do this you have to change the endpoint to begin with https:// One example of when you might need to do this is if you want to update a client’s credit card number. Change the endpoint when you instantiate the PHP SoapClient like this:

$this->client = new SoapClient('https://api.mindbodyonline.com/0_5/ClientService.asmx?WSDL', array("soap_version"=>SOAP_1_1,'location'=>'https://api.mindbodyonline.com/0_5/ClientService.asmx', 'trace'=>true));

Final Code

Trying to figure this all out for the first time can be frustrating. Hopefully this brief introduction has taught you enough that you can start developing with the MINDBODY API straight away. If you have any questions or suggested improvements, let me know in the comments section.

The final code for your MINDBODY_API_v0.5.php file could look like something like this:

ini_set("user_agent", "FOOBAR");
class MindBody_API {
	protected $client;
	protected $sourceCredentials = array("SourceName"=>'YourSourcenameHere', "Password"=>'YourPasswordHere', "SiteIDs"=>array('YourSiteIDHere'));
	protected $userCredentials = array("Username"=>'YourUsernameHere', "Password"=>'YourPasswordHere', "SiteIDs"=>array('YourSiteIDHere'));
	
	// CLIENT SERVICE //
	
	function addOrUpdateClients($params) {
		$this->client = new SoapClient('https://api.mindbodyonline.com/0_5/ClientService.asmx?WSDL', array("soap_version"=>SOAP_1_1,'location'=>'https://api.mindbodyonline.com/0_5/ClientService.asmx', 'trace'=>true));
		$request = array_merge(array("SourceCredentials"=>$this->sourceCredentials, "UserCredentials"=>$this->userCredentials),$params);
		try {
			$result = $this->client->AddOrUpdateClients(array("Request"=>$request));
		} catch (SoapFault $s) {
	    	echo 'ERROR: [' . $s->faultcode . '] ' . $s->faultstring;
		} catch (Exception $e) {
	    	echo 'ERROR: ' . $e->getMessage();
		}
		return $result;
	}
	
	function getClients($params) {
		$this->client = new SoapClient('https://api.mindbodyonline.com/0_5/ClientService.asmx?WSDL', array("soap_version"=>SOAP_1_1, 'trace'=>true));
		$request = array_merge(array("SourceCredentials"=>$this->sourceCredentials, "UserCredentials"=>$this->userCredentials),$params);
		try {
			$result = $this->client->GetClients(array("Request"=>$request));
		} catch (SoapFault $s) {
	    	echo 'ERROR: [' . $s->faultcode . '] ' . $s->faultstring;
		} catch (Exception $e) {
	    	echo 'ERROR: ' . $e->getMessage();
		}
		return $result;
	}
	
	
	// CLASS SERVICE //
	
	function getClasses($params = array()) {
		$this->client = new SoapClient('https://api.mindbodyonline.com/0_5/ClassService.asmx?WSDL', array("soap_version"=>SOAP_1_1, 'trace'=>true));
		$request = array_merge(array("SourceCredentials"=>$this->sourceCredentials, "UserCredentials"=>$this->userCredentials),$params);
		try {
			$result = $this->client->GetClasses(array("Request"=>$request));
		} catch (SoapFault $s) {
	    	echo 'ERROR: [' . $s->faultcode . '] ' . $s->faultstring;
		} catch (Exception $e) {
	    	echo 'ERROR: ' . $e->getMessage();
		}
		return $result;
	}
	
	function getXMLRequest() {
		return $this->client->__getLastRequest();
	}
	
	function getXMLResponse() {
		return $this->client->__getLastResponse();
	}
	
}