Download OpenAPI specification:Download
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
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).
All endpoints require a valid access token for authentication:
POST /access_token
endpoint to get a new access_tokenAuthorization: Bearer <access_token>
If you see a refresh token in your BL.INK UI, use that to get a new access_tokenThere 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..
To generate client SDK code:
Validates login information
email required | string <email> |
password required | string <password> |
{- "email": "bud@smartlinker.email",
- "password": "pa$$word"
}
{- "success": 1,
- "user": {
- "user_id": 2,
- "nickname": "Bud",
- "email": "bud@smartlinker.email"
}
}
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.
email required | string <email> |
password required | string <password> |
{- "email": "bud@smartlinker.email",
- "password": "pa$$word"
}
{- "success": 1,
- "user": {
- "user_id": 2,
- "nickname": "Bud",
- "email": "bud@smartlinker.email"
}, - "access_token": "8Am4WSbKTBvZtDRq48f7",
- "expires": 1918085162
}
Returns a list of the user's active domains
page | integer Page number |
{- "objects": [
- {
- "id": 0,
- "domain": "string",
- "created": 0,
- "modified": 0,
- "default": true,
- "type": "string",
- "url_404": "string",
- "homepage": "string",
- "has_ssl": true
}
], - "meta": {
- "current_page": 0,
- "previous_page": 0,
- "next_page": 0,
- "last_page": 0,
- "from": 0,
- "to": 0,
- "per_page": 0,
- "total": 0,
- "path": "string"
}
}
Returns a list of the user's requested domain
domain_id required | integer |
{- "objects": [
- {
- "id": 0,
- "domain": "string",
- "created": 0,
- "modified": 0,
- "default": true,
- "type": "string",
- "url_404": "string",
- "homepage": "string",
- "has_ssl": true
}
], - "meta": {
- "current_page": 0,
- "previous_page": 0,
- "next_page": 0,
- "last_page": 0,
- "from": 0,
- "to": 0,
- "per_page": 0,
- "total": 0,
- "path": "string"
}
}
Returns a list of the user's requested domain
domain_name required | string |
{- "objects": [
- {
- "id": 0,
- "domain": "string",
- "created": 0,
- "modified": 0,
- "default": true,
- "type": "string",
- "url_404": "string",
- "homepage": "string",
- "has_ssl": true
}
], - "meta": {
- "current_page": 0,
- "previous_page": 0,
- "next_page": 0,
- "last_page": 0,
- "from": 0,
- "to": 0,
- "per_page": 0,
- "total": 0,
- "path": "string"
}
}
Creates a domain and returns the domain object as part of the response
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://' |
{- "domain": "string",
- "default": true,
- "url_404": "string",
- "homepage": "string"
}
{- "objects": [
- {
- "id": 0,
- "domain": "string",
- "created": 0,
- "modified": 0,
- "default": true,
- "type": "string",
- "url_404": "string",
- "homepage": "string",
- "has_ssl": true
}
], - "meta": {
- "current_page": 0,
- "previous_page": 0,
- "next_page": 0,
- "last_page": 0,
- "from": 0,
- "to": 0,
- "per_page": 0,
- "total": 0,
- "path": "string"
}
}
Creates a domain and returns the domain object as part of the response
domain_id required | integer |
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://' |
{- "op": "replace",
- "path": "status",
- "value": "string"
}
{- "objects": [
- {
- "id": 0,
- "domain": "string",
- "created": 0,
- "modified": 0,
- "default": true,
- "type": "string",
- "url_404": "string",
- "homepage": "string",
- "has_ssl": true
}
], - "meta": {
- "current_page": 0,
- "previous_page": 0,
- "next_page": 0,
- "last_page": 0,
- "from": 0,
- "to": 0,
- "per_page": 0,
- "total": 0,
- "path": "string"
}
}
Returns a short link. Each short link has a corresponding domain it belongs to and and individual id.
domain_id required | integer |
link_id required | integer |
{- "objects": [
- {
- "id": 0,
- "url": "string",
- "alias": "string",
- "short_link": "string",
- "redirect_url": "string",
- "created": 0,
- "modified": 0,
- "user_id": 0,
- "domain_id": 0,
- "click_count": 0,
- "notify_on_click": "string",
- "notes": "string",
- "redirect_type": 0,
- "status": "string",
- "template_id": 0,
- "delete_on": 0,
- "archive_on": 0,
- "groups": [
- 0
], - "tags": [
- {
- "name": "string",
- "shared": true
}
], - "redirect_url_domain": "string",
- "redirect_url_path": "string"
}
]
}
Will take the passed in URL and create a new shortened link based on the parameters that are passed in.
domain_id required | integer |
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 |
{- "url": "string",
- "alias": "string",
- "rand_alias_length": 0,
- "dupe_check": 0,
- "notes": "string",
- "notify_on_click": 0,
- "override_404_check": 0,
- "tags": [
- {
- "name": "string",
- "shared": true
}
], - "utm_template_id": 0,
- "utm_fields": {
- "field_1": "value1",
- "field_2": "value2",
- "field_3": "value c"
}, - "archive_on": 0,
- "delete_on": 0,
- "redirect_type": 301
}
{- "objects": [
- {
- "id": 0,
- "url": "string",
- "alias": "string",
- "short_link": "string",
- "redirect_url": "string",
- "created": 0,
- "modified": 0,
- "user_id": 0,
- "domain_id": 0,
- "click_count": 0,
- "notify_on_click": "string",
- "notes": "string",
- "redirect_type": 0,
- "status": "string",
- "template_id": 0,
- "delete_on": 0,
- "archive_on": 0
}
], - "new_link": null
}
Will take an array of objects defining operations to be performed. This is based on the JSON patch format as defined in RFC 6902.
domain_id required | integer |
link_id required | integer |
op | string Default: "replace" Value: "replace" |
path | string Enum: "/alias" "/notes" "/notify_on_click" "/url" "/delete_on" "/archive_on" The path property accepts string values for all paths with the exception of notify_on_click which accepts only a 0 or 1. However, for the archive on and delete on paths a unix timestamp integer value can be accepted as an integer or string. |
string or integer |
[- {
- "op": "replace",
- "path": "/alias",
- "value": "string"
}
]
{- "objects": [
- {
- "id": 0,
- "url": "string",
- "alias": "string",
- "short_link": "string",
- "redirect_url": "string",
- "created": 0,
- "modified": 0,
- "user_id": 0,
- "domain_id": 0,
- "click_count": 0,
- "notify_on_click": "string",
- "notes": "string",
- "redirect_type": 0,
- "status": "string",
- "template_id": 0,
- "delete_on": 0,
- "archive_on": 0
}
]
}
Will take the passed in URL and validate it.
url required | string URL encoded URL. It's a URL |
{- "url": "string"
}
{- "objects": [
- {
- "url": "string"
}
]
}
Searches for all links matching the query parameters that belong to the API user
domain_id required | integer |
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. |
tag | string Search links by tag |
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' |
group_id | integer Search links by group_id |
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 |
{- "total": 0,
- "count": 0,
- "click_count": 0,
- "objects": [
- {
- "id": 0,
- "url": "string",
- "alias": "string",
- "short_link": "string",
- "redirect_url": "string",
- "created": 0,
- "modified": 0,
- "user_id": 0,
- "domain_id": 0,
- "click_count": 0,
- "notify_on_click": "string",
- "notes": "string",
- "redirect_type": 0,
- "status": "string",
- "template_id": 0,
- "delete_on": 0,
- "archive_on": 0,
- "tags": [
- {
- "name": "string",
- "shared": true
}
]
}
], - "meta": {
- "current_page": 0,
- "previous_page": 0,
- "next_page": 0,
- "last_page": 0,
- "from": 0,
- "to": 0,
- "per_page": 0,
- "total": 0,
- "path": "string"
}
}
(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.
domain_id required | integer The unique domain identifier. |
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. |
tag | string Search links by tag |
group_id | integer Search links by group_id |
{- "objects": [
- {
- "id": 0,
- "url": "string",
- "alias": "string",
- "short_link": "string",
- "redirect_url": "string",
- "created": 0,
- "modified": 0,
- "user_id": 0,
- "domain_id": 0,
- "click_count": 0,
- "notes": "string",
- "redirect_type": 0,
- "status": "string",
- "template_id": 0,
- "delete_on": 0,
- "archive_on": 0,
- "tags": [
- {
- "name": "string",
- "shared": true
}
], - "lifetime_count": 0,
- "last_clicked": "string"
}
], - "links": {
- "first": "string",
- "last": "string",
- "previous": "string",
- "next": "string"
}, - "meta": {
- "current_page": 0,
- "previous_page": 0,
- "next_page": 0,
- "last_page": 0,
- "from": 0,
- "to": 0,
- "per_page": 0,
- "total": 0,
- "path": "string"
}
}
Returns a short link. Each short link has a corresponding domain it belongs to and the provided.
domain_id required | integer |
alias required | string |
{- "objects": [
- {
- "id": 0,
- "url": "string",
- "alias": "string",
- "short_link": "string",
- "redirect_url": "string",
- "created": 0,
- "modified": 0,
- "user_id": 0,
- "domain_id": 0,
- "click_count": 0,
- "notify_on_click": "string",
- "notes": "string",
- "redirect_type": 0,
- "status": "string",
- "template_id": 0,
- "delete_on": 0,
- "archive_on": 0
}
]
}
Returns QR data for specified link, domain in the specified format. The API will return the image data in binary format.
domain_id required | integer |
link_id required | integer |
format | string png (default), eps, svg |
{- "errors": [
- {
- "code": 10000,
- "message": "string"
}
]
}
Returns a list of available UTM templates
domain_id required | integer Domain ID to query by |
{- "objects": [
- {
- "id": 0,
- "name": "string",
- "fields": [
- {
- "label": "string",
- "field_code": "string",
- "type": "string",
- "required": true
}
]
}
]
}
Returns a list of available groups
domain_id required | integer Domain ID to query by |
{- "objects": [
- {
- "id": 0,
- "created": 0,
- "modified": 0,
- "domain_id": 0,
- "user_id": 0,
- "is_global": "string",
- "users": [ ]
}
]
}
(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.
domain_id required | integer The unique domain identifier. |
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. |
{- "objects": [
- {
- "date": "string",
- "unix_date": 0,
- "count": 0,
- "scan_count": 0
}
], - "links": {
- "first": "string",
- "last": "string",
- "previous": "string",
- "next": "string"
}, - "meta": {
- "current_page": 0,
- "previous_page": 0,
- "next_page": 0,
- "last_page": 0,
- "from": 0,
- "to": 0,
- "per_page": 0,
- "total": 0,
- "path": "string"
}
}
(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.
domain_id required | integer The unique domain identifier. |
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. |
{- "objects": [
- {
- "country": "string",
- "count": 0
}
], - "links": {
- "first": "string",
- "last": "string",
- "previous": "string",
- "next": "string"
}, - "meta": {
- "current_page": 0,
- "previous_page": 0,
- "next_page": 0,
- "last_page": 0,
- "from": 0,
- "to": 0,
- "per_page": 0,
- "total": 0,
- "path": "string"
}
}
(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.
domain_id required | integer The unique domain identifier. |
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. |
{- "objects": [
- {
- "country": "string",
- "region": "string",
- "count": 0
}
], - "links": {
- "first": "string",
- "last": "string",
- "previous": "string",
- "next": "string"
}, - "meta": {
- "current_page": 0,
- "previous_page": 0,
- "next_page": 0,
- "last_page": 0,
- "from": 0,
- "to": 0,
- "per_page": 0,
- "total": 0,
- "path": "string"
}
}
(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.
domain_id required | integer The unique domain identifier. |
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. |
{- "objects": [
- {
- "country": "string",
- "region": "string",
- "city": "string",
- "count": 0
}
], - "links": {
- "first": "string",
- "last": "string",
- "previous": "string",
- "next": "string"
}, - "meta": {
- "current_page": 0,
- "previous_page": 0,
- "next_page": 0,
- "last_page": 0,
- "from": 0,
- "to": 0,
- "per_page": 0,
- "total": 0,
- "path": "string"
}
}
(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.
domain_id required | integer The unique domain identifier. |
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. |
{- "objects": [
- {
- "device": "string",
- "count": 0
}
], - "links": {
- "first": "string",
- "last": "string",
- "previous": "string",
- "next": "string"
}, - "meta": {
- "current_page": 0,
- "previous_page": 0,
- "next_page": 0,
- "last_page": 0,
- "from": 0,
- "to": 0,
- "per_page": 0,
- "total": 0,
- "path": "string"
}
}
(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.
domain_id required | integer The unique domain identifier. |
link_id required | integer The unique link identifier. |
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. |
{- "objects": [
- {
- "referrer": "string",
- "count": 0
}
], - "links": {
- "first": "string",
- "last": "string",
- "previous": "string",
- "next": "string"
}, - "meta": {
- "current_page": 0,
- "previous_page": 0,
- "next_page": 0,
- "last_page": 0,
- "from": 0,
- "to": 0,
- "per_page": 0,
- "total": 0,
- "path": "string"
}
}
This endpoint retrieves the total and total unique clicks made on a link. A unique click is a click that comes from an individual IP address. If a person clicks twice from the same internet device that has a corresponding IP address the latter click will not be counted in the total unique clicks result. The total count and the total unique count are only displayed when no filter is applied, however the filtered count is only present when a timestamp is set. A link ID and domain ID must be specified in the url parameters 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 unique and total counts. 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.
domain_id required | integer The unique domain identifier. |
link_id required | integer The unique link identifier. |
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. |
{- "total": 0,
- "unique": 0,
- "scan_count": 0
}
(Team, Business, and Enterprise Only) This endpoint retrieves the total clicks made on a link grouped by hours. The hours are in the military time range from 0 - 23. Over a span of days this response reports the total clicks on a link for each hour. For example if a link has 5 clicks yesterday at 5pm and 2 clicks at 5pm today and if the range is set for only those days. The report for hour:17 is 7 clicks; the sum of the clicks for that hour between the two days. A link ID and domain ID must be specified in the url parameters 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. Result are sorted by hour.
domain_id required | integer The unique domain identifier. |
link_id required | integer The unique link identifier. |
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. |
{- "objects": {
- "hour": 0,
- "count": 0,
- "scan_count": 0
}
}
(Team, Business, and Enterprise Only) This endpoint retrieves the total clicks made on a domain link grouped by days. A domain ID and link 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.
domain_id required | integer The unique domain identifier. |
link_id required | integer The unique link identifier. |
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. |
{- "objects": [
- {
- "date": "string",
- "unix_date": 0,
- "count": 0,
- "scan_count": 0
}
], - "links": {
- "first": "string",
- "last": "string",
- "previous": "string",
- "next": "string"
}, - "meta": {
- "current_page": 0,
- "previous_page": 0,
- "next_page": 0,
- "last_page": 0,
- "from": 0,
- "to": 0,
- "per_page": 0,
- "total": 0,
- "path": "string"
}
}
(Team, Business, and Enterprise Only) This endpoint retrieves the total clicks made on a link grouped by country. A link ID and domain ID must be specified in the url parameters 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.
domain_id required | integer The unique domain identifier. |
link_id required | integer The unique link identifier. |
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. |
{- "objects": [
- {
- "country": "string",
- "count": 0
}
], - "links": {
- "first": "string",
- "last": "string",
- "previous": "string",
- "next": "string"
}, - "meta": {
- "current_page": 0,
- "previous_page": 0,
- "next_page": 0,
- "last_page": 0,
- "from": 0,
- "to": 0,
- "per_page": 0,
- "total": 0,
- "path": "string"
}
}
(Team, Business, and Enterprise Only) This endpoint retrieves the total clicks made on a link grouped by region. A link ID and domain ID must be specified in the url parameters 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.
domain_id required | integer The unique domain identifier. |
link_id required | integer The unique link identifier. |
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. |
{- "objects": [
- {
- "country": "string",
- "region": "string",
- "count": 0
}
], - "links": {
- "first": "string",
- "last": "string",
- "previous": "string",
- "next": "string"
}, - "meta": {
- "current_page": 0,
- "previous_page": 0,
- "next_page": 0,
- "last_page": 0,
- "from": 0,
- "to": 0,
- "per_page": 0,
- "total": 0,
- "path": "string"
}
}
(Team, Business, and Enterprise Only) This endpoint retrieves the total clicks made on a link grouped by city. A link ID and domain ID must be specified in the url parameters 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.
domain_id required | integer The unique domain identifier. |
link_id required | integer The unique link identifier. |
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. |
{- "objects": [
- {
- "country": "string",
- "region": "string",
- "city": null,
- "count": 0
}
], - "links": {
- "first": "string",
- "last": "string",
- "previous": "string",
- "next": "string"
}, - "meta": {
- "current_page": 0,
- "previous_page": 0,
- "next_page": 0,
- "last_page": 0,
- "from": 0,
- "to": 0,
- "per_page": 0,
- "total": 0,
- "path": "string"
}
}
(Team, Business, and Enterprise Only) This endpoint retrieves the total clicks made on a link grouped by device. A link ID and domain ID must be specified in the url parameters 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.
domain_id required | integer The unique domain identifier. |
link_id required | integer The unique link identifier. |
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. |
{- "objects": [
- {
- "device": "string",
- "count": 0
}
], - "links": {
- "first": "string",
- "last": "string",
- "previous": "string",
- "next": "string"
}, - "meta": {
- "current_page": 0,
- "previous_page": 0,
- "next_page": 0,
- "last_page": 0,
- "from": 0,
- "to": 0,
- "per_page": 0,
- "total": 0,
- "path": "string"
}
}
(Team, Business, and Enterprise Only) This endpoint retrieves the total clicks made on a link grouped by referrer. A link ID and domain ID must be specified in the url parameters 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.
domain_id required | integer The unique domain identifier. |
link_id required | integer The unique link identifier. |
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. |
{- "objects": [
- {
- "referrer": "string",
- "count": 0
}
], - "links": {
- "first": "string",
- "last": "string",
- "previous": "string",
- "next": "string"
}, - "meta": {
- "current_page": 0,
- "previous_page": 0,
- "next_page": 0,
- "last_page": 0,
- "from": 0,
- "to": 0,
- "per_page": 0,
- "total": 0,
- "path": "string"
}
}
This endpoint retrieves a list of the clicks made on a link.
domain_id required | integer The unique domain identifier. |
link_id required | integer The unique link identifier. |
{- "total": 0,
- "count": 0,
- "click_count": 0,
- "objects": [
- {
- "created": 0,
- "type": "string",
- "device": "string",
- "referrer": "string",
- "city": "string",
- "country": "string",
- "region": "string",
- "engagement_id": "string"
}
], - "meta": {
- "current_page": 0,
- "previous_page": 0,
- "next_page": 0,
- "last_page": 0,
- "from": 0,
- "to": 0,
- "per_page": 0,
- "total": 0,
- "path": "string"
}
}
Returns a list of available error codes. The code is guaranteed to stay the same. The message and description may change.
{- "objects": [
- {
- "code": 10000,
- "description": "auth invalid token",
- "message": "invalid token"
}, - {
- "code": 10001,
- "description": "auth user may not be registered",
- "message": "%1$s may not be registered"
}, - {
- "code": 10100,
- "description": "link url invalid",
- "message": "url is invalid"
}, - {
- "code": 10101,
- "description": "link domain id invalid",
- "message": "domain_id is invalid"
}, - {
- "code": 10102,
- "description": "link alias invalid",
- "message": "alias is invalid"
}, - {
- "code": 10103,
- "description": "link alias too long",
- "message": "alias too long"
}, - {
- "code": 10104,
- "description": "link alias not allowed",
- "message": "alias is not allowed"
}, - {
- "code": 10105,
- "description": "link notes invalid",
- "message": "notes invalid"
}, - {
- "code": 10106,
- "description": "link notes too long",
- "message": "notes too long"
}, - {
- "code": 10107,
- "description": "link tags invalid",
- "message": "One or more of your tags are invalid"
}, - {
- "code": 10108,
- "description": "link utm template id invalid",
- "message": "utm_template_id is invalid"
}, - {
- "code": 10109,
- "description": "link utm template not found",
- "message": "UTM template not found"
}, - {
- "code": 10110,
- "description": "link utm template item invalid",
- "message": "One or more of your utm field keys/values are invalid"
}, - {
- "code": 10111,
- "description": "link delete on invalid",
- "message": "delete_on is invalid"
}, - {
- "code": 10112,
- "description": "link delete on in the past",
- "message": "delete_on must be after current time"
}, - {
- "code": 10113,
- "description": "link archive on invalid",
- "message": "archive_on is invalid"
}, - {
- "code": 10114,
- "description": "link archive on in the past",
- "message": "archive_on must be after current time"
}, - {
- "code": 10115,
- "description": "link redirect type invalid",
- "message": "redirect_type is invalid"
}, - {
- "code": 10116,
- "description": "link archive on and delete on mutually exclusive",
- "message": "setting both archive_on and delete_on is not allowed"
}, - {
- "code": 10120,
- "description": "link search page invalid",
- "message": "page is invalid"
}, - {
- "code": 10121,
- "description": "link search keyword invalid",
- "message": "keyword is invalid"
}, - {
- "code": 10122,
- "description": "link search url invalid",
- "message": "url is invalid"
}, - {
- "code": 10123,
- "description": "link search order invalid",
- "message": "order is invalid"
}, - {
- "code": 10130,
- "description": "link modify operation invalid",
- "message": "Operation %1$s not supported"
}, - {
- "code": 10131,
- "description": "link modify path invalid",
- "message": "Modifying path %1$s not supported"
}, - {
- "code": 10132,
- "description": "link modify url invalid",
- "message": "/url value invalid"
}, - {
- "code": 10133,
- "description": "link modify alias invalid",
- "message": "/alias value invalid"
}, - {
- "code": 10134,
- "description": "link modify notes invalid",
- "message": "/notes value invalid"
}, - {
- "code": 10135,
- "description": "link modify notes too long",
- "message": "/notes value too long"
}, - {
- "code": 10140,
- "description": "link modify alias not available",
- "message": "%1$s"
}, - {
- "code": 10141,
- "description": "link modify save failed",
- "message": "%1$s"
}, - {
- "code": 10142,
- "description": "link create save failed",
- "message": "%1$s"
}, - {
- "code": 10143,
- "description": "link suggestions not found",
- "message": "%1$s"
}, - {
- "code": 10144,
- "description": "You have exhausted the maximum number of Links, Dynamic Links, or Pages you can create on your current plan.",
- "message": "You have exhausted the limits of your current plan"
}, - {
- "code": 10200,
- "description": "utm domain id missing",
- "message": "domain_id is required"
}, - {
- "code": 10201,
- "description": "utm domain id invalid",
- "message": "domain_id is invalid"
}, - {
- "code": 10300,
- "description": "tags domain id missing",
- "message": "domain_id is required"
}, - {
- "code": 10301,
- "description": "tags domain id invalid",
- "message": "domain_id is invalid"
}, - {
- "code": 10302,
- "description": "tags search parameter invalid",
- "message": "search parameter is invalid"
}, - {
- "code": 10303,
- "description": "tags name missing",
- "message": "tag name is required"
}, - {
- "code": 10304,
- "description": "tags name invalid",
- "message": "tag name is invalid"
}, - {
- "code": 10305,
- "description": "tags shared invalid",
- "message": "shared is invalid"
}, - {
- "code": 10306,
- "description": "tags notes invalid",
- "message": "notes is invalid"
}, - {
- "code": 10307,
- "description": "tags notes too long",
- "message": "notes too long"
}, - {
- "code": 10308,
- "description": "tags name already exists",
- "message": "tag name already exists"
}
]
}