Skip to main content
POST
/
v1
/
events
Ingest an event
curl --request POST \
  --url https://api.scrip.dev/v1/events \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "event_data": {},
  "event_timestamp": "2024-01-15T10:30:00Z",
  "idempotency_key": "order-12345-completed",
  "program_id": "550e8400-e29b-41d4-a716-446655440000",
  "external_id": "user_abc123",
  "participant_id": "550e8400-e29b-41d4-a716-446655440000",
  "recipient_external_id": "user_xyz789",
  "recipient_id": "550e8400-e29b-41d4-a716-446655440001"
}
'
import requests

url = "https://api.scrip.dev/v1/events"

payload = {
    "event_data": {},
    "event_timestamp": "2024-01-15T10:30:00Z",
    "idempotency_key": "order-12345-completed",
    "program_id": "550e8400-e29b-41d4-a716-446655440000",
    "external_id": "user_abc123",
    "participant_id": "550e8400-e29b-41d4-a716-446655440000",
    "recipient_external_id": "user_xyz789",
    "recipient_id": "550e8400-e29b-41d4-a716-446655440001"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    event_data: {},
    event_timestamp: '2024-01-15T10:30:00Z',
    idempotency_key: 'order-12345-completed',
    program_id: '550e8400-e29b-41d4-a716-446655440000',
    external_id: 'user_abc123',
    participant_id: '550e8400-e29b-41d4-a716-446655440000',
    recipient_external_id: 'user_xyz789',
    recipient_id: '550e8400-e29b-41d4-a716-446655440001'
  })
};

fetch('https://api.scrip.dev/v1/events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.scrip.dev/v1/events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'event_data' => [
        
    ],
    'event_timestamp' => '2024-01-15T10:30:00Z',
    'idempotency_key' => 'order-12345-completed',
    'program_id' => '550e8400-e29b-41d4-a716-446655440000',
    'external_id' => 'user_abc123',
    'participant_id' => '550e8400-e29b-41d4-a716-446655440000',
    'recipient_external_id' => 'user_xyz789',
    'recipient_id' => '550e8400-e29b-41d4-a716-446655440001'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.scrip.dev/v1/events"

	payload := strings.NewReader("{\n  \"event_data\": {},\n  \"event_timestamp\": \"2024-01-15T10:30:00Z\",\n  \"idempotency_key\": \"order-12345-completed\",\n  \"program_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"external_id\": \"user_abc123\",\n  \"participant_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"recipient_external_id\": \"user_xyz789\",\n  \"recipient_id\": \"550e8400-e29b-41d4-a716-446655440001\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.scrip.dev/v1/events")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"event_data\": {},\n  \"event_timestamp\": \"2024-01-15T10:30:00Z\",\n  \"idempotency_key\": \"order-12345-completed\",\n  \"program_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"external_id\": \"user_abc123\",\n  \"participant_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"recipient_external_id\": \"user_xyz789\",\n  \"recipient_id\": \"550e8400-e29b-41d4-a716-446655440001\"\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.scrip.dev/v1/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"event_data\": {},\n  \"event_timestamp\": \"2024-01-15T10:30:00Z\",\n  \"idempotency_key\": \"order-12345-completed\",\n  \"program_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"external_id\": \"user_abc123\",\n  \"participant_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"recipient_external_id\": \"user_xyz789\",\n  \"recipient_id\": \"550e8400-e29b-41d4-a716-446655440001\"\n}"

response = http.request(request)
puts response.read_body
{
  "event_timestamp": "2024-01-15T10:30:00Z",
  "external_id": "user_abc123",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "idempotency_key": "order-12345-completed",
  "participant_id": "550e8400-e29b-41d4-a716-446655440002",
  "program_id": "550e8400-e29b-41d4-a716-446655440001",
  "status": "PENDING"
}
{
  "code": "bad_request",
  "details": {
    "expected": "uuid",
    "field": "asset_id",
    "fields": [
      {
        "expected": "<unknown>",
        "field": "amount",
        "message": "This field is required",
        "reason": "required",
        "received": "-10.00"
      }
    ],
    "reason": "invalid",
    "received": "not-a-uuid"
  },
  "message": "Invalid request parameters"
}
{
  "code": "unauthorized",
  "details": {
    "expected": "uuid",
    "field": "asset_id",
    "fields": [
      {
        "expected": "<unknown>",
        "field": "amount",
        "message": "This field is required",
        "reason": "required",
        "received": "-10.00"
      }
    ],
    "reason": "invalid",
    "received": "not-a-uuid"
  },
  "message": "Missing or invalid credentials"
}
{
  "code": "forbidden",
  "details": {
    "expected": "uuid",
    "field": "asset_id",
    "fields": [
      {
        "expected": "<unknown>",
        "field": "amount",
        "message": "This field is required",
        "reason": "required",
        "received": "-10.00"
      }
    ],
    "reason": "invalid",
    "received": "not-a-uuid"
  },
  "message": "Insufficient permissions for this action"
}
{
  "code": "unsupported_media_type",
  "details": {
    "expected": "uuid",
    "field": "asset_id",
    "fields": [
      {
        "expected": "<unknown>",
        "field": "amount",
        "message": "This field is required",
        "reason": "required",
        "received": "-10.00"
      }
    ],
    "reason": "invalid",
    "received": "not-a-uuid"
  },
  "message": "Content-Type must be application/json"
}
{
  "code": "internal_error",
  "message": "An internal error occurred"
}
Submits an event for asynchronous rule evaluation. The API returns 202 Accepted immediately. A worker picks up the event, evaluates all matching rules, and executes their actions. Identify the participant with exactly one of external_id or participant_id. Pass event_timestamp for when the event occurred and event_data containing the payload your rules will evaluate against. Optionally set recipient_id or recipient_external_id to route rewards to a different participant (e.g. gifting). The idempotency_key is required and scoped per program. Submitting the same key again returns the same event identity without reprocessing, even if the payload differs. To correct or replace an event, submit a new event with a new idempotency key. Use deterministic keys like order-12345-completed, not random UUIDs. If the participant doesn’t exist yet and the program’s on_unknown_participant is CREATE, Scrip creates the participant and processes the event in one step. The on_unknown_participant setting controls creation of new participants only. Existing participants are automatically enrolled in the target program if not already members. Inactive enrollments (FROZEN, LOCKED, or CLOSED) are reactivated. Enrollment behavior applies regardless of the on_unknown_participant setting. Business validation (program existence and status, participant resolution) happens asynchronously. A 202 Accepted response confirms receipt, not that the event is valid or will complete. Subscribe to event.failed webhooks for error notification. Failed events expose a machine-readable error_code (when the failure has a classified code, such as participant_suspended or program_inactive) on both the event resource and the event.failed webhook payload. Read-after-write is not immediate: in queue-based ingestion mode the returned id may briefly 404 on GET /v1/events/{id} and GET /v1/events/by-key (typically well under a second) until the async consumer materializes the event. The ID is durable; poll until it resolves. Every accepted submission eventually becomes readable, either as a processed event or as status FAILED with an error_code if it was rejected asynchronously. Events whose resolved actor or recipient is SUSPENDED or CLOSED are rejected before any rule runs: as a 422 with code participant_suspended or participant_closed when identities resolve synchronously, or as a terminal FAILED event with the same error_code in queue-based mode. Numeric values in event_data whose magnitude exceeds 2^53 are rejected with 400 amount_precision_exceeded; send very large values as strings to preserve them exactly.
For usage patterns and examples, see the Event Processing guide.

Authorizations

​
X-API-Key
string
header
required

API key passed in the X-API-Key header.

Body

application/json

Event with event_data for rule evaluation

​
event_data
object
required

EventData contains the event data used for rule condition evaluation

​
event_timestamp
string<date-time>
required

EventTimestamp is when the event occurred (used for rule evaluation)

Example:

"2024-01-15T10:30:00Z"

​
idempotency_key
string
required

IdempotencyKey ensures this event is only processed once (must be unique per program)

Required string length: 1 - 255
Example:

"order-12345-completed"

​
program_id
string<uuid>
required

ProgramID links this event to a specific program for rule evaluation

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
external_id
string

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.

Required string length: 1 - 255
Example:

"user_abc123"

​
participant_id
string<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.

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
recipient_external_id
string

RecipientExternalID optionally specifies a different participant (by external ID) to receive rewards (e.g., referral / gifting). Mutually exclusive with RecipientID. 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.

Required string length: 1 - 255
Example:

"user_xyz789"

​
recipient_id
string<uuid>

RecipientID optionally specifies a different participant (by UUID) to receive rewards (e.g., gifting). Mutually exclusive with RecipientExternalID. Must reference an existing participant; they are automatically enrolled in the target program if not already a member.

Example:

"550e8400-e29b-41d4-a716-446655440001"

Response

Event accepted for async processing (new or duplicate)

​
event_timestamp
string<date-time>

When the event occurred (from the ingestion request)

Example:

"2024-01-15T10:30:00Z"

​
external_id
string

Your system's identifier for the user, if provided

Example:

"user_abc123"

​
id
string<uuid>

Unique identifier for the created event

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
idempotency_key
string

Client-provided unique key for deduplication

Example:

"order-12345-completed"

​
participant_id
string<uuid>

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

Example:

"550e8400-e29b-41d4-a716-446655440002"

​
program_id
string<uuid>

Program the event was ingested into

Example:

"550e8400-e29b-41d4-a716-446655440001"

​
status
string

Processing status (PENDING on initial ingestion)

Example:

"PENDING"