working with our api

The CrowdTwist API provides an HTTP-based access point to all of the data and functionality provided by our product. This includes being able to create objects like users and manage a user's activities as well as retrieve information about the leaderboard, point scale and fan levels.

The API is designed to be accessed by server-to-server calls (RPC) or by Javascript "pixeling" (collectively known as API end points) or by using HTTP GET and POST requests (called HTTP end points). Which implementation you choose to use depends on the requirements of your application. All implementations, though, are documented throughout these pages.

All API end points are available over both HTTP and HTTPS.

If you have questions or need technical assistance with anything related to our API, feel free to email us at api@crowdtwist.com.

credentials

In order to use the API you must obtain from us a key and secret. Your key associates your API calls with the instance of our software that we have set up for you. The key must be provided in every API call made to our system.

The secret is the only security mechanism that exists between you and the API. You should go to great lengths to protect it. If you think your secret has been compromised you should email api@crowdtwist.com so we can issue you a new one.

* The security of your secret is your responsibility. We cannot be held accountable for any issues that arise from a compromised secret.

anatomy of a request url

A request URL follows this format:

http://api.crowdtwist.com/[version]/[return data format]?[query string]

For example, the following URL is the end point for creating a user:

http://api.crowdtwist.com/v1/json?api_ep=user-create

The version of the API is "v1". Presently the only supported formats for return data are "json" and "pixel". In the following pages, we will document all of the available end points and how to use them.

You must append three values to the query string before you send: "api_ep", "api_key" and "api_sig." You should concatenate the api_ep and api_key values before generating the signature. See the next section to understand how to sign requests.

signing requests

Every request to an API end point requires a query string parameter named "api_sig". This is the API signature that ensures the data you are transmitting to the end point has not been modified. The signature is created by concatenating the entire query string with your secret and MD5 hashing the concatenated value.

For example:

query string: city=New York&name=CrowdTwist

key: 12345678901234567890123456789012

secret : 12345678901234567890123456789012

end point: set-city

Would produce an "api_sig" of:

276ff8c2ce269ddcc32dfd741beb5cb8

The PHP code below demonstrates how to create the "api_sig" value:

        function get_signature($key, $secret, $end_point, $query_string)
        {
            // Parse the string $query_string into a hash.
            parse_str($query_string, $params);

            // Add the required CrowdTwist parameters and sort them
            // alphabetically by the name of the variable.
            $params[ 'api_ep' ]  = $end_point;
            $params[ 'api_key' ] = $key;
            ksort($params);

            // Generate the signature by concatenating the name/value pairs
            // together and adding the secret.
            $signature = '';
            foreach ($params as $key => $value)
            {
                $signature .= $key . '=' . $value;
            }
            $signature .= $secret;

            return md5($signature);
        }
    

When constructing the query string, make sure that is it alphabetized by the names of the variables and do not URL encode the individual values or the entire string prior to generating the hash.

return values

Our goal is to return consistent responses for all API calls. In the event you request a pixel response, a 1x1 transparent GIF image will be returned so that pixel based API calls can, for example, be put into an image tag and not break the functionality of the page they reside on.

If you request a JSON response you will either receive the data you requested or an empty JSON object. Empty JSON objects will be returned from API end points where no information has been requested. An example of such an end point is user-delete.

dates

All dates in our API must be represented as timestamps. By doing so, any presentation is eliminated on either side of the system which eliminates the need for special processing.

The following timestamp was created using the PHP code: "mktime(0, 0, 0, 1, 15, 1974)":

127454400

location

Exact geographic location is essential to the CrowdTwist platform. Location information is vetted against a real-world database that maps US zip codes and cities to pin-point accurate locations. As a result, you will need to verify location information against our API and provide city ID values to various end points.

When requesting location information from a US user, you only need to collect the five digit zip code for the purposes of using our system. When requesting location from a non-US user, you need the name of their country and city.

These pieces of information can be passed to the "Location" end points to get the necessary city ID value for the CrowdTwist system.

activities & points

A number of activities (and their related points) are awarded to users automatically either by actions taken during certain API calls or by back end mechanisms that run to award points for things that are being done when users are not directly interacting with your instance of the CrowdTwist software.

Below is a list of those activities and how points are awarded:

Added/removed during user creation or update:

Added Date of Birth
Facebook Connect
Sign in with Foursquare
Added Gender
Mobile Phone Added
Joined Email List
Sign in with Twitter
Daily Login

Managed by back end processes:

First Month Twitter Followership
Monthly Twitter Followership
Mentioned on Twitter
Retweeted Status
First Month Facebook Fanship
Monthly Facebook Fanship
Commented on a Posting
Liked a Posting

libraries

Below are the available libraries written for the CrowdTwist API:

PHP
git clone git://github.com/CrowdTwist/php.git