API Getting Started

Getting Started with the Buzzportal API

This page will help you get started with using the Buzzportal API. Before downloading one of the API wrappers or starting your own integration, you should first get an API key.

API Keys

The API key is a combination of a public and a secret key. It is important that the secret key be kept secret (imagine that!), so be sure to store these keys in an inaccessible location. The API key management page can be accessed by logging into your Buzzportal account, clicking ‘My Account’ in the top navigation bar, and clicking API Keys on in the dropdown menu. When you get to the API Key Management page, click the ‘New’ button to create a new API key pair. Clicking on the public key of the new record in the grid will bring up an overlay that has your public and secret key in it. Copy these and be sure to store them securely. You may also revoke API keys. These keys will still be visible but will no longer be active.

Language-Specific Details

This section covers specific details about either direct HTTP integration, or usage one of the API wrappers. API wrappers will ease the integration process by doing most of the work for you. The HTTP documentation will give you the details on creating a custom integration, though be warned that this is not for the faint of heart!

HTTP

Connecting to the API via direct HTTP requests is a much more involved process than using one of the wrappers. Constructing a request requires you to set up the appropriate headers and message body, and to place the request to a URL using a particular HTTP method. Details on these steps are provided below.

Request Method

The request method will be one of: GET, POST, or DELETE. These are operations that are performed on a resource. The documentation for each resource will describe how and when to use each method.

Request URL

Requests are made to a particular URL. The URL represents either a resource collection or a resource element. For example, a possible resource collection could be:

https://app.buzzportal.com/api/core/contactlists

A resource element on the previous collection would use an identifier (a list ID, in this case) following the collection, like so:

https://app.buzzportal.com/api/core/contactlists/1001001

Typically, resource collections can be retrieved from using GET, and can also be POSTed to, which creates a new resource element on the collection. Resource elements can be retrieved with GET, and may possibly be updated with a POST request or removed with a DELETE request. These are only general rules, some resources may not support all HTTP methods (you can’t modify the current date resource, for example).

Headers

When making a request to the API, there are several HTTP headers that must be set.

Header Name         Description

 

 

 

Authorization (for authenticated requests)

The value of this parameter is constructed from a combination of your public key, secret key and request data. To create this value, you first need to create a signature:

         requestData = <timestamp> + "<HTTP method> <URL>" + <message body>

        signature = hmac_sha1(requestData, <secretKey>);

The timestamp must be the current date and time, in GMT (conforming to ISO 8601, example: ‘Tue, 25 Sep 2012 04:19:05 +0000′). This has to be within 10 minutes of the server time. To ensure that this is the case, the current server time can be retrieved via the API (unauthenticated request to core/date). The entire request URL, followed by the message body (if applicable), must be appended to the timestamp. Each of these values must be trimmed of whitespace. Then, the request data must be HMAC_SHA1 encoded with the secret key. The signature is then provided, along with the public key, to create the Authorization header. Combine the public key and the signature with a colon separating them, and encode the result as base 64:

        

Authorization: Basic Base64Encode(<publicKey>:<signature>);

Example:

requestData = 'Tue, 25 Sep 2012 04:19:05 +0000' +

   'POST https://app.buzzportal.com/api/core/contactlists' +

   '<somexml></somexml>'

signature = hmac_sha1(requestData, 'secretkey')

headerValue = Base64Encode('publickey:' + signature)

Authorization: Basic cHVibGlja2V5OmUwNzQ2YmE4MDhjMzA5MzMyYmMwNDFjYWI0YWJiNjE0OGVmYTcxYTg=

 

 

Date (for authenticated requests)

 

 

The value for this header must be exactly the same as the date used when creating the authorization signature.
Example: Date: Tue, 25 Sep 2012 04:19:05 +0000

 

 

Accept-Encoding (optional)

 

 

If desired, set this to gzip to support compressed transmission.
Example: Accept-Encoding: gzip

 

 

Accept

 

 

The expected return data format (this may be either xml or json)
Example: Accept: application/json

 

The following headers are required when the request includes a message body:

 

Header Name Description
Content-Type The data format of the request message body.
Example: Content-Type: application/xml
Content-Length The length of the data, in bytes.
Example: Content-Length: 10

 

Message Body

A message body is provided in POST requests to specify the data to add or update. Be sure to supply the applicable HTTP Content headers when supplying a message body.

 

Responses

There are some important things to note about API responses. The response message body will contain data in the format specified in the Accept request header. This message will either be the expected return, or an error message of the form:

XML:

<error>Error message here!</error>

JSON:

{

"error": "Error message here!"

}

HTTP status codes will indicate either the success or failure of the request. There are various codes used for success and failure; the codes are described in the table below.

Status Code Description
2xx Success
200 OK This is the generic “Everything processed successfully” status.
201 Created This status indicates a new resource has been created. A representation of the created resource element should be returned in the response message body; this should include a link to the created resource.
202 Accepted The request has been accepted for processing, but may not have completed when the response is returned. This status is usually associated with a batch request, and a status resource that can be polled will be returned in the response message body.
204 No Content The request has been completed, and there is no message body in the response. This is usually the response to a successful DELETE request.
4xx Client Error
400 Bad Request There was an issue with the request. This could be due to a bad request message body or invalid query parameters. The error response message should have a detailed message of what was wrong with the request.
401 Unauthorized This status will be returned either when no authentication is provided for a non-public resource, or when the public key or the request signature could not be validated. The particular issue will be provided in the error response message.
403 Forbidden This error will occur when attempting to access a resource that does not belong to the account holding the authenticated key
404 Not Found Resource is not found. This may be returned when attempting to access a previously deleted resource.
405 Method Not Allowed The HTTP method used (GET, POST, etc.) is not allowed on this resource.
415 Unsupported Media Type The media type (application/xml, application/json, etc.) requested is not supported. All resources as of writing support XML and JSON for both request and response message bodies.
5xx Server Error
500 Internal Server Error This error is thrown when an internal API error occurs. In the event that this does happen, the API team is notified of the error so that it can be resolved quickly.

 

 

PHP

Using the PHP API Wrapper is quite straight forward. Here is a basic example of how to use it:

//These should be kept in a safe place! They're here just for example's sake.

$public = '<public_key>';

$secret = '<secret_key>';

$api = new BuzzportalAPI($public, $secret);

$myLists = $api->contactLists->getLists();

//Output each list ID and name.

foreach($myLists as $listId => $list) {

$listName = $list['name'];

echo "$listId: $listName\n";

}

That is all that is necessary to get a collection of the contact lists on an account!