Participants

Create a participant

Create a participant and return 201, or update the participant that already has this external_id and return 200.

post/v1/participants

Request

  • Base URL: https://api.scrip.dev
  • URL: https://api.scrip.dev/v1/participants
  • 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

attributesobject

Key-value metadata. Rules read each key as participant.attribute.<key>, which is null if unset, or with get(participant.attributes, "key", "").

display_namestring

The name to show for the participant.

emailstring

Contact email

external_idstring required

Your application's identifier for this participant. If a participant already has it, the request updates that participant.

first_namestring

The participant's first name.

last_namestring

The participant's last name.

phonestring

Contact phone

program_idstring uuid

Program to enroll this participant in on creation

status'ACTIVE' | 'SUSPENDED' | 'CLOSED'

Initial lifecycle state. Defaults to ACTIVE

tagsstring[]

Labels for segmentation. Rules read a tag as participant.tag.<name> (true or false) or 'name' in participant.tags.

Example request

{
  "attributes": {
    "plan": "premium",
    "region": "us-east"
  },
  "display_name": "Jane Doe",
  "email": "jane@example.com",
  "external_id": "user_123",
  "first_name": "Jane",
  "last_name": "Doe",
  "phone": "+15551234567",
  "program_id": "8f14e45f-ceea-4e70-9df8-2a7d1b3c9f01",
  "status": "ACTIVE",
  "tags": [
    "vip"
  ]
}

Response

Participant updated (already existed)

attributesobject

Key-value metadata. Rules read each key as participant.attribute.<key>, which is null if unset, or with get(participant.attributes, "key", ""). An empty object when the participant has none.

counter_settingsobject

Auto-reset settings for the counters that have one, keyed by counter key. An empty object when no counter resets. Set them with reset_after on a counter in PATCH.

countersobject

Numeric accumulators, returned as strings for precision. An empty object when the participant has none.

created_atstring date-time

When the participant was created

display_namestring

The name to show for the participant.

emailstring

Contact email

external_idstring

Your application's identifier for this participant

first_namestring

The participant's first name.

idstring uuid

The id of the participant. Use it in participant_id fields and paths.

last_namestring

The participant's last name.

phonestring

Contact phone

program_idsstring[]

Programs this participant is enrolled in

status'ACTIVE' | 'SUSPENDED' | 'CLOSED'

The participant's lifecycle state.

tagsstring[]

Labels for segmentation. Rules read a tag as participant.tag.<name> (true or false) or 'name' in participant.tags. An empty list when the participant has none.

tiersobject

Current tier level per tier type

updated_atstring date-time

When the participant was last modified

Example response

{
  "attributes": {
    "plan": "premium",
    "region": "us-east"
  },
  "balances": [
    {
      "asset_id": "a3bb189e-8bf9-4c8b-9be0-6b5d2f4e7a02",
      "available": "1500.00",
      "deferred": "0.00",
      "held": "200.00"
    }
  ],
  "counters": {
    "points_earned": "1500",
    "purchases": "42"
  },
  "created_at": "2027-01-15T10:30:00Z",
  "display_name": "Jane Doe",
  "email": "jane@example.com",
  "external_id": "user_123",
  "first_name": "Jane",
  "id": "f7a8b9c0-1d2e-4f3a-b4c5-d6e7f8a9b006",
  "last_name": "Doe",
  "phone": "+15551234567",
  "program_ids": [
    "8f14e45f-ceea-4e70-9df8-2a7d1b3c9f01"
  ],
  "status": "ACTIVE",
  "tags": [
    "vip"
  ],
  "tiers": {
    "loyalty": {
      "level": "gold",
      "rank": 2
    }
  },
  "updated_at": "2027-01-15T10:30:00Z"
}

Changes

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