logo
Documentation Powered by ReDoc

Version 3 of the BL.INK API (3.0.0)

Download OpenAPI specification:Download

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

Introduction

This is version 3 of the BL.INK API. It follows common REST patterns.

API PRIMARY BASE URL

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

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 a 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

200

Successfully validated that the username and password are correct

401

The input auth data was invalid

post /validate_login
https://{instance}.bl.ink/api/v3/validate_login

Request samples

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

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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
  • CredentialsEmailPassword
  • CredentialsEmailRefreshToken
email
required
string <email>
password
required
string <password>

Responses

200

A valid token should have been returned

401

The input auth data was invalid

post /access_token
https://{instance}.bl.ink/api/v3/access_token

Request samples

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

Response samples

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

List Domains

List Domains

Returns a list of the user's active domains

Returns a list of the user's active domains

Responses

200

Successfully returned a list of active domains.

type field

When set to shared-readonly it denotes that the domain is a smart link domain

get /domains
https://{instance}.bl.ink/api/v3/domains

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "objects":
    [
    ]
}

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

dupe_check
integer

A flag that when set to 1 will return check if a link if found first and returns the link if found or creates and returns a new link.

notes
string

Notes to attach onto the link.

tags
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

200

Successfully created the short link using passed in parameters

400

The input data was invalid

post /{domain_id}/links
https://{instance}.bl.ink/api/v3/{domain_id}/links

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "url": "string",
  • "alias": "string",
  • "dupe_check": 0,
  • "notes": "string",
  • "tags":
    [
    ],
  • "utm_template_id": 0,
  • "utm_fields":
    {
    },
  • "archive_on": 0,
  • "delete_on": 0,
  • "redirect_type": 301
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "objects":
    {
    }
}

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

200

The URL is valid

400

The input data was invalid

post /links/validate
https://{instance}.bl.ink/api/v3/links/validate

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "url": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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 privlidged users (domain admins or account admins) to specify returning all links from corresponding domain instead of just links they created. Example users=all

Responses

200

Successfully return a list of links

400

The input data was invalid

get /{domain_id}/links
https://{instance}.bl.ink/api/v3/{domain_id}/links

Response samples

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

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

200

Successfully returns a list of UTM templates available to the user on the domain passed in through query.

get /utm_templates
https://{instance}.bl.ink/api/v3/utm_templates

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "objects":
    [
    ]
}

Domain Click Count Per Day

List link count per hour

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 with the option to set a timestamp range. 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 usually 20. 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.

user_id
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.

label_id
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

200

Successfully return the daily total clicks for a given domain.

get /{domain_id}/links/clicks/daily
https://{instance}.bl.ink/api/v3/{domain_id}/links/clicks/daily

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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 usually 20. 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.

user_id
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.

label_id
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

200

Successfully return total clicks per country for a given domain.

get /{domain_id}/links/clicks/country
https://{instance}.bl.ink/api/v3/{domain_id}/links/clicks/country

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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 usually 20. 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.

user_id
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.

label_id
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

200

Successfully return total clicks per region for a given domain.

get /{domain_id}/links/clicks/region
https://{instance}.bl.ink/api/v3/{domain_id}/links/clicks/region

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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 usually 20. 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.

user_id
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.

label_id
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

200

Successfully return total clicks per city for a given domain.

get /{domain_id}/links/clicks/city
https://{instance}.bl.ink/api/v3/{domain_id}/links/clicks/city

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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 usually 20. 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.

user_id
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.

label_id
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

200

Successfully return total clicks per device for a given domain.

get /{domain_id}/links/clicks/device
https://{instance}.bl.ink/api/v3/{domain_id}/links/clicks/device

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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 usually 20. 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.

user_id
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.

label_id
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

200

Successfully return total clicks per referrer for a given domain.

get /{domain_id}/links/clicks/referrer
https://{instance}.bl.ink/api/v3/{domain_id}/links/clicks/referrer

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

Successfully returns a list of error codes that can be returned as part of error responses

get /error_codes
https://{instance}.bl.ink/api/v3/error_codes

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "objects":
    [
    ]
}