TALK TO THE EXPERTS FOR A PERSONALISED DEMO NOW! Request a Demo
Schedule Demo

API Documentation

Are you a Developer? Read our API Doc

The Marketing API must be enabled in Aritic PinPoint.

Within Aritic PinPoint, go to the Configuration page (located in the Settings menu) and under API Settings enable Aritic PinPoint’s marketing API. You can also choose which OAuth protocol to use here.

After saving the configuration, go to the API Credentials page (located in the Settings menu) and create a new client. Enter the callback/redirect URI that the request will be sent from. Click Apply then copy the Client ID and Client Secret to the application that will be using the API.

Requirements for Aritic PinPoint Marketing API

  • PHP 5.3.7 or newer
  • cURL support

Obtaining an access token

The first step is to obtain authorization. Aritic PinPoint supports OAuth 1.0a and OAuth 2 however it is up to the administrator to decide which is enabled. Thus it is best to have a configuration option within your project for the administrator to choose what method should be used by your code.

<p><?php</p>
<p>// Bootup the Composer autoloader<br />
include __DIR__ . '/vendor/autoload.php';</p>
<p>$publicKey = '';<br />
$secretKey = '';<br />
$callback = '';</p>
<p>// ApiAuth::initiate will accept an array of OAuth settings<br />
$settings = array(<br />
'baseUrl' => '', // Base URL of the Aritic instance<br />
'version' => 'OAuth2' // Version of the OAuth can be OAuth2 or OAuth1a. OAuth2 is the default value.<br />
'clientKey' => '', // Client/Consumer key from Aritic<br />
'clientSecret' => '', // Client/Consumer secret key from Aritic<br />
'callback' => '' // Redirect URI/Callback URI for this script<br />
);</p>
<p>/*<br />
// If you already have the access token, et al, pass them in as well to prevent the need for reauthorization<br />
$settings['accessToken'] = $accessToken;<br />
$settings['accessTokenSecret'] = $accessTokenSecret; //for OAuth1.0a<br />
$settings['accessTokenExpires'] = $accessTokenExpires; //UNIX timestamp<br />
$settings['refreshToken'] = $refreshToken;<br />
*/</p>
<p>// Initiate the auth object<br />
$auth = ApiAuth::initiate($settings);</p>
<p>// Initiate process for obtaining an access token; this will redirect the user to the $authorizationUrl and/or<br />
// set the access_tokens when the user is redirected back after granting authorization</p>
<p>// If the access token is expired, and a refresh token is set above, then a new access token will be requested</p>
<p>if ($auth->validateAccessToken()) {</p>
<p>// Obtain the access token returned; call accessTokenUpdated() to catch if the token was updated via a<br />
// refresh token</p>
<p>// $accessTokenData will have the following keys:<br />
// For OAuth1.0a: access_token, access_token_secret, expires<br />
// For OAuth2: access_token, expires, token_type, refresh_token</p>
<p>if ($auth->accessTokenUpdated()) {<br />
$accessTokenData = $auth->getAccessTokenData();</p>
<p>//store access token data however you want<br />
}<br />
}</p>
<p>

Marketing API Requests

Now that you have an access token and the auth object, you can make API requests. The API is broken down into contexts. Note that currently only the Lead context allows creating, editing and deleting items. The others are read only

Get a context object

<p><?php</p>
<p>// Create an api context by passing in the desired context (Leads, Forms, Pages, etc), the $auth object from above<br />
// and the base URL to the Aritic server (i.e. http://my-aritic-server.com/api/)</p>
<p>$leadApi = AriticApi::getContext("leads", $auth, $apiUrl);</p>
<p>

Supported contexts are currently:

  • Assets – read only
  • Campaigns – read only
  • Forms – read only
  • Leads – read and write
  • Pages – read only
  • Points – read only
  • PointTriggers – read only

Creating an item

Currently, only Leads support this

<p><?php</p>
<p>$fields = $leadApi->getFieldList();</p>
<p>$data = array();</p>
<p>foreach ($fields as $f) {<br />
$data[$f['alias']] = $_POST[$f['alias']];<br />
}</p>
<p>// Set the IP address the lead originated from if it is different than that of the server making the request<br />
$data['ipAddress'] = $ipAddress;</p>
<p>// Create the lead<br />
$lead = $leadApi->create($data);</p>
<p>

Editing an item

Currently, only Leads support this

<p><?php</p>
<p>$updatedData = array(<br />
'firstname' => 'Updated Name'<br />
);</p>
<p>$result = $leadApi->edit($leadId, $updatedData);</p>
<p>// If you want to create a new lead in the case that $leadId no longer exists<br />
// $result will be populated with the new lead item<br />
$result = $leadApi->edit($leadId, $updatedData, true);</p>
<p>

Error handling

<p><?php</p>
<p>// $result returned by an API call should be checked for errors<br />
$result = $leadApi->delete($leadId);</p>
<p>if (isset($result['error'])) {<br />
echo $result['error']['code'] . ": " . $result['error']['message'];<br />
} else {<br />
// do whatever with the info<br />
}</p>
<p>

Deleting an item

Currently, only Leads support this

<p><?php</p>
<p>$result = $leadApi->delete($leadId);</p>
<p>