×

Private: Short A Long URL – API Docs 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
    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

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 URLs present in the SMS. 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 URLs present in the SMS

custom_field - custom field passed in SMS 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

Country_code - Country code of the customer who received the SMS

Date_created - Date Time in ISO format when link was created 

Sms_sid - The Sid (unique id) of the SMS, this SID can be used to track the SMS

To -  Contact number of the customer who clicked on the URL

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
{
    "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 present in the SMS. 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 – API Docs New

To get the details of a shortened URL SMS , 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
{
    "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 present in the SMS. 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 

 

5xx

 

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