Skip to Content
API ReferenceEvent Ingestion

Event Ingestion

This reference describes the CDP ingest API for server-to-server customer events.

For the product overview, see CDP → Event Ingestion. For integration guidance, see Developers → CDP Integration.

1. Authentication

Use a CDP API key:

Authorization: Bearer <api_key>

Workspace administrators create CDP ingest API keys in workspace Settings, in the API keys panel.

2. Endpoints

2.1 POST /v1/cdp/events

Accepts one customer event.

Request body

FieldTypeRequiredDescription
sourcestring✅Source system identifier such as brand.pos or brand.crm.
externalEventIdstring✅Stable idempotency key for the business fact.
eventTypestring✅Registered CDP event type.
occurredAtISO 8601 timestamp❌Time when the business fact happened. Defaults to receipt time when omitted.
identityobject✅Inbound identity object used for profile resolution.
identity.externalUserIdstring❌External upstream user ID mapped to canonical EXTERNAL identity handling.
identity.emailstring❌Email identifier before normalization.
identity.phonestring❌Phone identifier before normalization.
identity.deviceKeystring❌Device-bound identifier when available.
propertiesobject❌Registered event properties.

At least one supported field inside identity must be present.

Example request

{
  "source": "brand.pos",
  "externalEventId": "txn_987654321",
  "eventType": "purchase_completed",
  "occurredAt": "2026-05-20T12:45:00Z",
  "identity": {
    "externalUserId": "L-123456789",
    "email": "customer@example.com"
  },
  "properties": {
    "order_id": "order_42",
    "amount": 120.50,
    "currency": "USD",
    "store_id": "store_42"
  }
}

Accepted response

{
  "status": "accepted",
  "event_id": "evt_74d63a"
}

Duplicate response

{
  "status": "duplicate",
  "original_event_id": "evt_74d63a"
}

2.2 POST /v1/cdp/events/batch

Accepts multiple events in one request.

Request body

FieldTypeRequiredDescription
itemsarray✅Array of event payloads matching POST /v1/cdp/events.

Example response

{
  "results": [
    { "status": "accepted", "event_id": "evt_a" },
    { "status": "duplicate", "original_event_id": "evt_b" },
    {
      "status": "error",
      "error_code": "validation_failed",
      "message": "identity.externalUserId, identity.email, identity.phone, or identity.deviceKey is required"
    }
  ]
}

Each item is evaluated independently.

3. Validation Rules

  • eventType must be registered in the CDP contract.
  • Required properties for that event type must be present.
  • Unknown or unsupported property shapes may be rejected.
  • At least one supported identity field must be provided.
  • externalEventId must stay stable across retries of the same business fact.

4. Deduplication

ResultFly deduplicates by:

(tenant, source, externalEventId)

This allows safe retries after transport failures.

5. Error Semantics

  • 401 Unauthorized if the API key is invalid.
  • 403 Forbidden if the key lacks permission for the operation.
  • 409 Conflict if the request collides with existing protected state in a non-retryable way.
  • 422 Unprocessable Entity if validation fails.
  • 5xx Server Error for transient issues. Retry with the same externalEventId.

6. Notes for Integrators

  • Send identifiers that are stable in your source systems.
  • Treat externalEventId as a business idempotency key, not as a request UUID.
  • Keep event schemas governed. If marketing teams need to segment on a property, that property should be registered and marked accordingly.
  • Problematic events are surfaced in Data Issues with a reason and safe payload details for review.
  • Successful events are stored as ingested events and can be inspected from the profile Event Timeline; workspaces with an Ingest Events view can also use it to check stored payload/properties directly. Sensitive identity or contact fields may be masked in UI views.
Idempotency & ErrorsCampaign Variables