iPhone paste handoff (opt-in): claim a one-time handoff token

iPhone paste handoff (opt-in): claim a one-time handoff token (exact, single use).

THE CALL, PART BY PART

method

POST

host

strait.link

version

/v1

resource

/handoff/claim

POST /v1/handoff/claim

Auth: publishable key as publishableKey in the JSON body. Safe in apps and websites.

Request

Only when the workspace turned on Paste handoff (Dashboard Settings -> iPhone installs; opt-in, off by default); the SDK reads it live from the ios.pasteHandoff field of POST /v1/match and checks the clipboard only then. The token comes from the handoff link https://<link host>/h/<token> that the tap page copied; it belongs to one tap of this workspace, works once and expires after 24 hours. When it does not match, nothing is recorded and the SDK falls back to POST /v1/match with the same openId. Rate limited per IP.

Body (JSON)

publishableKey required string
token required string
platform string
openId string
The open id of this first app open: the claim also reports the open.
at number
When the app opened (epoch ms).
appVersion string
The app's own version (iOS CFBundleShortVersionString, Android versionName), kept on the open. 1-64 printable ASCII characters; anything else is ignored, never an error.
sdkVersion string
The Strait SDK version, kept on the open. Same rule as appVersion.

Response

  • 200 Claim result: matchMethod clipboard with clickId, or matched:false with reason handoff_unknown, handoff_used, handoff_expired or not_found
  • 400 token is not a handoff token
  • 401 missing or invalid publishable key
  • 429 rate limited
Request · curl
curl -X POST https://strait.link/v1/handoff/claim \
  -H "Content-Type: application/json" \
  -d '{
    "publishableKey": "st_pub_live_…",
    "token": "Qm9yZWFsaXMtaGFuZG9mZg",
    "platform": "ios",
    "openId": "o_lx3k2a_9f8e7d6c5b4a",
    "at": 1790000000000
  }'

The response, printed

Response 200
{
  "matched": true,
  "longUrl": "https://shop.example.com/sale/summer?utm_source=whatsapp&utm_campaign=summer-2026",
  "linkId": "lnk_5f0c2a8e-3b1d-4f6a-9c7e-2d8b1a0e4f63",
  "matchMethod": "clipboard",
  "confidence": null,
  "clickId": "9a1c7e52-4b3d-4f8e-a6d1-0c2b5e7f9a34",
  "reasons": [
    "clipboard"
  ],
  "match": {
    "method": "clipboard",
    "confidence": "exact"
  }
}