API Documentation

Getting Started

The EziLinks API allows you to programmatically create and manage short links, QR codes, digital cards, bio pages, custom domains, and more. API access requires an Agency plan. All requests require authentication using an API key.

Base URL

https://app.ezilinks.com/api

Response Format

All responses are returned in JSON format. Successful responses return a 2xx status code, while errors return 4xx or 5xx status codes with an error message.

Your API Key

Enter your API key to test the endpoints below. Get your API key from Settings.

Authentication

All API requests must include your API key in the X-API-Key header:

X-API-Key: your_api_key_here

Example Request

curl -X POST https://app.ezilinks.com/api/urls \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"originalUrl": "https://example.com"}'

Getting Your API Key

Generate an API key from the Settings page, or programmatically via the POST /api/auth/regenerate-api-key endpoint using your JWT token.

Links

Create, manage, and organise your short links.

Create Short URL

Create a new short URL with an optional custom alias, password protection, and more.

POST /api/urls

Request Body

Parameter	Type	Required	Description
`originalUrl`	string	Required	The URL to shorten
`customAlias`	string	Optional	Custom short code (3-50 characters, letters, numbers, hyphens, underscores)
`title`	string	Optional	Title for the URL
`description`	string	Optional	Description for the URL
`expiresAt`	string	Optional	Expiration date (ISO 8601 format, e.g. "2026-12-31T23:59:59Z")
`password`	string	Optional	Password to protect the link
`domainId`	number	Optional	ID of a verified custom domain to use
`tagIds`	array	Optional	Array of tag IDs to associate with the link

Example Request

{
  "originalUrl": "https://example.com/very/long/url",
  "customAlias": "my-link",
  "title": "My Example Link",
  "description": "Summer campaign landing page",
  "expiresAt": "2026-12-31T23:59:59Z",
  "password": "secret123",
  "domainId": 1,
  "tagIds": [2, 5]
}

Example Response

{
  "id": 123,
  "originalUrl": "https://example.com/very/long/url",
  "shortUrl": "https://links.example.com/my-link",
  "shortCode": "my-link",
  "title": "My Example Link",
  "description": "Summer campaign landing page",
  "expiresAt": "2026-12-31T23:59:59Z",
  "hasPassword": true,
  "createdAt": "2026-03-18T08:59:34.832Z",
  "customDomain": "links.example.com",
  "tags": [
    {"id": 2, "name": "Summer 26"},
    {"id": 5, "name": "Campaigns"}
  ]
}

🚀 Try It Now

List URLs

GET /api/urls

Query Parameters

Parameter	Type	Default	Description
`page`	number	1	Page number for pagination
`limit`	number	500	Number of results per page

Example Response

{
  "urls": [
    {
      "id": 123,
      "originalUrl": "https://example.com",
      "shortUrl": "https://ezl.me/my-link",
      "shortCode": "my-link",
      "customAlias": "my-link",
      "title": "My Link",
      "description": null,
      "clickCount": 42,
      "expiresAt": null,
      "hasPassword": false,
      "isActive": true,
      "domainId": null,
      "customDomain": null,
      "targetingRules": null,
      "retargetingPixelIds": [],
      "defaultQrLogoId": null,
      "defaultQrColor": null,
      "tags": [{"id": 1, "name": "Marketing"}],
      "createdAt": "2026-03-18 08:59:34",
      "updatedAt": "2026-03-18 08:59:34"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 500,
    "hasMore": false
  }
}

🚀 Try It Now

Update URL

Update an existing short URL's details. You can only update URLs you own.

PUT /api/urls/:id

Request Body

All fields are optional. Only include the fields you want to update.

Parameter	Type	Description
`originalUrl`	string	Change the destination URL
`customAlias`	string	Change the short code
`title`	string	New title for the URL
`description`	string	New description
`expiresAt`	string	Set or change expiration date (ISO 8601)
`isActive`	boolean	Enable or disable the link
`domainId`	number	Change the custom domain
`tagIds`	array	Replace the link's tags with these tag IDs
`targetingRules`	object	Smart redirect rules (device/geo targeting)
`retargetingPixelIds`	array	Array of retargeting pixel IDs

Example Request

{
  "title": "Updated Title",
  "originalUrl": "https://new-destination.com",
  "customAlias": "new-alias"
}

Example Response

{
  "message": "URL updated successfully",
  "tags": [{"id": 1, "name": "Marketing"}]
}

Delete URL

DELETE /api/urls/:id

Example Response

{
  "message": "URL deleted successfully"
}

Analytics

Access click analytics for your links, plus platform-wide dashboard stats.

Link Analytics

Get detailed analytics for a specific short URL. Paid plans receive advanced breakdowns.

GET /api/urls/:id/analytics

Query Parameters

Parameter	Type	Default	Description
`days`	number	30	Number of days for recent clicks calculation
`tz`	number	0	Timezone offset in hours (e.g. `10` for AEST, `-5` for EST, `13` for NZDT). Used for daily, hourly, and day-of-week grouping.

Example Request

GET /api/urls/123/analytics?days=30&tz=10

Basic Response (all plans)

{
  "totalClicks": 156,
  "uniqueClicks": 98,
  "recentClicks": 45,
  "dailyClicks": [{"date": "2026-03-15", "clicks": 12}],
  "topCountries": [{"country": "Australia", "count": 50}],
  "topBrowsers": [{"browser": "Chrome", "count": 80}],
  "plan": "free",
  "hasAdvancedAnalytics": false
}

Advanced Response (Pro Toolkit+)

Paid plans receive all basic fields plus:

{
  "totalClicks": 156,
  "uniqueClicks": 98,
  "recentClicks": 45,
  "dailyClicks": [{"date": "2026-03-15", "clicks": 12}],
  "topCountries": [{"country": "Australia", "count": 50}],
  "topBrowsers": [{"browser": "Chrome", "count": 80}],
  "deviceBreakdown": [{"device_type": "Desktop", "count": 90}],
  "osBreakdown": [{"os": "Windows", "count": 60}],
  "topReferrers": [{"referrer": "Direct", "count": 50}],
  "topCities": [{"city": "Sydney", "country": "Australia", "count": 30}],
  "hourlyBreakdown": [{"hour": 14, "count": 20}],
  "dayOfWeekBreakdown": [{"day": 1, "count": 25}],
  "sourceBreakdown": [{"source": "direct", "count": 100}],
  "ruleBreakdown": [{"rule": "default", "count": 156}],
  "plan": "agency",
  "hasAdvancedAnalytics": true
}

Export Analytics CSV

Export all click data for a specific URL as a CSV file.

GET /api/urls/:id/analytics/export

Returns a CSV file download containing: Date/Time, Country, City, Device, Browser, OS, and Referrer for each click.

Example Request

curl "https://app.ezilinks.com/api/urls/123/analytics/export" \
  -H "X-API-Key: your_api_key_here" \
  -o analytics.csv

Dashboard Analytics

Get platform-wide analytics across all your links.

GET /api/analytics/dashboard

Returns total links, total clicks, unique clicks, and recent activity for your account.

GET /api/analytics/top-links

Returns your most clicked links.

GET /api/analytics/daily-clicks

Returns daily click totals for the last 30 days across all links.

GET /api/analytics/top-countries

Returns top countries by click count.

GET /api/analytics/top-browsers

Returns top browsers by click count.

GET /api/analytics/top-devices

Returns device type breakdown (Desktop, Mobile, Tablet).

GET /api/analytics/top-referrers

Returns top referrer sources.

GET /api/analytics/sources

Returns click breakdown by source (QR code vs direct link).

Parameter	Type	Required	Description
`name`	string	Required	Tag name (max 50 characters)

Parameter	Type	Required	Description
`name`	string	Required	New tag name (max 50 characters)

Parameter	Type	Required	Description
`tagIds`	array	Required	Array of tag IDs to assign (use `[]` to remove all tags)

Custom Domains

Manage custom domains for your short links. Domains must be verified via DNS before they can be used.

List Domains

GET /api/domains

Example Response

{
  "domains": [
    {
      "id": 1,
      "domain": "links.example.com",
      "isVerified": true,
      "isPrimary": true,
      "createdAt": "2026-03-01T10:00:00.000Z"
    }
  ]
}

Add Domain

POST /api/domains

Request Body

Parameter	Type	Required	Description
`domain`	string	Required	The domain to add (e.g. "links.example.com")

Example Response

{
  "message": "Domain added successfully",
  "domain": {
    "id": 2,
    "domain": "links.example.com",
    "isVerified": false,
    "isPrimary": false,
    "createdAt": "2026-03-18T09:00:00.000Z"
  }
}

Verify Domain

POST /api/domains/:id/verify

Trigger DNS verification for a domain. Configure your DNS records first using the instructions endpoint.

Example Response

{
  "domain": "links.example.com",
  "verified": true,
  "method": "CNAME",
  "message": "Domain verified successfully",
  "sslProvisioning": "SSL certificate is being provisioned in the background"
}

Get DNS Instructions

GET /api/domains/:id/dns-instructions

Get the DNS records you need to configure for domain verification.

Set Primary Domain

PUT /api/domains/:id/primary

Set a verified domain as your primary domain. New links will use this domain by default.

Example Response

{
  "message": "Primary domain updated successfully"
}

Delete Domain

DELETE /api/domains/:id

Example Response

{
  "message": "Domain deleted successfully"
}

QR Codes

Generate, save, and manage QR codes.

Generate QR Code

GET /api/qr/generate

Returns a PNG or SVG image of the QR code. Save the response as a file.

Query Parameters

Parameter	Type	Required	Description
`url`	string	Required	The URL to encode (e.g. https://ezl.me/my-link)
`size`	number	Optional	Image size in pixels (default: 500)
`format`	string	Optional	`png` (default) or `svg`
`color`	string	Optional	Foreground color as hex (e.g. `#FF0000`, default: `#000000`)
`logoId`	number	Optional	ID of an uploaded logo to embed (PNG format only)
`logoPosition`	string	Optional	Position of the logo: `center` (default)

Example Request

curl "https://app.ezilinks.com/api/qr/generate?url=https://ezl.me/my-link&size=400&format=png" \
  -H "X-API-Key: your_api_key_here" \
  -o qrcode.png

Save QR Code

POST /api/qr/save

Save a QR code configuration for later use.

List Saved QR Codes

GET /api/qr/saved

Get all your saved QR codes.

Get Saved QR Code

GET /api/qr/saved/:id

Get a specific saved QR code by ID.

Update Saved QR Code

PUT /api/qr/saved/:id

Update a saved QR code's settings.

Delete Saved QR Code

DELETE /api/qr/saved/:id

Delete a saved QR code.

Regenerate QR Code

GET /api/qr/saved/:id/regenerate

Regenerate a QR code image from its saved configuration.

Digital Cards

Create and manage digital business cards (vCards) with QR codes.

Create Digital Card

POST /api/vcard

Request Body

Parameter	Type	Required	Description
`first_name`	string	Required	First name
`last_name`	string	Optional	Last name
`email`	string	Optional	Email address
`phone`	string	Optional	Phone number
`company`	string	Optional	Company name
`title`	string	Optional	Job title
`website`	string	Optional	Website URL
`social_links`	object	Optional	Social media links (e.g. `{"linkedin": "...", "twitter": "..."}`)
`card_theme`	string	Optional	Card theme name
`card_color`	string	Optional	Card colour (hex)

List Digital Cards

GET /api/vcard

Get all your digital cards.

Get Digital Card

GET /api/vcard/:id/json

Get a specific digital card's data for editing.

Update Digital Card

PUT /api/vcard/:id

Update a digital card. Accepts the same fields as create.

Delete Digital Card

DELETE /api/vcard/:id

Example Response

{
  "message": "vCard deleted successfully"
}

Bio Pages

Create and manage link-in-bio pages.

Create Bio Page

POST /api/bio

Request Body

Parameter	Type	Required	Description
`title`	string	Required	Page title / display name
`slug`	string	Required	URL slug (e.g. "john" for ezl.me/bio/john)
`bio`	string	Optional	Bio description text
`links`	array	Optional	Array of link objects: `[{"title": "...", "url": "..."}]`
`theme`	string	Optional	Page theme

List Bio Pages

GET /api/bio

Get all your bio pages.

Get Bio Page

GET /api/bio/:id

Get a specific bio page for editing.

Update Bio Page

PUT /api/bio/:id

Update a bio page. Accepts the same fields as create.

Delete Bio Page

DELETE /api/bio/:id

Example Response

{
  "message": "Bio page deleted successfully"
}

Bio Page Analytics

GET /api/bio/:id/analytics

Get view and click analytics for a bio page.

Retargeting Pixels

Manage retargeting pixels that can be attached to your links. Supports Meta, Google, TikTok, LinkedIn, Twitter, Snapchat, and Pinterest.

List Pixels

GET /api/pixels

Example Response

{
  "pixels": [
    {
      "id": 1,
      "name": "Meta Pixel",
      "platform": "meta",
      "pixelId": "123456789",
      "createdAt": "2026-03-01T10:00:00.000Z"
    }
  ]
}

Create Pixel

POST /api/pixels

Request Body

Parameter	Type	Required	Description
`name`	string	Required	Display name for the pixel
`platform`	string	Required	Platform: `meta`, `google`, `tiktok`, `linkedin`, `twitter`, `snapchat`, `pinterest`
`pixelId`	string	Required	The pixel/tag ID from the platform

Update Pixel

PUT /api/pixels/:id

Update a pixel's name or pixel ID. Accepts the same fields as create.

Delete Pixel

DELETE /api/pixels/:id

Example Response

{
  "message": "Pixel deleted successfully"
}

CSV Import/Export

Bulk import and export your links via CSV files.

Export Links

GET /api/csv/export

Export all your links as a CSV file download.

Example Request

curl "https://app.ezilinks.com/api/csv/export" \
  -H "X-API-Key: your_api_key_here" \
  -o links.csv

Download CSV Template

GET /api/csv/template

Download a CSV template file showing the required format for bulk import.

Import Links

POST /api/csv/import

Import links from a CSV file. Send as multipart/form-data with the file in a field named file.

Example Request

curl -X POST "https://app.ezilinks.com/api/csv/import" \
  -H "X-API-Key: your_api_key_here" \
  -F "file=@links.csv"

Rate Limits

API requests are subject to rate limiting to ensure fair usage and platform stability. Limits are applied per API key over a 1-minute rolling window.

Plan	Rate Limit
Free	20 requests/min
Pro Toolkit / Agency	100 requests/min

Write operations (POST, PUT, DELETE) cost 3 points per request. Read operations (GET) cost 1 point.

Every API response includes rate limit headers:

Header	Description
`RateLimit-Limit`	Your total allowance per minute
`RateLimit-Remaining`	Requests remaining in the current window
`RateLimit-Reset`	Seconds until the window resets

When you exceed the rate limit, the API returns a 429 Too Many Requests response with a retryAfter value in seconds.

Error Codes

Status Code	Error Code	Description
`200`	-	Success
`201`	-	Created (returned when a new URL is created)
`400`	-	Bad Request - Invalid parameters or URL format
`401`	-	Unauthorized - Invalid or missing API key
`401`	`API_KEY_EXPIRED`	API key has expired, generate a new one from Settings
`403`	`PLAN_REQUIRED`	API access requires an Agency subscription
`403`	-	Forbidden - Feature requires a higher plan, or you don't own the resource
`404`	-	Not Found - Resource doesn't exist or has been deleted
`429`	-	Too Many Requests - Rate limit exceeded, wait before retrying
`500`	-	Internal Server Error