/api/v6/urlshortener/linksCreate a short link
Publish a short link with a generated code or your own alias. Charged on creation, unless your plan includes it.
Scope and limits
API key with the urlshortener service enabled and the urlshortener.write capability granted
35 requests per second
Supports Idempotency-Key
- The destination URL allows up to 2048 characters; the body, up to 64 KiB.
- Destinations on
localhost,*.local,*.internalor on private or reserved IPs are rejected; so are destinations that already are a short link (our domains or shorteners such as bit.ly, tinyurl.com or t.co); destinations with a user or password before the domain (user@); domains with accents, ñ or other alphabets (also asxn--), and URLs with invisible characters. - With a plan: up to 100,000 creations per Colombia day (daily quota).
Creates a short link on one of the domains available to your organization. If you do not send code, the service generates a 7-character one (0-9a-z); if you do, it becomes an alias (isAlias: true). Codes are unique per domain, and the code of a deleted link cannot be used for another link: if it was yours, you can restore it for 90 days.
Each created link is charged at your organization’s current price (see `GET /api/v6/urlshortener/pricing`). If your organization has an active monthly URL shortener plan, creating links is not charged, and a daily creation quota applies instead (100,000 per Colombia day, unless you agreed another one): once reached, the API returns 429 URLSHORTENER_LINK_QUOTA_EXCEEDED until midnight. Without a plan there is no daily quota: without available balance the API returns 402 and the link is not created.
Retry without duplicates with `Idempotency-Key`. If a creation is cut off (a timeout, a 5xx) and you repeat it with the same key and the same body, you get the same link —201 with Idempotency-Status: replayed— without creating another one or charging twice, even while the first one is still being processed. The same key with a different body returns 422 IDEMPOTENCY_KEY_REUSED. On this endpoint the key stays tied to the link forever. Without a key, each retry creates and charges another link.
The body is validated before the balance is checked: an invalid URL, alias, domain or expiry returns its error without touching your balance.
Requires a key that can write
Besides the urlshortener service, the API key needs the urlshortener.write capability, which only an owner or an administrator of your organization can grant when creating the key. Without it, the key lists and reads links, statistics, the overview, the domains and the pricing, and gets 403 AUTH_CAPABILITY_NOT_ALLOWED here.
Many links at once, for example for a campaign? Use bulk creation: up to 1,000 per request, with the same rules and a single charge for what was created.
Headers
Idempotency-KeyA-Za-z0-9_-), unique per organization. If you repeat the creation with the same key and the same body, you get the link that was already created, without creating another one or charging again. See the idempotency guide.Request body
application/jsonOnly these four fields are accepted. One that does not exist —for example `url` or `alias`, from the previous contract— is rejected with `400` naming the field.longUrlhttp or https with a host, max 2048 characters. Parameters (UTM included) go inside the URL as is: the redirector sends visitors to exactly this address. It cannot be another short link, carry a user before the domain, or have a domain with accents or invisible characters.domain409 DOMAIN_NOT_VERIFIED.code- and _ (uppercase is lowercased). Must be free on the domain and not a reserved word (api, admin, stats, docs, login, status…). On the platform domains, which every organization shares, aliases that look like a brand, a bank, a payment method or a public entity (bancolombia-seguro, pago-pse, dian…) are not accepted either; on your own domain they are.expiresAtYYYY-MM-DD HH:MM:SS, YYYY-MM-DDTHH:MM or YYYY-MM-DD. Without a time zone it is read in Colombia time (`-05:00`); with one, the zone you send is honored. Once expired, the link stops redirecting (the visitor gets 404) and keeps status: active.{
"longUrl": "https://example.com/landing?utm_source=sms",
"domain": "h0b.co",
"code": "promo-septiembre",
"expiresAt": "2026-12-31T23:59:59-05:00"
}Responses
Link created. With a repeated Idempotency-Key and the same body, it is the link from the first time (Idempotency-Status: replayed): no other one was created or charged.
{
"success": true,
"data": {
"domain": "h0b.co",
"code": "a1b2c3d",
"shortUrl": "https://h0b.co/a1b2c3d",
"longUrl": "https://example.com/landing?utm_source=sms",
"isAlias": false,
"status": "active",
"domainStatus": "active",
"expiresAt": null,
"createdAt": "2026-09-23T15:04:05Z",
"clicks": 0,
"uniqueClicks": 0,
"firstClickAt": null,
"lastClickAt": null
},
"meta": {
"requestId": "8f0c0e2a4b1d4c8fae2b7a91e0c5d3f6",
"timestamp": "2026-09-23T18:30:00+00:00",
"responseTimeMs": 7.2
}
}Invalid body: destination URL, alias, expiry or domain, a field that does not exist, malformed JSON, or an Idempotency-Key with another shape.
Invalid or missing credentials.
Your organization has no available balance to create the link (or no active billing account), or creating it would exceed a spend limit it configured itself (URLSHORTENER_SPEND_LIMIT_REACHED: adjust it in the spend limits, topping up does not fix it). The link is not created.
The API key does not have the URL shortener enabled (or it is turned off for your organization), lacks the urlshortener.write capability to create and edit links, cannot be used from the request network, or the organization is not active.
The alias is already taken on that domain, is a reserved word or a brand on a shared domain, or belongs to a deleted link of yours (ALIAS_RETIRED: restore it); the own domain is not verified; or the URL shortener has no price for your organization’s currency, or your organization does not have a currency yet. In the last two cases retrying does not fix it.
The Idempotency-Key was already used to create a link with a different body. Use a new key for a new link.
The request limit was exceeded, or —with a plan— the daily creation quota. In the second case Retry-After says how long until midnight in Colombia.
A free code could not be generated. Retry.
Balance could not be checked right now. The link is not created; you can retry (better with Idempotency-Key).
Possible errors
Codes this endpoint can return in error.code. The full detail lives in the catalog.
AUTH_REQUIREDNo Bearer token was sent, and every call requires one.401AUTH_INVALID_KEYThe API key is not recognized: wrong format, revoked or expired.403AUTH_SERVICE_NOT_ALLOWEDThe key is not allowed to use the service behind this endpoint.403AUTH_IP_NOT_ALLOWEDThe key only works from certain networks and your IP is not one of them.403ACCOUNT_NOT_ACTIVEYour organization is suspended or closed.403AUTH_CAPABILITY_NOT_ALLOWEDThe key has the service, but not the capability this endpoint requires.400VALIDATION_INVALID_PARAMETERA parameter or a body field is not valid.400IDEMPOTENCY_KEY_INVALIDThe idempotency key does not match the format.422IDEMPOTENCY_KEY_REUSEDThe key already exists, but with a different body.400URL_INVALIDThe destination URL is malformed.400URL_SCHEME_NOT_ALLOWEDOnly http/https destinations are allowed.400URL_TOO_LONGThe destination URL exceeds the maximum length.400URL_BLOCKED_HOSTThe destination host is private or reserved.400ALIAS_INVALIDThe custom alias doesn't match the allowed format.409ALIAS_TAKENThe alias was already used on this domain.409ALIAS_RESERVEDThe alias is a reserved word.409ALIAS_RETIREDThe alias belongs to a link of yours that you deleted.400EXPIRES_AT_INVALIDexpiresAt must be a future ISO date-time.400DOMAIN_NOT_ALLOWEDThe chosen domain isn't available to your account.409DOMAIN_NOT_VERIFIEDYour domain is not verified yet.402URLSHORTENER_INSUFFICIENT_FUNDSYour organization has no balance to create the link.402URLSHORTENER_SPEND_LIMIT_REACHEDA spend limit your organization configured was reached.403ACCOUNT_CONFIG_NOT_FOUNDWe could not load the organization behind your key.409URLSHORTENER_NOT_PRICEDThe URL shortener has no price configured for your currency.409URLSHORTENER_CURRENCY_UNDEFINEDYour organization does not have a currency yet.429URLSHORTENER_LINK_QUOTA_EXCEEDEDYour organization reached its plan’s daily link quota.429RATE_TPS_EXCEEDEDYou exceeded your organization quota for this endpoint.500INTERNAL_SERVER_ERRORSomething went wrong on our side.503SERVICE_UNAVAILABLEGeneric 503: a service we depend on is not responding.