Events

Ingest an event

Submit an event for asynchronous rule evaluation; the same idempotency_key for a program returns the existing event instead of creating a new one.

post/v1/events

Request

  • Base URL: https://api.scrip.dev
  • URL: https://api.scrip.dev/v1/events
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

A key you choose to make this request safe to retry: 1 to 255 printable ASCII characters. Send the same key with the same request to get the first response again, marked Idempotent-Replayed: true. Routes that return a secret once, and claim links, do not replay a response. Event ingest uses the key as the event's identity.

Request body

event_dataobject required

JSON object exposed to rule conditions and action expressions as event data

event_timestampstring date-time required

Time the event occurred; rules evaluate against this timestamp rather than ingestion time

external_idstring

Your system's identifier for the user who triggered this event. Mutually exclusive with participant_id - exactly one must be provided. Auto-creates a participant if this ID doesn't exist (based on the program's on_unknown_participant setting). Existing participants are automatically enrolled in the target program.

idempotency_keystring required

Your key for this event within the program. Send it here or in the Idempotency-Key header. Sending the same key again returns the same event.

participant_idstring uuid

Scrip's UUID for the participant. Mutually exclusive with external_id - exactly one must be provided. The participant is automatically enrolled in the target program if not already a member.

program_idstring uuid required

Program that supplies the rules evaluated for this event

recipient_external_idstring

Optional external identifier for a second participant the event is for, such as a gift recipient. Rules read it as recipient.id and recipient.external_id. It does not move rewards by itself: actions without a target still apply to the sender, so pay the recipient with a target such as {"participant_id": "${{ recipient.id }}"}. Mutually exclusive with recipient_id. Auto-creates the recipient if this ID doesn't exist (based on the program's on_unknown_participant setting), mirroring external_id. An existing recipient is automatically enrolled in the target program if not already a member.

recipient_idstring uuid

Optional Scrip UUID for a second participant the event is for, such as a gift recipient. Rules read it as recipient.id and recipient.external_id. It does not move rewards by itself: actions without a target still apply to the sender, so pay the recipient with a target such as {"participant_id": "${{ recipient.id }}"}. Mutually exclusive with recipient_external_id. Must reference an existing participant; they are automatically enrolled in the target program if not already a member.

Example request

{
  "event_data": {
    "amount": 120,
    "type": "purchase"
  },
  "event_timestamp": "2027-01-15T10:30:00Z",
  "external_id": "user_123",
  "idempotency_key": "order-1001-completed",
  "participant_id": "f7a8b9c0-1d2e-4f3a-b4c5-d6e7f8a9b006",
  "program_id": "8f14e45f-ceea-4e70-9df8-2a7d1b3c9f01",
  "recipient_external_id": "user_xyz789",
  "recipient_id": "f7a8b9c0-1d2e-4f3a-b4c5-d6e7f8a9b007"
}

Response

Event accepted for async processing (new or duplicate)

event_timestampstring date-time

When the event occurred (from the ingestion request)

external_idstring

Your system's identifier for the user, if provided

idstring uuid

Unique identifier for the created event

idempotency_keystring

Client-provided unique key for deduplication

participant_idstring uuid

Participant UUID. May be null if only external_id was provided (resolution may be deferred to async processing).

program_idstring uuid

Program the event was ingested into

status'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED'

The event's processing status right after it is accepted.

status_urlstring

Path to fetch this event and its processing status, such as /v1/events/{id}; the same path is in the Location header of the single-event response

Example response

{
  "event_timestamp": "2027-01-15T10:30:00Z",
  "external_id": "user_123",
  "id": "e5dc1b6a-7f3d-4e2a-8c1b-9a0f4d7e6c05",
  "idempotency_key": "order-1001-completed",
  "participant_id": "f7a8b9c0-1d2e-4f3a-b4c5-d6e7f8a9b006",
  "program_id": "8f14e45f-ceea-4e70-9df8-2a7d1b3c9f01",
  "status": "PENDING",
  "status_url": "/v1/events/e5dc1b6a-7f3d-4e2a-8c1b-9a0f4d7e6c05"
}

Changes

No recorded changes to this operation across all 1 revision of this API.