Basic Structure of the API

Introduction to API Methods?

API Methods are functions that perform actions associated with system objects. For example, a method could add a Contact or delete a List. Each object includes methods that are unique to it.

The API methods are grouped according to the objects that they operate on. The following list briefly describes the objects and includes links to their reference sections. The reference sections define the objects' structures and include API method reference pages.

• Account and User

  An Account includes information about your system, such as User privileges and purchased options. A User is an individual who has access to an Account.

• Autoresponder

  An Autoresponder contains a Message ID and a trigger. When the trigger event occurs, the Autoresponder sends the Message. Examples of triggers are a Contact subscribing and a Contact confirming a subscription.

• Contact

  A Contact is an individual in one of your Lists.

• File

  A File is a file (or image) and its metadata. Once uploaded, Files are contained in File Folders.

• Folder

  A Folder is a container of Lists, Messages, or Files.

• List and Field

  A List contains one or more Contacts and their Fields. Fields are properties, such as last_name and is_active that define any of your other objects, but in the API, Field methods only perform actions on List Fields. Fields have their own Fields, such as time_format and show_in_form. To avoid confusion we often refer to Fields of Fields as properties.

• Message and Batch A Message is an Email or SMS. A a Batch handles the process of sending the Message to Contacts.

Each section includes reference pages that give detailed explanations of each method, including descriptions of optional and required parameters, values returned, and sample code.

How are Objects Interconnected?

The following system object map shows how the objects in your system are related. The solid black arrows indicate required relationships, and the dotted arrows indicate optional relationships.

The box labelled API includes the objects most Users with API access can process. Accounts and Users appear in an adjacent box because they are accessible through the API, but only to Users with Administrative access.

The API cannot process Campaigns, so they are located outside the API with their steps and Autoresponders. API methods can act on Autoresponders, but not in relationship to Campaigns. Autoresponders must belong to a List and contain a Message.

How the API Communicates using JSON-RPC

The API uses JSON-RPC to send method requests and responses over HTTP.

A call includes the method name and an associative array of the method's parameters. An associative array (defined in more detail in the next section) is composed of key => value pairs. In our methods and most of our code, each key is a Field. The first Field => value pair for each method must be API Key => value in order to access the API.

The following PHP code is an example using the method editContact. The method's parameters are the API key, a List ID, and an array of Contacts stored in the variable $modify_contacts. First the code enters values into the parameters, and then it calls the editContact method:

In the code, each Contact to be edited is also an associative array of details. The first Field => value pair in each Contacts array is id => value, which enables the code to find the Contact by ID. Below the Contact ID are Field => value pairs for Contact Fields that you want to edit. The value holds the new content that you want to enter in the Field.

The method call appears in the last line of the sample code.

When the system receives the request, it gets the List, and then finds each Contact and replaces the values of the specified Fields with the new values.

The method returns each Contact ID with a 1 if the edits to the Contact were successful, and with a 0 if they were not.

Object Arrays and Associative Arrays

The Contact arrays in the above code and any other arrays that contain object details are object arrays. In the API, object arrays are always associative arrays, which are structured with key => value pairs, as shown in the previous example.

You can always change the value in a key => value pair, but you cannot change the key. In the example above, you can replace the value joe@example.com with jsmith@domain.com, but you cannot change the Field name Email.

If the object array includes one array, it is a singular object array (or singular associative array)

:$field = array( 'name' => 'Name');

In the editContact example, above, the Contact arrays are array elements in a container array. Since the entire array is composed of multiple levels of arrays, it is called a multidimensional object array, or in the case of the example, a multidimensional associative array.

In each multidimensional array, the contents of each container array are indexed so they can be referenced individually. In the example, the two second level arrays could be referred to as modify_contacts[1] and modify_contacts[2].

Search arrays are another type of array used by the API. To read more about search arrays, see Using Search Methods.