URL Shortener

Goal

By the end of this guide you will know how to create a short link (for example https://h0b.co/promo-octubre) that leads to the long address you choose, know how many people open it, change or turn it off whenever you want and recover it if you delete it by mistake.

It is useful when you send links inside messages (where every character counts), when you want to measure a campaign or when you need to be able to change the destination of a link that has already been handed out.

Requirements

• An active Hablame organization, with a valid API key. How to get one.
• The urlshortener service on the key. It grants the whole URL shortener: list and view links, statistics, overview, domains and price, and also create (each creation is charged), edit, delete and restore. Only the owner of your organization creates keys.
• Available balance or an active URL Shortener plan to create links. Your organization also needs to have its currency defined and a URL Shortener price in that currency.
• If you want to use your own domain, it must be registered and verified in your organization. There is no endpoint to register or verify it.

Credentials

Every request carries your API key in the Authorization: Bearer hk_TU_API_KEY header. The urlshortener service is granted in full: there are no read-only URL shortener keys.

Steps

1. 01
   Check your key

   Call GET /utilities/ping. A 200 confirms the key and the network work.

2. 02
   See your domains

   GET /urlshortener/domains lists where you can publish, with the default first. If you do not send domain when creating, that one is used.

3. 03
   Check the price

   GET /urlshortener/pricing tells you what creating a link and each visit cost your organization, and whether your plan includes it. This documentation does not publish figures.

4. 04
   Create a link

   POST /urlshortener/links with the destination address. Always send an Idempotency-Key: if the request is cut off and you repeat it, no other link is created or charged.

5. 05
   Check it

   Open the short URL in a browser and query the link with GET /urlshortener/links/{domain}/{code}.

6. 06
   Measure

   GET /urlshortener/links/{domain}/{code}/stats brings a link’s visits per day or per hour and its breakdown by country, device, system, browser and source. GET /urlshortener/overview summarizes your whole organization.

7. 07
   Maintain

   Change the destination, turn a link off or back on with PATCH; delete it with DELETE and recover it for 90 days with restore.

Examples

Create a link

Only four fields are accepted: longUrl (required), domain, code (your alias) and expiresAt. A field that does not exist is rejected with 400 naming the field.

curl -X POST https://developers.hablame.co/api/v6/urlshortener/links \
  -H 'Authorization: Bearer hk_TU_API_KEY' \
  -H 'Idempotency-Key: 5f3b2c10-9a7e-4b2d-8c1f-0a1b2c3d4e5f' \
  -H 'Content-Type: application/json' \
  -d '{
    "longUrl": "https://example.com/landing?utm_source=sms",
    "code": "promo-octubre",
    "expiresAt": "2026-12-31T23:59:59-05:00"
  }'

import { randomUUID } from 'node:crypto'

const idempotencyKey = randomUUID()

const res = await fetch('https://developers.hablame.co/api/v6/urlshortener/links', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.HABLAME_API_KEY}`,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    longUrl: 'https://example.com/landing?utm_source=sms',
    code: 'promo-octubre',
  }),
})
const body = await res.json()
if (body.success) console.log(body.data.shortUrl)
else console.error(body.error.code, body.meta.requestId)

import os
import uuid
import requests

r = requests.post(
    "https://developers.hablame.co/api/v6/urlshortener/links",
    headers={
        "Authorization": f"Bearer {os.environ['HABLAME_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"longUrl": "https://example.com/landing?utm_source=sms", "code": "promo-octubre"},
    timeout=30,
)
body = r.json()
print(body["data"]["shortUrl"] if body["success"] else body["error"]["code"])

<?php
$ch = curl_init('https://developers.hablame.co/api/v6/urlshortener/links');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('HABLAME_API_KEY'),
        'Idempotency-Key: ' . bin2hex(random_bytes(16)),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        'longUrl' => 'https://example.com/landing?utm_source=sms',
        'code'    => 'promo-octubre',
    ]),
]);
$body = json_decode(curl_exec($ch), true);
echo $body['success'] ? $body['data']['shortUrl'] : $body['error']['code'];

Create many at once

For a campaign use bulk creation: up to 1,000 links per request. An invalid link does not sink the batch; the response carries one result per link.

LOTE=campana-octubre-lote-01
curl -X POST https://developers.hablame.co/api/v6/urlshortener/links/batch \
  -H 'Authorization: Bearer hk_TU_API_KEY' \
  -H "Idempotency-Key: $LOTE" \
  -H 'Content-Type: application/json' \
  -d '{
    "links": [
      { "longUrl": "https://example.com/landing?c=1" },
      { "longUrl": "https://example.com/landing?c=2", "code": "oferta-2" }
    ]
  }'

List and measure

curl 'https://developers.hablame.co/api/v6/urlshortener/links?perPage=20&search=promo' \
  -H 'Authorization: Bearer hk_TU_API_KEY'

curl 'https://developers.hablame.co/api/v6/urlshortener/links/h0b.co/promo-octubre/stats?from=2026-10-01&to=2026-10-24' \
  -H 'Authorization: Bearer hk_TU_API_KEY'

Turn off and restore

curl -X PATCH https://developers.hablame.co/api/v6/urlshortener/links/h0b.co/promo-octubre \
  -H 'Authorization: Bearer hk_TU_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "status": "disabled" }'

curl -X POST https://developers.hablame.co/api/v6/urlshortener/links/h0b.co/promo-octubre/restore \
  -H 'Authorization: Bearer hk_TU_API_KEY'

Expected responses

Creating a link answers 201 with the link inside data. The values are examples:

{
  "success": true,
  "data": {
    "domain": "h0b.co",
    "code": "promo-octubre",
    "shortUrl": "https://h0b.co/promo-octubre",
    "longUrl": "https://example.com/landing?utm_source=sms",
    "isAlias": true,
    "status": "active",
    "domainStatus": "active",
    "expiresAt": "2027-01-01T04:59:59Z",
    "createdAt": "2026-10-24T15:04:05Z",
    "clicks": 0,
    "uniqueClicks": 0,
    "firstClickAt": null,
    "lastClickAt": null
  },
  "meta": {
    "requestId": "5d0f3a9c7b2e41a8",
    "clientIp": "203.0.113.45",
    "timestamp": "2026-10-24T15:04:05+00:00",
    "responseTimeMs": 31.2
  }
}

shortUrl

The full short URL, always https://{domain}/{code}. It is the one you hand out.

status

active, disabled or blocked. Expired is not a status: an active link whose expiresAt has passed stops redirecting but stays active. blocked is set by Hablame for security: it does not redirect and cannot be edited, deleted or reactivated.

domainStatus

Whether the domain lets the link open. With suspended, released or pending the link does not redirect even if its status is active.

clicks / uniqueClicks

Lifetime visits of the link and the sum of each day’s unique visits. They can take from seconds to a few minutes to show up. They do not count bots or previews.

With a repeated Idempotency-Key and the same body, you receive the same link with the Idempotency-Status: replayed header, without creating or charging another. Deleting answers 204 with no body. Lists carry items, total, hasMore and nextCursor: to walk through many links pass the nextCursor as cursor in the next request.

Common errors

All the codes are in the error catalog and the most common symptoms are in troubleshooting.

Security

• Separate your keys by service. The URL shortener is granted in full: a key with it can also create, redirect and delete your links if it leaks. Give the urlshortener service only to the system that really manages them; only the owner of your organization creates keys.
• Look after the destination. Whoever controls longUrl controls where your already distributed links lead. Validate where each destination comes from before sending it.
• Hablame filters dangerous destinations. localhost, internal names, private or reserved IP addresses, other short links, destinations with a user before the domain and domains with invisible characters or characters from other alphabets are rejected. On shared domains, aliases that imitate a brand, a bank, a payment method or a public entity are not accepted either.
• A deleted link does not release its code. Nobody can reuse it to point somewhere else. You can restore it for 90 days.
• Every change is recorded: the previous value, the new one and who made it (the API key or the Cloud user).

Related endpoints

All of them only require the urlshortener service: with it, the key also creates, edits, deletes and restores.

Next steps

For technical questions, email developers@hablame.co. If you have a production incident, message us on WhatsApp at +57 319 660 0002, 24/7.