# URL Shortener API V3

The URL Shortener API enables applications to create shortened URLs and vanity links using URL shorteners configured for your Sprinklr environment.
Use this API to:

* Retrieve available URL shorteners.
* Create standard shortened URLs.
* Create vanity URLs using a custom link hash.
To create a shortened URL, first retrieve the available shorteners and use the returned id as the urlShortenerId in the shorten request.


## API Endpoints

| Operation | Method | Path |
|  --- | --- | --- |
| Fetch URL Shorteners | GET | `/api/v3/link/shorteners` |
| Shorten URL | POST | `/api/v3/link/shorten` |


## Base URL

All API calls are sent to:

```
https://api3.sprinklr.com/{env}/api/v3
```

The URL Shortener resources are:

```
https://api3.sprinklr.com/{env}/api/v3/link/shorteners
https://api3.sprinklr.com/{env}/api/v3/link/shorten
```

Replace `{env}` with your assigned Sprinklr environment. See [APIs | Sprinklr Developer Portal](https://dev.sprinklr.com/apis) for the published environment list.
For the production environment at app.sprinklr.com, omit the {env} segment from the URL.

## Authentication & Headers

| Header | Value | Purpose |
|  --- | --- | --- |
| `Authorization` | `Bearer {{accessToken}}` | Bearer token used to authenticate the user with the server |
| `Key` | `{{apiKey}}` | API key that authenticates your application with the server |
| `Content-Type` | `application/json` | Required on `POST /link/shorten` |
| `Accept` | `application/json` | Acceptable response type |


Include `Content-Type`: `application/json` when sending a request body.

## URL Shortener Operations

### Fetch URL Shorterner

```
GET /link/shorteners
```

Retrieves the URL shorteners available for use.
The response provides the shortener id required by the Shorten URL operation and indicates whether a shortener supports vanity links.

**Example Request**

```Shell
curl --location --request GET \
'https://api3.sprinklr.com/{env}/api/v3/link/shorteners' \
--header 'Authorization: Bearer {access-token}' \
--header 'Key: {api-key}' \
--header 'Accept: application/json'
```

**Example Response**

```JSON
{
  "data": [
    {
      "id": "0000000000000000000000a1",
      "name": "Corporate spr.ly",
      "provider": "SPRINKLR",
      "canUseForVanityLink": true
    },
    {
      "id": "0000000000000000000000b2",
      "name": "Marketing Bitly",
      "provider": "BITLY",
      "canUseForVanityLink": false
    }
  ],
  "errors": []
}
```

**Response Parameters**

| Field | Description | Type |
|  --- | --- | --- |
| `id` | Unique identifier of the URL shortener. Use this value as `urlShortenerId`. | String |
| `name` | Name of the URL shortener. | String |
| `provider` | URL-shortening service provider. | String |
| `canUseForVanityLink` | Indicates whether the shortener supports vanity links. | Boolen |


### Shorten URL

```
POST /api/v3/link/shorten
```

Creates a shortened URL using the specified URL shortener.

**Request Parameters**

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `link` | string | **Yes** | The URL to be shortened. Provide a fully qualified URL including the scheme |
| `urlShortenerId` | string | **Yes** | The URL shortener to use. Obtain this from `GET /link/shorteners` |
| `name` | string | No | Unique name or URL hash. When supplied, it becomes the link hash, producing a vanity link |
| `description` | string | No | Description of the URL being shortened |


Obtain `urlShortenerId` from the Fetch URL Shorteners operation.

**Example Request**

```Shell
curl --location --request POST \
  'https://api3.sprinklr.com/{env}/api/v3/link/shorten' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'Key: {api-key}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "link": "https://www.example.com/spring-campaign-landing-page",
    "urlShortenerId": "0000000000000000000000a1"
  }'
```

**Example Response**

```JSON
{
  "data": {
    "id": 600000000,
    "urlShortenerId": "0000000000000000000000a1",
    "linkHash": "6003ZAI5v",
    "originalLink": "https://www.example.com/spring-campaign-landing-page",
    "shortLink": "https://spr.ly/6003ZAI5v",
    "campaignId": -11
  },
  "errors": []
}
```

Use the returned `shortLink` as the shortened URL.

### Create a Vanity link

To create a vanity link, include name in the shorten request.

The selected URL shortener must return:

```JSON
{
"canUseForVanityLink": true
}
```

**Example Request:**

```Shell
curl --location --request POST \
  'https://api3.sprinklr.com/{env}/api/v3/link/shorten' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'Key: {api-key}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "link": "https://www.example.com/spring-campaign-landing-page",
    "urlShortenerId": "0000000000000000000000a1",
    "name": "SpringSale"
  }'
```

**Example Reponse**

```JSON
{
  "data": {
    "id": 600000001,
    "urlShortenerId": "0000000000000000000000a1",
    "linkHash": "SpringSale",
    "originalLink": "https://www.example.com/spring-campaign-landing-page",
    "shortLink": "https://spr.ly/SpringSale",
    "campaignId": -10,
    "domain": "spr.ly"
  },
  "errors": []
}
```

## Short Link Response Parameters

| Parameter | Description | Type |
|  --- | --- | --- |
| `id` | Unique identifier of the shortened link. | Integer `(int64)` |
| `urlShortenerId` | Identifier of the URL shortener used. | String |
| `linkHash` | Hash associated with the shortened URL. | String |
| `originalLink` | Original URL submitted for shortening. | String |
| `shortLink` | Generated shortened URL. | String |
| `campaignId` | Campaign identifier associated with the shortened URL. | Integer (int64) |
| `description` | Description of the shortened URL. | String |
| `domain` | Domain used for the shortened URL. | String |
| `provider` | URL-shortening provider. | String |
| `createdTime` | Creation timestamp. | Integer (int64) |
| `modifiedTime` | Last modified timestamp. | Integer (int64) |
| `archived` | Indicates whether the link is archived. | Boolean |


## Response format and status codes

### Response envelope

Every Sprinklr V3 response is wrapped in a standard envelope:

```json
{
  "data": { },
  "errors": [ ]
}
```

`GET /link/shorteners` returns an array in `data`. `POST /link/shorten` returns a single object in `data`.

Each entry in `errors` contains:

| Field | Type | Description |
|  --- | --- | --- |
| `id` | string | Error identifier |
| `code` | string | Error code |
| `message` | string | Human-readable message |


**Bind your client to this envelope**, and inspect the `errors` array even when the HTTP status indicates success.

### Status codes

| Code | Meaning | Handling |
|  --- | --- | --- |
| `200` | Success | Returned by `GET /link/shorteners` |
| `201` | Created | Returned by `POST /link/shorten` on success |
| `400` | Bad request | A required field is missing, the URL is malformed, or the vanity name was rejected |
| `401` | Unauthorized | Expired token, wrong environment, or a missing authentication header |
| `403` | Forbidden | Your user lacks permission for the shortener, or the partner is not entitled |
| `404` | Not found | Typically an unrecognised `urlShortenerId` |


Accept both `200` and `201` as success on `POST /link/shorten`, or check for any `2xx`.

Rate limiting is applied at the Sprinklr API gateway across the platform. Implement retry with exponential backoff for `429` and `5xx` responses, and honour the `Retry-After` header when it is present. Because shortening is not idempotent, retry only on network-level failures and on `429`, and be aware that retrying after a timeout may create a second link.

### About error messages

Validation errors for shortening are surfaced from the external shortening provider rather than generated by Sprinklr. This has three practical consequences:

- Error message text and codes are not stable across providers. A partner using Bitly and a partner using `spr.ly` can receive different error bodies for the same mistake.
- Branch your error handling on the HTTP status code rather than on the message text.
- Log the full `errors` array and surface the message to an operator rather than attempting to parse it.


## Migrating from V2

### The short version

Change `v2` to `v3` in the path. For most integrations, that is the entire migration.

|  | V2 | V3 |
|  --- | --- | --- |
| Shorten | `POST /{env}/api/v2/link/shorten` | `POST /{env}/api/v3/link/shorten` |
| List shorteners | `GET /{env}/api/v2/link/shorteners` | `GET /{env}/api/v3/link/shorteners` |
| Request fields | `link`, `urlShortenerId`, `name` | Unchanged |
| Required fields | `link`, `urlShortenerId` | Unchanged |
| Response envelope | `{data, errors}` | Unchanged |
| Authentication headers | `Authorization`, `Key` | Unchanged |
| Success status on shorten | `200` | `201` |


### The two things that genuinely differ

**Success status code.** V2 returned `200` on shortening. V3 returns `201 Created`. A client written as `if (status === 200)` will treat a successful V3 creation as a failure. **This is the most likely cause of a broken migration.** Widen the check to accept `200` and `201`, or accept any `2xx`.

**Link hash format for standard links.** In V2, the standard-link `linkHash` was the decimal string form of the numeric `id`, for example `id: 101612830` with `linkHash: "101612830"`. In V3, standard links return an alphanumeric token unrelated to the `id`. If any code derives one value from the other, or validates that `linkHash` is numeric, update it to read `linkHash` and `shortLink` directly from the response.

Vanity links are unaffected, because their hash has always been the `name` you supply.

### What did not change

Request field names and semantics, the required field set, the `{data, errors}` envelope, the `campaignId` sentinels (`-10` for vanity, `-11` for standard), authentication, and the vanity-capability rule are all identical. Error responses are also unchanged, because validation errors originate from the external shortening provider in both versions.

## Common Use Cases

### Shorten a link for a scheduled campaign post

Fetch the shortener list once at start-up and cache it. For each URL, call `POST /link/shorten` with `link` and the cached `urlShortenerId`, then publish `data.shortLink`. Store `data.id` and `data.linkHash` alongside your campaign record so reporting can be correlated later.

### Reserve a memorable vanity link

Select a shortener where `canUseForVanityLink` is `true`, then post with `name` set to the hash you want. Confirm success by checking that `data.linkHash` equals the `name` you sent and that `campaignId` is `-10`. If the hash comes back different, you did not receive the vanity link you requested, so do not publish it as one.

### Build a link-shortening service for internal teams

Expose a thin wrapper over `POST /link/shorten` and maintain your own mapping from original URL to short link. Check your mapping first and call Sprinklr only on a miss. This keeps your short-link inventory stable and avoids creating a new link each time the same URL is submitted.

### Choose between multiple configured shorteners

`GET /link/shorteners` returns `name` and `provider` for each entry. Use `name` for human-facing selection and `provider` when behaviour depends on the underlying service. Keep the choice configurable so the same code works across environments and partners.

## Best practices

- **Cache the shorteners list.** It changes only when an administrator adds or removes a shortener. Fetch it at start-up rather than before every shortening call.
- **Persist the creation response.** Store `id`, `linkHash`, and `shortLink` when the link is created. These values are returned at creation time.
- **Accept `200` and `201`** as success on shortening.
- **Null-check optional fields.** Depend only on `id`, `urlShortenerId`, `linkHash`, `originalLink`, `shortLink`, and `campaignId`.
- **Read the scheme from `shortLink`.** Embed the returned string as-is rather than reconstructing the URL from `domain` and `linkHash`.
- **Deduplicate before retrying.** Shortening is not idempotent, so a retry after a timeout can create a duplicate link.
- **Check `canUseForVanityLink` before requesting a vanity link**, and treat a missing value as `false`.
- **Do not look up `campaignId` values of `-10` or `-11`.** These are sentinel values indicating a vanity or standard link, not references to a real campaign.
- **Keep shortener IDs in configuration**, not in code, because they differ across environments and partners.


> **Firebase shorteners.** Google deprecated its Firebase URL shortener, and Firebase shorteners are no longer supported in Sprinklr effective **25 August 2025**. If your integration selects a shortener by `provider`, ensure it does not target Firebase.


## Troubleshooting

| Symptom | Likely cause | Resolution |
|  --- | --- | --- |
| `401` on every call | Wrong `{env}`, expired access token, or a missing `Key` header | Confirm the environment, refresh the token, and send both authentication headers |
| `400` with an unclear message | A required field is missing, or the provider rejected the request | Confirm `link` and `urlShortenerId` are both present and that `link` includes a scheme |
| `404` on shortening | `urlShortenerId` does not exist or is not visible to your user | Re-fetch `GET /link/shorteners` and use an `id` from that response |
| Vanity name ignored, standard hash returned | The shortener does not support vanity links | Check `canUseForVanityLink` and select a different shortener |
| Vanity request rejected | The hash is already claimed on that domain | Retry with a different `name` |
| Client fails to deserialize the response | Client bound to the inner object rather than the envelope | Bind to `{data, errors}` and read the payload from `data` |
| Duplicate short links after a retry | Shortening is not idempotent | Deduplicate against your own mapping before retrying |
| Success status but nothing usable in `data` | An error was returned alongside a success status | Inspect the `errors` array on every response |


**Product documentation**

- [Configure a URL shortener](https://www.sprinklr.com/help/articles/url-shorteners/configure-a-url-shortener/6467ab928ea3c9635cf374a9)
- [The Sprinklr APIs](https://www.sprinklr.com/help/articles/platform-modules/the-sprinklr-apis/633c5c2359534970b26f96ae)