Lookup Click

Look up the expected affiliate tag for a click. Use this at checkout to verify the tag hasn't been hijacked.

Endpoint

GET https://api.linkbay.io/api/v1/merchant/lookup-click

Parameters

Name	Type	Required	Description
`click_id`	string	Yes	The click ID from the `lb_click` URL parameter

Response

{
  "clickId": "xyz789",
  "expectedTag": "CREATOR123",
  "creatorId": "abc123",
  "timestamp": "2026-01-15T10:30:00Z",
  "status": "pending",
  "referrer": "youtube.com/watch?v=...",
  "geo": {
    "country": "US",
    "city": "New York",
    "region": "NY"
  }
}

Response Fields

Field	Type	Description
`clickId`	string	The unique click identifier
`expectedTag`	string	The affiliate tag that should be used for attribution
`creatorId`	string	The Linkbay ID of the creator who generated the link
`timestamp`	string	ISO 8601 timestamp of when the click occurred
`status`	string	Click status: `pending`, `verified`, or `expired`
`referrer`	string?	The page where the link was clicked (if available)
`geo`	object?	Geographic information about the click

Errors

Status	Error	Description
400	`click_id is required`	The click_id parameter is missing
401	`API key required`	Missing X-API-Key header
401	`Invalid API key`	API key not found or revoked
404	`Click not found or expired`	Click ID doesn't exist or TTL expired (1 hour)

Example Usage

JavaScript/TypeScript

// Extract click ID from URL
const urlParams = new URLSearchParams(window.location.search);
const clickId = urlParams.get('lb_click');
const arrivedTag = urlParams.get('tag');

// Verify at checkout (server-side)
const response = await fetch(
  `https://api.linkbay.io/api/v1/merchant/lookup-click?click_id=${clickId}`,
  {
    headers: {
      'X-API-Key': process.env.LINKBAY_API_KEY,
    },
  }
);

const { expectedTag } = await response.json();

if (arrivedTag !== expectedTag) {
  console.log('Hijack detected!');
  // Credit the real creator (expectedTag), not the hijacker (arrivedTag)
}

cURL

curl "https://api.linkbay.io/api/v1/merchant/lookup-click?click_id=xyz789" \
  -H "X-API-Key: YOUR_API_KEY"

Important Notes

Click data expires after 1 hour. If you need to verify a click, do so promptly.
The expectedTag is the tag that was set when the creator generated the Linkbay link.
Compare expectedTag with the tag that arrived in your URL (usually a tag or affiliate parameter) to detect hijacking.
This endpoint is designed for server-side use. Never expose your API key in client-side code.