Developer’s love APIs. There are APIs for everything. The popular ones like Google’s javascript mapping APIs, or Twitter’s REST apis. Amazingly useful APIs like Stripe and Paypal for running a business. APIs rule the world.

However, APIs aren’t everything, and they definitely can leave holes in your application’s integration when it comes data. This is because your application because responsible to go and fetch information from an API; or go and put information into that remote application using an API call.

What happens when that data can be changed by either application? Imagine a situation where you’re taking lead information from your website, and storing it in Mautic. But you also have another application that you want to house the information. You could use Mautic’s REST API and continually go and fetch new information, merge with any data you’ve curated on your own, and maintain a synced set of data that way.

You don’t have to think about that solution very long before you start realizing where it falls short – synchronized changes become a nightmare. What happens if a remote application changes some data?

A Mautic example might be a lead has the bounced flag added to it. Now your application has to be responsible to re-fetch that information. And your application can’t know that change has occurred, so it has to continually poll that external resource to keep that data synced. It can be a hassle for any application to continually do this. Add in other complications like API limits, which many large API providers like Paypal, Twitter, Google, and Facebook all enforce, and you’re left with a very likely possibility that at some point, you will not have an accurate representation of your data. This would be a lot like taking a roller coaster ride without knowing if the tracks in the loop are complete – you could end up careening to a swift and painful stop! Scary.

Enter Webhooks

Webhooks are a fantastic solution, guaranteed to save you time and money. A webhook is an HTTP URL endpoint supported by your third party application, which can receive a POST. It feels a lot like a REST API, but for you application’s purposes it is just one half of the API (eg: all the POST endpoints). That endpoint URL is then “executed” each time an “event” occurs. Webhooks close the roller coaster loop and ensure a safe ride for all your data passengers.

Adding webhooks to an application where data is changing constantly is a perfect solution to the API loophole, because now we know that data has changed, and our application just has to be responsible to receive the payload and update it appropriately.

Gone is the need to continually poll the remote resource to find out if data has changed, update it, and then check again in a little while to do the exact same check. This eliminates so many variables. API limits become a non-issue, out of sync data liabilities are reduced, and CPU cycles get saved by everyone in the transaction.

Webhooks are Simple

Webhooks are perfect at sharing bits of data on-time, when an event occurs, to a remote resource. This is usually all third party developers want from remote systems anyway. In these situations, using an API instead of a Webhook would be massive overkill. Using a webhook avoids the cost and time associated with building out an entire application to support API endpoints.

Next time you’re planning to create a full blown API for your application, ask yourself if the problem you’re trying to solve could be solved with some event listeners and a webhook call to a remote resource.

1. Install the Mautic API with Composer

API library is at Packagist. So simple composer require mautic/api-library command will installation of the library to your project for you. Composer will also automatically include the library to your project.

2. Alternate Ways to Install Mautic API

If your project doesn’t use Composer yet, don’t worry! You can either clone it from GitHub or download the ZIP package and copy the library folder to your project. Let’s look quickly at those two methods and how you would go about using them.

Install by git clone

1. Go to your project folder where you want to place Mautic API library to be. For example:
   cd /var/www/html/myproject
2. Run git clone to this folder
   git clone git@github.com:mautic/api-library.git .
   (the dot at the end means current folder)

Copy from ZIP package

1. Download the library from https://github.com/mautic/api-library/archive/master.zip
2. Extract the package to some temporary location.
3. Copy the /lib folder to your project.

3. How to Authorize Your Mautic API Application

To use API calls, your application has to be authorized in Mautic instance you want to connect with. Mautic supports OAuth1 and OAuth2. I’ll focus to OAuth1 since it doesn’t require HTTPS. If your application has some kind of administration, you’ll need to add 3 text inputs and an Authorization button.

Get authorization keys in Mautic

You can create specific authorization API credentials for each connected application. To do that, go to your Mautic administration and follow these steps:

1. Go to Mautic Configuration / API Settings and set ‘API enabled’ to ‘Yes’, leave ‘API mode’ to ‘OAuth1’. Save changes.
2. At the right-hand side menu where Configuration is should appear the new menu item ‘API Credentials’. Click this menu item.
3. Create a new set of credentials. Fill in the ‘Name’ (name of your app for example) and the Callback URL (URL where your app will be listening responses from Mautic). Save your new credentials.
4. Mautic will generate ‘Consumer Key’ and ‘Consumer Secret’ key.

Create authorization form

If you don’t want to hard-code authorization details then you can create a form with the following text inputs: Mautic Base URL, Consumer Key and Consumer Secret with Save & Authorize button. This form should not be accessible for public.

Handle authorization request

When the user for your app hits Save & Authorize, this is how you will handle the request:

// @todo check if the request is sent from user with admin rights
// @todo check if Base URL, Consumer/Client Key and Consumer/Client secret are not empty

// @todo load this array from database or config file
$accessTokenData = array(
    'accessToken' => '',
    'accessTokenSecret' => '',
    'accessTokenExpires' => ''
);

// @todo Sanitize this URL. Make sure it starts with http/https and doesn't end with '/'
$mauticBaseUrl = $_POST['mauticBaseUrl'];

$settings = array(
    'baseUrl'           => $mauticBaseUrl,
    'clientKey'         => $_POST['clientKey'],
    'clientSecret'      => $_POST['clientSecret'],
    'callback'          => 'http://yourapp.com', // @todo Change this to your app callback. It should be the same as you entered when you were creating your Mautic API credentials.
    'version'           => 'OAuth1a'
);

if (!empty($accessTokenData['accessToken']) && !empty($accessTokenData['accessTokenSecret'])) {
    $settings['accessToken']        = $accessTokenData['accessToken'] ;
    $settings['accessTokenSecret']  = $accessTokenData['accessTokenSecret'];
    $settings['accessTokenExpires'] = $accessTokenData['accessTokenExpires'];
}

$auth = MauticAuthApiAuth::initiate($settings);

if ($auth->validateAccessToken()) {
    if ($auth->accessTokenUpdated()) {
        $accessTokenData = $auth->getAccessTokenData();
        // @todo Save $accessTokenData
        // @todo Display success authorization message
    } else {
        // @todo Display info message that this app is already authorized.
    }
} else {
    // @todo Display info message that the token is not valid.
}

The workflow can be broken down like this:

1. Admin user fills in the Access Keys and Mautic Base URL to the form.
2. If $accessTokenData aren’t known yet, $auth->validateAccessToken() will redirect user to Mautic where he can authorize the app.
3. After user confirms authorization, Mautic will redirect him back (to the Callback URL) to your app.
4. $auth->getAccessTokenData() will return $accessTokenData which you have to save.

Live examples of authorization can be found at:

• Mautic API Tester
• Mautic-Joomla plugin

4. Making API Calls

Finally the fun part. I suppose the most frequently used REST API call will be to create new lead in Mautic. For example, if a visitor submits a form in your app. Since this is probably the most widely used, here is an example of the code to do this:

$leadApi    = MauticMauticApi::getContext(
    "leads",
    $auth,
    $mauticBaseUrl . '/api/'
);

$lead = $leadApi->create(array(
    'ipAddress' => $_SERVER['REMOTE_ADDR'],
    'firstname' => $formData['firstname'],
    'lastname'  => $formData['lastname'],
    'email'     => $formData['email'],
));

There is so much more you can do. Fortunately all of these API examples and more are described here in the API Library Documentation. Don’t wait, get started now building something amazing!

This post was originally published on http://johnlinhart.com/blog/implementing-mautic-api

This is the beginning for what we anticipate to be one of our greatest resources for developers working with marketing automation and Mautic, specifically the Mautic SDK. This is for all you looking to hack together something amazing and use Mautic in your setup. We’ve got real-life examples, code snippets, a full marketing automation API for Mautic and tons of other resources packed in here to help you.

Our Mautic SDK gives you the opportunity to integrate anything with your marketing automation. With our Mautic SDK you can use a REST API to integrate all the things. Doesn’t matter what language or codebase your other systems are written in, or even what language you know – with a beautiful and detailed REST API you can interact easily with Mautic.

And this is just the beginning of what we want to offer in our Mautic Developer Hub. We think it’s a pretty great start but we’re not done. Keep an eye on this space as we continue to add features and goodies specifically relevant for developers. We know how hard you work to make the rest of the company look good! Here’s some Mautic awesomeness just for you.

Mautic Developer Hub