Skip to main content
POST
/
v1
/
participants
Create a participant
curl --request POST \
  --url https://api.scrip.dev/v1/participants \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "external_id": "user_abc123",
  "attributes": {
    "plan": "premium",
    "region": "us-east"
  },
  "program_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "ACTIVE",
  "tags": [
    "vip"
  ]
}
'
{
  "attributes": {
    "plan": "premium",
    "region": "us-east"
  },
  "balances": [
    {
      "asset_id": "550e8400-e29b-41d4-a716-446655440000",
      "available": "1500.00",
      "deferred": "0.00",
      "held": "200.00"
    }
  ],
  "counters": {
    "points_earned": "1500",
    "purchases": "42"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "external_id": "user_123",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "program_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "status": "ACTIVE",
  "tags": [
    "vip"
  ],
  "tiers": {
    "loyalty": {
      "level": "gold",
      "rank": 2
    }
  },
  "updated_at": "2024-01-15T10:30:00Z"
}
Creates a new participant identified by your external_id. Tags, attributes, and initial status can be set in the same call. Status defaults to ACTIVE. Counters and tiers cannot be set at creation — they are managed through their dedicated endpoints or automatically by rules during event processing. Pass program_id to enroll the participant in a program at creation time. Event ingestion automatically enrolls existing participants in the target program, so pre-enrolling here is optional. If your program’s on_unknown_participant is set to CREATE, new participants are also created automatically on their first event. If a participant with the same external_id already exists, the call behaves as an upsert and updates the existing record rather than returning an error.
For usage patterns and examples, see the Participants guide.

Authorizations

​
X-API-Key
string
header
required

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

Body

application/json

Participant details

​
external_id
string
required

Your application's identifier for this user. Upserts if it already exists

Required string length: 1 - 255
Example:

"user_abc123"

​
attributes
object

Key-value metadata. Each key is accessible in rules as participant.attributes.{key}

Example:
{ "plan": "premium", "region": "us-east" }
​
program_id
string<uuid>

Program to enroll this participant in on creation

Example:

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

​
status
enum<string>

Initial lifecycle state. Defaults to ACTIVE

Available options:
ACTIVE,
SUSPENDED,
CLOSED
Example:

"ACTIVE"

​
tags
string[]

Labels for segmentation, accessible in rules as participant.tags

Example:
["vip"]

Response

Participant updated (already existed)

​
attributes
object

Key-value metadata. Each key is accessible in rules as participant.attributes.{key}

Example:
{ "plan": "premium", "region": "us-east" }
​
balances
object[]

Current balances per asset, split by bucket

​
counters
object

Numeric accumulators, returned as strings for precision

Example:
{
  "points_earned": "1500",
  "purchases": "42"
}
​
created_at
string<date-time>

When the participant was created

Example:

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

​
external_id
string

Your application's identifier for this user

Example:

"user_123"

​
id
string<uuid>

Participant ID

Example:

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

​
program_ids
string[]

Programs this participant is enrolled in

Example:
["550e8400-e29b-41d4-a716-446655440000"]
​
status
string

Lifecycle state

Example:

"ACTIVE"

​
tags
string[]

Labels for segmentation, accessible in rules as participant.tags

Example:
["vip"]
​
tiers
object

Current tier level per tier type

Example:
{ "loyalty": { "level": "gold", "rank": 2 } }
​
updated_at
string<date-time>

When the participant was last modified

Example:

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