Developer documentation

Introduction

The URLCrop API lets you create branded short links, dynamic QR codes and link-in-bio pages, read analytics, and attribute leads and sales back to the link, QR code, campaign or partner that produced them. It is a REST API that speaks JSON over HTTPS:

https://api.urlcrop.com/v1

What you can build

Shorten every link your CRM, SMS or WhatsApp platform sends, on your own domain, with UTM tags applied automatically.
Generate thousands of print-ready, branded QR codes for packaging, menus, posters and UPI counters — and change where they point later.
Pull clicks, scans, countries, devices and referrers into your own dashboards or a Google Sheet.
Send purchases and leads to URLCrop (JavaScript snippet or server-side) and see revenue per link, QR code and campaign.
React to events in real time with signed webhooks.

Who can use it. API access is included on the Pro, Business and Agency plans. Every request is made on behalf of a workspace with an API key you create in the dashboard; there is no anonymous access and nothing is created without an account.

Interactive reference (every endpoint, schema and example, powered by the OpenAPI document): https://docs.urlcrop.com/api/reference

Quickstart

2.1 Create an API key

Sign in at https://app.urlcrop.com (verify your email first).
Open Settings → API keys → Create key.
Choose Secret key, give it a name, pick scopes (start with links:read, links:write, insights:read) and copy the key. It is shown once.

Your key looks like uc_live_3f9aKq2Z…. Keys that start with uc_test_ belong to your test workspace (see section 12).

2.2 First request — who am I?

curl https://api.urlcrop.com/v1/workspace \
  -H "Authorization: Bearer uc_live_EXAMPLEKEY000000000000000000000000000000000"

{
  "id": "ws_01JB4M0A1B2C3D4E5F6G7H8J9K",
  "object": "workspace",
  "name": "Brand India",
  "environment": "live",
  "is_test": false,
  "plan": "pro",
  "settings": { "timezone": "Asia/Kolkata", "append_click_id": true, "click_id_param": "ucid", "default_domain": "crop.sh" }
}

2.3 Create a link

curl -X POST https://api.urlcrop.com/v1/links \
  -H "Authorization: Bearer $URLCROP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6c0f1d7e-9a2b-4c3d-8e5f-1a2b3c4d5e6f" \
  -d '{
    "destination_url": "https://brand.in/diwali-sale",
    "domain": "go.brand.in",
    "slug": "diwali",
    "title": "Diwali Sale 2026",
    "utm": { "source": "whatsapp", "medium": "broadcast", "campaign": "diwali-2026" }
  }'

{
  "id": "lnk_01JB4N8ZK3Q9WXYZ0123456789",
  "object": "link",
  "domain": "go.brand.in",
  "slug": "diwali",
  "short_url": "https://go.brand.in/diwali",
  "destination_url": "https://brand.in/diwali-sale",
  "status": "active",
  "safety": { "status": "safe", "risk_score": 2, "scanned_at": "2026-12-05T10:15:30.000Z" },
  "clicks": 0,
  "created_at": "2026-12-05T10:15:30.000Z"
}

Node (@urlcrop/sdk):

import { URLCrop } from '@urlcrop/sdk';

const uc = new URLCrop({ apiKey: process.env.URLCROP_API_KEY! });

const link = await uc.links.create({
  destination_url: 'https://brand.in/diwali-sale',
  domain: 'go.brand.in',
  slug: 'diwali',
  utm: { source: 'whatsapp', medium: 'broadcast', campaign: 'diwali-2026' },
});
console.log(link.short_url); // https://go.brand.in/diwali

Install the Node SDK with npm i @urlcrop/sdk. Examples for lists, errors, webhooks and test mode are in section 9.

JavaScript (fetch, server-side only — never ship a secret key to the browser):

const res = await fetch('https://api.urlcrop.com/v1/links', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.URLCROP_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({ destination_url: 'https://brand.in/diwali-sale', slug: 'diwali' }),
});
const link = await res.json();

2.4 Fetch its stats

curl "https://api.urlcrop.com/v1/links/lnk_01JB4N8ZK3Q9WXYZ0123456789/stats?from=2026-11-05&to=2026-12-05" \
  -H "Authorization: Bearer $URLCROP_API_KEY"

{
  "object": "stats",
  "period": { "from": "2026-11-05T00:00:00.000Z", "to": "2026-12-05T23:59:59.999Z", "timezone": "Asia/Kolkata" },
  "totals": { "clicks": 8450, "scans": 1210, "unique_visitors": 7120 },
  "timeseries": [ { "date": "2026-12-04", "clicks": 410, "scans": 55 }, { "date": "2026-12-05", "clicks": 388, "scans": 61 } ],
  "top": { "countries": [ { "key": "IN", "label": "India", "value": 7890, "share": 0.82 } ], "devices": [], "referrers": [] }
}

const stats = await uc.links.stats(link.id, { from: '2026-11-05', to: '2026-12-05' });