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.
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 'http://<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 => 'http://%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 = "http://<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("http://<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

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
JSON

{
    "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 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
JSON

{
    "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.

Voice

SMS

Exophones

Heartbeat

Call Campaigns

SMS Campaigns

Lead Assist

Users

ExoVerify

Whatsapp

URL shortening

More...

Voice

SMS

Exophones

Heartbeat

Call Campaigns

SMS Campaigns

LeadAssist

More...

Greeting

Connect

Passthru

Transfer

SMS

Email

More

Shorten A Long URL ^New

Short URL details ^New

Voice

SMS

Exophones

Heartbeat

Call Campaigns

SMS Campaigns

Lead Assist

Users

ExoVerify

Whatsapp

URL shortening

More...

Voice

SMS

Exophones

Heartbeat

Call Campaigns

SMS Campaigns

LeadAssist

More...

Greeting

Connect

Passthru

Transfer

SMS

Email

More

Shorten A Long URL New

Short URL details New

Shorten A Long URL ^New

Short URL details ^New