Automating Short Links

Use this page when you need more links than the dashboard is comfortable for: a per-store QR code, a per-provider link, a per-recipient campaign link, or a migration from another link tool.

Full request and response reference lives on the Short Links API page. This page covers the workflow around it.

What you can automate

Authentication and key management are covered in Platform API authentication.

Create a link

Every field is optional, so an empty body creates a placeholder link you can fill in later. In practice you will send the destination and the campaign tags together:

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 Postcard QR",
    "redirectUrl": "https://northsidehealth.example/spring",
    "utm": { "campaign": "spring_2026", "source": "postcard", "medium": "direct_mail" },
    "qr": { "theme": "midnight", "frameShape": "rounded" }
  }'

The response includes the composed public URL, so you can render a QR code or hand the link off without a second request.

Remember that the name you send becomes the event name on every click. Generate names you will be able to read in Analytics later.

Publish

A short link created through the API is a draft, exactly like one created in the dashboard. It does not resolve until a version is published.

curl -X POST https://app.oursprivacy.com/rest/v1/versions \
  -H "Authorization: Bearer $OURS_API_KEY"

When creating many links, create them all first and publish once at the end rather than publishing per link.

Bulk creation

There is no batch endpoint today. Loop the create call, then publish a single version:

#!/usr/bin/env bash
# One QR code per clinic location, from a CSV of name,url
while IFS=, read -r name url; do
  curl -sS -X POST https://app.oursprivacy.com/rest/v1/short-links \
    -H "Authorization: Bearer $OURS_API_KEY" \
    -H "Content-Type: application/json" \
    -d "$(jq -n --arg n "$name" --arg u "$url" \
      '{name: $n, redirectUrl: $u, utm: {campaign: "clinic_signage_2026", medium: "signage"}}')" \
    | jq -r '.shortUrl'
done < locations.csv

curl -sS -X POST https://app.oursprivacy.com/rest/v1/versions \
  -H "Authorization: Bearer $OURS_API_KEY"

Two practical notes for a bulk run:

• Keep the returned public URL. You will need it to generate artwork, and pairing it back to your source rows afterwards is more work than capturing it as you go.
• Give every link the same campaign value so the set can be read together.

Migrating from another link tool

The short code is generated and cannot be set, so links cannot be recreated with their existing back-halves. A migration therefore means new URLs and new QR codes.

A workable sequence:

1. Export your existing links, with their destinations and campaign tags.
2. Create an Ours Privacy short link per row, preserving the destination and tags.
3. Publish.
4. Repoint the old tool's links at the new Ours Privacy URLs, so existing printed and distributed material keeps working and starts flowing through your own reporting.
5. Use the new URLs for everything created from that point on.

Step 4 is what makes the migration survivable. Old codes redirect twice, which is slower but functional, and new codes redirect once.

Pull reporting

The results endpoint returns the same numbers as the Analytics tab: totals, a time series, and country, city, and device breakdowns.

curl -sS "https://app.oursprivacy.com/rest/v1/short-links/$LINK_ID/results?from=2026-03-01&to=2026-03-31" \
  -H "Authorization: Bearer $OURS_API_KEY"

Windows are capped at 92 days for daily granularity and 31 days for hourly. Bots are excluded unless you ask for them.

This endpoint requires the View Short Link Reporting scope, which is granted separately from short link management because click analytics can carry protected health information.

MCP tools

The same operations are available as MCP tools for agent-driven workflows: creating, reading, listing, updating, and deleting short links, plus pulling results. They mirror the REST contract field for field. See SDKs and MCP.

Next Steps

• Short Links API reference: every endpoint, field, and response.
• Platform API authentication: creating and scoping a key.
• Recipes: worked configurations, including per-location codes.