Is this submission method right for you?

If you want to...	Use this method...
Submit a manual, one-time file with no coding	Email batch processing or upload file via FTP
Set up automated conversion reporting	Conversions / Actions API or pull file via FTP

Conversions accepts a POST verb to submit a conversion event, which at a minimum requires:

Event type ID or code
Attribution key
Event date
Program or campaign ID
Order ID

These are the minimum requirements to submit a conversion. Generally, we recommend submitting as much data as possible for all conversions to accurately connect the conversion to a click path, attribute it to a particular partner (or source), and calculate an associated payout, if applicable. Once a conversion has been attributed to a source, it becomes a pending action.

Warning: We strongly recommend not submitting actions older than 88 days, as impact.com does not currently process FTP-submitted conversions with event dates beyond that window. Conversions up to 398 days old can be processed, but only if attribution is done using MediaId.

Parameters

Event ID or code

`EventTypeId` required, unless code is provided

Unique identifier for the event type (or action tracker) that tracked this conversion. Functionally identical to ActionTrackerId.

`EventTypeCode` required, unless ID is provided

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.

Attribution key

Aminimum of 1 parameter is required, but we recommend you submit as many as possible for more accurate attribution.

`ClickId` required, unless another attribution parameter is provided

Unique case-sensitive identifier generated by impact.com of a referring click, used to construct a click path. This value is usually passed onto the landing page after a click redirect occurs under the query string parameter name ClickId. Configured on the Gateway Settings screen.

`CustomerId` required, unless another attribution parameter is provided

Unique identifier that you generate for the customer that converted. These values must be non-identifying (e.g., plain text email addresses are not permitted). Used for Optimize reporting and conversion chaining.

`CustomProfileId` required, unless another attribution parameter is provided

Unique identifier used to identify a visitor on your website (regardless of whether they're signed in). Common examples include anonymous user cookies and IDFVs.

`OrderPromoCode` required, unless another is provided

Promo code used for the order tracked by the conversion. 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.

`UniqueUrl` required, unless another attribution parameter is provided

Unique URL for a partner or source that referred the conversion. Only used if you've configured and assigned Unique Domains to your partners.

`GoogAId` required, unless another attribution parameter is provided

Google Advertising ID associated with the mobile device the customer converted on. Used for attribution purposes. Typically only available for Android in-app conversions.

`AppleIfa` required, unless another attribution parameter is provided

Apple ID for Advertising (IDFA) associated with the mobile device the customer converted on. Used for attribution purposes. Typically only available for iOS in-app conversions.

`AppleIfv` required, unless another attribution parameter is provided

Apple ID for Vendors (IDFV) associated with the mobile device the customer converted on. Used for attribution purposes. Typically only available for iOS in-app conversions.

`MediaId` required, unless another attribution parameter is provided

Unique identifier of the partner or source to which you want to force attribution. Only used if you cannot pass any other attribution key as this bypasses the click path mapping process. By passing this value, you force them to win credit for this conversion.

`PhoneNumber` required only for call tracking

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.

`CallerId` required, unless another attribution parameter is provided

Unique identifier of the customer in call tracking conversions. Value is used to match the conversion to the originating call record.

`IpAddress` optional

IP address of the customer. 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.

Event date

`EventDate` required

Time and date when the conversion event actually took place, in ISO 8601 format.

Program/Campaign

`CampaignId` required

Unique identifier for the campaign (or program) that the conversion is associated with. This value is also known as the ProgramId.

Order and items

`OrderId` required

Your unique identifier for the order associated with this conversion. For example, in a retail sale, this could be the Order ID you've assigned the customer for their purchase. Note that an OrderId value only needs to be unique to the event type (also known as the action tracker).

`ItemSku[i]` required if passing item-level details, otherwise optional

Unique stock-keeping unit (SKU) value of the product referenced at the item level.

`ItemCategory[i]` required if passing item-level details, otherwise optional

Category for the product referenced at the item level. Can also be automatically pulled if a product catalog has been uploaded.

`ItemSubTotal[i]` required if passing item-level details, otherwise optional

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. Note that this field should not be sent if ItemPrice is passed.

`ItemPrice[i]` required if `ItemSubtotal` can't be reported, otherwise optional

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 ifItemSubtotal is passed.

`ItemQuantity[i]` required if passing item-level details, otherwise optional

Quantity of the item that was purchased in the order, expressed as a whole number.

View more parameters

`ItemPromoCode[i]` optional

Promotional code applied to the item for the order. Note that this parameter does not work with unique tracking codes setup for particular partners.

`ItemTotalDiscount[i]` optional

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.

`ItemSubCategory[i]` optional

If applicable, the subcategory for the product referenced at the item level. Can also be automatically pulled if a product catalog has been uploaded.

`ItemName[i]` optional

The name for the product referenced. Can also be automatically appended through uploading a product catalog.

`ItemMpn[i]` optional

Manufacturer part number (MPN) for the product referenced. Can also be automatically pulled if a product catalog has been uploaded.

`ItemBrand[i]` optional

Brand name for the product referenced. Can also be automatically pulled if a product catalog has been uploaded.

`ItemDiscount[i]` optional

Discount applied to each item purchased of this type (not to the entire line item).

`ItemDiscountRate[i]` optional

The discount rate (%) applied to each item purchased.

`ItemDeliveryType[i]` optional

Type of delivery method specified for this item (e.g. INSTORE).

`PaymentType` optional

This method of payment used for this conversion (e.g. Credit).

`OrderSubTotalPostDiscount` optional

Used when reporting conversions at the order-level (i.e., no item reporting). The subtotal of the order after discounts, taxes, shipping, and any other costs. If you're submitting item-level data, this value should not be submitted.

`OrderDiscount` optional

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.

`OrderDiscountRate` optional

The discount rate (%) applied to the order.

`OrderShipping` optional

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.

`OrderTax` optional

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.

`OrderMargin` optional

Primarily used for retail sales. This is the total margin made on the conversion (revenue less costs). Typically this is provided either at an item level through the ItemMargin field or through the product catalog.

`GiftPurchase` optional

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.

`LocationId` optional

Primarily used for accommodations, this is the unique identifier for the location specified in this conversion.

`LocationName` optional

Primarily used for accommodations, this is the name for the location specified in this conversion.

`LocationType` optional

Primarily used for accommodations, this is the category for the location specified in this conversion.

`PropertyId` optional

For mobile app conversions, this value is the "System App ID" of your app in impact.com. Found in Settings → Mobile Apps .

`TrackingConsent` optional

Indicates whether the user has provided consent to be tracked at the moment of the request. Derived from your consent management platform or through frameworks like Apple’s ATT (App Tracking Transparency) available on iOS.

`CustomerStatus` optional

Status of the customer, such as NEW or EXISTING. Before being passed, values must be configured in the Customer Status Mapping section when editing an event type, found in the event type settings section of the platform.

`CustomerCity` optional

City of the customer, such as Santa Barbara.

`CustomerPostCode` optional

Postal (or "ZIP") code of the customer, such as 93101.

`CustomerCountry` optional

Country of the customer, such as USA.

`CustomerRegion` optional

Region of the customer, such as AMER.

`UserAgent` optional

User agent of the customer, used to provide device reporting.

`DispositionCode` optional

If you have a custom disposition code configured in event type settings, you can submit that value as a default disposition for the action that results from this conversion.

`DeviceMfr` optional

Mobile device's manufacturer. impact.com expects this to be passed in a specific format—refer to the code below that needs to be included in your mobile app to be passed to impact.com.

Android:

String manufacturer = android.os.Build.MANUFACTURER;

iOS:

NSString *manufacturer = @"Apple";

`DeviceModel` optional

Mobile device's model. impact.com expects this to be passed in a specific format—refer to the code below that needs to be included in your mobile app to be passed to impact.com.

Android:

String model = android.os.Build.MODEL;

iOS:

NSSString *model = [NSString stringWithCString:systemInfo.machineencoding:NSUTF8StringEncoding];

`AppPackage` optional

Package name for the mobile app the user installed. Only for mobile conversions. Note that this is also picked up through the PropertyId field.

`AppInstallRef` optional

Only for Android conversions. Install referrer passed from the Google Play Store when the app is installed. Usually, the value passed from impact.com tracking links will be ClickId={clickidvalue}.

`AppVer` optional

Version of the mobile app. Only for mobile conversions.

`Amount` integer

This is the total order sale amount made on an item or order level of the conversion.

Additional parameters

View additional parameters

`Note` optional

General field used to pass information for event-level reporting purposes.

`Date1-10` optional

Field that accepts a date string, for example “2022-03-28”, or a datetime string , for example “2022-05-21T07:25:00Z”. Appears in your reports.

E.g., Date1, Date3, Date5

`ItemDate[i]_1-10`

General date field that accepts a date or datetime for a SKU.

E.g., ItemDate[i]_1, ItemDate[i]_2, ItemDate[i]_3

`Text1-10` optional

General text field that accepts strings of any text data you want to send. Appears in your reports.

E.g., Text2, Text3, Text7

`ItemText[i]_1-10` optional

General text field that accepts strings of any text data for a SKU.

E.g., ItemText[i]_1, ItemText[i]_2, ItemText[i]_3

`Numeric1-10` optional

General numeral field that accepts strings of any numeric data you want to send. Appears in your reports.

E.g., Numeric1, Numeric4, Numeric8

`ItemNumeric[i]_1-10` optional

General numeral field that accepts strings of any numeric data for a SKU.

E.g., ItemNumeric[i]_1, ItemNumeric[i]_2, ItemNumeric[i]_3

`Money1-3` optional

General numeral field that accepts strings of any money or financial data you want to send. Appears in your reports.

`ItemMoney[i]_1-3` optional

General numeral field that accepts strings of any money or financial data for a SKU.

E.g., ItemMoney[i]_1, ItemMoney[i]_2, ItemMoney[i]_3

Returns

Returns the status of the reported conversion and the URI of the API submission to check on the status of the conversion. A newly-created conversion always starts out as QUEUED. Returns an error when invalid parameters are provided.

Example request

curl "https://api.impact.com/Advertisers/<AccoundSID>/Conversions" \
  -X POST \
  -u "<AccountSID>:<AuthToken>" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \ 
  -d 'EventTypeId=12345' \
  -d 'ClickId=QiiWXOVnrQ3SQHl24jQjyxBGUkmzfJ3i1VHrWM0' \
  -d 'CustomerId=BCZ2WVSH674563PDPYOTM3AXDQ' \
  -d 'OrderPromoCode=10OFF-ROCKET' \
  -d 'EventDate=2023-12-01T23:55:24-08:00' \
  -d 'CampaignId=1000' \
  -d 'OrderId=9217374917471' \
  -d 'OrderDiscount=5' \
  -d 'ItemSku1=12345' \
  -d 'ItemName1=Anvil' \
  -d 'ItemCategory1=Blacksmithing' \
  -d 'ItemQuantity1=1' \
  -d 'ItemPrice1=10' \
  -d 'ItemSku2=78909' \
  -d 'ItemName2=Tennis Balls' \
  -d 'ItemCategory2=Sports' \
  -d 'ItemQuantity2=6' \
  -d 'ItemPrice2=3.14' \
  -d 'CustomerStatus=NEW' \
  -d 'CustomerPostCode=93101' \
  -d 'CurrencyCode=USD' \
  -d 'IpAddress=1.1.1.1' \
  -d 'Amount=123' \
  -d 'CustomerEmail=7076656fee27c02fd8a1cbd17828c9cf28f2c250'

Example response

{
  "Status": "QUEUED",
  "QueuedUri": "/Advertisers/<AccountSID>/APISubmissions/<SubmissionID>"
}

{
  "Status": "ERROR",
  "errors": [
    {
      "field": "Margin",
      "level": "ERROR",
      "message": "Invalid numeric format (fifty)"
    }
  ]
}