Changes made to the API for Version 3.0

Changes made to the API for Version 3.0

Top ↑

This page gives a general overview of what has changed in the API for Version 3.0. If you are migrating from a previous version of the API, you will need to refer to the documentation for each method you are using as there are too many minor changes to be listed here.

Authentication

  • Authentication in version 3.0 is done with an API Key. The Key must be supplied as the first argument for all method calls.
  • The login() method from previous versions of the API has been deprecated and should not be used anymore.

JSON Error Object

  • The JSON-RPC interface now returns all errors as an object instead of a string. The error object contains code and message values with details about the error.
{
    "id": 1,
    "result": null,
    "error": {
        "code": 301,
        "message": "Server Error: Authorisation Failed - Please provide an API key"
    }
}
 

Search Criteria

  • Supplying an invalid field name in the search criteria will now return an error instead of silently ignoring it. Previously the API would return all items without filtering. This may mean that invalid calls to the search methods which appeared to work in previous versions, will now return an error.
  • The search criteria now supports OR logic by inserting the string "OR" between individual search criteria arrays.
$search_criteria = array(
    array('First Name', 'exactly', 'Alice'),
    'OR',
    array('First Name', 'exactly', 'Bob'),
);
 
[
    ["First Name", "exactly", "Alice"],
    "OR",
    ["First Name", "exactly", "Bob"],
]
 
  • You can now also group criteria together by nesting them inside an array and then combining the arrays with "AND"/"OR" logic.
$search_criteria = array(
    array(
        array('First Name', 'exactly', 'Alice'),
        'AND',
        array('Last Name', 'exactly', 'Smith'),
    ),
    'OR',
    array(
        array('First Name', 'exactly', 'Bob'),
        'AND',
        array('Last Name', 'exactly', 'Jones'),
    )
);
 
[
    [
        ["First Name", "exactly", "Alice"],
        "AND",
        ["Last Name", "exactly", "Smith"],
    ],
    "OR",
    [
        ["First Name", "exactly", "Bob"],
        "AND",
        ["Last Name", "exactly", "Jones"],
    ]
]
 

New Methods

  • All search* methods now have corresponding count* methods which return the number of items that match the search criteria. These methods are useful if you do not need the details of each matching item, otherwise you should continue to use the search methods and count the number of items returned.
  • Methods for adding and editing Autoresponders have been added.

Changes to Method Names

  • The Email methods have been removed and replaced by the new Message methods which support SMS messages.
  • Database methods have been renamed to List to be more consistent with the terminology used in the user interface.
  • Campaign methods have been renamed to Batch.

Changes to Method Parameters

  • Method parameters are now checked more thoroughly and may return an error where the API would have previously ignored it. This may mean that invalid method calls which were allowed in previous versions, will now return an error. For instance, where an incorrect number of arguments is passed to a method; Or an array is supplied in place of a string/integer.
  • The parameters for unsubscribeContact have been swapped. The list_id is now before the email_address parameter.
  • The searchContacts and getContactById methods now return all system values by default.
  • The message_type parameter has been added to getMessagesSentToContact.
  • The list_id parameter for editList has been removed and added as a mandatory id value in the supplied list_details array.
  • The is_scheduled and is_sms parameters have been removed from addBatch. Supplying a send_time now implies the Batch is a scheduled send.
  • The list_id parameter has been added to searchPreviousUnsubscribers.
  • Many of the values in array parameters have changed. In many cases the values have been renamed to be more consistent across all methods. Check the Method Reference for more information.

Changes to Return Values

  • All numbers are now returned as integers instead of strings where relevant.
  • Integer constants are now returned as more descriptive string constants. For instance, in the past the API would return magic numbers like 1 or 2 for "email" and "sms".
  • The getListById method no longer wraps the result in an extra array.
  • The getBatchStatus method now returns an associative array.
  • The uploadBase64FileData method now returns an associative array.
  • Many of the values returned in arrays have changed. In many cases the values have been renamed to be more consistent across all methods. Check the Method Reference for more information.

Changes to Error Messages

  • Error messages have been updated where required to use current system terminology. The most significant change is the renaming of database to List.

See Also

Popular Pages