Reference

Client APIs

Client APIs are for SDKs and trusted public clients. They use publishable keys and cannot create links, read analytics, mutate domains, manage apps, or rotate credentials.

Client Auth Headers

Parameter	Type	Required	Description
x-publishable-key	string	Optional	Publishable key. Authorization: Bearer and publishable-key are also accepted.
x-shortify-environment	string	Optional	Must match the key environment when provided.
x-shortify-platform	browser \| android \| ios	Optional	Must match the key platform when provided.
Origin	URL	Optional	Checked for browser keys when origins are configured.
x-android-package	string	Optional	Checked for Android keys when configured.
x-android-sha256-cert	string	Optional	Checked for Android keys when configured.
x-ios-bundle-id	string	Optional	Checked for iOS keys when configured.

Resolve Link

POST/v1/client/resolve

Provide one link reference form.

Parameter	Type	Required	Description
linkId	string	Optional	Stable link ID.
shortLink	URL	Optional	Full short-link URL. url is also accepted.
domain + key	string	Optional	Domain and key pair. slug is accepted as an alias for key.

Resolve link

curl -X POST "https://api.shortify.com/v1/client/resolve" \
  -H "x-publishable-key: pk_live_your_publishable_key" \
  -H "x-shortify-platform: browser" \
  -H "Content-Type: application/json" \
  --data '{"shortLink":"https://go.example.com/invite-abc"}'

Record Click

POST/v1/client/attribution/click

Parameter	Type	Required	Description
linkId	string	Optional	Stable link ID.
shortLink	URL	Optional	Full short-link URL. url is also accepted.
domain + key	string	Optional	Domain and key pair. slug is accepted as an alias for key.
sessionId	string	Optional	Anonymous session identifier. Generated when omitted.
installId	string	Optional	Opaque install identifier.
deviceId	string	Optional	Opaque device identifier used for matching.
anonymousDeviceId	string	Optional	Alias for deviceId.

201

Created

{
  "success": true,
  "data": {
    "clickId": "0c78f83b-3917-4c9d-81c7-9a7dc7d5d76e",
    "attributionId": "97f4cf8d-4d39-4c92-9a18-bf68a39c1e14",
    "sessionId": "anon-session-123",
    "installId": "install-456",
    "expiresAt": "2026-07-10T09:00:00.000Z",
    "eligible": true,
    "deferredDeepLink": {
      "linkId": "link_01HV5A4W7QJ9K2X4Q8ZW5FGZ2R",
      "linkType": "DEEPLINK",
      "deepLinkAppId": "app_01HV4Z4Y6W3D4J9B2Y8QH6P8JS",
      "shortLink": "https://go.example.com/invite-abc",
      "domain": "go.example.com",
      "key": "invite-abc",
      "url": "https://example.com/app-open"
    }
  },
  "requestId": "req_01HV5A4W7QJ9K2X4Q8ZW5FGZ2R"
}

Deferred Deep Link

POST/v1/client/deferred-deep-link

Matches an eligible attribution touch by attributionId, clickId, installId, sessionId, or anonymous device hints. A matched touch is consumed once.

Lookup deferred payload

curl -X POST "https://api.shortify.com/v1/client/deferred-deep-link" \
  -H "x-publishable-key: pk_live_your_publishable_key" \
  -H "x-shortify-platform: android" \
  -H "Content-Type: application/json" \
  --data '{"attributionId":"97f4cf8d-4d39-4c92-9a18-bf68a39c1e14","installId":"install-456"}'

First Open Or Install

POST/v1/client/first-open

Parameter	Type	Required	Description
eventType	first_open \| install	Optional	Defaults to first_open.
attributionId	string	Optional	Attribution ID from record-click.
clickId	string	Optional	Click ID from record-click.
installId	string	Optional	Opaque install identifier.
sessionId	string	Optional	Anonymous session identifier.
externalUserId	string	Optional	Opaque non-PII user identifier. Raw email, phone, and similar PII are rejected.

Customer Events

POST/v1/client/events

Send 1 to 50 events per request. Each event must include a valid name and link context through linkId, clickId, or attributionId. Supplied eventId values are treated as idempotency keys.

Parameter	Type	Required	Description
events[].name	string	Required	Starts with a letter. Letters, numbers, underscore, period, colon, and dash are allowed.
events[].eventId	string	Optional	Caller-supplied idempotency key for this event.
events[].linkId	string	Optional	Stable link ID. Required unless clickId or attributionId is provided.
events[].clickId	string	Optional	Click ID from record-click.
events[].attributionId	string	Optional	Attribution ID from record-click.
events[].externalUserId	string	Optional	Opaque non-PII user identifier.
events[].properties	object	Optional	Up to 50 primitive string, number, or boolean properties. Direct PII is rejected.

Publish customer event

curl -X POST "https://api.shortify.com/v1/client/events" \
  -H "x-publishable-key: pk_live_your_publishable_key" \
  -H "x-shortify-platform: ios" \
  -H "Content-Type: application/json" \
  --data '{
    "events": [{
      "name": "purchase",
      "eventId": "order-1001",
      "attributionId": "97f4cf8d-4d39-4c92-9a18-bf68a39c1e14",
      "properties": {"currency": "USD", "value": 49}
    }]
  }'

202

Accepted

{
  "success": true,
  "data": {
    "accepted": [
      {
        "eventId": "order-1001",
        "status": "queued"
      }
    ]
  },
  "requestId": "req_01HV5A4W7QJ9K2X4Q8ZW5FGZ2R"
}

Getting Started

API Reference