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"
  },
  "display_name": "Jane Doe",
  "email": "jane@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "phone": "+15551234567",
  "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",
  "display_name": "Jane Doe",
  "email": "jane@example.com",
  "external_id": "user_123",
  "first_name": "Jane",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "last_name": "Doe",
  "phone": "+15551234567",
  "program_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "status": "ACTIVE",
  "tags": [
    "vip"
  ],
  "tiers": {
    "loyalty": {
      "level": "gold",
      "rank": 2
    }
  },
  "updated_at": "2024-01-15T10:30:00Z"
}

Documentation Index

Fetch the complete documentation index at: https://docs.scrip.dev/llms.txt

Use this file to discover all available pages before exploring further.

Creates a new participant identified by your external_id. Tags, attributes, profile fields (email, phone, first_name, last_name, display_name), 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" }
​
display_name
string

Display name

Maximum string length: 255
Example:

"Jane Doe"

​
email
string

Contact email

Maximum string length: 255
Example:

"jane@example.com"

​
first_name
string

First name

Maximum string length: 255
Example:

"Jane"

​
last_name
string

Last name

Maximum string length: 255
Example:

"Doe"

​
phone
string

Contact phone

Maximum string length: 50
Example:

"+15551234567"

​
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"

​
display_name
string

Display name

Example:

"Jane Doe"

​
email
string

Contact email

Example:

"jane@example.com"

​
external_id
string

Your application's identifier for this user

Example:

"user_123"

​
first_name
string

First name

Example:

"Jane"

​
id
string<uuid>

Participant ID

Example:

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

​
last_name
string

Last name

Example:

"Doe"

​
phone
string

Contact phone

Example:

"+15551234567"

​
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"