<img height="1" width="1" style="display:none" src="https://www.facebook.com/tr?id=1511120552487711&amp;ev=PageView&amp;noscript=1">

API Ideas or Questions?

API Documentation

RESTful, robust and open to evolution

BudURL is the most flexible link management platform in existence - and we built our API to be open and ready to serve new ideas as fast as our brilliant customers can dream them up.

Don't see what you're looking for? Let's talk - you'd be surprised what's possible. 

BudURL API

Currently the BudURL API only supports GET calls to all methods. Below is documentation and sample code to use the API. API Keys are available only for registered accounts so Sign Up if you need one. You can obtain your API Key by going to your Profile page. Please report issues or ask questions by visiting our Support site. Thanks for giving the API a try!

API Primary Base URL

https://pro.budurl.com/api/v2

Note: Enterprise customers must use the admin panel domain in place of pro.budurl.com.

Please use SSL (https) for all requests.

Request Variables in GET call

It is always best to url encode all your variables especially the long url, notes, and any parameter values that are comma seperated. See sample code below on how do do this in PHP.

Examples

https://pro.budurl.com/api/v2/links/shrink?api_key=abc&long_url=http%3A%2F%2Fwww.44doors.com&notes=some%20long%20notes 

Responses in JSON or plain text

Examples

{success: "1", link: "http://budurl.me/e92j", hash: "e92j"} 

http://budurl.me/e92j 

 

Authentication

Must supply API Key in GET call

Parameters

  • api_key As assigned in BudURL registered account

Examples

https://pro.budurl.com/api/v2/links/shrink?api_key=abc&long_url=http://44doors.com 

Shrink with /links/shrink

Note: You may use POST method instead of GET with /links/shrink.

Parameters

  • long_url A long URL you wish to shrink
  • notes The notes to attach to the newly created link. (Note: can be changed later)
  • redirect_type Type of Redirect: 301 or 307. (Note: 301 is default unless set in your user settings)
  • alias Custom alias you wish to assign to short link. (optional)
  • format Choose txt or json (Note: json is default)
  • dupe_check Set to 1 if you want system to return last created short link that matches long_url (character for character and case sensitive) instead of creating a new short link.
  • date_delete Date to have link deleted from the system YYYY-MM-DD or format Nd where N is a number of days in future i.e 30d (optional)
  • date_archive Date to have link archived in the systemYYYY-MM-DD or format Nd where N is a number of days in future i.e 30d (optional)
  • labels Comma-separated list of labels to assign to link. Will auto-create label(s) if they do not exist. Specify a global link with global.png notation appended to end of label name. Global flag will be ignored if user is not an admin. (optional)
  • utm_template_id If UTM templates enabled, specify the id of the template to associate with link (optional)
  • utm_template_values If UTM templates enabled, a comma-separated list of pre-defined fields (optional. i.e utm_source=google,utm_campaign=spring) 

Examples (not url-encoded)

https://pro.budurl.com/api/v2/links/shrink?api_key=abc&long_url=http://44doors.com&notes=abc&alias=abcd&labels=red,blueglobal.png,yellow 

JSON Response Values

  • link Full URL of Link
  • hash Hash value of Link
  • redirect_type 301 or 307
  • utm_template_id Returns same id specified
  • utm_template_values Returns same sent

Examples

{success: 1, link: http://budurl.me/e92j, hash: e92j, redirect_type: 307, utm_template_id: abc123xyz, utm_template_values: {utm_source: google, utm_campaign: spring}

{success:"0",error_code:"400",error_message:"Link/Custom Alias is not available! Try another."} 
{success: "0", error_code: "100", error_message: "Invalid API key."} 
http://budurl.me/e92j 

 

Modify links with /links/modify

Parameters

  • link Link you wish to modify. (Note: will only accept full URL of Link)
  • long_url A long URL that your link redirects (optional)
  • notes The notes to attach to the newly created link. (optional)
  • redirect_type Type of Redirect: 301 or 307. (optional)
  • alias Custom alias you wish to assign to short link. (optional)
  • format Choose txt or json (Note: json is default - optional)
  • date_delete Date to have link deleted from the system YYYY-MM-DD or format Nd where N is a number of days in future i.e 30d (optional)
  • date_archive Date to have link archived in the system YYYY-MM-DD or format Nd where N is a number of days in future i.e 30d (optional)

Examples(not url-encoded)

https://pro.budurl.com/api/v2/links/modify?api_key=abc&link=http://budurl.me/wxyz&long_url=http://44doors.com&notes=abc&alias=abcd 

JSON Response Values

  • link Full URL of Link
  • hash Hash value of Link
  • link_preview Full URL of preview link

Examples

{success: 1, link: http://budurl.me/e92j, hash: e92j, link_preview: http://budurl.me/e92j?} 

{success:"0",error_code:"400",error_message:"Link/Custom Alias is not available! Try another."} 
{success: "0", error_code: "100", error_message: "Invalid API key."} 
http://budurl.me/e92j 

 

 

Expand with /links/expand

Parameters

  • link Link you wish to expand. (Note: will only accept full URL of Link)

Examples (not url-encoded)

https://pro.budurl.com/api/v2/links/expand?link=http://budurl.me/eji9 

https://pro.budurl.com/api/v2/links/expand?link=http://go.44doors.com/eji9 

Response Values

  • long_url Full URL of expanded Link

Notes

API Key not required

Examples

{success: "1", long_url: "http://44doors.com"} 
{success: "0", error_code: "100", error_message: "Invalid API key."} 

Domain links with /links/history

Parameters

  • limit Max results to return (Defaults to 50 and max of 100 - optional)
  • offset Offset results with 0 being most recently created link. (optional)
  • domain Return all links for domain when set to 1 otherwise just API user links. (Defaults to 0 - optional)
  • date_from Starting date of date range for click count YYYY-MM-DD (Note: optional unless date_to is set)
  • date_to Ending date of date range for click count YYYY-MM-DD (Note: optional)
  • omit_userids Comma-separated list of user ids to omit from results when domain is on. (optional)
  • label Filter results by label (optional)
  • utm_template_id If UTM templates enabled, filter results by those links using template (optional)
  • utm_template_values If UTM templates enabled, filter results by a comma-separated list of pre-defined fields (optional. i.e utm_source=google,utm_campaign=spring) 

Examples

https://pro.budurl.com/api/v2/links/history?api_key=abc 
https://pro.budurl.com/api/v2/links/history?api_key=abc&offset=50&limit=20&label=marketing 

Response Values

  • result_count Total links returned
  • links List of links with following:
    • hash Hash value of Link
    • link Full URL of Link
    • link_type Link category such as url,route
    • long_url Full URL of redirect external link
    • status Status of link
    • created Unix timestamp of link creation date/time
    • notes Any user associated notes for link
    • click_count clicks for link

Examples

{success: "1", result_count: "1", links: [ {hash: "xm8q", link: "http://go.44doors.com/xm8q", link_type: "url", long_url: "http://44doors.com", status: "active", created: "1410299990", notes: "my link notes", click_count:"12"} ] }
{success: 0, error_code: 100, error_message: "Invalid API key."} 

DOMAIN LINKS WITH /LINKS/COUNT

Parameters

  • domain Return count for domain links when set to 1 otherwise just API user links. (Defaults to 0 - optional)
  • omit_userids Comma-separated list of user ids to omit from results when domain is on. (optional)
  • label Filter results by label (optional)
  • date_from Starting date of date range for click count YYYY-MM-DD (Note: optional unless date_to is set)
  • date_to Ending date of date range for click count YYYY-MM-DD (Note: optional)
  • utm_template_id If UTM templates enabled, filter results by those links using template (optional)
  • utm_template_values If UTM templates enabled, filter results by a comma-separated list of pre-defined fields (optional. i.e utm_source=google,utm_campaign=spring) 

Examples

https://pro.budurl.com/api/v2/links/count?api_key=abc 
https://pro.budurl.com/api/v2/links/count?api_key=abc&label=marketing 

Response Values

  • result_count Total links

Examples

{success: "1", result_count: "1" }
{success: 0, error_code: 100, error_message: "Invalid API key."} 

 

Click count with /clicks/count

Parameters

  • link Link you wish to receive click counts. (Note: will only accept full URL of Link)
  • date_from Starting date of date range for click count YYYY-MM-DD (Note: optional unless date_to is set)
  • date_to Ending date of date range for click count YYYY-MM-DD (Note: optional)
  • daily If set to 1, will show a daily breakdown of counts
  • domain Return all clicks for domain when set to 1 otherwise just API user clicks. (Defaults to 0 - optional)
  • type Set to 'mobile' if you want to return click count for only mobile traffic

Examples (not url-encoded) (Note: first example will provide total click count for entire history)

https://pro.budurl.com/api/v2/clicks/count?api_key=abc&link=http://budurl.me/eji9 


https://pro.budurl.com/api/v2/clicks/count?api_key=abc&link=http://budurl.me/eji9&date_from=2010-01-01 


https://pro.budurl.com/api/v2/clicks/count?api_key=abc&link=http://budurl.me/eji9&date_from=2010-01-01&date_to=2010-01-31&daily=1 


https://pro.budurl.com/api/v2/clicks/count?api_key=abc&link=http://go.44doors.com/eji9&date_from=2010-01-01&date_to=2010-01-31&daily=1 

Response Values

  • link Full URL of Link
  • hash Hash value of Link
  • count Total click count for date range
  • dates If daily set to 1, list of dates and count key-value pairs.

Examples

{success: "1", link: "http://budurl.me/e92j", hash: "e92j", count: "1390"} 

{success: "1", link: "http://budurl.me/e92j", hash: "e92j", count: "154", dates: {"2010-01-01":29,"2010-01-02":80,"2010-01-03":45}} 

{success: "0", error_code: "100", error_message: "Invalid API key."} 

Sample PHP code using curl to shrink a URL 

$request =  'https://pro.budurl.com/api/v2/links/shrink?api_key='
         . rawurlencode('abc-key') . '&long_url='
         . rawurlencode('http://44doors.com') . '&notes='
         . rawurlencode('abc-notes');

$session = curl_init($request);
curl_setopt($session, CURLOPT_HEADER, false);
curl_setopt($session, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($session);
curl_close($session);

$decode = json_decode($response, true);

//to see array
var_dump($decode); 

 

Sample PHP code using curl to expand a Link  

$request =  'https://pro.budurl.com/api/v2/links/expand?link='
         . rawurlencode('http://budurl.me/e3ja');

$session = curl_init($request);
curl_setopt($session, CURLOPT_HEADER, false);
curl_setopt($session, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($session);
curl_close($session);

$decode = json_decode($response, true);

//to see array
var_dump($decode);