To set up a custom integration, you’ll first need to create and configure a postback URL that securely sends your event data directly to our platform.
This guide explains how to structure your URLs correctly for installs and in-app events and details all the required and optional parameters for each event type, helping you smoothly integrate your custom measurement solution with our platform.
Install postback URL parameters
These are the parameters expected in the install-level postback:
| Name | Parameter | Required? | Description | Example Value | Apple Ads Attribution API Equivalent | Apple Ads Attribution API v4 IDs |
|---|---|---|---|---|---|---|
| Device Type | deviceType |
✅ If possible | The type of device that triggered the event | iPhone, iPad | - | - |
| Organization ID | orgId |
✅ If possible | Your organization's unique ID | 5555555 | orgId |
iad-org-id |
| App ID | trackId |
✅ Yes | The ID of your app on the App Store | 123456789 | - | - |
| Country Code | countryCode |
✅ If possible | Country based on user’s IP address | US, UK, etc. | - | - |
| Country/Region | countryRegion |
✅ If possible | Country selected for the campaign | US, UK, etc. | countryOrRegion |
iad-country-region |
| Campaign ID | campaignId |
✅ Yes | Apple Ads Campaign ID | 448876249 | campaignId |
iad-campaign-id |
| Ad Group ID | adgroupId |
✅ Yes | Apple Ads Ad Group ID | 258876905 | adgroupId |
iad-adgroup-id |
| Ad ID | adId |
✅ If possible | Apple Ads Creative ID | 12345678 | adId |
iad-ad-id |
| Keyword | keyword |
✅ If possible | Keyword that triggered the ad | games | - | iad-keyword |
| Keyword ID | keywordId |
✅ If possible | Apple Ads Keyword ID | 84567829 | keywordId |
iad-keyword-id |
| Match Type | keywordMatchType |
✅ If possible | Type of keyword match | Exact; Broad; Search Match | - | iad-keyword-matchtype |
| Install Time | installTimestamp |
✅ Yes | Timestamp of the install in seconds | 1590161787 | - | - |
| Reattribution | reattribution |
Optional | Is reattributed data | 0 or 1 | - | - |
| Conversion Type | conversionType |
Optional | Type of install: download or redownload | download | conversionType |
iad-conversion-type |
| Claim Type | claimType |
Optional | Method of attribution: click or impression | click | claimType |
- |
Install postback format
Use the HTTP method: GET and include the provided API key.
URL template:
https://attrs.searchads.com/api/postbacks/custom/installs/{api_key}?deviceType={device_type}&orgId={org_id}&trackId={app_id}&countryCode={country_code}&countryRegion=country_or_region}&campaignId={campaign_id}&adgroupId={ad_group_id}&adId={ad_id}&keyword={keyword}&keywordId={keyword_id}&keywordMatchType={keyword_match_type}&installTimestamp={install_time_stamp}&reAttribution={re_attribution}&conversionType={conversion_type}&claimType={claim_type}
Example URL:
https://attrs.searchads.com/api/postbacks/custom/installs/abcEfg1b644d?deviceType=iPhone&orgId=116750&trackId=id1105855019&countryCode=US&countryRegion=ES&campaignId=372373519&adgroupId=371423499&adId=7412457&keyword=game&keywordId=12455643&keywordMatchType=Exact&installTimestamp=1589560389&reAttribution=0&claimType=Click
In-app event postback parameters
After the install, you may want to track specific in-app actions like purchases or sign-ups. These are the required parameters for sending in-app event postback:
| Name | Parameter | Required? | Description | Example Value | Apple Ads Attribution API Equivalent | Apple Ads Attribution API v4 IDs |
|---|---|---|---|---|---|---|
| Device Type | deviceType |
✅ If possible | The type of device that triggered the event | iPhone, iPad | - | - |
| Organization ID | orgId |
✅ Yes | Your organization’s unique ID | 5555555 | orgId |
iad-org-id |
| App ID | trackId |
✅ Yes | The ID of your app on the App Store | 123456789 | - | - |
| Country Code | countryCode |
✅ If possible | Country based on user’s IP address | US, UK, etc. | - | - |
| Country/Region | countryRegion |
✅ If possible | Country selected for the campaign | US, UK, etc. | countryOrRegion |
iad-country-region |
| Campaign ID | campaignId |
✅ Yes | Apple Ads Campaign ID | 448876249 | campaignId |
iad-campaign-id |
| Ad Group ID | adgroupId |
✅ Yes | Apple Ads Ad Group ID | 258876905 | adgroupId |
iad-adgroup-id |
| Ad ID | adId |
✅ If possible | Apple Ads Creative ID | 12345678 | adId |
iad-ad-id |
| Keyword | keyword |
✅ If possible | Keyword that triggered the ad | games | - | iad-keyword |
| Keyword ID | keywordId |
✅ If possible | Apple Ads Keyword ID | 84567829 | keywordId |
iad-keyword-id |
| Match Type | keywordMatchType |
✅ If possible | Type of match used | Exact; Broad; Search Match | - | iad-keyword-matchtype |
| Install Time | installTimestamp |
✅ Yes | Timestamp of the install in seconds | 1590161787 | - | - |
| Event Time | eventTimestamp |
✅ Yes | Timestamp of the event (e.g., purchase) in seconds | 1590161237 | - | - |
| Event Name | eventName |
✅ Yes | Name of the event | Purchase, Subscription etc. | - | - |
| USD Revenue | usdRevenue |
✅ If possible | Revenue in USD | 9.99 | - | - |
| Original Revenue | origRevenue |
✅ If possible | Original revenue | 25.45 | ||
| Currency | currency |
✅ If possible | Original ISO 4217 currency code | EUR | - | - |
| Reattribution | reattribution |
Optional | Is reattributed data | 0 or 1 | - | - |
| Conversion Type | conversionType |
Optional | Type of conversion: download or redownload | Download; Redownload | conversionType |
iad-conversion-type |
| Claim Type | claimType |
Optional | Attribution method: click or impression |
Click Impression |
claimType |
- |
Note: You can choose to provide either the USD revenue or the original revenue along with its currency code. If you send the original currency, the team will handle the conversion on our end. This approach also allows you to view metrics in both USD and the original currency within your dashboard, supporting a more localized and flexible reporting experience.
In-app postback URL format
Use the HTTP method: GET and include the provided API key.
URL template:
https://attrs.searchads.com/api/postbacks/custom/events/{api_key}?deviceType={device_type}&orgId={org_id}&trackId={app_id}&countryCode={country_code}&countryRegion={country_or_region}&campaignId={campaign_id}&adgroupId={ad_group_id}&adId={ad_id}&keyword={keyword}&keywordId={keyword_id}&keywordMatchType={keyword_match_type}&installTimestamp={install_time_stamp}&eventTimestamp={event_time_stamp}&eventName={event_name}&usdRevenue={usd_revenue}&origRevenue={orig_revenue}¤cy={currency}&reAttribution={re_attribution}&conversionType={conversion_type}&claimType={claim_type}
Example in-app postback:
https://attrs.searchads.com/api/postbacks/custom/events/abcEfg1b644de32349?deviceType=iPhone&orgId=116750&trackId=id1105855019&countryCode=US&countryRegion=ES&campaignId=372373519&adgroupId=371423499&adId=7412457&keyword=game&keywordId=12455643&keywordMatchType=Exact&installTimestamp=1589560389&eventTimestamp=1589560889&eventName=purchase&usdRevenue=35.97&origRevenue=33.45¤cy=EUR&reAttribution=0&claimType=Click
If you need support while setting up your custom integration, feel free to contact your Customer Success Manager or reach out to us directly via live chat. We’re here to help!