API document
SHORTEN WORLD's API exposes the entire SHORTEN WORLD infrastructure via a standardized programmatic interface. Using SHORTEN WORLD's API, you can do just about anything you can do on shortenworld.com via the customer dashboard.
The SHORTEN WORLD API is a RESTful API based on HTTPS requests and JSON responses. If you are registered with SHORTEN WORLD, you can obtain your API key from the top of the "API key" page, found here:
Go to My account
Endpoints
The API is accessed by making HTTPS requests to a specific version endpoint URL, in which GET, POST, PUT, PATCH, and DELETE methods dictate how your interact with the information available. Every endpoint is accessed only via the SSL-enabled HTTPS (port 443) protocol.
Everything (methods, parameters, etc.) is fixed to a version number, and every call must contain one. The latest version is Version 1.
The stable base URL for all Version 1 HTTPS endpoints is:
https://api.shortenworld.com/v1/
All API list
Get token
Refresh token
Revoke token
Get team list
Get campaign list
Get domain subscriptions
Get link list
Create link
Update link
Delete link
Redirect link
Redirect mobile link
Expiration link
Link password
Get tracker list
Get team tracker list
Get link tracker list
Create link tracker
Delete link tracker
Link A/B/C/D/E/F... testing
Link analytics
API limits
Get token
First of all, we need to use this API to authen yourself and get the token. We will use this token to authenticate all other APIs.
Using access_token
to authen other APIs, and using refresh_token
to get a new access_token
without calling this API again
Required headers
Content-Type |
[String, Required]. Value is: application/json |
Possible parameters
username |
[String, Required]. Your username (not email). |
key |
[String, Required]. Your API key. |
Examples
To get pretty JSON response we can use format tool: https://format.asia/json-format
HTTP Status
200 |
Success |
401 |
Unauthorized |
403 |
Your account is locked or permission denied |
429 |
Login too many failed |
500 |
An unknown error |
Json string will be sent, containing following data
status => code: 0 |
Success |
status => code: not equal 0 |
Error |
status => message |
Error message |
status => timestamp |
The time server responses |
If HTTP Status is 200 and status => code
is equal to 0, then
token => access_token |
Using this access_token to authen other APIs. It will be valid in 01 hour |
token => refresh_token |
Using refresh_token to get a new access_token without calling this API again. It will be valid in 07 days |
token => expires_in |
The rest time (in second) access_token is valid |
Refresh token
We use this API to refresh a new token base on the old refresh_token.
Required headers
Content-Type |
[String, Required]. Value is: application/json |
Possible parameters
refreshToken |
[String, Required]. Get refresh_token from the response of Get token API. |
Examples
To get pretty JSON response we can use format tool: https://format.asia/json-format
HTTP Status
200 |
Success |
401 |
Unauthorized |
403 |
Your account is locked or permission denied |
429 |
Login too many failed |
500 |
An unknown error |
Json string will be sent, containing following data
status => code: 0 |
Success |
status => code: not equal 0 |
Error |
status => message |
Error message |
status => timestamp |
The time server responses |
If HTTP Status is 200 and status=>code is equal to 0, then
token => access_token |
Using this access_token to authen other APIs. It will be valid in 01 hour |
token => refresh_token |
Using refresh_token to get a new access_token without calling Get token API again. It will be valid in 07 days |
token => expires_in |
The rest time (in second) access_token is valid |
Revoke token
We use this API to revoke a token.
Required headers
Content-Type |
[String, Required]. Value is: application/json |
Authorization |
[String, Required]. Value is: Bearer [access_token] |
Possible parameters
Examples
To get pretty JSON response we can use format tool: https://format.asia/json-format
HTTP Status
200 |
Success |
401 |
Unauthorized |
403 |
Your account is locked or permission denied |
429 |
Login too many failed |
500 |
An unknown error |
Json string will be sent, containing following data
status => code: 0 |
Success |
status => code: not equal 0 |
Error |
status => message |
Error message |
status => timestamp |
The time server responses |
Get team list
We use this API to get all team list which belong to you or you are member
Required headers
Content-Type |
[String, Required]. Value is: application/json |
Authorization |
[String, Required]. Value is: Bearer [access_token] |
Possible parameters
size |
[Number, Optional]. The number of results each page, default 20 results. |
page |
[Number, Optional]. The page of results, default is 0. Start page is 0. |
Examples
To get pretty JSON response we can use format tool: https://format.asia/json-format
HTTP Status
200 |
Success |
401 |
Unauthorized |
403 |
Your account is locked or permission denied |
429 |
Login too many failed |
500 |
An unknown error |
Json string will be sent, containing following data
status => code: 0 |
Success |
status => code: not equal 0 |
Error |
status => message |
Error message |
status => timestamp |
The time server responses |
Get campaign list
We use this API to get all campaign list which belong to your teams or the teams you are member
Required headers
Content-Type |
[String, Required]. Value is: application/json |
Authorization |
[String, Required]. Value is: Bearer [access_token] |
Possible parameters
teamId |
[String, Optional]. Get teamId from Get team list API. Will list all campaigns belong to this team, if not specified it will return all campaigns of all team you are managing. |
size |
[Number, Optional]. The number of results each page, default 20 results. |
page |
[Number, Optional]. The page of results, default is 0. Start page is 0. |
Examples
To get pretty JSON response we can use format tool: https://format.asia/json-format
HTTP Status
200 |
Success |
401 |
Unauthorized |
403 |
Your account is locked or permission denied |
429 |
Login too many failed |
500 |
An unknown error |
Json string will be sent, containing following data
status => code: 0 |
Success |
status => code: not equal 0 |
Error |
status => message |
Error message |
status => timestamp |
The time server responses |
Get domain subscriptions
We use this API to get all domain subscriptions which you have subscribed to your team. Both rent domains and your own domains
Required headers
Content-Type |
[String, Required]. Value is: application/json |
Authorization |
[String, Required]. Value is: Bearer [access_token] |
Possible parameters
teamId |
[String, Required]. Get teamId from Get team list API. |
size |
[Number, Optional]. The number of results each page, default 20 results. |
page |
[Number, Optional]. The page of results, default is 0. Start page is 0. |
Examples
To get pretty JSON response we can use format tool: https://format.asia/json-format
HTTP Status
200 |
Success |
401 |
Unauthorized |
403 |
Your account is locked or permission denied |
429 |
Login too many failed |
500 |
An unknown error |
Json string will be sent, containing following data
status => code: 0 |
Success |
status => code: not equal 0 |
Error |
status => message |
Error message |
status => timestamp |
The time server responses |
Get link list
We use this API to get all your links which belong to your teams or the teams you are member
Required headers
Content-Type |
[String, Required]. Value is: application/json |
Authorization |
[String, Required]. Value is: Bearer [access_token] |
Possible parameters
teamId |
[String, Optional]. Get teamId from Get team list API. |
domainIds |
[Many Strings. Separate by comma "," , Optional]. Get domainId from Get domain subscriptions API. |
campaignIds |
[Many Strings. Separate by comma "," , Optional]. Get campaignId from Get campaign list API. |
hidden |
[String, Optional]. Value is: true or false. If value is true, it will return all hidden links |
search |
[String, Optional]. Full text search with link code and link title |
size |
[Number, Optional]. The number of results each page, default 20 results. |
page |
[Number, Optional]. The page of results, default is 0. Start page is 0. |
Examples
To get pretty JSON response we can use format tool: https://format.asia/json-format
HTTP Status
200 |
Success |
401 |
Unauthorized |
403 |
Your account is locked or permission denied |
429 |
Login too many failed |
500 |
An unknown error |
Json string will be sent, containing following data
status => code: 0 |
Success |
status => code: not equal 0 |
Error |
status => message |
Error message |
status => timestamp |
The time server responses |
Create link
We use this API to shorten link
Required headers
Content-Type |
[String, Required]. Value is: application/json |
Authorization |
[String, Required]. Value is: Bearer [access_token] |
Possible parameters
teamId |
[String, Required]. Get teamId from Get team list API. |
domainId |
[String, Required]. Get domainId from Get domain subscriptions API. |
campaignId |
[String, Optional]. Get campaignId from Get campaign list API. |
noTitle |
[Boolean, Optional]. Value is: true or false. If value is true it will disable getting the page title from the source page meta tag which results in faster API response time (Check subscription plan) |
destination |
[String, Required]. Your long link to shorten |
utmSource |
[String, Optional]. Campaign Source |
utmMedium |
[String, Optional]. Campaign Medium |
utmCampaign |
[String, Optional]. Campaign Name |
utmTerm |
[String, Optional]. Campaign Term |
utmContent |
[String, Optional]. Campaign Content |
Examples
To get pretty JSON response we can use format tool: https://format.asia/json-format
HTTP Status
200 |
Success |
401 |
Unauthorized |
403 |
Your account is locked or permission denied |
429 |
Login too many failed |
500 |
An unknown error |
Json string will be sent, containing following data
status => code: 0 |
Success |
status => code: not equal 0 |
Error |
status => message |
Error message |
status => timestamp |
The time server responses |
Update link
We use this API to update link
Required headers
Content-Type |
[String, Required]. Value is: application/json |
Authorization |
[String, Required]. Value is: Bearer [access_token] |
Possible parameters
linkId |
[String, Required]. Get linkId from Get link list API or Create link api. |
title |
[String, Optional]. Change title. |
code |
[String, Optional]. Change code (Back-half of the link). |
tags |
[Boolean, Optional]. Add tag for link |
hide |
[String, Optional]. Value is "on" or "off". If "on" it will be hidden from the Dashboard |
Examples
To get pretty JSON response we can use format tool: https://format.asia/json-format
HTTP Status
200 |
Success |
401 |
Unauthorized |
403 |
Your account is locked or permission denied |
429 |
Login too many failed |
500 |
An unknown error |
Json string will be sent, containing following data
status => code: 0 |
Success |
status => code: not equal 0 |
Error |
status => message |
Error message |
status => timestamp |
The time server responses |
Delete link
We use this API to delete link
Required headers
Content-Type |
[String, Required]. Value is: application/json |
Authorization |
[String, Required]. Value is: Bearer [access_token] |
Possible parameters
linkId |
[String, Required]. Get linkId from Get link list API or Create link api. |
Examples
To get pretty JSON response we can use format tool: https://format.asia/json-format
HTTP Status
200 |
Success |
401 |
Unauthorized |
403 |
Your account is locked or permission denied |
429 |
Login too many failed |
500 |
An unknown error |
Json string will be sent, containing following data
status => code: 0 |
Success |
status => code: not equal 0 |
Error |
status => message |
Error message |
status => timestamp |
The time server responses |
Redirect link
We use this API to redirect link, change destination, change click type or update UTM Campaign
Required headers
Content-Type |
[String, Required]. Value is: application/json |
Authorization |
[String, Required]. Value is: Bearer [access_token] |
Possible parameters
linkId |
[String, Required]. Get linkId from Get link list API or Create link api. |
destination |
[String, Optional]. Your new long link to redirect |
clickType |
[Number, Optional]. If value is "0" it will count on All clicks. If value is "1" it will count on Unique clicks. |
uniqueTime |
[Number, Optional]. if clickType above is "1", this will handle how Unique clicks work. Let's say uniqueTime = 15 (minutes), if user click on the link consecutively we only count each 15 minutes is one click |
utmSource |
[String, Optional]. Campaign Source |
utmMedium |
[String, Optional]. Campaign Medium |
utmCampaign |
[String, Optional]. Campaign Name |
utmTerm |
[String, Optional]. Campaign Term |
utmContent |
[String, Optional]. Campaign Content |
Examples
To get pretty JSON response we can use format tool: https://format.asia/json-format
HTTP Status
200 |
Success |
401 |
Unauthorized |
403 |
Your account is locked or permission denied |
429 |
Login too many failed |
500 |
An unknown error |
Json string will be sent, containing following data
status => code: 0 |
Success |
status => code: not equal 0 |
Error |
status => message |
Error message |
status => timestamp |
The time server responses |
Redirect mobile link
This API will redirect link separately on each mobile platform
Required headers
Content-Type |
[String, Required]. Value is: application/json |
Authorization |
[String, Required]. Value is: Bearer [access_token] |
Possible parameters
linkId |
[String, Required]. Get linkId from Get link list API or Create link api. |
ios |
[String, Optional]. If device of the user is IOS platform, the link will redirect to this destination |
android |
[String, Optional]. If device of the user is android platform, the link will redirect to this destination |
windows |
[String, Optional]. If device of the user is windows phone platform, the link will redirect to this destination |
mobile |
[String, Optional]. If device of the user is mobile and not one of above platforms, the link will redirect to this destination |
Examples
To get pretty JSON response we can use format tool: https://format.asia/json-format
HTTP Status
200 |
Success |
401 |
Unauthorized |
403 |
Your account is locked or permission denied |
429 |
Login too many failed |
500 |
An unknown error |
Json string will be sent, containing following data
status => code: 0 |
Success |
status => code: not equal 0 |
Error |
status => message |
Error message |
status => timestamp |
The time server responses |
Expiration link
This API will set expiration of the link by time or number of clicks
Required headers
Content-Type |
[String, Required]. Value is: application/json |
Authorization |
[String, Required]. Value is: Bearer [access_token] |
Possible parameters
linkId |
[String, Required]. Get linkId from Get link list API or Create link api. |
date |
[String, Optional]. The date to be expired, format: dd/MM/yyyy |
destinationByDate |
[String, Optional]. The link will redirect to this destination after above date |
click |
[Number, Optional]. Number of clicks to be expired |
clickType |
[Number, Optional]. If value is "0", click above will count on All clicks. If value is "1" click above will count on Unique clicks. |
destinationByClick |
[String, Optional]. If number of clicks more than click above, the link will redirect to this destination |
Examples
To get pretty JSON response we can use format tool: https://format.asia/json-format
HTTP Status
200 |
Success |
401 |
Unauthorized |
403 |
Your account is locked or permission denied |
429 |
Login too many failed |
500 |
An unknown error |
Json string will be sent, containing following data
status => code: 0 |
Success |
status => code: not equal 0 |
Error |
status => message |
Error message |
status => timestamp |
The time server responses |
Link password
This API will set password of the link. Users have to fill password before go to destination
Required headers
Content-Type |
[String, Required]. Value is: application/json |
Authorization |
[String, Required]. Value is: Bearer [access_token] |
Possible parameters
linkId |
[String, Required]. Get linkId from Get link list API or Create link api. |
password |
[String, Required]. The password to open link |
Examples
To get pretty JSON response we can use format tool: https://format.asia/json-format
HTTP Status
200 |
Success |
401 |
Unauthorized |
403 |
Your account is locked or permission denied |
429 |
Login too many failed |
500 |
An unknown error |
Json string will be sent, containing following data
status => code: 0 |
Success |
status => code: not equal 0 |
Error |
status => message |
Error message |
status => timestamp |
The time server responses |
Get tracker list
This API will get tracker list. Embedding retargeting tracker will help you track all your traffics to other tools to analyze. Including Facebook Pixel, Google Analytics Pixel, Quora Pixel, Twitter Pixel, Google Tag Manager Pixel, Linkedin Pixel, Google Adwords Pixel, Pinterest Pixel, Segment Pixel...
Required headers
Content-Type |
[String, Required]. Value is: application/json |
Authorization |
[String, Required]. Value is: Bearer [access_token] |
Possible parameters
Examples
To get pretty JSON response we can use format tool: https://format.asia/json-format
HTTP Status
200 |
Success |
401 |
Unauthorized |
403 |
Your account is locked or permission denied |
429 |
Login too many failed |
500 |
An unknown error |
Json string will be sent, containing following data
status => code: 0 |
Success |
status => code: not equal 0 |
Error |
status => message |
Error message |
status => timestamp |
The time server responses |
Get team tracker list
This API will get team tracker list. We can create team tracker from the dashboard.
Required headers
Content-Type |
[String, Required]. Value is: application/json |
Authorization |
[String, Required]. Value is: Bearer [access_token] |
Possible parameters
teamId |
[String, Required]. Get teamId from Get team list API. |
size |
[Number, Optional]. The number of results each page, default 20 results. |
page |
[Number, Optional]. The page of results, default is 0. Start page is 0. |
Examples
To get pretty JSON response we can use format tool: https://format.asia/json-format
HTTP Status
200 |
Success |
401 |
Unauthorized |
403 |
Your account is locked or permission denied |
429 |
Login too many failed |
500 |
An unknown error |
Json string will be sent, containing following data
status => code: 0 |
Success |
status => code: not equal 0 |
Error |
status => message |
Error message |
status => timestamp |
The time server responses |
Get link tracker list
This API will get link tracker list.
Required headers
Content-Type |
[String, Required]. Value is: application/json |
Authorization |
[String, Required]. Value is: Bearer [access_token] |
Possible parameters
linkId |
[String, Required]. Get linkId from Get link list API or Create link API. |
size |
[Number, Optional]. The number of results each page, default 20 results. |
page |
[Number, Optional]. The page of results, default is 0. Start page is 0. |
Examples
To get pretty JSON response we can use format tool: https://format.asia/json-format
HTTP Status
200 |
Success |
401 |
Unauthorized |
403 |
Your account is locked or permission denied |
429 |
Login too many failed |
500 |
An unknown error |
Json string will be sent, containing following data
status => code: 0 |
Success |
status => code: not equal 0 |
Error |
status => message |
Error message |
status => timestamp |
The time server responses |
Create link tracker
This API will create link tracker.
Required headers
Content-Type |
[String, Required]. Value is: application/json |
Authorization |
[String, Required]. Value is: Bearer [access_token] |
Possible parameters
linkId |
[String, Required]. Get linkId from Get link list API or Create link API. |
type |
[String, Required]. If value is "1", we will create link tracker by copy from team tracker. If value is "0", we will create link tracker by adding new code of tracker provider directly (like Google pixel code...) |
teamTrackers |
[String array, Optional]. Required if type above is "1".
If value is "all-trackers", we will create link trackers by copy all team trackers. Otherwise it will be the list of teamTrackers => id from Get team tracker list API |
code |
[String, Optional]. Required if type above is "0". The code of your tracker provider (like Google pixel code...) |
trackerId |
[String, Optional]. Required if type above is "0". Get trackerId from trackers => id at Get tracker list API |
Examples
To get pretty JSON response we can use format tool: https://format.asia/json-format
HTTP Status
200 |
Success |
401 |
Unauthorized |
403 |
Your account is locked or permission denied |
429 |
Login too many failed |
500 |
An unknown error |
Json string will be sent, containing following data
status => code: 0 |
Success |
status => code: not equal 0 |
Error |
status => message |
Error message |
status => timestamp |
The time server responses |
Delete link tracker
This API will delete link tracker.
Required headers
Content-Type |
[String, Required]. Value is: application/json |
Authorization |
[String, Required]. Value is: Bearer [access_token] |
Possible parameters
linkTrackerId |
[String, Required]. Get linkTrackerId from Get link tracker list API. |
Examples
To get pretty JSON response we can use format tool: https://format.asia/json-format
HTTP Status
200 |
Success |
401 |
Unauthorized |
403 |
Your account is locked or permission denied |
429 |
Login too many failed |
500 |
An unknown error |
Json string will be sent, containing following data
status => code: 0 |
Success |
status => code: not equal 0 |
Error |
status => message |
Error message |
status => timestamp |
The time server responses |
Link A/B/C/D/E/F... testing
This API will set alternate redirect URLs to see which one is the best for customers
Required headers
Content-Type |
[String, Required]. Value is: application/json |
Authorization |
[String, Required]. Value is: Bearer [access_token] |
Possible parameters
linkId |
[String, Required]. Get linkId from Get link list API or Create link API. |
testing |
[Object Array, Required]. Array of object containing: link and percentage .
link (String) is new destination and percentage (Number: 1-100 percent) is the rate to redirect.
Each object in array order is equivalent to A,B,C,D... testing
|
Examples
To get pretty JSON response we can use format tool: https://format.asia/json-format
HTTP Status
200 |
Success |
401 |
Unauthorized |
403 |
Your account is locked or permission denied |
429 |
Login too many failed |
500 |
An unknown error |
Json string will be sent, containing following data
status => code: 0 |
Success |
status => code: not equal 0 |
Error |
status => message |
Error message |
status => timestamp |
The time server responses |
Link analytics
This API will get analytics of the link follow by time filters
Required headers
Content-Type |
[String, Required]. Value is: application/json |
Authorization |
[String, Required]. Value is: Bearer [access_token] |
Possible parameters
linkId |
[String, Required]. Get linkId from Get link list API or Create link API. |
startTime |
[String, Optional]. Start time to filter, format: dd/MM/yyyy. If not specified, it will filter in last 30 days |
endTime |
[String, Optional]. End time to filter, format: dd/MM/yyyy. If not specified, it will filter in last 30 days |
Examples
To get pretty JSON response we can use format tool: https://format.asia/json-format
HTTP Status
200 |
Success |
401 |
Unauthorized |
403 |
Your account is locked or permission denied |
429 |
Login too many failed |
500 |
An unknown error |
Json string will be sent, containing following data
status => code: 0 |
Success |
status => code: not equal 0 |
Error |
status => message |
Error message |
status => timestamp |
The time server responses |
If HTTP Status is 200 and status=>code is equal to 0, then
metricsMap => 1 |
Source of clicks by date |
metricsMap => 2 |
Devices clicks |
metricsMap => 3 |
System (OS) clicks |
metricsMap => 4 |
Browsers clicks |
metricsMap => 5 |
Brand clicks |
metricsMap => 6 |
Languages clicks |
metricsMap => 7 |
Geo Location clicks |
metricsMap => 8 |
Bots clicks. Not available on free plan |
metricsMap => 9 |
Total clicks by date |
API limits
API limits per account depending on subscription plan
Check API limits |