Guide
AdServices attribution API: what 404, 400 and attribution=false mean
Updated 2026-11-03 · 3 min read
Short answer: A
404 means Apple couldn't find the record yet or the token is older than its 24-hour TTL; retry every 5 seconds, up to three times. A 400 means the token is invalid. A 200 with attribution=false means no matching Apple Ads tap (30 days) or view (24 hours), or the ad group uses age or gender settings. A 500 means retry later.The flow
- Call
AAAttribution.attributionToken()on the device (iOS 14.3+, macOS 11.1+). It returns a Base64 token with a 24-hour TTL. - POST the token as the raw body with
Content-Type: text/plaintohttps://api-adservices.apple.com/api/v1/. - Read the JSON payload:
attribution,orgId,campaignId,adGroupId,keywordId,adId,conversionType,claimType,clickDateorimpressionDate,countryOrRegion,supplyPlacement.
Response codes
| Code | Meaning | What to do |
|---|---|---|
| 200, attribution=true | Matching Apple Ads tap or view | Store the campaign, ad group and keyword ids |
| 200, attribution=false | No match, or the ad group uses age/gender settings | Treat as not attributed to Apple Ads |
| 400 | Invalid token | Check you're sending the raw token as text/plain |
| 404 | Record not found yet, or the token is older than 24 hours | Retry every 5 seconds, max three attempts; post within 24 hours |
| 500 | Apple Ads server temporarily unavailable | Retry later |
Common mistakes
- Calling once, too early. A 404 straight after install is normal. Without retries, those installs become "organic".
- Sending the token as JSON. The body is the token itself, as text/plain.
- Getting test data. Apple returns a test payload when the app is in developer mode.
- Expecting keyword ids with search match. When search match is on,
keywordIdisn't returned.
Tap vs view
claimType is Click for tap-through (30-day window) or Impression for view-through (24-hour window). Taps take priority over views.
Questions
How long is the AdServices token valid?
24 hours. Posting it later returns 404.
Why does attribution return false for my campaign?
Either there was no Apple Ads tap in the last 30 days or view in the last 24 hours, or the ad group uses age or gender settings, which always return false.