Participants

Update a participant

Change a participant's status, contact details, tags, attributes and counters in one request. Scrip applies every change together or none of them, and returns the participant with its updated state.

patch/v1/participants/{participant_id}

Request

Base URL: https://api.scrip.dev
URL: https://api.scrip.dev/v1/participants/{participant_id}
Auth: HTTP bearer

Path parameters

participant_idstring required

The participant's id, or ext: followed by the participant's external_id.

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

Attributes to change, as a merge patch. Keys you send are set, keys you leave out keep their value, and a key sent as null is removed. Removing a key that does not exist succeeds and changes nothing, so retries are safe. Rules read each key as participant.attribute.<key> or with get(participant.attributes, "key", "").

countersobject

Counters to change. Each key maps to {"increment": n} to add to the counter, {"set": n} to replace its value, {"reset_after": "720h"} to change only the reset window and keep the value, or null to remove it. Removing a counter that does not exist succeeds and changes nothing, so retries are safe. Scrip applies every change in the request together or none of them. Counters need an ACTIVE participant.

display_namestring

Display name. Empty string clears the value

emailstring

Contact email. Empty string clears the value

first_namestring

First name. Empty string clears the value

forceboolean

When true, suspending or closing the sole active ADMIN of a group proceeds and ends that participant's ADMIN membership in each such group; otherwise the request returns 409 last_admin_status_change_forbidden.

last_namestring

Last name. Empty string clears the value

phonestring

Contact phone. Empty string clears the value

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

Lifecycle state

tagsstring[]

The participant's full tag set. Sending tags replaces every existing tag, and an empty list removes them all. Leave the field out to keep the tags. null is not allowed.

Example request

{
  "attributes": {
    "legacy_segment": null,
    "plan": "premium"
  },
  "counters": {
    "points_cycle": {
      "set": "0"
    },
    "purchases": {
      "increment": "1"
    },
    "trial_days": null
  },
  "display_name": "Jane Doe",
  "email": "jane@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "phone": "+15551234567",
  "status": "SUSPENDED",
  "tags": [
    "vip"
  ]
}

Response

Participant updated

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.