impact.com Action & Conversion Data References
Use the conversion data references and template examples when sending conversion data to impact.com.
Event Type Data
| Parameter Name | Format (Size) | Description | Requirement | Example | Notes |
|---|---|---|---|---|---|
ActionTrackerId | INTEGER (10) | Unique identifier for the event type (or action tracker) that tracked this conversion. Normal web: Settings → Events Types. Mobile App: Settings → Mobile App | Required, unless EventTypeCode is provided | 1000 | Also known as EventTrackerID |
EventTypeCode | STRING (128) | Configurable string value for the event type that identifies it when submitting conversions. To view or configure this value, see Settings → Events Types → Actions → View/Edit → "Codes" in the platform. | Required, unless ActionTrackerId is provided | SALE | |
EventCode | STRING (128) | Custom identifier for the event that occurred in your mobile app that you want to report (e.g., INSTALL, SIGN-UP, SALE, etc.). | Required, when submitting mobile conversions | INSTALL | With Mobile events, the ActionTrackerId is specific to the mobile type (E.g., iOS, Android). EventCode is submitted to distinguish between the different mobile events (INSTALL, SIGN-UP, SALE, etc.) |
EventDate | DATETIME (ISO 8601) | The date and time when the conversion event occurred; use ISO 8601 format. | Required | 2038-01-19T03:14:08Z | NOW is also an accepted value, but should only be used when a datetime in ISO 8601 format cannot be provided. If using NOW and any reporting delays or outages occur, events sent to the platform will have incorrect EventDate values. |
DispositionCode | STRING (64) | Configurable string value for the event type that will modify the conversion's Reporting State and/or Action State, depending on what's been configured. | Optional | ORDER RETURNED | Disposition codes are used to change the Reporting State of the action (report status partners can see), and/or Action State (i.e., approved, rejected, modified). See Settings → Events Types → … → Disposition Codes in the platform. |
Attribution Data
| Parameter Name | Type | Description | Required | Example | Notes |
|---|---|---|---|---|---|
ClickId |
STRING (64) | An identifier for a referred click that represents the consumer's journey. When a visitor lands on your page via an impact.com tracking link, this value is generated and appended as a query string parameter, which should be captured for conversion reporting. | Required, unless another attribution parameter is provided Required when you or your partners are passing SubIds or a SharedId |
QiiWXOVnrQ3SQHl24jQjyxBGUkmzfJ3i1VHrWM0 |
If available, it's generally always recommended to pass the ClickId value when reporting a conversion. Also note that any generated ClickId value can be associated with multiple clicks — it is not unique to an individual click. |
CustomerId |
STRING (255) | A unique identifier that you (or your systems) generate for the customer driving this conversion. These IDs should be non-identifying (e.g. plain text email addresses are not permitted). | Required, unless another attribution parameter is provided | R523GSSD2342333FSCSA |
This key will be used for insights reporting along with conversion chaining. |
CustomProfileId |
STRING (70) | An id used to uniquely identify a user on your property (regardless of whether they are signed in or not). | Required, unless another attribution parameter is provided | POOWXOVnrQ3SQHl24jQjyxBGUkmzfJ3i1VHrWM0 |
Common examples include anonymous user cookies and IDFVs. |
OrderPromoCode || PromoCode |
STRING (255) | The promotional code associated with this conversion. Note that this only works as an attribution key if this code was assigned as a unique tracking code to a particular partner. In that case, that partner will win credit for this conversion. Otherwise, this will be reported as the promo code used for an order. | Required (if available), unless another attribution parameter is provided | ACMEPARTNER |
To use promo codes as an attribution key, they need to be configured in Ad Settings and validated in the Event Type Settings screen of the platform. When using, OrderPromoCode is preferred over PromoCode. |
UniqueUrl |
STRING (255) | Only used if you have issued unique URLs to partners for tracking purposes. You may send the unique URL here that referred this conversion. Note that these must first be set up in your account before they can be used for attribution. | Required (if available), unless another attribution parameter is provided | https://www.example.com/acmepartner | Learn more about Unique URLs. |
GoogAId |
STRING (36) | Google Advertising Id associated with the mobile device the customer converted on. | Required (if available), unless another attribution parameter is provided | cdda802e-fb9c-47ad-9866-0794d394c912 |
Used for attribution purposes. Typically only available for Android in-app conversions. |
AppleIfa |
STRING (36) | Apple Id for Advertising (IDFA) associated with the mobile device the customer converted on. | Required (if available), unless another attribution parameter is provided | EA7583CD-A667-48BC-B806-42ECB2B48606 |
Used for attribution purposes. Typically only available for iOS in-app conversions. |
AppleIfv |
STRING (36) | Apple ID for Vendors (IDFV) associated with the mobile device the customer converted on. | Required (if available), unless another attribution parameter is provided | AEBE52E7-03EE-455A-B3C4-E57283966239 |
Used for attribution purposes. Typically only available for iOS in-app conversions. |
MediaId || MediaPartnerId |
INTEGER (10) | ID of the partner or media source that will automatically receive credit for the conversion. By passing this value, you force them to win credit for this conversion, bypassing the consumer journey. Only used in specific cases where forced attribution is required — do not submit this value otherwise. | Only used and required for "Forced Attribution" (read description & notes) | 1234567 |
Only pass a value for this parameter if you have no other attribution keys or are forcing attribution to a specific partner or media source intentionally. Do not use this attribution parameter if you or your partners are passing any SubIds or SharedIds. |
IpAddress |
STRING (128) | The customer's public IP address when driving the conversion. The IP address is used to help the system identify fraudulent activity. The IP address will only be used for attribution in the case of installs. | Optional, primarily used for mobile app tracking | 72.194.216.61 || 2001:0db8:85a3:0000:0000:8a2e:0370:7334 |
Supports both IPv4 and IPv6 addresses. |
PhoneNumber |
STRING | Phone number the customer called in call tracking conversions. If call tracking is configured to use unique phone numbers, value is used to match the conversion to the originating call record. | Only used and required for Call Tracking (read description & notes) | 15558675309 |
|
CallerId |
STRING | Unique identifier of the customer in call tracking conversions. Value is used to match the conversion to the originating call record. | Only used and required for Call Tracking (read description & notes) | ||
CountryCode |
STRING (2) | Two-letter country code of the customer's phone country code; use ISO 3166-1 alpha-2. | Only used and required for Call Tracking (read description & notes) | US |
See countrycode.org |
Program Data
| Parameter Name | Type | Description | Required | Example | Notes |
|---|---|---|---|---|---|
| CampaignId | INTEGER (10) | Unique identifier for the campaign (or program) that the conversion is associated with. | Required | 1000 | This value is always required when submitting conversions. |
Order-Level Data
| Parameter Name | Format (Size) | Description | Requirement | Example | Notes |
|---|---|---|---|---|---|
OrderId || Oid | STRING (64) | Your unique identifier for the order associated with this conversion. For example, in a retail sale, this could be the Order ID your eCommerce engine assigns to the customer's order. | Required | T52324111211 | This value is always required when submitting conversions — the preferred parameter name is OrderId, however, Oid is still supported. Note that an OrderId value only needs to be unique to the event type (also known as the action tracker). |
Amount | DECIMAL (8,2) | Total amount for the line item (quantity * price), pre-tax, pre-shipping and post-discount. | Required if passing item-level details, otherwise optional; do not submit if using ItemPrice or ItemSubtotal | 1234.99 | In most cases, submit Quantity & Price in order for impact.com to accurately generate this value. |
CurrencyCode || Currency | STRING (3) | The three character currency code of the purchase made. This is used to calculate exchange rates into funding and payment currencies if needed. Note that if this is not sent, your account's default currency will be used. | Optional | USD | CurrencyCode is the preferred parameter name. |
PaymentType | STRING (32) UTF-8 | This method of payment used for this conversion. | Optional | CREDIT | |
OrderSubtotal | DECIMAL | The subtotal of the order before discounts, taxes, shipping, and any other costs. | Optional | 49.99 | |
OrderDiscount | DECIMAL (12,2) | For sales, this is the discount applied to the order overall. Amount is automatically subtracted from the order total on processing. If item amounts are used, this discount will be subtracted proportionally from each item amount sent in. Note that typically you will want to exclude shipping discounts from this field. | Optional | 3.99 | |
OrderShipping | DECIMAL (14,2) | Primarily used for retail sales. This is the cost of shipping for this conversion. Note that the total sale amount used for payout purposes will not include shipping costs. | Optional | 9.99 | |
OrderTax | DECIMAL (14,2) | Primarily used for retail sales. This is the cost of tax for this conversion. Note that the total sale amount used for payout purposes will not include shipping costs. | Optional | 8.99 | |
OrderMargin | DECIMAL (14,2) | Primarily used for retail sales. This is the total margin made on the conversion (revenue less costs). Typically this is provided through the product catalog. | Optional | 12.34 | |
GiftPurchase | BOOLEAN | If you're tracking gift purchases, you can submit true to mark the order in the conversion as a gift purchase. Submit false if the order isn't a gift purchase. | Optional | true || false | |
LocationId | STRING (64) | Primarily used for accommodations, this is the unique identifier for the location specified in this conversion. | Optional | SBHOTEL | |
LocationName | STRING (64) | Primarily used for accommodations, this is the name for the location specified in this conversion. | Optional | Fess Parker | |
LocationType | STRING (64) UTF-8 | Primarily used for accommodations, this is the category for the location specified in this conversion. | Optional | Hotel |
Item-Level Data
| Parameter Name | Format (Size) | Description | Requirement | Example | Notes |
|---|---|---|---|---|---|
Sku | STRING (255) | Unique stock-keeping unit (SKU) value of the product referenced at the item level. | Required if passing item-level details, otherwise optional | 79369127 | |
Category | STRING (255) | Category for the product referenced at the item level. Can also be automatically pulled if a product catalog has been uploaded. | Required if passing item-level details, otherwise optional | Metalworking | |
Quantity | INTEGER | Quantity of the item that was purchased in the order, expressed as a whole number. | Required if passing item-level details, otherwise optional | 1 | |
ItemPrice | DECIMAL | Individual unit price for each product in this line item. This is multiplied by the ItemQuantity (and discounts are subtracted) to derive the ItemSubTotal. Note that this field should not be sent if ItemSubtotal is passed. | Required if passing item-level details, otherwise optional; do not submit if using ItemSubTotal | 499.99 | |
ItemSubtotal | DECIMAL (14,2) | Total price for this line item (all products purchased of this type). The final value will be determined by subtracting the corresponding discounts from this value. This field should not be sent if ItemPrice is passed. | Required if passing item-level details, otherwise optional; do not submit if using ItemPrice | 299.99 | |
Amount | DECIMAL (8,2) | Total amount for the line item (quantity * price), pre-tax, pre-shipping and post-discount. | Required if passing item-level details, otherwise optional; do not submit if using ItemPrice or ItemSubtotal | 1234.99 | In most cases, submit Quantity & Price in order for impact.com to accurately generate this value. |
ItemSubCategory | STRING (255) | If applicable, the subcategory for the product referenced at the item level. Can also be automatically pulled if a product catalog has been uploaded. | Optional | Metalsmithing | |
Name | STRING (255) | The name for the product referenced. Can also be automatically appended through uploading a product catalog. | Optional | Iron Anvil | |
ItemMpn | STRING (64) | Manufacturer part number (MPN) for the product referenced. Can also be automatically pulled if a product catalog has been uploaded. | Optional | 123456789 | |
ItemBrand | STRING (64) | Brand name for the product referenced. Can also be automatically pulled if a product catalog has been uploaded. | Optional | Acme Corp | |
ItemDiscount | DECIMAL (12,2) | Discount applied to each item purchased of this type (not to the entire line item). | Optional | 2.99 | |
ItemPromoCode | STRING (255) | Promotional code applied to the item for the order. Note that this parameter does not work with unique tracking codes setup for particular partners. | Optional | ITEMDISCOUNT10 | |
ItemTotalDiscount | DECIMAL (12,2) | Discount applied to this line item (not just for each product of this type). Note that this amount is automatically subtracted from the ItemSubTotal to determine the final sale amount for payout and reporting purposes. | Optional | 49.99 | |
ItemDeliveryType | STRING (64) | Type of delivery method specified for this item. | Optional | EXPRESS |
Chained Actions
| Parameter Name | Format (Size) | Description | Requirement | Example | Notes |
|---|---|---|---|---|---|
CustomerId | STRING (255) | A unique identifier that you (or your systems) generate for the customer driving this conversion. These IDs should be non-identifying (e.g. plain text email addresses are not permitted). | Required | R523GSSD2342333FSCSA | This key will be used for insights reporting along with conversion chaining. In the case of chained actions, for the Child Tracker, you should pass the same customer ID as that of the Parent event or else it won't chain the actions. |
Call Conversion Data
| Parameter name | Format | Requirement | Description |
|---|---|---|---|
CampaignId | INTEGER | Required | Unique identifier for the campaign (or program) that the call conversion is associated with. |
MediaId | INTEGER | Required | Unique identifier for the partner or media source. |
EventDate | DATETIME (ISO 8601) | Required | ISO 8601 format of the date and time when the call conversion event occurred. |
ActionTrackerId | INTEGER | Required | Unique identifier for the action tracker (i.e., event type) that's tracking the phone call. |
CallProvider | STRING | Required | The vendor or client who is sending the call event data |
CallSessionId | STRING | Required | A unique session ID that the vendor or client uses to identify the call. |
CallerId | STRING | Required | The phone number of the originating call, used to match the final conversion. |
CalledPhoneNumber | STRING | Required | The destination phone number or the phone number that received the call. |
CallDuration | STRING | Required | Total duration (in seconds) of the call. |
TalkDuration | STRING | Required | Actual talk duration (in seconds) of the call. |
AdId | INTEGER | Optional | Unique identifier for the ad associated with the call conversion. |
CallStatus | STRING | Optional | This value indicates the final outcome of the call. If the field is not present in request, we make it ANSWER by default. Valid values are: UNKNOWN_CALLERID, FAILURE, CONGESTION, INCOMPLETE, CANCEL, IVR_DROPOFF, NO_TRANSFER_ATTEMPT, ANSWER |
CallerPhoneNumberCountry | STRING | Optional | Two-digit country code for the originating phone number (ISO 3166 alpha-2). When NULL, defaults to US. |
CalledPhoneNumberCountry | STRING | Optional | Two-digit country code for the called phone number (ISO 3166 alpha-2). When NULL, defaults to US. |
SubId1 | STRING | Optional | This value is specific and only available to the media partner. This is the placeholder where Media Partner can add data points that they want impact.com to report back to them. |
SubId2 | STRING | Optional | This value is specific and only available to the media partner. This is the placeholder where Media Partner can add data points that they want impact.com to report back to them. |
SubId3 | STRING | Optional | This value is specific and only available to the media partner. This is the placeholder where Media Partner can add data points that they want impact.com to report back to them. |
ClickId | STRING | Optional | Unique case-sensitive identifier generated by impact.com of a referring click, used to construct a consumer journey. |
Country | STRING | Optional | Country of the CallerId - as identified by the call tracking vendor. |
City | STRING | Optional | City of the CallerId - as identified by the call tracking vendor. |
Region | STRING | Optional | Region of the CallerId - as identified by the call tracking vendor. |
Zip | INTEGER | Optional | Zip of the CallerId - As identified by the call tracking vendor. |
RepeatCaller | STRING | Optional | Repeat vs New call to indicate whether the caller was recorded as a repeat caller by the call tracking vendor. |
PhoneType | STRING | Optional | The type of phone (i.e., landline, mobile). |
CallRecording | STRING | Optional | Unique URL of the call recording. |
IvrDuration | STRING | Optional | Duration in seconds that the call spent in the IVR tree. |
Keypresses | STRING | Optional | List of unique keynames that were pressed during the call. |
Key1 | STRING | Optional | Name of the first key that was pressed. |
Key2 | STRING | Optional | Name of the second key that was pressed. |
Key3 | STRING | Optional | Name of the third key that was pressed. |
Key4 | STRING | Optional | Name of the fourth key that was pressed. |
TrafficSource | STRING | Optional | Source of the transaction (referring media source). |
OptInSms | STRING | Optional | Whether the caller opted in to receive an SMS promotion. |
UserAgent | STRING | Optional | The user agent of the conversion generator. |
DispositionName | STRING | Optional | The Conversion Event Name. |
SaleAmount | CURRENCY | Optional | If Sale Conversion, Sale Amount |
ReferenceId | STRING | Optional | Customer Disposition Code for reference. |
CustomConversionEvent1Name | STRING | Optional | Custom name for reporting on conversion events |
CustomConversionEvent2Name | STRING | Optional | Custom name for reporting on conversion events |
CustomConversionEvent3Name | STRING | Optional | Custom name for reporting on conversion events |
CustomConversionEvent1Value | STRING | Optional | Custom value for reporting on conversion events |
CustomConversionEvent2Value | STRING | Optional | Custom value for reporting on conversion events |
CustomConversionEvent3Value | STRING | Optional | Custom value for reporting on conversion events |
VendorEventId | STRING | Optional | Will be unique for call event and unique for the conversion event. |
PromoNumberDescription | STRING | Optional | Describes the called phone number |
CustomCallEvent1Name | STRING | Optional | Custom name for reporting on call events |
CustomCallEvent2Name | STRING | Optional | Custom name for reporting on call events |
CustomCallEvent3Name | STRING | Optional | Custom name for reporting on call events |
CustomCallEvent1Value | STRING | Optional | Custom value for reporting on call events |
CustomCallEvent2Value | STRING | Optional | Custom value for reporting on call events |
CustomCallEvent3Value | STRING | Optional | Custom value for reporting on call events |
Additional Parameters
| Parameter Name | Type | Description | Required/Optional | Example |
|---|---|---|---|---|
Money1-3 | DECIMAL (18,3) | General numeral fields for any financial data. Appear in reports. | Optional | 12345.678 |
Numeric1-3 | DECIMAL (18,3) | General numeral fields for any numeric data. Appear in reports. | Optional | 987654.321 |
Date1-3 | STRING (30) | General date fields for any date/datetime. Appear in reports. | Optional | 2038-01-19 |
SubId1-3 | STRING (255) | General fields used for event-level reporting purposes. | Optional | |
Text1-3 | STRING (64) | General text fields for any text data. Appear in reports. | Optional | |
UserAgent | STRING (255) | Describes the user agent associated with the conversion. | Optional | Mozilla/5.0 |
CustomerStatus | STRING (30) | Customer status at the time of conversion. | Optional | Active |
CustomerCity | STRING (255) | Customer's city during conversion. | Optional | Amsterdam |
CustomerCountry | STRING (255) | Customer's country during conversion. | Optional | Netherlands |
CustomerPostCode | STRING (255) | Customer's postal code during conversion. | Optional | 1011 AC |
CustomerRegion | STRING (255) | Customer's region during conversion. | Optional | North Holland |
DeviceModel | STRING (255) | Device model used during conversion. | Optional | iPhone 13 Pro |
DeviceMfr | STRING (255) | Device manufacturer used during conversion. | Optional | Apple |
AppPackage | STRING (255) | App package name used during conversion. | Optional | com.example.app |
AppInstallRef | STRING (255) | App installation reference during conversion. | Optional | Ref12345 |
AppVer | STRING (255) | App version during conversion. | Optional | 1.0.0 |
PropertyId | STRING (255) | Property ID associated with the conversion. | Optional | Property123 |
IrAppId | STRING (255) | IR App ID associated with the conversion. | Optional | IRApp123 |
Referral Landing Page | STRING (255) | URL of the landing page where the referral originated. | Optional | https://example.com/referral |
Referral Subaccount ID | STRING (255) | ID of the referral subaccount. | Optional | SubID123 |
Referral Subaccount Name | STRING (255) | Name of the referral subaccount. | Optional | SubName |
Referral Ad Program | STRING (255) | Ad program associated with the referral. | Optional | AdProgram123 |
Referral Ad Type | STRING (255) | Ad type associated with the referral. | Optional | Display |
Referral Ad Group | STRING (255) | Ad group associated with the referral. | Optional | AdGroup123 |
Referral Traffic Type | STRING (255) | Type of traffic associated with the referral. | Optional | Organic |
Referral URL | STRING (255) | URL of the referral source. | Optional | https://example.com |
Path Media Count | INTEGER | Number of media elements in the conversion path. | Optional | 5 |
Path Channel Count | INTEGER | Number of channels in the conversion path. | Optional | 3 |
Path Steps | INTEGER | Number of steps in the conversion path. | Optional | 10 |
Site Category | STRING (255) | Category of the site where the conversion occurred. | Optional | E-commerce |
Site Version | STRING (255) | Version of the site where the conversion occurred. | Optional | v1.0 |
Hear About Us | STRING (255) | How the customer heard about the business. | Optional | Social Media |
TrackingConsent | BOOLEAN | Indicates whether the user has provided consent to be tracked. | Optional | true |
Note | STRING (255) | General field used for event-level reporting purposes. Requires MediaPartnerId. | Optional | Hello, World! |
Updated 20 days ago
