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
https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/links
<your_api_key> and <your_api_token> with the API key and token created by you.<your_sid> with your “Account sid”<subdomain> with the region of your account
<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. |
| 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 |
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:
{ "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. |
