Linkly’s Link Shortening & Reporting API

Before you Begin

Linkly generates API requests in the interface for you to copy & paste into your applications.

This works for both link creation, link update, and traffic reporting.

Save time and let us do the hard work:

  1. See below for either link creation API requests or reporting API requests.
  2. Copy the requests in their entirety. You can verify they work for you.
  3. Ask ChatGPT or an equivalent to adapt these requests into source code for your application. There is no need to spend time doing a complex integration. Our API is entirely machine-consumable.

About the Linkly API

Linkly has two API’s:

  1. Link creation API (as documented here).
  2. Reporting API

You can generate API requests directly from the Linkly user interface.

Linkly's Link Shortening API Builder

Linkly's link shortening API builds API requests automatically based on the contents of the form. You can paste the text given here into any LLM to automatically generate code for your application.

Linkly’s API is documented using the OpenAPI standard, which goes beyond what is provided below.

Authorization

  • Your API Key
  • Workspace ID

You can get these details from inside Linkly.

  1. Login to Linkly.
  2. Click Settings.
  3. Click API Keys.

To create a link, all you need to do is send a POST request to:

https://app.linklyhq.com/api/v1/link

with the following fields in the body.

The encoding type is x-www-form-urlencoded or application/json.

If you are submitting the Rules field, you must use application/json.

We recommend you use JSON with the Open API spec.

Label
Key
Type
Notes
Account Email
email
String
Required
Account API Key
api_key
String
Required
Workspace ID
workspace_id
Integer
Required
Link ID
id
Integer
Required if updating existing link
Destination
url
String
Required
Nickname
name
String
Notes
note
String
Retargeting tags (head region)
head_tags
String
Retargeting tags (body region)
body_tags
String
Forward Params
forward_params
Boolean
Publishing Status
enabled
Boolean
UTM Source
utm_source
String
UTM Medium
utm_medium
String
UTM Campaign
utm_campaign
String
UTM Term
utm_term
String
UTM Content
utm_content
String
Custom Domain
domain
String
Required if slug is provided
Custom Domain Suffix
slug
String
If domain is provided and null, will be auto-generated
Open Graph Title
og_title
String
Open Graph Description
og_description
String
Open Graph Image URL
og_image
String
Meta Pixel ID
fb_pixel_id
String
Google Analytics 4 ID
ga4_tag_id
String
Google Tag Manager container
gtm_id
String
Expiry DateTime
expiry_datetime
ISO8601 DateTime String
Expiry Destination
expiry_destination
String
Rules
rules
JSON array
For advanced redirects, see below
← Scroll →

Example Request using cURL

The code below illustrates how to make an API request to create a link.

curl -X POST https://app.linklyhq.com/api/v1/link  
-H 'cache-control: no-cache'  
-d 'api_key=your_secret_key&email=chris%40linklyhq.com&workspace_id=1&url=http%3A%2F%2Fwww.wikijob.co.uk&name=Test%20Link'

A successful response will return a JSON object representing the link, along with a link id.

{
    "id": 9512,
    "alias": null,
    "url": "https://www.wikijob.co.uk",
    "name": "Test Link",
    "note": null,
    "head_tags": null,
    "body_tags": null,
    "linkify_words": null,
    "enabled": true,
    "cloaking": false,
    "replacements": null,
    "domain": null,
    "slug": null,
    "utm_source": null,
    "utm_medium": null,
    "utm_campaign": null,
    "utm_term": null,
    "utm_content": null,
    "og_title": null,
    "og_description": null,
    "og_image": null,
    "full_url": "https://l.linklyhq.com/l/2TQ",
    "block_bots": false,
    "rules": [],
    "workspace_id": 1448,
    "referer_mode": null,
    "custom_referer": null,
    "click_fraud_mode": null,
    "deleted": false
}

In order to update a link, send the same request you’d use to create the link, but include the field link_id for the link you want to update, as well as the changes.

Creating Rotators via API

In order to create a rotator, submit a field called rules as a JSON array, along with the link payload above. You must use application/json to send JSON arrays.

For example:

[
  {what: ‘rotator’, url: ‘https://www.microsoft.com’, percentage: ‘50’},
  {what: ‘rotator’, url: ‘https://www.apple.com’, percentage: ‘50’}
]

Creating Geo-Redirects via API

In order to redirect by country, submit a field called rules as a JSON array, along with the link payload above. You must use application/json encoding to send JSON arrays.

For example:

[
  {what: ‘country’, url: ‘https://www.microsoft.com’, matches: ‘UK’}, 
  {what: ‘country’, url: ‘https://www.apple.com’, matches: ‘US’}
]

The country is the alpha-2 ISO 3166 country code.

Creating Device Redirects via API

In order to redirect by device, submit a field called rules as a JSON array, along with the link payload above.

For example:

[
  {what: ‘platform’, url: ‘https://www.google.com’, matches: ‘windows’}, 
  {what: ‘platform’, url: ‘https://www.apple.com’, matches: ‘ios’}
]

Where the field matches is one of:

  • ios
  • android
  • windows
  • linux
  • mac

Linkly supports the creation/amending of up 1000 links per request.

To do so, submit your API key as part of the request as follows:

https://app.linklyhq.com/api/v1/link?api_key=XXXXXXXXXXX

Then, use the same schema as above for the individual link cases, but wrap the link requests in an array, of the form:

[{link}, {link}]

Here is a complete request that will update two links:

wget --no-check-certificate \
  --method POST \
  --timeout=0 \
  --header 'Content-Type: application/json' \
  --body-data '[
    {
        "email": "[email protected]",
        "workspace_id": "WORKSPACE_ID",
        "url": "https://nature.com",
        "name": "Test",
        "id": LINK_ID
    },
    {
        "email": "[email protected]",
        "workspace_id": "WORKSPACE_ID",
        "url": "https://science.com",
        "id": LINK_ID
    }
]' \
   'https://app.linklyhq.com/api/v1/workspace/WORKSPACE_ID/links?api_key=API_KEY'

This works for both creation and update actions.

Please be aware it can take up to 60 seconds for a large request. If requests take longer than this, they will fail, and you should consider breaking your workload up into smaller chunks.

Reporting API

Linkly automatically produces API requests for you inside your traffic reports.

Linkly's Traffic Reports API
Linkly's Traffic Reports API

Linkly’s traffic reports automatically build API requests for you, based on the data shown on the screen.

These links include your API key, and are easily customizable and usable in your own applications.

Track 1000 monthly clicks with all features included.

No credit card required