Conversion Submission Field References
Use this reference to identify the correct fields when submitting new conversions in bulk. It covers standard submission scenarios as well as chained actions and other advanced use cases, and is suited for online sales, offline sales, CRM imports, and scheduled conversion loads.
Use Action Modification & Reversal Field References to update or reverse an existing action.
The two most common use cases are
Missed online conversions
Uploading conversions again with the correct data
Submit a manual, one-time file with no coding
Email batch processing or upload file via FTP
Set up automated conversion reporting
Conversions API, push file via FTP, or pull file via FTP
Conversion details reference
The references below let you submit new conversions.
Event type fields
Use these fields to define what type of conversion occurred, e.g., online sale / app install. You should submit Event Type data when initially sending a conversion.
ActionTrackerId
Unique identifier for the event type (or action tracker) that tracked this conversion. Normal web: Settings → Event Types. Mobile App: Settings → Mobile App
Required, unless EventTypeCode is provided
INTEGER (10)
1000
Also known as EventTrackerID
EventTypeCode
Configurable string value for the event type that identifies it when submitting conversions. To view or configure this value, see Settings → Event Types → Actions → View/Edit → "Codes" in the platform.
Required, unless ActionTrackerId is provided
STRING (128)
SALE
EventCode
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
STRING (128)
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
The date and time when the conversion event occurred; use ISO 8601 format.
Required
DATETIME (ISO 8601)
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. NOW records the time the event is processed, not when it occurred. If delays or outages happen, this may result in incorrect EventDate values.
DispositionCode
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
STRING (64)
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 → Event Types → … → Disposition Codes in the platform.
Attribution fields
Use these fields to determine which partner receives credit for a conversion and how the consumer journey is evaluated. You can submit attribution data when reporting new conversions.
Note: At least one attribution key is required. See the Required column below for more details.
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
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
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
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
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
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
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
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 and notes)
1234567
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
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 or 2001:0db8:85a3:0000:0000:8a2e:0370:7334
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 and 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 and 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 and notes)
US
Note: 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.
Program fields
Use this field to associate a conversion with a specific impact.com program (formerly known as a campaign). Every conversion must belong to a program.
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.
Advanced scenarios reference
These references are relevant only to specific tracking configurations, e.g., parent-child events or phone call events.
Chained action fields
Chained actions allow impact.com to associate follow-up events with an original conversion, e.g., a ticket sale with an initial reservation. Use these fields to link together multiple related conversion events.
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 fields
Warning: Native phone number tracking has been deprecated. For alternative solutions, use a supported 3rd-party provider like Invoca.
Use these fields when reporting conversions that originate from tracked phone calls. This data is only required for call tracking integrations and should not be sent for web or app conversions.
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 key names 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
Optional reporting fields reference
Use these fields to add extra context to a conversion for reporting or troubleshooting. These fields are all optional and enhance reporting, segmentation, and analytics. If you don’t need this data in your reports, you can leave these fields out.
Money1-3
DECIMAL (18,3)
General decimal fields for any financial data. Appears in reports.
Optional
12345.67
Numeric1-3
DECIMAL (18,3)
General decimal fields for any numeric data. Appears in reports.
Optional
987654.321
Date1-3
STRING (30)
General date fields for any date/datetime. Appears in reports.
Optional
2038-01-19
SubId1-3
STRING (255)
General fields used for event-level reporting purposes.
Optional
Text1-50
STRING (64)
General text fields for adding any text data. Modifiable and appears in reports.
Optional
ItemText1-10
STRING (64)
General text fields for adding item text data.
Optional
ItemNumeric1-10
DECIMAL (18,3)
General decimal fields for any numeric data.
Optional
10.00
ItemDate1-10
STRING (30)
General item date fields.
Optional
2028-01-19
ItemMoney1-3
DECIMAL (18,3)
Decimal fields for item financial data.
Optional
12345.67
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
New
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
Last updated