API

Last updated on 16 November 2023.

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:

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.

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

Retrieve a paginated list of links.

ParameterTypeDescription
pageThe page number to retrieve
Default: 1
limitThe 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"
  }
}

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 a new link.

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

Short Link

Shorten a long URL.

ParameterTypeDescription
typeThe type of link to create
titleAn optional title for the link
forward_parametersWhether URL parameters should be forwarded to the destination
Default: false
destinationThe destination URL
Request
POST /links
{
  "type": "short-link",
  "destination": "https://example.com"
}

QR Code

Create a QR code from a URL.

ParameterTypeDescription
typeThe type of link to create
titleAn optional title for the link
forward_parametersWhether URL parameters should be forwarded to the destination
Default: false
destinationThe 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.

ParameterTypeDescription
typeThe type of link to create
titleAn optional title for the link
forward_parametersWhether URL parameters should be forwarded to the destination
Default: false
destinationsList 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.

ParameterTypeDescription
typeThe type of link to create
titleAn optional title for the link
forward_parametersWhether URL parameters should be forwarded to the destination
Default: false
destinationsList 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.

ParameterTypeDescription
typeThe type of link to create
titleAn optional title for the link
forward_parametersWhether URL parameters should be forwarded to the destination
Default: false
destinationsList of device types and their corresponding destination URLs
destinations.*.categorydesktop, tablet, mobile, or fallback
destinations.*.urlThe 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.

ParameterTypeDescription
typeThe type of link to create
titleAn optional title for the link
forward_parametersWhether URL parameters should be forwarded to the destination
Default: false
destinationsList of operating systems and their corresponding destination URLs
destinations.*.categoryios, android, or fallback
destinations.*.urlThe 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 Country

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

ParameterTypeDescription
typeThe type of link to create
titleAn optional title for the link
forward_parametersWhether URL parameters should be forwarded to the destination
Default: false
destinationsList of countries and their corresponding destination URLs
destinations.*.categoryISO 3166-1 alpha-2 country code
destinations.*.urlThe 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 Click Count

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

ParameterTypeDescription
typeThe type of link to create
titleAn optional title for the link
forward_parametersWhether URL parameters should be forwarded to the destination
Default: false
destinationsList of limits and their corresponding destination URLs
destinations.*.limitNumber of clicks allowed per destination
-1 represents fallback.
destinations.*.urlThe 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.

ParameterTypeDescription
typeThe type of link to create
titleAn optional title for the link
forward_parametersWhether URL parameters should be forwarded to the destination
Default: false
destinationsList of datetimes and and their corresponding destination URLs
destinations.*.datetimeDatetime in YYYY-MM-DDThh:mm format
destinations.*.urlThe 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 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"
  }
}

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 or monthly number of clicks on a link

ParameterTypeDescription
intervaldaily or monthly
startIn YYYY-MM-DD format
endIn 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
}
TermsPrivacyCookies
Copyright © 2024