Overview

Our system offers a variety of API integrations that you can use with your system. See the basics below of how this works and refer to our API Library for the technical information for each API.

How APIs Work

An API (Application Programming Interface) is a tool that makes data readable and editable to a computer. This means that when you integrate your customer management system with our API, you can automate tasks like list management and email sending.

The API consists of two systems:

  • Our server that waits for users to ask it to perform a task
  • The client that knows what API data is available and can manipulate it at the user’s request
API Diagram

API Endpoints

The API endpoint is a web interface defined by a WDSL file that determines the address or connection point to a web service. You can use two endpoint methods with our system:

The REST API

REST (or Representational State Transfer) is an architectural style that simplifies the design of Web Services. It’s based on the concept that everything is a resource and that each resource can be identified by and accessed at a uniform resource identifier (URI). Using this URI, the resource can be acted upon using various HTTP methods.

The XML-RPC API

XML-RPC is a protocol specification that defines how Remote Procedure Calls can be made by sending XML to a Web Service using the HTTP protocol. Each call has a unique signature. The programmer uses an external library to connect to the API, so any implementation details will be based on the library they choose to use.

Authentication

To keep things simple, we use Basic HTTP Authentication on all our endpoints. Here are some reasons why:

  • Security: Basic Authentication uses bcrypt encryption, which is more secure than the md5 encryption used by Digest Authentication.
  • Speed: Because of the increased security, requests using Basic Authentication can send the user’s credentials in the initial requests instead of having an extra request to negotiate the connection each time.
  • Simplicity: Basic Authentication is simple and easy to implement. It’s also widely supported by libraries, browsers, and frameworks.

Most HTTP libraries have methods in place for Basic HTTP Authentication. If your library doesn’t provide this functionality, here is how to do it manually:

  • Basic HTTP Authentication works by adding a header in your request. Request headers are a list of key-value pairs. The key for the header to add for authentication is “Authorization”.
  • The value for the header is the word “Basic” followed by a space followed by a base64 encoded hash.
  • To generate this base64 encoded hash, start with the string “username:apikey”, substituting your username and apikey for our system.
  • Next, run a base64 encode function on that string.

The resulting header should look like:

Note: If your API client hasn’t been authenticated yet, you’ll receive a 401 Unauthorized HTTP response. If you receive a 403 Forbidden HTTP response, it means that you can’t access the requested resource.

Tutorial

When you find the API data you’re looking for in our API Library, apply it as follows. This PHP example is for creating a customer:

Open the request and pass in your credentials
<?php

$user = ‘Administrator’;

$apiKey = ‘(Your API Key)’;
Load the API

The following line of code tells the server which API URL to access for the request.

Here’s an example for creating a customer:

$host = ‘(Your URL)’;

$path = ‘[the REST path in the method table]’;

Your URL is the URL of your installation.

Method

In this line of code, you tell the API which REST function to use:

$method = ‘POST’;
Set up the fields to pass to the server
$json = ‘

{

“name”:”customer name”,

“email”:”[email protected]”

}

‘;
cURL

cURL is a tool for sending and receiving files from a web server. This line of code initialises

$cSession = curl_init();

the cURL session.

Initiate the Headers

This section of the code opens the headers section and passes the authentication (including your API key).

$auth = base64_encode($user . ‘:’ . $apiKey);

$headers = array();

$headers[] = ‘Authorization: Basic ‘ . $auth;

$headers[] = ‘Content-Type: application/json’;

curl_setopt($cSession, CURLOPT_HTTPHEADER, $headers);
Set the cURL options for the request
curl_setopt($cSession, CURLOPT_URL, $host . $path);

curl_setopt($cSession, CURLOPT_RETURNTRANSFER, true);

curl_setopt($cSession, CURLOPT_HEADER, false);

curl_setopt($cSession, CURLOPT_CUSTOMREQUEST,

strtoupper($method));

curl_setopt($cSession, CURLOPT_POSTFIELDS, $json);
Execute the request and close the session
$result = curl_exec($cSession);

curl_close($cSession);
Print the result as a JSON string
echo $result;