Skip to main content
POST /api/v2/buyer/advertisers/{advertiserId}/log-event Sends up to 10,000 outcome or marketing events in a single call, scoped to an event_source_id previously registered via Sync event sources. Events are deduplicated by event_id + event_type + event_source_id, so retries are safe.
Never send raw PII. Use only pre-hashed identifiers (SHA-256, lowercase, 64-char hex) or pre-resolved identity tokens. See the Conversion API guide for hashing rules.

​
Request

curl -X POST https://api.interchange.io/api/v2/buyer/advertisers/12345/log-event \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_source_id": "website_pixel",
    "events": [
      {
        "event_id": "order_12345",
        "event_type": "purchase",
        "event_time": "2026-01-15T14:30:00Z",
        "action_source": "website",
        "event_source_url": "https://shop.example.com/checkout/complete",
        "user_match": {
          "click_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
          "click_id_type": "sc3clid"
        },
        "custom_data": { "value": 99.99, "currency": "USD", "order_id": "order_12345" }
      }
    ]
  }'

​
Parameters

FieldTypeRequiredNotes
advertiserIdstringYesPath. Owning advertiser
event_source_idstringYesMust match a source registered on the advertiser
eventsobject[]Yes1–10,000 events
events[].event_idstringYesDedup key, unique within event_type + event_source_id
events[].event_typeenumYesADCP event type, such as purchase, lead, add_to_cart, refund, subscribe, start_trial, app_install, or custom
events[].event_timestringYesISO 8601 timestamp when the event occurred
events[].custom_event_namestringConditionalRequired when event_type is custom
events[].action_sourceenumNowebsite, app, in_store, phone_call, system_generated, other
events[].event_source_urlstringConditionalRecommended when action_source is website
events[].user_matchobjectNoIdentity fields: hashed_email, hashed_phone, click_id + click_id_type, uids, client_ip, client_user_agent
events[].custom_dataobjectNovalue, currency, order_id, content_ids, num_items, contents
test_event_codestringNoMarks the request as test traffic — validated but excluded from production data

​
Response

{
  "events_received": 1,
  "events_processed": 1,
  "partial_failures": [],
  "warnings": [],
  "match_quality": 0.87
}
A 200 with partial_failures is normal — bad events are rejected individually while the rest succeed. Each failure carries event_id, code, and message. Treat a failure as something to fix at source, not a transient error.

​
Errors

  • 400 VALIDATION_ERROR — empty events, more than 10,000 events, or missing custom_event_name on a custom event.
  • 404 NOT_FOUND — advertiserId does not exist, or event_source_id is not registered on the advertiser.
See Errors for the full error contract.

Event source tasks

All event source operations

Log Events guide

Event types, identity fields, and best practices

Conversion API

Identity-hashing rules and attribution methods

Sync event sources

Register a source before logging