To get started using the ity.im api, login into your member account and click "Account Settings" in the top menu. Once there on the right side of the page that says "Activate API key". Click that button and your api key will be generated.

You can write your own software to access our api or use our ready made wrapper class written in PHP to get started right away.
We also provide free plugins for wordpress,vbulletin and phpBB.



All API endpoints require that authentication credentials be supplied as query arguments. To get started, you'll need a free ity.im user account and apiKey.

login=apidemo@ity.im&apiKey=apiKey



All ity.im APIs support an optional return format parameter. Note that json is the default response format. but xml is also available.

format=json

All ity.im APIs support jsonp which is the json format with a callback specified, such as:

format=json&callback=callback_method


* All API requests should be against the domain api.ity.im (see examples).
* HTTP Response Status Code is 200 on all valid response in json and xml formats. In json and xml responses, the status_code and status_txt values indicate whether a request is well formed and valid.
* For txt format calls, the HTTP Response Status Codes 403, 500 and 503 are used denote rate limiting, a problem with the request format, or an unknown error. The response body will be equivalent to status_txt in json and xml calls for non 200 response codes.
* The status_code is 200 for a successful request, 403 when rate limited, 503 for an unknown error or temporary unavailability, and 500 for all other invalid requests or responses.
* status_txt will be a value that describes the nature of any error encountered. Common values are MISSING_ARG_%s to denote a missing URL parameter, and INVALID_%s to denote an invalid value in a request parameter (where %s is substituted with the name of the request parameter).

Here are some examples:


* json { "status_code": 200, "status_txt": "OK", "data" : ... }
* json { "status_code": 403, "status_txt": "RATE_LIMIT_EXCEEDED", "data" : null }
* json { "status_code": 500, "status_txt": "INVALID_URI", "data" : null }
* json { "status_code": 500, "status_txt": "MISSING_ARG_LOGIN", "data" : null }
* json { "status_code": 503, "status_txt": "UNKNOWN_ERROR", "data" : null }
* jsonp callback_method({ "status_code": 200, "status_txt": "OK", "data" : ... })

XML Example:



ity.im currently limits API users to no more than five concurrent connections from a single IP address. Also, ity.im also institutes per-hour limits for each API method.
While rate limits exist, default limits are more than sufficient for nearly any size site.
Please note that our API rate limits reset every hour on the hour. If you are experiencing rate limiting errors, please wait until the top of the hour to resume making API calls.
If you're a high-volume user of the ity.im API, please contact us at support[AT]ity.im to discuss your options. When contacting ity.im support include a description of how you are using the ity.im API, which API endpoints you are using, and a current request volume over a 24 hour period.



When accessing our API you will make requests to the following files:


- For a long URL, /v1/shorten.php encodes a URL and returns a short one.

- Given a ity.im URL or hash (or multiple), /v1/expand.php decodes it and returns back the target URL as well as click stats.



We have created a simple wrapper class in PHP for using the ity.im API. Integration into your website is fast and easy.

To learn more about the free PHP wrapper class for accessing our API or download it:


Example usage (intialize class):

Example usage (shrink a url):


//Returned Accessable Object---------------
// $ityclass->returned->status_code - the status code
// $ityclass->returned->status_txt - status description
// $ityclass->returned->data->url - complete shortened url
// $ityclass->returned->data->hash - hash only
// $ityclass->returned->data->long_url - the long url submitted

Example usage (expand a url & get click stats):


//Returned Object---------------
// $ityclass->returned->status_code - the status code
// $ityclass->returned->status_txt - status description
// $ityclass->returned->data->expand[0]->long_url - long url assigned to hash
// $ityclass->returned->data->expand[0]->hash - hash only
// $ityclass->returned->data->expand[0]->short_url - short url
// $ityclass->returned->data->expand[0]->clicks_today - clicks today
// $ityclass->returned->data->expand[0]->clicks_month - clicks this month
// $ityclass->returned->data->expand[0]->clicks_overall - clicks overall
//------------------------------
//NOTE: if multiple hash's or short urls were submitted the returned data object will be an array with multiple rows. A single row returned will
//be on row [0] of the array.
//***********************************************************