logo
API docs by Redocly

Version 4 of the BL.INK API (4.0.0)

Download OpenAPI specification:Download

API Support: help@bl.ink URL: https://help.bl.ink

Introduction

This is version 4 of the BL.INK API. It follows common REST patterns. Download a Postman file to help you get gain knowledge of our API. Learn more about Postman Desktop App. NOTE: This version of tha API is exactly like v3 with responses that are more consistent. Docs for v3 can be found at: https://developers.bl.ink/api-v3.html Endpoints that have changed include Get Link, Create Link, and Update Link, and Validate Link, and Create Tag. Please test the responses before using in production systems.

API PRIMARY BASE URL

https://app.bl.ink/api/v4

Note: Enterprise customers must use the admin panel domain in place of https://app.bl.ink. Please use SSL (https) for all requests. All API calls are subject to a rate limit of 5 connections per second per IP address. All requests exceeding that limitation will receive an HTTP 533, HTTP 544, or HTTP 503 (Service Temporarily Unavailable).

Authentication

All endpoints require a valid access token for authentication:

  1. Invoke the POST /access_token endpoint to get a new access_token
  2. Add the following header to all endpoint requests: Authorization: Bearer <access_token> If you see a refresh token in your BL.INK UI, use that to get a new access_token

There are two types of tokens, access and refresh token. An access token is used with each api call to verify the user. A user requests an access token with either their username and password, or their username and their refresh token. An access token expires after 24 hours. Our api end point to retrieve an access token will always return a valid access token so the user doesn't need to keep track of expiration.

If you would rather not supply your password to receive an access token, you may use the refresh token instead..

Client

To generate client SDK code:

  1. Download the OpenApi specification file (above)
  2. Follow these instructions: Swagger Code Generation

Validate Login

Validate Customer Login Credentials

Validates login information

Validates login information

Request Body schema: application/json
email
required
string <email>
password
required
string <password>

Responses

Request samples

Content type
application/json
{
  • "email": "bud@smartlinker.email",
  • "password": "pa$$word"
}

Response samples

Content type
application/json
{
  • "success": 1,
  • "user": {
    }
}

Access Token

Create Access Token

Returns a valid authentication token

Returns a valid authentication token. When requesting a token it will return an existing not-expired token. If an existing expired token exists, it will generate a new token and return that. This will accept either a password for the account or a refresh token.

Request Body schema: application/json
One of
email
required
string <email>
password
required
string <password>

Responses

Request samples

Content type
application/json
Example
{
  • "email": "bud@smartlinker.email",
  • "password": "pa$$word"
}

Response samples

Content type
application/json
{
  • "success": 1,
  • "user": {
    },
  • "access_token": "8Am4WSbKTBvZtDRq48f7",
  • "expires": 1918085162
}

List Users

List Users

Returns the users in an account for those who have account admin authorization.

Responses

Response samples

Content type
application/json
{
  • "first_name": "string",
  • "last_name": "string",
  • "email_address": "string",
  • "domains": {
    }
}

List Domains

List Domains

Returns a list of the user's active domains

Returns a list of the user's active domains

query Parameters
page
integer

Page number

Responses

Response samples

Content type
application/json
{
  • "objects": [
    ],
  • "meta": {
    }
}

Get Domain by ID

Get Domain by ID

Returns a list of the user's requested domain

Returns a list of the user's requested domain

path Parameters
domain_id
required
integer

Responses

Response samples

Content type
application/json
{
  • "objects": [
    ],
  • "meta": {
    }
}

Get Domain by Domain Name

Returns a list of the user's requested domain

Returns a list of the user's requested domain

query Parameters
domain_name
required
string

Responses

Response samples

Content type
application/json
{
  • "objects": [
    ],
  • "meta": {
    }
}

Create Domain

Create Domain

Creates a new domain on the user's account

Creates a domain and returns the domain object as part of the response

Request Body schema: application/json
domain
required
string

the domain name

default
boolean

boolean denoting whether this domain should be the user's default domain

url_404
string

The address you would like 404 errors to redirect to. Must be a valid URL including protocol e.g. 'https://'

homepage
string

The address you would like to redirect users to when they visit your domain without an alias. Must be a valid URL including protocol e.g. 'https://'

Responses

Request samples

Content type
application/json
{
  • "domain": "string",
  • "default": true,
  • "url_404": "string",
  • "homepage": "string"
}

Response samples

Content type
application/json
{
  • "objects": [
    ],
  • "meta": {
    }
}

Update Domain

Update Domain

Updates the domain in question

Creates a domain and returns the domain object as part of the response

path Parameters
domain_id
required
integer
Request Body schema: application/json
op
string
Value: "replace"

The operation to be performed. Currently only replace is supported

path
string
Enum: "status" "homepage" "url_404"

Path or property you want updated

value
string

The new value you want the path/property to take. When path is status, only 'active' and 'disabled' are permitted. When path is homepage or url_404, they must be a valid URL including protocol e.g. 'https://'

Responses

Request samples

Content type
application/json
{
  • "op": "replace",
  • "path": "status",
  • "value": "string"
}

Response samples

Content type
application/json
{
  • "objects": [
    ],
  • "meta": {
    }
}

Delete Domain

Delete Domain

Delete the domain in question including all its links

Deletes a domain and all its links

path Parameters
domain_id
required
integer

Responses

Response samples

Content type
application/json
[ ]

Will take the passed in URL and create a new shortened link.

Will take the passed in URL and create a new shortened link based on the parameters that are passed in.

path Parameters
domain_id
required
integer
Request Body schema: application/json
url
required
string

The long link. The URL protocol is optional.

alias
string

Short string that will be used at the end of the domain to build your short link. Alias

rand_alias_length
integer

The length of the randomly generated alias when one is not specified. It is ignored when an alias is specified.

dupe_check
integer

When set to 1, BL.INK will search for BL.INKs matching the url to be shortened. If one or more existing BL.INKs exist BL.INK will return the first already existing BL.INK. Otherwise it will create and return a new BL.INK

notes
string

Notes to attach onto the link.

notify_on_click
integer

When set to 1, the user will be notified by email when this link has been clicked. The default is 0 no notification

override_404_check
integer

When set to 1, creation will proceed without checking that the long URL returns a 404 response

Array of objects

Array of objects defining tags to be attached to the link

utm_template_id
integer
utm_fields
object

Object defining key-value pairs for builder fields

archive_on
integer

GMT Unix timestamp defining the date to archive the link

delete_on
integer

GMT Unix timestamp defining the date to delete the link

redirect_type
integer
Enum: 301 307

Responses

Request samples

Content type
application/json
{
  • "url": "string",
  • "alias": "string",
  • "rand_alias_length": 0,
  • "dupe_check": 0,
  • "notes": "string",
  • "notify_on_click": 0,
  • "override_404_check": 0,
  • "tags": [
    ],
  • "utm_template_id": 0,
  • "utm_fields": {
    },
  • "archive_on": 0,
  • "delete_on": 0,
  • "redirect_type": 301
}

Response samples

Content type
application/json
{
  • "objects": [
    ],
  • "new_link": null
}

Will take the passed in URL and validate it.

Will take the passed in URL and validate it.

Request Body schema: application/json
url
required
string

URL encoded URL. It's a URL

Responses

Request samples

Content type
application/json
{
  • "url": "string"
}

Response samples

Content type
application/json
{
  • "objects": [
    ]
}

Returns a list of user's links filtering by query params

Searches for all links matching the query parameters that belong to the API user

path Parameters
domain_id
required
integer
query Parameters
keyword
string

Search link alias, notes, and redirect url for keyword

page
integer

Page number

url
string

long URL to search links by

order
string

Orders results differently. Possible values 'oldest' or 'latest'. Defaults to 'oldest'

users
string

A flag for privileged users (domain admins or account admins) to specify returning all links from corresponding domain instead of just links they created. Example users=all

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "count": 0,
  • "click_count": 0,
  • "objects": [
    ]
}

Returns links clicked on within a specified time range as well as the number of clicks (lifetime and within range)

(Team, Business, and Enterprise Only) This endpoint retrieves the links that have been clicked within a specified timeframe. A user with elevated privileges automatically queries all user's links under the domain and must use the 'from_user' flag to specify themselves. See request parameters. A user without these privileges will only be able to query their own links. A domain ID must be specified in the URL. You may provide a timestamp range as well as a page number. The timestamp is assumed to be in UTC format and follow unix standards. The max time period allowed to query is a year. If no timestamp range is set, the output will return any links clicked from a week ago til today. If only the starting timestamp is set, the result will be the clicked links from a year ahead of starting timestamp. The ending timestamp cannot be specified on its own without a starting timestamp. The range cannot exceed a year at a time. The page defaults to 1 with a max number of results set to a predefined number 50. The click count is retrieved from a cached instance and therefore does not represent the real-time total. Results are sorted by most clicked.

path Parameters
domain_id
required
integer

The unique domain identifier.

query Parameters
from_unix
integer

The UTC unix timestamp, query returns values after this date.

to_unix
integer

The UTC unix timestamp, query returns values before this date. Required if from_unix is specified.

from_user
any

An optional parameter. Valid value 'me' is allowed to only query for your links.

keyword
string

Search link alias, notes, and redirect url for keyword

page
integer

The page of to query the values from the paginated results. Defaults to 1.

Responses

Response samples

Content type
application/json
{
  • "objects": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Retrieve QR Code

Once a link is created you may retrieve it in the form of a QR code.

List UTM Templates

List UTM Templates

Returns a list of available UTM templates

Returns a list of available UTM templates

query Parameters
domain_id
required
integer

Domain ID to query by

Responses

Response samples

Content type
application/json
{
  • "objects": [
    ]
}

Domain Click Count Per Day

List link count per day

Returns the domain click count for each day.

(Team, Business, and Enterprise Only) This endpoint retrieves the total clicks made on a domain grouped by days. A domain ID must be specified in the URL. Optionally, you may provide a timestamp range as well as a page number. The timestamp is assumed to be in UTC format and follow unix standards. The max time period allowed to query is a year. If no timestamp range is set, the output will be the total count from a week ago til today. If only the starting timestamp is set, the result will be the counts from a year ahead of starting timestamp. The ending timestamp cannot be specified on its own without a starting timestamp. The range cannot exceed a year at a time. The page defaults to 1 with a max number of results set to a predefined number 50. The counts are retrieved from a cached instance and therefore does not represent the real-time total but comes close. Result are sorted by day.

path Parameters
domain_id
required
integer

The unique domain identifier.

query Parameters
from_unix
integer

The UTC unix timestamp, query returns values after this date.

to_unix
integer

The UTC unix timestamp, query returns values before this date. Required if from_unix is specified.

string or integer

An optional parameter containing the user's ID to query. Elevated privileges are required to specify another. Defaults to current user. Valid value 'all' is allowed for users of elevated privileges.

string or integer

An optional parameter containing the label's ID to query.

keyword
string

Search link alias, notes, and redirect url for keyword

page
integer

The page of to query the values from the paginated results.

Responses

Response samples

Content type
application/json
{
  • "objects": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Domain Click Count Per Country

List link count per country

Returns the total click count per country.

(Team, Business, and Enterprise Only) This endpoint retrieves the total clicks made on a domain grouped by country. A domain ID must be specified in the url with the option to set a timestamp range and a page to retrieve the paginated results. If the timestamp range exceeds a day the hour The timestamp is assumed to be in UTC format and follow unix standards. The max time period allowed to query is a year. If no timestamp range is set, the output will be the total count from a week ago til today. If only the starting timestamp is set, the result will be the counts from a year ahead of starting timestamp. The ending timestamp cannot be specified on its own without a starting timestamp. The range cannot exceed a year at a time. The page defaults to 1 with a max number of results set to a predefined number 50. The count is retrieved from a cached instance and therefore does not represent the real-time total. Results are sorted by popularity then by country.

path Parameters
domain_id
required
integer

The unique domain identifier.

query Parameters
from_unix
integer

The UTC unix timestamp, query returns values after this date.

to_unix
integer

The UTC unix timestamp, query returns values before this date. Required if from_unix is specified.

string or integer

An optional parameter containing the user's ID to query. Elevated privileges are required to specify another. Defaults to current user. Valid value 'all' is allowed for users of elevated privileges.

string or integer

An optional parameter containing the label's ID to query.

keyword
string

Search link alias, notes, and redirect url for keyword

country
string

The country to query the values

page
integer

The page of to query the values from the paginated results.

Responses

Response samples

Content type
application/json
{
  • "objects": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Domain Click Count Per Region

List link count per region

Returns the total click count per region.

(Team, Business, and Enterprise Only) This endpoint retrieves the total clicks made on a domain grouped by region. A domain ID must be specified in the url with the option to set a timestamp range and a page to retrieve the paginated results. If the timestamp range exceeds a day the hour The timestamp is assumed to be in UTC format and follow unix standards. The max time period allowed to query is a year. If no timestamp range is set, the output will be the total count from a week ago til today. If only the starting timestamp is set, the result will be the counts from a year ahead of starting timestamp. The ending timestamp cannot be specified on its own without a starting timestamp. The range cannot exceed a year at a time. TThe page defaults to 1 with a max number of results set to a predefined number 50. The count is retrieved from a cached instance and therefore does not represent the real-time total. Results are sorted by popularity then by country and region.

path Parameters
domain_id
required
integer

The unique domain identifier.

query Parameters
from_unix
integer

The UTC unix timestamp, query returns values after this date.

to_unix
integer

The UTC unix timestamp, query returns values before this date. Required if from_unix is specified.

string or integer

An optional parameter containing the user's ID to query. Elevated privileges are required to specify another. Defaults to current user. Valid value 'all' is allowed for users of elevated privileges.

string or integer

An optional parameter containing the label's ID to query.

keyword
string

Search link alias, notes, and redirect url for keyword

country
string

The country to query the values

region
string

The region to query the values

page
integer

The page of to query the values from the paginated results.

Responses

Response samples

Content type
application/json
{
  • "objects": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Domain Click Count Per City

List link count per city

Returns the total click count per city.

(Team, Business, and Enterprise Only) This endpoint retrieves the total clicks made on a domain grouped by city. A domain ID must be specified in the url with the option to set a timestamp range and a page to retrieve the paginated results. If the timestamp range exceeds a day the hour The timestamp is assumed to be in UTC format and follow unix standards. The max time period allowed to query is a year. If no timestamp range is set, the output will be the total count from a week ago til today. If only the starting timestamp is set, the result will be the counts from a year ahead of starting timestamp. The ending timestamp cannot be specified on its own without a starting timestamp. The range cannot exceed a year at a time. The page defaults to 1 with a max number of results set to a predefined number 50. The count is retrieved from a cached instance and therefore does not represent the real-time total. Results are sorted by popularity then by country, region, and city.

path Parameters
domain_id
required
integer

The unique domain identifier.

query Parameters
from_unix
integer

The UTC unix timestamp, query returns values after this date.

to_unix
integer

The UTC unix timestamp, query returns values before this date. Required if from_unix is specified.

string or integer

An optional parameter containing the user's ID to query. Elevated privileges are required to specify another. Defaults to current user. Valid value 'all' is allowed for users of elevated privileges.

string or integer

An optional parameter containing the label's ID to query.

keyword
string

Search link alias, notes, and redirect url for keyword

country
string

The country to query the values

region
string

The region to query the values

city
string

The city to query the values

page
integer

The page of to query the values from the paginated results.

Responses

Response samples

Content type
application/json
{
  • "objects": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Domain Click Count Per Device

List link count per device

Returns the total click count per device.

(Team, Business, and Enterprise Only) This endpoint retrieves the total clicks made on a domain grouped by device. A domain ID must be specified in the url with the option to set a timestamp range and a page to retrieve the paginated results. If the timestamp range exceeds a day the hour The timestamp is assumed to be in UTC format and follow unix standards. The max time period allowed to query is a year. If no timestamp range is set, the output will be the total count from a week ago til today. If only the starting timestamp is set, the result will be the counts from a year ahead of starting timestamp. The ending timestamp cannot be specified on its own without a starting timestamp. The range cannot exceed a year at a time. The page defaults to 1 with a max number of results set to a predefined number 50. The count is retrieved from a cached instance and therefore does not represent the real-time total. Results are sorted by popularity then by device.

path Parameters
domain_id
required
integer

The unique domain identifier.

query Parameters
from_unix
integer

The UTC unix timestamp, query returns values after this date.

to_unix
integer

The UTC unix timestamp, query returns values before this date. Required if from_unix is specified.

string or integer

An optional parameter containing the user's ID to query. Elevated privileges are required to specify another. Defaults to current user. Valid value 'all' is allowed for users of elevated privileges.

string or integer

An optional parameter containing the label's ID to query.

keyword
string

Search link alias, notes, and redirect url for keyword

device
string

The device to query the values

page
integer

The page of to query the values from the paginated results.

Responses

Response samples

Content type
application/json
{
  • "objects": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Domain Click Count Per Referrer

List link count per referrer

Returns the total click count per referrer.

(Team, Business, and Enterprise Only) This endpoint retrieves the total clicks made on a domain grouped by referrer. A domain ID must be specified in the url with the option to set a timestamp range and a page to retrieve the paginated results. If the timestamp range exceeds a day the hour The timestamp is assumed to be in UTC format and follow unix standards. The max time period allowed to query is a year. If no timestamp range is set, the output will be the total count from a week ago til today. If only the starting timestamp is set, the result will be the counts from a year ahead of starting timestamp. The ending timestamp cannot be specified on its own without a starting timestamp. The range cannot exceed a year at a time. The page defaults to 1 with a max number of results set to a predefined number 50. The count is retrieved from a cached instance and therefore does not represent the real-time total. Results are sorted by popularity then by referrer.

path Parameters
domain_id
required
integer

The unique domain identifier.

link_id
required
integer

The unique link identifier.

query Parameters
from_unix
integer

The UTC unix timestamp, query returns values after this date.

to_unix
integer

The UTC unix timestamp, query returns values before this date. Required if from_unix is specified.

string or integer

An optional parameter containing the user's ID to query. Elevated privileges are required to specify another. Defaults to current user. Valid value 'all' is allowed for users of elevated privileges.

string or integer

An optional parameter containing the label's ID to query.

keyword
string

Search link alias, notes, and redirect url for keyword

referrer
string

The referrer to query the values

page
integer

The page of to query the values from the paginated results. Defaults to 1.

Responses

Response samples

Content type
application/json
{
  • "objects": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Error Codes

List of all the error codes that can be returned

List Error Codes

Returns a list of available error codes. The code is guaranteed to stay the same. The message and description may change.

Responses

Response samples

Content type
application/json
{
  • "objects": [
    ]
}