Screener participants

Screener participants represent tenant participants that have been invited to a screener. Each record links the participant profile, the screener they belong to, and the latest screening session so you can monitor progress. Use the endpoints below to manage the assignment lifecycle and keep screener rosters in sync with your source of truth.

Endpoints

GET/screener-participants
GET/screener-participants/{id}
DELETE/screener-participants/{id}
POST/screener-participants-import

The Screener Participant model

Every screener participant follows a shared schema that exposes the linkage between screeners and tenant participants. Audit history lives on the participant resource itself, so screener participants focus on assignment metadata.

Properties

Name
_type
Type
string
Description
Resource discriminator. Screener participants always return ScreenerParticipant.
Name
id
Type
string
Description
Unique identifier for the screener participant record.
Name
screenerId
Type
string
Description
Identifier of the screener the participant belongs to.
Name
participantId
Type
string
Description
Identifier of the underlying tenant participant profile.
Name
externalParticipantUid
Type
string
Description
Optional identifier that links the participant to an external system of record.
Name
currentSessionId
Type
string | null
Description
Identifier of the participant’s active screener session, or null if no session has started.
Name
name
Type
string
Description
Participant’s display name copied from the tenant participant profile.
Name
email
Type
string
Description
Email address copied from the tenant participant profile.
Name
status
Type
'NOT_STARTED' | 'IN_PROGRESS' | 'QUALIFIED' | 'DISQUALIFIED' | 'UNKNOWN'
Description
Current screening status derived from the participant’s latest session.

ScreenerParticipant

{
  "_type": "ScreenerParticipant",
  "id": "scpar_123",
  "screenerId": "scr_123",
  "participantId": "ptp_001",
  "externalParticipantUid": "crm-001",
  "currentSessionId": "scses_789",
  "name": "Alex Lee",
  "email": "alex@example.com",
  "status": "IN_PROGRESS"
}

GET/screener-participants

List screener participants

Retrieve a paginated list of screener participants that belong to your workspace. Results include the participant’s current screening status and the session that is actively assigned. Use filters to scope the collection to a single screener. Each request must include the authentication headers described in the authentication guide.

Response structure

Name
total
Type
number
Description
Total number of screener participants that match the query.
Name
limit
Type
number
Description
Number of records returned in this page.
Name
offset
Type
number
Description
Zero-based index of the first record in this response.
Name
items
Type
ScreenerParticipant[]
Description
Array of screener participant resources for this page.

Request

GET

/screener-participants

curl -G https://api.spot-thought.com/screener-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[screenerId][eq]=scr_123" \
  --data-urlencode "pagination[limit]=50"

Response

{
  "total": 2,
  "limit": 50,
  "offset": 0,
  "items": [
    {
      "_type": "ScreenerParticipant",
      "id": "scpar_123",
      "screenerId": "scr_123",
      "participantId": "ptp_001",
      "externalParticipantUid": "crm-001",
      "currentSessionId": "scses_789",
      "name": "Alex Lee",
      "email": "alex@example.com",
      "status": "IN_PROGRESS"
    },
    {
      "_type": "ScreenerParticipant",
      "id": "scpar_456",
      "screenerId": "scr_123",
      "participantId": "ptp_002",
      "externalParticipantUid": "crm-002",
      "currentSessionId": null,
      "name": "Morgan Rivera",
      "email": "morgan@example.com",
      "status": "NOT_STARTED"
    }
  ]
}

GET/screener-participants/{id}

Retrieve a screener participant

Fetch a single screener participant to inspect their assignment metadata and current session. Provide the participant id in the request path.

Path parameters

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

Request

GET

/screener-participants/{id}

curl https://api.spot-thought.com/screener-participants/scpar_123 \
  -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": "ScreenerParticipant",
  "id": "scpar_123",
  "screenerId": "scr_123",
  "participantId": "ptp_001",
  "externalParticipantUid": "crm-001",
  "currentSessionId": "scses_789",
  "name": "Alex Lee",
  "email": "alex@example.com",
  "status": "QUALIFIED"
}

DELETE/screener-participants/{id}

Remove a screener participant

Remove a participant from a screener roster. Deleting the screener participant severs the link between the screener and the tenant participant but leaves the original participant record intact so you can re-invite them later.

Path parameters

Name
id
Type
string
Description
Identifier of the screener participant to remove.

Request

DELETE

/screener-participants/{id}

curl https://api.spot-thought.com/screener-participants/scpar_123 \
  -X DELETE \
  -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": "ScreenerParticipant",
  "id": "scpar_123",
  "screenerId": "scr_123",
  "participantId": "ptp_001",
  "externalParticipantUid": "crm-001",
  "currentSessionId": "scses_789",
  "name": "Alex Lee",
  "email": "alex@example.com",
  "status": "REMOVED"
}

POST/screener-participants-import

Import screener participants

Import one or more participants into a screener in a single request. Imports either upsert new participants or fully synchronize the roster depending on the selected mode. Use this endpoint to keep Spot Thought aligned with your CRM.

Body attributes

Name
screenerId
Type
string
Description
Identifier of the screener that participants will be assigned to.
Name
importMode
Type
'UPDATES_ONLY' | 'FULL_SYNC' | null
Description
Optional synchronization mode. UPDATES_ONLY inserts new rows and updates existing records. FULL_SYNC also removes screener participants that are not present in the payload. Defaults to UPDATES_ONLY.
Name
participants
Type
ImportParticipant[]
Description
Array of participant payloads to upsert.

ImportParticipant object

Name
externalUid
Type
string
Description
External identifier that links the participant to your source system.
Name
email
Type
string
Description
Participant email address.
Name
name
Type
string
Description
Participant full name.

Request

POST

/screener-participants-import

curl https://api.spot-thought.com/screener-participants-import \
  -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 '{
    "screenerId": "scr_123",
    "importMode": "FULL_SYNC",
    "participants": [
      { "externalUid": "crm-001", "email": "alex@example.com", "name": "Alex Lee" },
      { "externalUid": "crm-002", "email": "morgan@example.com", "name": "Morgan Rivera" }
    ]
  }'

Response

[
  {
    "_type": "ScreenerParticipant",
    "id": "scpar_123",
    "screenerId": "scr_123",
    "participantId": "ptp_001",
    "externalParticipantUid": "crm-001",
    "currentSessionId": "scses_789",
    "name": "Alex Lee",
    "email": "alex@example.com",
    "status": "NOT_STARTED"
  },
  {
    "_type": "ScreenerParticipant",
    "id": "scpar_456",
    "screenerId": "scr_123",
    "participantId": "ptp_002",
    "externalParticipantUid": "crm-002",
    "currentSessionId": null,
    "name": "Morgan Rivera",
    "email": "morgan@example.com",
    "status": "NOT_STARTED"
  }
]