Short Links

Create and manage short links (QR codes and redirects) programmatically. Every short link redirects visitors to a destination URL, records a click, and can carry campaign tags and QR styling, all creatable in a single call.

For the product behind this API, including the QR design surface, campaign tagging, and reporting, see Short Links. For automation workflows such as bulk creation and migrating from another link tool, see Automating short links.

What a short link is

A short link bundles three things:

• A short code, embedded in the public URL (/r/{code}). One is generated for you unless you supply a code on create; it's returned as pixel and shortLinkCode on the entity and is immutable once the link is published.
• A destination (redirectUrl), where the visitor is sent.
• A design: campaign (utm) tags saved with the link and QR code visual styling (qr).

The composed public URL is returned as shortUrl. New links resolve at /r/{code} with no query string; the link name is the tracked event name and campaign tags are read from the published link at click time. That same URL is what a QR code should encode. It also resolves on any branded custom domains configured for your account, so you can front it with your own domain without regenerating printed QR codes.

Creating a short link

POST /rest/v1/short-links creates a usable short link in one call. All fields are optional; send {} to create an unconfigured link and fill it in later with PATCH.

curl -X POST https://app.oursprivacy.com/rest/v1/short-links \
  -H "Authorization: Bearer $OURS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spring Sale",
    "redirectUrl": "https://example.com/spring",
    "utm": { "campaign": "spring_sale", "source": "newsletter" },
    "qr": { "fgColor": "#001722", "dotStyle": "rounded" }
  }'

The response includes the composed shortUrl and the folded shortLinkDesign, so you can render a QR and share the link without a follow-up request.

Making a short link live

A newly created short link only resolves at the edge once a version is published. Publish with POST /rest/v1/versions after creating or editing your short links. Until then, the destination is saved but the short URL does not redirect.

Bulk creation

To migrate or create many short links at once, loop POST /rest/v1/short-links per link, then publish a single version at the end. (A dedicated batch endpoint is planned.)

Click analytics

GET /rest/v1/short-links/{id}/results returns aggregate click analytics over a date window: total and unique clicks, a daily or hourly time series, and breakdowns by country, city, and device. QR scans are counted as clicks. This endpoint requires the shortlink:reporting scope, which is granted separately because analytics data is PHI-bearing.

curl -X GET "https://example.com/rest/v1/short-links"

{  "entities": [    {      "id": "string",      "name": "string",      "status": "Disabled",      "createdAt": "string",      "accountId": "string",      "isPublished": true,      "redirectUrl": "string",      "pixel": "string",      "shortLinkCode": "string",      "hasCustomShortLinkCode": true,      "shortUrl": "string",      "shortLinkDesign": {}    }  ],  "pagination": {    "nextCursor": "string",    "hasMore": true  }}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

curl -X POST "https://example.com/rest/v1/short-links" \  -H "Content-Type: application/json" \  -d '{}'

{  "id": "string",  "name": "string",  "status": "Disabled",  "createdAt": "string",  "accountId": "string",  "isPublished": true,  "redirectUrl": "string",  "pixel": "string",  "shortLinkCode": "string",  "hasCustomShortLinkCode": true,  "shortUrl": "string",  "shortLinkDesign": {}}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

curl -X GET "https://example.com/rest/v1/short-links/string"

{  "id": "string",  "name": "string",  "status": "Disabled",  "createdAt": "string",  "accountId": "string",  "isPublished": true,  "redirectUrl": "string",  "pixel": "string",  "shortLinkCode": "string",  "hasCustomShortLinkCode": true,  "shortUrl": "string",  "shortLinkDesign": {}}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

curl -X PATCH "https://example.com/rest/v1/short-links/string" \  -H "Content-Type: application/json" \  -d '{}'

{  "id": "string",  "name": "string",  "status": "Disabled",  "createdAt": "string",  "accountId": "string",  "isPublished": true,  "redirectUrl": "string",  "pixel": "string",  "shortLinkCode": "string",  "hasCustomShortLinkCode": true,  "shortUrl": "string",  "shortLinkDesign": {}}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

curl -X DELETE "https://example.com/rest/v1/short-links/string"

{  "deleted": true}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

curl -X GET "https://example.com/rest/v1/short-links/string/results?from=2026-06-01&to=2026-06-30"

{  "totalClicks": 0,  "uniqueClicks": 0,  "timeSeries": [    {      "period": "string",      "clicks": 0,      "uniqueClicks": 0    }  ],  "geoByCountry": [    {      "name": "string",      "clicks": 0,      "uniqueClicks": 0    }  ],  "geoByCity": [    {      "name": "string",      "clicks": 0,      "uniqueClicks": 0    }  ],  "devices": [    {      "name": "string",      "clicks": 0,      "uniqueClicks": 0    }  ]}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}