API - Nimble Links

Features listed in this page are currently only available on the Advanced plan. See Pricing for more details.

This is an overview of the Application Programming Interfaces (APIs) available on Nimble Links. In this document, we cover:

# Authentication
# Rate Limits
# Link Management API

# List Links
# Get Link
# Create Link
# Delete Link
# Get QR Code

# Link Analytics API

# Clicks Total
# Clicks Trend

Base URL

The base URL to send all API requests is:

https://www.nimblelinks.com/api/v1.0

Authentication

To get started, head over to your team settings and generate an API key. A key will look something like this:

1a2b3c4d5e6f7g8h9i0j1k2l3m4n5

Every request you send to our API should include your API key as a bearer token:

Authorization: Bearer 1a2b3c4d5e6f7g8h9i0j1k2l3m4n5

Rate Limits

To ensure a consistent developer experience for all API users, the Nimble Links API is rate limited. Rate limits are applied on a per-team basis in unit time. If you exceed the rate limit, you will receive a 429 Too Many Requests response.

These are the current limits that apply to all teams by default:

30 requests per minute
300 requests per hour

We may change these limits in the future to balance for demand and reliability.

For higher limits, please reach out to support@nimblelinks.com.

Link Management API

This API allows you to list, create, and delete links under your team.

List Links

Retrieve a paginated list of links.

Parameter	Type	Description
`page`		The page number to retrieve Default: 1
`limit`		The number of links to retrieve per page Default: 10 Maximum: 25

Request

GET /links

Response

{
  "data": [
    {
      "id": "a1b2c3e4",
      "title": null,
      "type": "short-link",
      "settings": {
        "destination": "https://example.com",
        "forward_parameters": false
      },
      "url": "https://nimble.li/a1b2c3e4",
      "created_at": "2023-11-14T13:32:55.000000Z",
      "updated_at": "2023-11-14T13:33:38.000000Z"
    },
    {
      "...": "..."
    }
  ],
  "links": {
    "first": "https://www.nimblelinks.com/api/v1.0/links?page=1",
    "last": "https://www.nimblelinks.com/api/v1.0/links?page=4",
    "prev": null,
    "next": "https://www.nimblelinks.com/api/v1.0/links?page=2"
  }
}

Get Link

Retrieve a specific link.

Request

GET /links/{:id}

Response

{
  "data": {
    "id": "a1b2c3e4",
    "title": null,
    "type": "qr-code",
    "settings": {
      "destination": "https://example.com",
      "forward_parameters": false
    },
    "url": "https://nimble.li/a1b2c3e4",
    "created_at": "2023-11-14T13:31:41.000000Z",
    "updated_at": "2023-11-14T13:31:41.000000Z"
  }
}

Create Link

Create a new link.

This endpoint accepts different parameters depending on the type of link you're creating.

Short Link

Shorten a long URL.

Parameter	Type	Description
`type`		The type of link to create
`title`		An optional title for the link
`forward_parameters`		Whether URL parameters should be forwarded to the destination Default: false
`destination`		The destination URL

Request

POST /links

{
  "type": "short-link",
  "destination": "https://example.com"
}

QR Code

Create a QR code from a URL.

Parameter	Type	Description
`type`		The type of link to create
`title`		An optional title for the link
`forward_parameters`		Whether URL parameters should be forwarded to the destination Default: false
`destination`		The destination URL

Request

POST /links

{
  "type": "qr-code",
  "destination": "https://example.com"
}

This endpoint does not return QR code files. To access links to downloadable files, see the Get QR Code endpoint.

Redirect Evenly

Create a link that distributes traffic evenly.

Parameter	Type	Description
`type`		The type of link to create
`title`		An optional title for the link
`forward_parameters`		Whether URL parameters should be forwarded to the destination Default: false
`destinations`		List of destination URLs

Request

POST /links

{
  "type": "redirect-evenly",
  "destinations": [
    "https://example.com/a",
    "https://example.com/b"
  ]
}

Redirect Randomly

Create a link that distributes traffic randomly.

Parameter	Type	Description
`type`		The type of link to create
`title`		An optional title for the link
`forward_parameters`		Whether URL parameters should be forwarded to the destination Default: false
`destinations`		List of destination URLs

Request

POST /links

{
  "type": "redirect-randomly",
  "destinations": [
    "https://example.com/a",
    "https://example.com/b"
  ]
}

Redirect by Device

Create a link that redirects users to different destinations based on their device type.

Parameter	Type	Description
`type`		The type of link to create
`title`		An optional title for the link
`forward_parameters`		Whether URL parameters should be forwarded to the destination Default: false
`destinations`		List of device types and their corresponding destination URLs
`destinations.*.category`		desktop, tablet, mobile, or fallback
`destinations.*.url`		The destination URL

Request

POST /links

{
  "type": "redirect-device",
  "destinations": [
    {
      "category": "mobile",
      "url": "https://m.example.com"
    },
    {
      "category": "fallback",
      "url": "https://example.com"
    }
  ]
}

Redirect by Operating System

Create a link that redirects users to different destinations based on their operating system.

Parameter	Type	Description
`type`		The type of link to create
`title`		An optional title for the link
`forward_parameters`		Whether URL parameters should be forwarded to the destination Default: false
`destinations`		List of operating systems and their corresponding destination URLs
`destinations.*.category`		ios, android, or fallback
`destinations.*.url`		The destination URL

Request

POST /links

{
  "type": "redirect-operating-system",
  "destinations": [
    {
      "category": "ios",
      "url": "https://example.com/ios"
    },
    {
      "category": "fallback",
      "url": "https://example.com"
    }
  ]
}

Redirect by Browser

Create a link that redirects users to different destinations based on their web browser.

Parameter	Type	Description
`type`		The type of link to create
`title`		An optional title for the link
`forward_parameters`		Whether URL parameters should be forwarded to the destination Default: false
`destinations`		List of browsers and their corresponding destination URLs
`destinations.*.category`		chrome, firefox, safari, edge, opera, or fallback
`destinations.*.url`		The destination URL

Request

POST /links

{
  "type": "redirect-browser",
  "destinations": [
    {
      "category": "chrome",
      "url": "https://example.com/chrome"
    },
    {
      "category": "fallback",
      "url": "https://example.com"
    }
  ]
}

Redirect by Country

Create a link that redirects users to different destinations based on their country.

Parameter	Type	Description
`type`		The type of link to create
`title`		An optional title for the link
`forward_parameters`		Whether URL parameters should be forwarded to the destination Default: false
`destinations`		List of countries and their corresponding destination URLs
`destinations.*.country`		ISO 3166-1 alpha-2 country code
`destinations.*.url`		The destination URL

Request

POST /links

{
  "type": "redirect-country",
  "destinations": [
    {
      "country": "US",
      "url": "https://example.com/us"
    },
    {
      "country": "CA",
      "url": "https://example.com/ca"
    },
    {
      "country": "fallback",
      "url": "https://example.com"
    }
  ]
}

Redirect by Language

Create a link that redirects users to different destinations based on their preferred language.

Parameter	Type	Description
`type`		The type of link to create
`title`		An optional title for the link
`forward_parameters`		Whether URL parameters should be forwarded to the destination Default: false
`destinations`		List of languages and their corresponding destination URLs
`destinations.*.language`		ISO 639-1 country code
`destinations.*.url`		The destination URL

Request

POST /links

{
  "type": "redirect-language",
  "destinations": [
    {
      "country": "en",
      "url": "https://example.com/en"
    },
    {
      "country": "fr",
      "url": "https://example.com/fr"
    },
    {
      "country": "fallback",
      "url": "https://example.com"
    }
  ]
}

Redirect by Click Count

Create a link that redirects users to different destinations based on the number of clicks on your link.

Parameter	Type	Description
`type`		The type of link to create
`title`		An optional title for the link
`forward_parameters`		Whether URL parameters should be forwarded to the destination Default: false
`destinations`		List of limits and their corresponding destination URLs
`destinations.*.limit`		Number of clicks allowed per destination -1 represents fallback.
`destinations.*.url`		The destination URL

Request

POST /links

{
  "type": "redirect-click-count",
  "destinations": [
    {
      "limit": 10,
      "url": "https://example.com/super-early-bird"
    },
    {
      "limit": 90,
      "url": "https://example.com/early-bird"
    },
    {
      "limit": -1,
      "url": "https://example.com/fallback"
    }
  ]
}

Redirect by Date & Time

Create a link that redirects users to different destinations based on the time they click on the link.

Parameter	Type	Description
`type`		The type of link to create
`title`		An optional title for the link
`forward_parameters`		Whether URL parameters should be forwarded to the destination Default: false
`destinations`		List of datetimes and and their corresponding destination URLs
`destinations.*.datetime`		Datetime in YYYY-MM-DDThh:mm format
`destinations.*.url`		The destination URL

Request

POST /links

{
  "type": "redirect-date-time",
  "destinations": [
    {
      "datetime": "2023-01-15T15:12",
      "url": "https://example.com/early-bird"
    },
    {
      "datetime": -1,
      "url": "https://example.com/standard-price"
    }
  ]
}

Redirect Formula

Creating links that redirect by formula is currently not supported via the API.

Delete Link

Delete a link permanently.

Request

DELETE /links/{:id}

Get QR Code

Retrieve the QR Code files for a specific link.

Request

GET /links/{:id}/qr

Response

{
  "data": {
    "svg": "https://www.nimblelinks.com/links/a1b2c3e4/qr/download?format=svg",
    "png": "https://www.nimblelinks.com/links/a1b2c3e4/qr/download?format=png"
  }
}

Link Analytics API

The Analytics API provides endpoints for monitoring how a team's links are performing.

Link Clicks Total

Get the total number of times a link has been clicked.

Request

GET /links/{:id}/clicks/total

Response

{
  "value": 4812
}

Link Clicks Trend

Get the daily, weekly, or monthly number of clicks on a link

Parameter	Type	Description
`interval`		daily, weekly, or monthly
`start`		In YYYY-MM-DD format
`end`		In YYYY-MM-DD format

Request

GET /links/{:id}/clicks?interval=daily&start=2023-01-01&end=2023-01-03

Response

{
  "2023-01-01": 3,
  "2023-01-02": 0,
  "2023-01-03": 1
}