×

    • Shorten A Long URL New

    This API will shorten a long URL to a short URL, which can be used to track data. To shorten a long URL through our API, you will need to make a HTTP POST request to

    POST

    https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/links

    • Replace <your_api_key> and <your_api_token> with the API key and token created by you.
    • Replace <your_sid> with your “Account sid”
    • Replace <subdomain> with the region of your account
      1. <subdomain> of Singapore cluster is @api.exotel.com

    <your_api_key> , <your_api_token> and <your_sid> are available in the API settings page of your Exotel Dashboard

    You can use our official postman collection to try out the APIs.

    The following are the POST parameters:

    Parameter Name Mandatory/Optional Value
    long_url Mandatory The URL that you wish to shorten. Only valid URL’s will be shortened.
    expire_in Optional

    The duration(seconds) after which the short URL becomes invalid.
    Minimum is 60 seconds and default is 31 days. max. value is  365 days
    tracking Optional

    Whether to track the short URL click. Can be: "true" or "false". "ShortenUrl" needs to be "true" for Tracking to work.
    shorten_url_header Optional

    Applicable only for Indian businesses

    If you are creating a shortened link from this API to send SMSes in India, enter the header that you have registered on your DLT(Distributed Ledger Technology) platform. Please ensure that it matches exactly with what you have entered in your DLT platform to avoid failure of SMSes

    If you using this feature for anything apart from SMS, please ignore this parameter
    callback_url Optional

    Once someone clicks on the shortened URL,  Exotel will do a POST callback to your end point if the URL is set as a parameter in the API.  

    Below are the parameters:

    sid - The Sid (unique id) of the shortened URL  

    short_url - The complete shortened URL

    short_code - Key of the shortened URL 

    long_url - Original URL which is shortened

    Tracking - Whether to track the short URLs click

    custom_field - custom field passed in API request String value

    Expires_at -  Date Time in ISO format when link will expire

    Created_time - Date Time in ISO format when URL is created

    Last_viewed -  Date Time in ISO format when link was visited last

    Total_clicks  - count of total views of short url

    Account_sid -  Exotel’s unique Account SID

    Date_created - Date Time in ISO format when link was created 

    city - City where the shorten URL is clicked

    Country - Country code where shorten URL is clicked

    IP - IP address where shorten URL is clicked

    Postal_code - Postal code where shorten URL is clicked 

    Region - Region where shorten URL is clicked

    Accuracy_radius - Aproximate accuracy radius where shorten URL is clicked 

    OS_version - OS version of the customer who clicked the shorten URL 

    OS_name - OS name of the customer who clicked the shorten URL 

    Device_name - Device name of the customer who clicked the shorten URL 

    Platform_type - Platform where shorten URL is clicked 
    custom_field Optional

    Set a Custom Field relevant to your use case while sending a long URL. E.g Order ID, Payment ID, Login Attempt etc. Any content / json body upto 1024 chars
    custom_domain Optional

    Whether you want the short URL to start with default domain- exo.tl or you want to provide a custom domain of your own choice.

         If custom domain is not present or empty, we will use the default domain(exo.tl)

          If custom domain is given in the request it will be used to form the short URL

    Note : Clients will have to route the traffic on their custom domain to exo.tl domain, this is a change on your domain management system

    		 
    curl --location --request POST 'https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/exotel/links' \
--header 'Content-Type: application/json' \
--data-raw '{
"links": [
{
"long_url": "https://www.google.co.in/",
"expire_in": 100,
"tracking": true,
"callback_url": "https://www.google.co.in/",

}
]
}'    
    var http = require('follow-redirects').http;
var fs = require('fs');

var options = {
'method': 'POST',
'hostname': '<your_api_key>',
'port': <your_api_token><subdomain>,
'path': '/v2/accounts/exotel/links',
'headers': {
'Content-Type': 'application/json'
},
'maxRedirects': 20
};

var req = http.request(options, function (res) {
var chunks = [];

res.on("data", function (chunk) {
chunks.push(chunk);
});

res.on("end", function (chunk) {
var body = Buffer.concat(chunks);
console.log(body.toString());
});

res.on("error", function (error) {
console.error(error);
});
});

var postData = "{\n\"links\": [\n{\n\"long_url\": \"https://www.google.co.in/\",\n\"expire_in\": 100,\n\"tracking\": true,\n\"callback_url\": \"https://www.google.co.in/\",\n\n}\n]\n}";

req.write(postData);

req.end();
    <?php

$curl = curl_init();

curl_setopt_array($curl, array(
CURLOPT_URL => 'https://%3Cyour_api_key%3E:%3Cyour_api_token%3E%3Csubdomain%3E/v2/accounts/exotel/links',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{
"links": [
{
"long_url": "https://www.google.co.in/",
"expire_in": 100,
"tracking": true,
"callback_url": "https://www.google.co.in/",

}
]
}',
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json'
),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
    import requests
import json

url = "https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/exotel/links"

payload = "{\n\"links\": [\n{\n\"long_url\": \"https://www.google.co.in/\",\n\"expire_in\": 100,\n\"tracking\": true,\n\"callback_url\": \"https://www.google.co.in/\",\n\n}\n]\n}"
headers = {
'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)
    require "uri"
require "json"
require "net/http"

url = URI("https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/exotel/links")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request.body = "{\n\"links\": [\n{\n\"long_url\": \"https://www.google.co.in/\",\n\"expire_in\": 100,\n\"tracking\": true,\n\"callback_url\": \"https://www.google.co.in/\",\n\n}\n]\n}"

response = http.request(request)
puts response.read_body
    curl --location --request POST 'https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/exotel/links' \
--header 'Content-Type: application/json' \
--data-raw '{
"links": [
{
"long_url": "https://www.google.co.in/",
"expire_in": 100,
"url_shorten_header": "EXOTEL",
"tracking": true,
"callback_url": "https://www.google.co.in/",

}
]
}'    
    var http = require('follow-redirects').http;
var fs = require('fs');

var options = {
'method': 'POST',
'hostname': '<your_api_key>',
'port': <your_api_token><subdomain>,
'path': '/v2/accounts/exotel/links',
'headers': {
'Content-Type': 'application/json'
},
'maxRedirects': 20
};

var req = http.request(options, function (res) {
var chunks = [];

res.on("data", function (chunk) {
chunks.push(chunk);
});

res.on("end", function (chunk) {
var body = Buffer.concat(chunks);
console.log(body.toString());
});

res.on("error", function (error) {
console.error(error);
});
});

var postData = "{\n\"links\": [\n{\n\"long_url\": \"https://www.google.co.in/\",\n\"expire_in\": 100,\n\"url_shorten_header\": \"EXOTEL\",\n\"tracking\": true,\n\"callback_url\": \"https://www.google.co.in/\",\n\n}\n]\n}";

req.write(postData);

req.end();
    <?php

$curl = curl_init();

curl_setopt_array($curl, array(
CURLOPT_URL => 'https://%3Cyour_api_key%3E:%3Cyour_api_token%3E%3Csubdomain%3E/v2/accounts/exotel/links',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{
"links": [
{
"long_url": "https://www.google.co.in/",
"expire_in": 100,
"url_shorten_header": "EXOTEL",
"tracking": true,
"callback_url": "https://www.google.co.in/",

}
]
}',
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json'
),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
    import requests
import json

url = "https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/exotel/links"

payload = "{\n\"links\": [\n{\n\"long_url\": \"https://www.google.co.in/\",\n\"expire_in\": 100,\n\"url_shorten_header\": \"EXOTEL\",\n\"tracking\": true,\n\"callback_url\": \"https://www.google.co.in/\",\n\n}\n]\n}"
headers = {
'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)
    require "uri"
require "json"
require "net/http"

url = URI("https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/exotel/links")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request.body = "{\n\"links\": [\n{\n\"long_url\": \"https://www.google.co.in/\",\n\"expire_in\": 100,\n\"url_shorten_header\": \"EXOTEL\",\n\"tracking\": true,\n\"callback_url\": \"https://www.google.co.in/\",\n\n}\n]\n}"

response = http.request(request)
puts response.read_body

    HTTP Response:

    • On success, the HTTP response status code will be 200
    • The Sid is the unique identifier of the shortened URL and it will be useful to log this for future debugging
    • the HTTP body will contain an JSON similar to the one below
    • Example Response
    {
    "request_id": "c3586f381db043e899138770673bc527",
    "method": "POST",
    "http_code": 200,
    "metadata": {
        "failed": 0,
        "total": 1,
        "success": 1
    },
    "response": [
        {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "sid": "6275306c51104f25802ba900eb4a977d",
                "short_url": "https://exo.tl/VhK5vk",
                "short_code": "VhK5vk",
                "long_url": "https://www.google.co.in/",
                "tracking": true,
                "custom_field": "Order details",
                "expires_at": "2023-01-09 18:39:26",                           
                "created_time": "2023-01-09 16:59:26",
                "last_viewed": "0001-01-01T00:00:00Z"             
                "total_clicks": 0,
                "url_shorten_header": "EXOTEL"    //This will be blank if the field is not used in the API request
            }
        }
    ]
}

    Description of parameters mentioned in the above response:

    Parameter Name

    Type & Value

    code

    The code to show the status of the request. Please refer to the error log below for more details 

    sid

    string; an alpha-numeric unique identifier of the shortened URL

    short_url

    string; the shortened URL will be added here

    short_code

    String; unique key of the shortened URL

    long_url

    String ; Original long URL which needed to be shortened

    tracking

    String; Whether to track the URLs. Can be: "true" or "false".

    custom_field 

    		 String ;Set a Custom Field relevant to your use case while sending a long URL. E.g Order ID, Payment ID, Login Attempt etc. Any content / json body upto 1024 chars

    expires_at

    Time in format YYYY-MM-DD HH:mm:ss; time when short URL will expire

    created_time

    Time in format YYYY-MM-DD HH:mm:ss; The time when the short URL was created
    last_viewed Time in format YYYY-MM-DD HH:mm:ss; time when short URL was last viewed
    total_clicks String ;count of total views of short url

    HTTP Error codes - 

    Scenario

    HTTP Error Codes

    API Error code

    Error Message

    On success

    200

    -

    -

    On Partial Success

    207

    -

    -

    Mandatory parameters are missing in the request body

    400

    1001

    Bad Request - Mandatory Parameter missing

    values in the request body are invalid

    400

    1002

    Bad Request - Invalid parameter

    Invalid request body 

    400

    1007

    Bad Request - Invalid request body,failed parsing

    Invalid credentials 

    401

    1015

    Unauthorized - Authentication failed

    User don’t have the access 

    403

    1010

    Forbidden - Your credentials are valid, but you don’t have access to the requested resource.

    Get request on invalid Sid or short_code

    404

    1012

    Not Found - short code not found or expired

    Invalid Endpoint

    404

    		  

    Not Found 
    For any errors because of issue at server side

    5xx

    		  

    Server Errors - Something went wrong at our end. Please try again.
     

    Short URL details New

    To get the details of a shortened URL , you will need to make a HTTP GET request to

    GET

    https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/links/<uuid>

    • Replace <your_api_key> and <your_api_token> with the API key and token created by you.
    • Replace <your_sid> with your “Account sid”
    • Replace <subdomain> with the region of your account
      1. <subdomain> of Singapore cluster is @api.exotel.com
      2. <subdomain> of Mumbai cluster is @api.in.exotel.com

    <your_api_key> , <your_api_token> and <your_sid> are available in the API settings page of your Exotel Dashboard

    curl --location --request GET 'http://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<account_sid>/links/<uuid>
    var http = require('follow-redirects').http;
var fs = require('fs');

var options = {
'method': 'GET',
'hostname': '<your_api_key>',
'port': <your_api_token><subdomain>,
'path': '/v2/accounts/<account_sid>/links/<uuid>',
'headers': {
},
'maxRedirects': 20
};

var req = http.request(options, function (res) {
var chunks = [];

res.on("data", function (chunk) {
chunks.push(chunk);
});

res.on("end", function (chunk) {
var body = Buffer.concat(chunks);
console.log(body.toString());
});

res.on("error", function (error) {
console.error(error);
});
});

req.end();
    <?php

$curl = curl_init();

curl_setopt_array($curl, array(
CURLOPT_URL => 'http://%3Cyour_api_key%3E:%3Cyour_api_token%3E%3Csubdomain%3E/v2/accounts/%3Caccount_sid%3E/links/%3Cuuid%3E',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
    import requests

url = "http://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<account_sid>/links/<uuid>"

payload={}
headers = {}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)
    require "uri"
require "net/http"

url = URI("http://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<account_sid>/links/<uuid>")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

    HTTP Response:

    • On success, the HTTP response status code will be 200
    • The Sid is the unique identifier of the shortened URL and it will be useful to log this for future debugging
    • the HTTP body will contain an JSON similar to the one below
    • Example Response
    {
    "request_id": "c3586f381db043e899138770673bc527",
    "method": "POST",
    "http_code": 200,
    "metadata": {
        "failed": 0,
        "total": 1,
        "success": 1
    },
    "response": [
        {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "sid": "6275306c51104f25802ba900eb4a977d",
                "short_url": "https://exo.tl/VhK5vk",
                "short_code": "VhK5vk",
                "long_url": "https://www.google.co.in/",
                "tracking": true,
                "custom_field": "Order details",
                "expires_at": "2023-01-09 18:39:26",                           
                "created_time": "2023-01-09 16:59:26",
                "last_viewed": "0001-01-01T00:00:00Z"             
                "total_clicks": 0,
            }
        }
    ]
}

    Description of parameters mentioned in the above response:

    Parameter Name

    Type & Value

    code

    The code to show the status of the request. Please refer to the error log below for more details 

    Sid

    string; an alpha-numeric unique identifier of the shortened URL

    short_url

    string; the shortened URL will be added here

    short_code

    String; unique key of the shortened URL

    long_url

    String ; Original long URL which needed to be shortened

    tracking

    String ; Whether to track the short URL click. Can be: "true" or "false". "ShortenUrl" needs to be "true" for Tracking to work.

    custom_field 

    		 String ;Set a Custom Field relevant to your use case while sending a long URL. E.g Order ID, Payment ID, Login Attempt etc. Any content / json body upto 1024 chars

    expires_at

    Time in format YYYY-MM-DD HH:mm:ss; time when short URL will expire

    created_time

    Time in format YYYY-MM-DD HH:mm:ss; The time when the short URL was created
    last_viewed Time in format YYYY-MM-DD HH:mm:ss; time when short URL was last viewed
    total_clicks String ;count of total views of short url

    HTTP Error codes - 

    Scenario

    HTTP Error Codes

    API Error code

    Error Message

    On success

    200

    -

    -

    On Partial Success

    207

    -

    -

    Mandatory parameters are missing in the request body

    400

    1001

    Bad Request - Mandatory Parameter missing

    values in the request body are invalid

    400

    1002

    Bad Request - Invalid parameter

    Invalid request body 

    400

    1007

    Bad Request - Invalid request body,failed parsing

    Invalid credentials 

    401

    1015

    Unauthorized - Authentication failed

    User don’t have the access 

    403

    1010

    Forbidden - Your credentials are valid, but you don’t have access to the requested resource.

    Get request on invalid Sid or short_code

    404

    1012

    Not Found - short code not found or expired

    Invalid Endpoint

    404

    		  

    Not Found 
    For any errors because of issue at server side

    5xx

    		  

    Server Errors - Something went wrong at our end. Please try again.