API Reference

Create a conversion

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

  1. Event type ID or code
  2. Attribution key
  3. Event date
  4. Program or campaign ID
  5. 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.

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 Events Types → Actions → View/Edit → "Codes" in the platform.

Attribution key

A minimum 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. Alternatively, submit NOW for impact.com to use the date & time when the conversion is submitted.

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 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 if ItemSubtotal 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).

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.

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.

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

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

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

Money1 optional

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

Money2 optional

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

Money3 optional

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

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 'CustomerEmail=7076656fee27c02fd8a1cbd17828c9cf28f2c250'

Example response

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

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