×

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.