Onboard Online/Offline Conversion Data

Onboard your online and offline conversion data to activate measurement, reporting and optimization use cases within Viant DSP

Please be aware that the payload is ARRAY of JSON objects. One JSON object can contain array of values.
Conversion API supports up to 10MB of payload size.
Conversion API supports gzipped payload. Specify Content-Encoding: gzip in the HTTP header and attach gzipped payload.
Given salesData should belong to the accountId of the API user.
When data validation fails for a single record, the API will return the number of bad records and the actual bad record data to the user to ensure data quality. We check up to 1000 bad records.

Supported Fileds

advertiser.advertiserId (Required) Viant Advertiser ID
salesData (Required) Array of sales transaction records
- salesData[].transactionId (Required) Unique identifier for the transaction
- salesData[].conversionEventType (Required) Type of conversion event:
  - PageView
  - LandingPage
  - ItemView
  - AddToCart
  - InitiateCheckout
  - AddPaymentInfo
  - Purchase
  - Lead
  - If you have any non-standard event you cannot map to the above list, you can pass a custom event name instead of above standard list as part of same salesData[].conversionEventType field.
- salesData[].conversionTimestamp (Required) ISO 8601 timestamp of the conversion (e.g. 2025-07-28T15:32:00Z)
- salesData[].identifiers (Required; ≥ 1 entry) Array of customer identifiers (each with type and value), e.g.:
  - email_sha256
  - address_sha256
  - ip
  - mobile_id
  - cookie
- salesData[].amount (Optional) Total conversion or transaction amount
- salesData[].storeId (Optional) Unique identifier for the store or location
- salesData[].currency (Optional) Currency code (e.g. USD, EUR)
- salesData[].purchasedItems (Optional) Array of items purchased
  - salesData[].purchasedItems[].itemId (Required if items present) Unique identifier for the product/SKU
  - salesData[].purchasedItems[].productName (Optional) Human-readable name of the product
  - salesData[].purchasedItems[].productCategory (Optional) Category of the product
  - salesData[].purchasedItems[].price (Required if items present) Price per unit
  - salesData[].purchasedItems[].quantity (Required if items present) Quantity purchased
- salesData[].channel (Optional) Sales channel (e.g. Online, In-store)
- salesData[].conversionLocation (Optional) Location details for the conversion:
  - country (country code)
  - state (state or region)
  - city (city name)
- salesData[].custom (Optional) Up to 10 custom key--value metadata pairs for any additional context (e.g. campaign IDs, user segments).

Endpoint: PUT /v1/conversions

Request Body:

[
{
  "accountId": 2222,
  "advertisers": [55812],
  "salesData": {
    "transactionId": "001_abc123",
    "conversionEventType": "Purchase",
    "conversionTimestamp": "2025-07-28T15:32:00Z",
    "identifiers": [
      {
        "type": "hashed_email",
        "value": "a0173a5248b1233ffea53f36b24479b90ae5b3202d8043c3b7461e7262f8698e"
      }
    ],
    "amount": 79.98,
    "storeId": "store_9876",
    "currency": "USD",
    "purchasedItems": [
      {
        "itemId": "SKU12345",
        "productName": "Bluetooth Headphones",
        "productCategory": "Electronics",
        "price": 39.99,
        "quantity": 2
      }
    ],
    "channel": "Online",
    "conversionLocation": {
      "country": "US",
      "state": "CA",
      "city": "Los Angeles"
    },
    "custom": {
      "campaignId": "camp_2025_summer",
      "membershipTier": "gold"
    }
  }
},
{
  "accountId": 2222,
  "advertisers": [55812],
  "salesData": {
    "transactionId": "002_xyz789",
    "conversionEventType": "AddToCart",
    "conversionTimestamp": "2025-07-27T10:05:00Z",
    "identifiers": [
      {
        "type": "AdvertisingIDs",
        "value": "adid_89d0f8c7-5cde-4a8a-9172-24a9c18e0d0f"
      },
      {
        "type": "IP",
        "value": "192.168.1.25"
      }
    ],
    "amount": 25.00,
    "storeId": "store_6543",
    "currency": "USD",
    "purchasedItems": [
      {
        "itemId": "SKU54321",
        "productName": "Fitness Tracker",
        "productCategory": "Wearables",
        "price": 25.00,
        "quantity": 1
      }
    ],
    "channel": "Online",
    "conversionLocation": {
      "country": "US",
      "state": "NY",
      "city": "Brooklyn"
    },
    "custom": {
      "promoCode": "JULY25",
      "testGroup": "B"
    }
  }
},
{
  "accountId": 2222,
  "advertisers": [55812],
  "salesData": {
    "transactionId": "lmn456",
    "conversionEventType": "Lead",
    "conversionTimestamp": "2025-07-26T08:45:00Z",
    "identifiers": [
      {
        "type": "hashed_physical_address",
        "value": "c1a1f017f1135e4c4c53754163e5ae58f289cd8eb7d3bba07e3f4862609b69a1"
      }
    ],
    "amount": 0.00,
    "currency": "USD",
    "purchasedItems": [],
    "channel": "In-store",
    "conversionLocation": {
      "country": "US",
      "state": "TX",
      "city": "Austin"
    },
    "custom": {
      "leadType": "newsletter",
      "source": "store-kiosk"
    }
  }
}

]

Response (Success):

HTTP Response Code: 200
{
  "message" : "Conversion data queued for processing.",
  "bad_records" : 0,
  "bad_records_details" : ""
}

Failure Examples:

HTTP Response Code: 400
{
  "message" : "found 10 bad records",
  "bad_records" : 10,
  "bad_records_details" : "actual bad record data will be returned back here"
}

HTTP Response Code: 400
{
"error" : "error message"
}