# 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](/brand-api-reference/reference/action-and-conversion-field-references/action-modification-and-reversal-field-references.md) to update or reverse an existing action.
The two most common use cases are
* Missed online conversions
* Uploading conversions again with the correct data
| If you want to... | Use this method... |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Submit a manual, one-time file with no coding | [Email](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/submit-and-modify-conversion-data/submit-conversion-data/batch-submit-conversion-data#email-file-to-system-smtp-server) batch processing or [upload file via FTP](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/submit-and-modify-conversion-data/submit-conversion-data/batch-submit-conversion-data#upload-file-to-system-ftp-server) |
| Set up automated conversion reporting | [Conversions](https://integrations.impact.com/impact-brand/reference/submit-a-conversion) API, [push file via FTP](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/submit-and-modify-conversion-data/submit-conversion-data/batch-submit-conversion-data#upload-file-to-system-ftp-server), or [pull file via FTP](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/submit-and-modify-conversion-data/submit-conversion-data/batch-submit-conversion-data#pull-file-from-your-own-ftp-server) |
## 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.
| Field | Description | Required? | Format (Size) | Example | Notes |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ActionTrackerId` | Unique identifier for the event type (or action tracker) that tracked this conversion. Normal web: **Settings →** [**Event Types**](https://app.impact.com/secure/advertiser/tracking-settings/actiontracker/view-actiontracker-flow.ihtml)**.** 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.
{% hint style="success" %}
**Note:** At least one attribution key is required. See the *Required* column below for more details.
{% endhint %}
| Parameter Name | Type | Description | Required | Example |
| ------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `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` |
{% hint style="success" %}
**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.
{% endhint %}
### 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.
| 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. |
## 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.
| 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 fields
{% hint style="warning" %}
**Warning:** Native phone number tracking has been deprecated. For alternative solutions, use a [supported 3rd-party provider](https://integrations.impact.com/impact-brand/reference/call-data-overview) like Invoca.
{% endhint %}
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.
| 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 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.
| Parameter Name | Type | Description | Required/Optional | Example |
| ------------------ | -------------- | -------------------------------------------------------------------------------- | ----------------- | ------------- |
| `Money1-3` | DECIMAL (18,3) | General decimal fields for any financial data. Appears in reports. | Optional | 12345.678 |
| `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 | |
| `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 |
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://integrations.impact.com/brand-api-reference/reference/action-and-conversion-field-references/conversion-submission-field-references.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.