Log event

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

Field	Type	Required	Notes
`advertiserId`	string	Yes	Path. Owning advertiser
`event_source_id`	string	Yes	Must match a source registered on the advertiser
`events`	object[]	Yes	1–10,000 events
`events[].event_id`	string	Yes	Dedup key, unique within `event_type` + `event_source_id`
`events[].event_type`	enum	Yes	ADCP event type, such as `purchase`, `lead`, `add_to_cart`, `refund`, `subscribe`, `start_trial`, `app_install`, or `custom`
`events[].event_time`	string	Yes	ISO 8601 timestamp when the event occurred
`events[].custom_event_name`	string	Conditional	Required when `event_type` is `custom`
`events[].action_source`	enum	No	`website`, `app`, `in_store`, `phone_call`, `system_generated`, `other`
`events[].event_source_url`	string	Conditional	Recommended when `action_source` is `website`
`events[].user_match`	object	No	Identity fields: `hashed_email`, `hashed_phone`, `click_id` + `click_id_type`, `uids`, `client_ip`, `client_user_agent`
`events[].custom_data`	object	No	`value`, `currency`, `order_id`, `content_ids`, `num_items`, `contents`
`test_event_code`	string	No	Marks 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

Getting Started

Advertisers

Campaigns

Product Discovery

Webhooks

Creatives

Signals & Brand

Audiences & Inventory

Measurement & Conversions

Reporting & Activity

Planning & Governance

Connections

Account & Billing

Request

Parameters

Response

Errors

Event source tasks

Log Events guide

Conversion API

Sync event sources

​Request

​Parameters

​Response

​Errors

​Related

Event source tasks

Log Events guide

Conversion API

Sync event sources

Request

Parameters

Response

Errors

Related