TinyUrl¶
The TinyUrl APIs shorten destination URLs for use in messages. You can generate a short code automatically or choose a static Tiny URL with a named path, such as https://links.example.com/privacy.
API versions and authentication¶
These examples describe the versioned API contract implemented in platform 7.5.
| API version | Register one URL | Register a list |
|---|---|---|
| 3.0 | POST /api/v3.0/TinyUrl/Register |
POST /api/v3.0/TinyUrl/RegisterList |
| 3.1 | POST /api/v3.1/TinyUrl/Register |
POST /api/v3.1/TinyUrl/RegisterList |
| 3.2 | POST /v3.2/TinyUrl/Register |
POST /v3.2/TinyUrl/RegisterList |
Use your allocated API host over HTTPS, send Content-Type: application/json, and authenticate as described in Security. The account must have permission to register Tiny URLs. The unversioned legacy API uses a different request contract.
Custom Tiny URLs¶
DIY Surveys supports custom domains for short links. You can use the platform's configured default domain or ask DIY Surveys to register and configure a domain for your account.
Supply the domain in TinyDomain, for example links.example.com. It must already be mapped to the DIY Surveys service and available to the authenticated account. Supplying a domain in a request does not register or configure it.
If TinyDomain is omitted or empty, the service selects the account's first configured Tiny URL domain, or the platform default if the account has none. The returned link uses the HTTP/HTTPS setting configured for that domain.
All examples below use the placeholder links.example.com with HTTPS configured. Replace it with a domain configured for your account.
Static Tiny URLs¶
A slashtag is the named part of a short link after the domain. In https://links.example.com/privacy, the slashtag is privacy.
| Link type | Request | Example result |
|---|---|---|
| Generated short link | Omit Slashtag, or leave it empty. |
https://links.example.com/00AB12 |
| Static short link | Set Slashtag to privacy. |
https://links.example.com/privacy |
Static links are useful for a shared destination such as a privacy policy or campaign landing page. Use recipient-specific links when each recipient needs a different destination; do not give those different destinations the same static slashtag.
For a new static link, choose an unused slashtag on the selected domain. Supply only the path name, without the domain or a leading slash. Simple names such as privacy or customer-feedback are easy to share.
Slashtag selects the fixed path. Reuse is a separate option that requests reuse of an existing link; setting Reuse to true alone does not create a named path. Do not rely on registration to replace the destination of an existing slashtag.
Register¶
Registers one destination URL and returns an object containing the short link.
Request fields¶
| Field | Type | Description |
|---|---|---|
FullUrl |
string | Required. The complete destination URL, including its scheme, for example https://www.example.com/privacy. |
TinyDomain |
string | Optional. A Tiny URL domain configured for the account. If omitted or empty, the service selects a configured domain as described above. |
Reuse |
boolean | Optional. Requests reuse of an existing link. Defaults to false. This does not select the static path. |
Slashtag |
string | Optional. A fixed path name such as privacy. Omit it or leave it empty for a generated short code. |
The request field is TinyDomain; TinyUrl is the field returned in the response.
Generated short link¶
{
"FullUrl": "https://www.example.com",
"TinyDomain": "links.example.com",
"Reuse": false
}
Example response:
{
"TinyUrl": "https://links.example.com/00AB12"
}
The generated code in this response is illustrative.
Static short link¶
{
"FullUrl": "https://www.example.com/privacy",
"TinyDomain": "links.example.com",
"Reuse": false,
"Slashtag": "privacy"
}
Example response:
{
"TinyUrl": "https://links.example.com/privacy"
}
Opening this static short link redirects to the registered destination, https://www.example.com/privacy.
RegisterList¶
Registers multiple destination URLs. Each entry accepts the same fields as Register, so a list can include both generated and static links.
Use the Urls collection. UrlList is also accepted for compatibility; supply one collection rather than both.
{
"Urls": [
{
"FullUrl": "https://www.example.com",
"TinyDomain": "links.example.com",
"Reuse": false
},
{
"FullUrl": "https://www.example.com/contact",
"TinyDomain": "links.example.com",
"Reuse": false,
"Slashtag": "contact"
}
]
}
The response is a JSON array of URL strings in request order, without a UrlList wrapper:
[
"https://links.example.com/00AB12",
"https://links.example.com/contact"
]
Static links in message macros¶
You can also create a static link while processing a message using the four-parameter tiny macro:
{tiny(https://www.example.com/privacy,links.example.com,false,privacy)}
With the example domain configured, this inserts https://links.example.com/privacy into the message. The parameters are the destination URL, Tiny URL domain, reuse option and slashtag, in that order.
See Macro Reference for all parameters and Macros for a complete message request.
Metadata¶
The current versioned Tiny URL request model does not define a MetaData field. Do not copy the metadata fields from legacy registration examples into this contract. Message metadata is documented separately under Metadata.
Responses and troubleshooting¶
| Status or result | Meaning |
|---|---|
200 from Register |
An object containing TinyUrl. Check that the returned URL is non-empty. |
200 from RegisterList |
An array of URL strings. Check each entry before using it. |
400 |
Registration failed. The controller reports: There was a problem registering the tiny url. |
401 or 403 |
Check the API credentials and the account's permissions. |
A custom domain that is not configured for the authenticated account can return an empty URL even with HTTP 200. Check the domain's account mapping if this happens.