Participants

Participants represent the people you recruit into Spot Thought from your own source of truth. Each participant tracks their contact information plus audit metadata describing who created or last updated the record. Use the endpoints below to keep participant data synchronized with your CRM and to inspect a single profile on demand.

Endpoints

GET/participants
POST/participants
PATCH/participants/{id}
GET/participants/{id}

The Participant Model

Participants surface the identifiers and metadata you need to join Spot Thought data back to your source system. The schema also includes audit actors so you can trace who performed changes.

Properties

Name
_type
Type
string
Description
Resource discriminator. Participants always return Participant.
Name
id
Type
string
Description
Unique identifier for the participant.
Name
externalUid
Type
string
Description
Identifier that links this participant to your CRM or marketing automation platform.
Name
email
Type
string
Description
Participant email address. Must be unique per workspace.
Name
name
Type
string
Description
Participant full name.
Name
createdBy
Type
Actor | null
Description
Actor who created the participant.
Name
createdAt
Type
timestamp | null
Description
ISO-8601 timestamp describing when the participant was created.
Name
updatedBy
Type
Actor | null
Description
Actor who most recently updated the participant.
Name
updatedAt
Type
timestamp | null
Description
ISO-8601 timestamp for the latest participant update.

Actors follow the shared schema described in the Actor reference. Use that guide whenever you need to branch logic by actor subtype or hydrate audit metadata.

Participant

{
  "_type": "Participant",
  "id": "ptp_001",
  "externalUid": "crm-001",
  "email": "alex@example.com",
  "name": "Alex Lee",
  "createdBy": {
    "_type": "TenantUserActor",
    "id": "user_789",
    "name": "Quinn Garcia"
  },
  "createdAt": "2024-01-08T18:24:03Z",
  "updatedBy": {
    "_type": "TenantUserActor",
    "id": "user_789",
    "name": "Quinn Garcia"
  },
  "updatedAt": "2024-05-12T16:41:55Z"
}

GET/participants

List participants

Retrieve a paginated list of participants that belong to your workspace. Use the externalUid filter to locate specific records or iterate through the entire collection with pagination.

Query parameters

Name
filter[externalUid]
Type
object
Description
Optional filter that supports eq, ne, in, and nin keys to match participants by their external identifier.
Name
pagination[limit]
Type
number
Description
Maximum number of records returned per request. Minimum value is 1.
Name
pagination[offset]
Type
number
Description
Zero-based offset that determines where pagination starts.

Request

GET

/participants

curl -G https://api.spot-thought.com/participants \
  -H "X-Spot-Api-Key: acct_123" \
  -H "X-Spot-Api-Secret: sk_live_abcd" \
  -H "X-Spot-Api-Version: 1.0.0" \
  --data-urlencode "filter[externalUid][eq]=crm-001" \
  --data-urlencode "pagination[limit]=25"

Response

{
  "total": 1,
  "limit": 25,
  "offset": 0,
  "items": [
    {
      "_type": "Participant",
      "id": "ptp_001",
      "externalUid": "crm-001",
      "email": "alex@example.com",
      "name": "Alex Lee",
      "createdBy": {
        "_type": "TenantUserActor",
        "id": "user_789",
        "name": "Quinn Garcia"
      },
      "createdAt": "2024-01-08T18:24:03Z",
      "updatedBy": {
        "_type": "TenantUserActor",
        "id": "user_789",
        "name": "Quinn Garcia"
      },
      "updatedAt": "2024-05-12T16:41:55Z"
    }
  ]
}

POST/participants

Create a participant

Create a new participant. External identifiers let you correlate the participant with another system, while email and name seed downstream screener participants and notifications.

Required attributes

Name
externalUid
Type
string
Description
External identifier that must be unique per workspace.
Name
email
Type
string
Description
Participant email address.
Name
name
Type
string
Description
Participant full name.

Request

POST

/participants

curl https://api.spot-thought.com/participants \
  -H "Content-Type: application/json" \
  -H "X-Spot-Api-Key: acct_123" \
  -H "X-Spot-Api-Secret: sk_live_abcd" \
  -H "X-Spot-Api-Version: 1.0.0" \
  -d '{
    "externalUid": "crm-003",
    "email": "sasha@example.com",
    "name": "Sasha Patel"
  }'

Response

{
  "_type": "Participant",
  "id": "ptp_003",
  "externalUid": "crm-003",
  "email": "sasha@example.com",
  "name": "Sasha Patel",
  "createdBy": {
    "_type": "ApplicationActor",
    "id": "app_001",
    "name": "Developer API Key"
  },
  "createdAt": "2024-06-02T10:12:44Z",
  "updatedBy": {
    "_type": "ApplicationActor",
    "id": "app_001",
    "name": "Developer API Key"
  },
  "updatedAt": "2024-06-02T10:12:44Z"
}

PATCH/participants/{id}

Update a participant

Update an existing participant’s profile. Send only the fields you need to change. Provide the participant id in the request path.

Path parameters

Name
id
Type
string
Description
Identifier of the participant to update.

Optional attributes

Name
email
Type
string | null
Description
Updated email address, or null to clear the current email.
Name
name
Type
string | null
Description
Updated display name, or null to clear the current name.

Request

PATCH

/participants/{id}

curl https://api.spot-thought.com/participants/ptp_001 \
  -X PATCH \
  -H "Content-Type: application/json" \
  -H "X-Spot-Api-Key: acct_123" \
  -H "X-Spot-Api-Secret: sk_live_abcd" \
  -H "X-Spot-Api-Version: 1.0.0" \
  -d '{
    "name": "Alex Lee (Updated)",
    "email": "alex.lee@example.com"
  }'

Response

{
  "_type": "Participant",
  "id": "ptp_001",
  "externalUid": "crm-001",
  "email": "alex.lee@example.com",
  "name": "Alex Lee (Updated)",
  "createdBy": {
    "_type": "TenantUserActor",
    "id": "user_789",
    "name": "Quinn Garcia"
  },
  "createdAt": "2024-01-08T18:24:03Z",
  "updatedBy": {
    "_type": "TenantUserActor",
    "id": "user_502",
    "name": "Morgan Rivera"
  },
  "updatedAt": "2024-06-15T09:03:11Z"
}

GET/participants/{id}

Retrieve a participant

Fetch a single participant by id. This is useful when hydrating profile details in your own tooling or matching a screener participant back to the original record.

Path parameters

Name
id
Type
string
Description
Identifier of the participant to retrieve.

Request

GET

/participants/{id}

curl https://api.spot-thought.com/participants/ptp_001 \
  -H "X-Spot-Api-Key: acct_123" \
  -H "X-Spot-Api-Secret: sk_live_abcd" \
  -H "X-Spot-Api-Version: 1.0.0"

Response

{
  "_type": "Participant",
  "id": "ptp_001",
  "externalUid": "crm-001",
  "email": "alex@example.com",
  "name": "Alex Lee",
  "createdBy": {
    "_type": "TenantUserActor",
    "id": "user_789",
    "name": "Quinn Garcia"
  },
  "createdAt": "2024-01-08T18:24:03Z",
  "updatedBy": {
    "_type": "TenantUserActor",
    "id": "user_502",
    "name": "Morgan Rivera"
  },
  "updatedAt": "2024-06-02T10:12:44Z"
}