Attribution Endpoints

These are the core SDK endpoints for click tracking, install attribution, and event tracking.

GET /api/v1/clicks

Track an ad click and redirect to the app store.

Authentication: None (public endpoint)


curl -v "https://api.attributehq.com/v1/clicks?app_id=YOUR_APP_ID&c=summer_campaign&pid=facebook&advertising_id=IDFA_123"

Query Parameters:

Param	Required	Description
`app_id`	Yes	App UUID
`c`	No	Campaign ID
`pid`	No	Media source (publisher ID): `facebook`, `google`, etc.
`af_adset`	No	Ad set identifier
`af_ad`	No	Ad identifier
`advertising_id`	No	IDFA (iOS) or GAID (Android)
`redirect_url`	No	Custom redirect URL (highest priority)

Response (302 Found):

Redirects to:

redirect_url param (if provided)
App store URL from app settings (based on platform detection)
Default app store URL

Side Effects:

Click stored to DynamoDB with 7-day TTL
Device fingerprint generated from IP + User-Agent
Click event archived to S3 data lake

This endpoint always redirects — it never returns an error page. If the app is not found, it gracefully redirects to the default app store.

Click URL Format

Use this URL format in your ad campaigns:


https://api.attributehq.com/v1/clicks?app_id={app_id}&c={campaign_name}&pid={media_source}

POST /api/v1/installs

Track an app install and return attribution result. Called automatically by the SDKs on first launch.

Authentication: API Key (X-API-Key header)


curl -X POST https://api.attributehq.com/v1/installs \
  -H "X-API-Key: ak_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "YOUR_APP_ID",
    "device_id": "IDFA_OR_GAID",
    "platform": "android",
    "install_referrer": "utm_source=facebook&utm_campaign=summer",
    "sdk_version": "1.0.0",
    "screen_resolution": "1080x1920",
    "timezone": "Africa/Lagos",
    "language": "en-NG"
  }'

Request Body:

Field	Type	Required	Description
`app_id`	string	Yes	Must match API key’s app
`device_id`	string	No	IDFA (iOS) or GAID (Android)
`platform`	string	Yes	`"ios"`, `"android"`, or `"web"`
`install_referrer`	string	No	Android Install Referrer string
`sdk_version`	string	Yes	SDK version (e.g., `"1.0.0"`)
`screen_resolution`	string	No	For fingerprinting
`timezone`	string	No	For fingerprinting
`language`	string	No	For fingerprinting
`os_version`	string	No	OS version string
`device_model`	string	No	Device model

Response (201 Created):


{
  "success": true,
  "data": {
    "matchType": "device_id",
    "confidence": 100,
    "mediaSource": "facebook",
    "campaignId": "summer_campaign",
    "isOrganic": false,
    "attributedTouchTime": 1700000000000
  }
}

Attribution Waterfall

Priority	Method	Confidence	Trigger
1	Install Referrer	100%	`install_referrer` param present (Android)
2	Device ID	95-100%	`device_id` matches a stored click
3	Fingerprint	60-80%	IP + UA hash matches (requires 60%+)
4	Organic	—	No matching click within 7-day window

Errors: 400 validation, 401 invalid key, 403 app_id mismatch

POST /api/v1/events

Track in-app events (purchases, signups, custom events).

Authentication: API Key (X-API-Key header or _api_key in body)


curl -X POST https://api.attributehq.com/v1/events \
  -H "X-API-Key: ak_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "YOUR_APP_ID",
    "device_id": "DEVICE_UUID",
    "events": [
      {
        "event_name": "purchase",
        "properties": {
          "amount": 5000,
          "currency": "NGN",
          "product_id": "premium_plan"
        },
        "timestamp": 1700000000000,
        "session_id": "session-uuid"
      }
    ],
    "sdk_version": "1.0.0"
  }'

Request Body:

Field	Type	Required	Description
`app_id`	string	Yes	App UUID
`device_id`	string	No	Links events to install for LTV
`events`	array	Yes	Array of event objects
`sdk_version`	string	Yes	SDK version
`_api_key`	string	No	Fallback auth for sendBeacon

Event Object:

Field	Type	Required	Description
`event_name`	string	Yes	Event name (e.g., `"purchase"`)
`properties`	object	Yes	Custom properties
`timestamp`	number	Yes	Unix milliseconds
`session_id`	string	Yes	Session UUID

Response (200 OK):


{
  "success": true,
  "data": {
    "accepted": 1
  }
}

Revenue Events

Events with properties.amount and properties.currency are automatically recognized as revenue events:


{
  "event_name": "purchase",
  "properties": {
    "amount": 5000,
    "currency": "NGN"
  }
}