> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interchange.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Log event

> Send outcome or marketing events to an advertiser for measurement

`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](/v2/buyer/event-sources/tasks/sync-event-sources). Events are deduplicated by `event_id` + `event_type` + `event_source_id`, so retries are safe.

<Warning>
  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](/v2/integrations/conversion-api) for hashing rules.
</Warning>

## Request

<CodeGroup>
  ```bash curl theme={null}
  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" }
        }
      ]
    }'
  ```
</CodeGroup>

## 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

```json theme={null}
{
  "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](/v2/reference/errors) for the full error contract.

## Related

<CardGroup cols={2}>
  <Card title="Event source tasks" href="/v2/buyer/event-sources/tasks" icon="list-check">
    All event source operations
  </Card>

  <Card title="Log Events guide" href="/v2/guides/log-events" icon="circle-dot">
    Event types, identity fields, and best practices
  </Card>

  <Card title="Conversion API" href="/v2/integrations/conversion-api" icon="bolt">
    Identity-hashing rules and attribution methods
  </Card>

  <Card title="Sync event sources" href="/v2/buyer/event-sources/tasks/sync-event-sources" icon="arrows-rotate">
    Register a source before logging
  </Card>
</CardGroup>