Overview
POST /api/v2/buyer/advertisers/:advertiserId/log-event is a single-call ingest endpoint for sending outcome or marketing events to an advertiser. It accepts the standard ADCP event types — purchase, refund, lead, add_to_cart, initiate_checkout, view_content, content_view, watch_milestone, follow, complete_registration, subscribe, start_trial, page_view, app_install, app_launch — and a custom event type for events that don’t map to any of those.
Use it for:
- Bespoke conversion definitions — a “qualified demo booked” or “tier upgrade” event that doesn’t fit the standard taxonomy. Send
event_type: customwithcustom_event_name. - Internal-only events for ML training — engagement signals you want to feed measurement, even if they aren’t reportable conversions.
- Custom funnel steps — domain-specific milestones (game level reached, KYC step completed) that drive your bidding logic.
- Server-to-server batch ingestion — up to 10,000 events per call.
How it differs from event sources and measurement data
The three measurement ingest paths overlap; pick the one that matches the shape of your data.log-event is the path for identified, per-user events at advertiser scope. Event sources are the configuration layer you call once; log-event is the runtime path you call repeatedly.
Every event must reference an
event_source_id that is already registered
on the advertiser via POST /advertisers/:advertiserId/event-sources/sync.
Events sent against an unregistered source are rejected. See the
Measurement & Incrementality guide
for event-source setup.Request shape
All examples use:Response
Top-level fields
Per-event fields
user_match — identity fields
Send at least one identifier per event. More identifiers = higher match rate.
custom_data — event payload
Response shape
A
200 with partial_failures is normal — bad events are rejected individually, the rest succeed. Treat any failure as something to fix at source, not a transient error.
Best practices
Pick stable, descriptive custom_event_name values
Pick stable, descriptive custom_event_name values
Custom event names become the join key for downstream measurement and
reporting. Pick names you won’t want to change (
qualified_demo_booked,
kyc_step_2_complete). Renaming after launch breaks historical
continuity.Use a standard event_type when one fits
Use a standard event_type when one fits
If your event is genuinely a purchase or a lead, use
purchase or
lead. Standard types get first-class treatment in measurement and
optimization; custom events fall back to generic handling.Use event_id for idempotency
Use event_id for idempotency
event_id is the dedup key, scoped to event_type + event_source_id.
Re-sending the same event_id is safe — duplicates are dropped. Use
your stable upstream identifier (transaction ID, demo booking ID) so
retries don’t double-count.Send events in real time when you can
Send events in real time when you can
Recent events match better — click IDs and probabilistic signals decay
quickly. Aim for sub-hour latency for behavioral events; daily batches
are fine for offline conversions like CRM exports.
Use test_event_code in non-prod
Use test_event_code in non-prod
Set
test_event_code for test traffic. Events validate end-to-end
but are excluded from production reporting and the measurement engine.Batch up to 10,000 events
Batch up to 10,000 events
The endpoint accepts up to 10,000 events per call. Batch larger flows
rather than firing one HTTP request per event — same data, much less
overhead.
Privacy
The same privacy contract applies whether an event ispurchase or custom. Custom events are not a back door for raw PII.
Related
Conversion API
Detailed identity-hashing rules and the same
log-event payload viewed
as a conversion-tracking integration.Measurement & Incrementality
Register event sources, configure measurement, and run incrementality
tests against the events you log.