Screener sessions

Screener sessions capture each participant’s journey through a screener. Sessions reference the screener publication that was delivered, the participant assignment, and timestamps that describe when the interview started, progressed, and completed. Use the endpoints below to monitor qualification funnels and inspect individual progress.

Endpoints

GET/screener-sessions
GET/screener-sessions/{id}
DELETE/screener-sessions/{id}
GET/screener-responses

The Screener Session model

Screener sessions expose linkage fields that tie together screeners, participants, and publications. They also include a set of timestamps and tags you can use for analytics, plus stateful status values to help automate follow-up actions.

Properties

Name
_type
Type
string
Description
Resource discriminator. Sessions always return ScreenerSession.
Name
id
Type
string
Description
Unique identifier for the screener session.
Name
screenerId
Type
string
Description
Screener that the participant is completing.
Name
screenerParticipantId
Type
string
Description
Identifier of the screener participant associated with this session.
Name
screenerPublicationId
Type
string
Description
Publication version used when the participant started the screener.
Name
screenerSessionLink
Type
string
Description
Direct link that opens the participant’s screening experience.
Name
linkSlug
Type
string
Description
Short slug used to build the participant’s unique screener URL.
Name
status
Type
'ACTIVE' | 'ARCHIVED' | 'REMOVED'
Description
Administrative status that determines whether the session can receive responses.
Name
state
Type
'NOT_STARTED' | 'IN_PROGRESS' | 'COMPLETED'
Description
Participant progress state for the session.
Name
startedAt
Type
timestamp | null
Description
Timestamp of the participant’s first submission.
Name
lastActiveAt
Type
timestamp | null
Description
Timestamp of the participant’s most recent activity.
Name
completedAt
Type
timestamp | null
Description
Timestamp of the participant’s final submission.
Name
assignedTags
Type
Tag[]
Description
Tags inherited from the publication that can be used to categorize the session.

Tags follow the reusable schema outlined in the Tag reference, ensuring publication metadata and assigned sessions share the same structure.

ScreenerSession

{
  "_type": "ScreenerSession",
  "id": "scses_789",
  "screenerId": "scr_123",
  "screenerParticipantId": "scpar_123",
  "screenerPublicationId": "scpub_456",
  "screenerSessionLink": "https://spot-thought.com/screeners/scr_123/scses_789",
  "linkSlug": "onboarding-001-alex",
  "status": "ACTIVE",
  "state": "IN_PROGRESS",
  "startedAt": "2024-05-01T15:08:21Z",
  "lastActiveAt": "2024-05-01T15:14:44Z",
  "completedAt": null,
  "assignedTags": [
    {
      "_type": "Tag",
      "id": "tag_qual",
      "category": "qualification",
      "value": "priority"
    }
  ]
}

GET/screener-sessions

List screener sessions

Retrieve a paginated list of screener sessions. Filters let you scope sessions to a specific screener or provide explicit session identifiers. Combine filters with pagination to iterate through large datasets.

Query parameters

Name
filter[id]
Type
object
Description
Optional filter that accepts eq, ne, in, or nin keys with UUID values to control which session ids are returned.
Name
filter[screenerId]
Type
object
Description
Filter sessions by screener id using eq, ne, in, or nin keys.
Name
pagination[limit]
Type
number
Description
Maximum number of records to return. Minimum value is 1.
Name
pagination[offset]
Type
number
Description
Zero-based offset that determines where the page starts.

Request

GET

/screener-sessions

curl -G https://api.spot-thought.com/screener-sessions \
  -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]=25" \
  --data-urlencode "pagination[offset]=0"

Response

{
  "total": 1,
  "limit": 25,
  "offset": 0,
  "items": [
    {
      "_type": "ScreenerSession",
      "id": "scses_789",
      "screenerId": "scr_123",
      "screenerParticipantId": "scpar_123",
      "screenerPublicationId": "scpub_456",
      "screenerSessionLink": "https://spot-thought.com/screeners/scr_123/scses_789",
      "linkSlug": "onboarding-001-alex",
      "status": "ACTIVE",
      "state": "IN_PROGRESS",
      "startedAt": "2024-05-01T15:08:21Z",
      "lastActiveAt": "2024-05-01T15:14:44Z",
      "completedAt": null,
      "assignedTags": [
        { "_type": "Tag", "id": "tag_qual", "category": "qualification", "value": "priority" }
      ]
    }
  ]
}

GET/screener-sessions/{id}

Retrieve a screener session

Fetch a single screener session to inspect timestamps, current state, and tag assignments. Provide the session id in the request path.

Path parameters

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

Request

GET

/screener-sessions/{id}

curl https://api.spot-thought.com/screener-sessions/scses_789 \
  -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": "ScreenerSession",
  "id": "scses_789",
  "screenerId": "scr_123",
  "screenerParticipantId": "scpar_123",
  "screenerPublicationId": "scpub_456",
  "screenerSessionLink": "https://spot-thought.com/screeners/scr_123/scses_789",
  "linkSlug": "onboarding-001-alex",
  "status": "ACTIVE",
  "state": "COMPLETED",
  "startedAt": "2024-05-01T15:08:21Z",
  "lastActiveAt": "2024-05-01T15:16:55Z",
  "completedAt": "2024-05-01T15:16:55Z",
  "assignedTags": [
    { "_type": "Tag", "id": "tag_qual", "category": "qualification", "value": "priority" }
  ]
}

DELETE/screener-sessions/{id}

Remove a screener session

Remove a session when you want to revoke a participant’s link or clean up test data. Removing a session marks its status as REMOVED while preserving history so audits still show when it existed. Send the session id in the request path.

Path parameters

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

Request

DELETE

/screener-sessions/{id}

curl https://api.spot-thought.com/screener-sessions/scses_789 \
  -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": "ScreenerSession",
  "id": "scses_789",
  "screenerId": "scr_123",
  "screenerParticipantId": "scpar_123",
  "screenerPublicationId": "scpub_456",
  "screenerSessionLink": "https://spot-thought.com/screeners/scr_123/scses_789",
  "linkSlug": "onboarding-001-alex",
  "status": "REMOVED",
  "state": "NOT_STARTED",
  "startedAt": null,
  "lastActiveAt": null,
  "completedAt": null,
  "assignedTags": [
    { "_type": "Tag", "id": "tag_qual", "category": "qualification", "value": "priority" }
  ]
}

GET/screener-responses

List screener responses

Retrieve the granular responses captured across screener sessions. This endpoint lets you export question-level data for downstream analytics or to sync with your own data warehouse. Combine filters to scope results to a specific screener, publication version, or set of participant assignments.

Query parameters

Name
filter[screenerId]
Type
object
Description
Restrict responses to a single screener using the eq operator.
Name
filter[screenerPublicationId]
Type
object
Description
Scope responses to a specific publication version with eq.
Name
filter[screenerSessionId]
Type
object
Description
Filter by session identifiers using eq or in to target a set of sessions.
Name
filter[screenerParticipantId]
Type
object
Description
Filter by screener participant identifiers using eq or in.
Name
pagination[limit]
Type
number
Description
Maximum number of responses per page. Minimum value is 1.
Name
pagination[offset]
Type
number
Description
Zero-based offset that determines where the page starts.

Response structure

Name
total
Type
number
Description
Total number of responses that match the filters.
Name
limit
Type
number
Description
Number of responses returned in this page.
Name
offset
Type
number
Description
Zero-based offset used for this page.
Name
items
Type
ScreenerResponse[]
Description
Array of typed screener responses. Each response includes the screener, publication, session, participant, and question prompt along with the typed answer payload (answer or arrays of answer objects depending on the question type).

Request

GET

/screener-responses

curl -G https://api.spot-thought.com/screener-responses \
  -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 "filter[screenerSessionId][in][]=scses_789" \
  --data-urlencode "pagination[limit]=100"

Response

{
  "total": 2,
  "limit": 100,
  "offset": 0,
  "items": [
    {
      "_type": "ScreenerTextResponse",
      "questionType": "ScreenerTextQuestion",
      "screenerSessionId": "scses_789",
      "screenerPageId": "scp_intro",
      "screenerQuestionId": "scq_role",
      "screenerId": "scr_123",
      "screenerPublicationId": "scpub_456",
      "participantId": "ptp_001",
      "externalParticipantUid": "crm-001",
      "screenerParticipantId": "scpar_123",
      "screenerQuestionPrompt": "What is your role?",
      "answer": "VP of Research"
    },
    {
      "_type": "ScreenerMultiSelectResponse",
      "questionType": "ScreenerMultiSelectQuestion",
      "screenerSessionId": "scses_789",
      "screenerPageId": "scp_focus",
      "screenerQuestionId": "scq_channels",
      "screenerId": "scr_123",
      "screenerPublicationId": "scpub_456",
      "participantId": "ptp_001",
      "externalParticipantUid": "crm-001",
      "screenerParticipantId": "scpar_123",
      "screenerQuestionPrompt": "Which teams will use Spot Thought?",
      "answer": [
        { "text": "Sales", "isWriteIn": false },
        { "text": "Other: Insights Hub", "isWriteIn": true }
      ]
    }
  ]
}

Name
answer
Type
string | number | object | object[] | null
Description
The payload varies by questionType. Text questions return strings, numeric questions return numbers, and select questions return option objects with text and isWriteIn flags.