Screeners

Screeners define the set of questions you present to participants in Spot Thought. Each screener tracks its own publication history and audit metadata so you can understand when a questionnaire changed and who changed it. Use the endpoints below to manage the collection of screeners that belong to your workspace.

Endpoints

GET/screeners
POST/screeners
GET/screeners/{id}
PATCH/screeners/{id}
GET/screeners/{id}/publications
POST/screener-publications
GET/screener-publications/{id}

The Screener model

Every screener shares a common schema. Responses reference the screener id, and the audit fields identify the actors who created or last updated the resource.

Properties

Name
_type
Type
string
Description
Resource discriminator. Screeners always return Screener for this value.
Name
id
Type
string
Description
Unique identifier for the screener.
Name
title
Type
string
Description
Human readable title that appears wherever the screener is referenced.
Name
description
Type
string | null
Description
Optional longer description of the screener’s purpose. Returns null when no description has been set.
Name
activePublicationId
Type
string | null
Description
Identifier of the currently active screener publication, or null when no publication is active.
Name
createdBy
Type
Actor | null
Description
Actor who originally created the screener. The shape follows the Actor schema and includes an _type, id, and name.
Name
createdAt
Type
timestamp | null
Description
ISO-8601 timestamp indicating when the screener was created.
Name
updatedBy
Type
Actor | null
Description
Actor who most recently updated the screener.
Name
updatedAt
Type
timestamp | null
Description
ISO-8601 timestamp for the most recent update to the screener.

Actor objects follow the schema documented in the Actor reference, so you can reuse that definition across every resource that exposes audit metadata.

Screener

{
  "_type": "Screener",
  "id": "scr_123",
  "title": "Customer onboarding",
  "description": "Screen potential research participants.",
  "activePublicationId": "scpub_456",
  "createdBy": {
    "_type": "TenantUserActor",
    "id": "user_789",
    "name": "Alex Lee"
  },
  "createdAt": "2024-01-08T18:24:03Z",
  "updatedBy": {
    "_type": "TenantUserActor",
    "id": "user_987",
    "name": "Sam Taylor"
  },
  "updatedAt": "2024-05-12T16:41:55Z"
}

GET/screeners

List screeners

Retrieve a paginated list of screeners that belong to your workspace. The response follows the PaginatedScreener schema with pagination metadata and an items array of screener objects. Each request must include the authentication headers described in the authentication guide.

Response structure

Name
total
Type
number
Description
Total number of screeners available in the workspace.
Name
limit
Type
number
Description
Number of records returned in this response page.
Name
offset
Type
number
Description
Zero-based offset of the first screener in the returned page.
Name
items
Type
Screener[]
Description
Array of screener resources for this page.

Request

GET

/screeners

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

Response

{
  "total": 1,
  "limit": 20,
  "offset": 0,
  "items": [
    {
      "_type": "Screener",
      "id": "scr_123",
      "title": "Customer onboarding",
      "description": "Screen potential research participants.",
      "activePublicationId": "scpub_456",
      "createdBy": {
        "_type": "TenantUserActor",
        "id": "user_789",
        "name": "Alex Lee"
      },
      "createdAt": "2024-01-08T18:24:03Z",
      "updatedBy": {
        "_type": "TenantUserActor",
        "id": "user_789",
        "name": "Alex Lee"
      },
      "updatedAt": "2024-05-12T16:41:55Z"
    }
  ]
}

POST/screeners

Create a screener

Create a new screener. Provide at least a title and optionally a description. The response returns the persisted screener object with audit metadata. Use null for optional fields you want to clear explicitly.

Required attributes

Name
title
Type
string
Description
Title for the screener displayed throughout Spot Thought.

Optional attributes

Name
description
Type
string | null
Description
Longer explanation of what the screener is used for.

Request

POST

/screeners

curl https://api.spot-thought.com/screeners \
  -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 '{
    "title": "Customer onboarding",
    "description": "Screen potential research participants."
  }'

Response

{
  "_type": "Screener",
  "id": "scr_123",
  "title": "Customer onboarding",
  "description": "Screen potential research participants.",
  "activePublicationId": null,
  "createdBy": {
    "_type": "TenantUserActor",
    "id": "user_789",
    "name": "Alex Lee"
  },
  "createdAt": "2024-01-08T18:24:03Z",
  "updatedBy": {
    "_type": "TenantUserActor",
    "id": "user_789",
    "name": "Alex Lee"
  },
  "updatedAt": "2024-01-08T18:24:03Z"
}

GET/screeners/{id}

Retrieve a screener

Fetch a single screener by its identifier. This is useful for hydrating edit forms or showing the current active publication. Pass the screener id in the request path.

Path parameters

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

Request

GET

/screeners/{id}

curl https://api.spot-thought.com/screeners/scr_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": "Screener",
  "id": "scr_123",
  "title": "Customer onboarding",
  "description": "Screen potential research participants.",
  "activePublicationId": "scpub_456",
  "createdBy": {
    "_type": "TenantUserActor",
    "id": "user_789",
    "name": "Alex Lee"
  },
  "createdAt": "2024-01-08T18:24:03Z",
  "updatedBy": {
    "_type": "TenantUserActor",
    "id": "user_789",
    "name": "Alex Lee"
  },
  "updatedAt": "2024-05-12T16:41:55Z"
}

PATCH/screeners/{id}

Update a screener

Update a screener’s title or description. Send only the fields you want to change. Provide null to clear an optional value such as the description.

Path parameters

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

Optional attributes

Name
title
Type
string | null
Description
New title for the screener, or null to remove the existing value.
Name
description
Type
string | null
Description
New description for the screener, or null to clear the description.

Request

PATCH

/screeners/{id}

curl https://api.spot-thought.com/screeners/scr_123 \
  -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 '{
    "title": "Customer onboarding (2024 refresh)",
    "description": null
  }'

Response

{
  "_type": "Screener",
  "id": "scr_123",
  "title": "Customer onboarding (2024 refresh)",
  "description": null,
  "activePublicationId": "scpub_456",
  "createdBy": {
    "_type": "TenantUserActor",
    "id": "user_789",
    "name": "Alex Lee"
  },
  "createdAt": "2024-01-08T18:24:03Z",
  "updatedBy": {
    "_type": "TenantUserActor",
    "id": "user_502",
    "name": "Morgan Rivera"
  },
  "updatedAt": "2024-06-02T10:12:44Z"
}

GET/screeners/{id}/publications

List screener publications

Retrieve the publication history for a specific screener. Each publication represents an immutable snapshot that can be activated for participants or referenced when analyzing responses. Use this endpoint to audit the version history before inviting new participants.

Path parameters

Name
id
Type
string
Description
Identifier of the screener whose publications you want to list.

Publication properties

Name
_type
Type
string
Description
Always ScreenerPublication.
Name
id
Type
string
Description
Unique identifier for the publication.
Name
screenerId
Type
string
Description
Screener that the publication belongs to.
Name
version
Type
number
Description
Incrementing version for the screener. Higher numbers represent newer publications.
Name
status
Type
'ACTIVE' | 'ARCHIVED'
Description
Indicates whether the publication currently accepts new sessions.
Name
targetQualifiedParticipants
Type
number | null
Description
Optional quota that records how many qualified participants the publication was targeting.
Name
tags
Type
Tag[]
Description
Tags that cascade to screener sessions. Each tag provides an _type, id, category, and value.
Name
createdBy
Type
Actor | null
Description
Actor who initially published the screener. Follows the Actor schema described earlier.
Name
createdAt
Type
timestamp | null
Description
Timestamp for when the publication was created.
Name
updatedBy
Type
Actor | null
Description
Actor who last updated metadata on the publication.
Name
updatedAt
Type
timestamp | null
Description
Timestamp of the most recent publication update.

Request

GET

/screeners/{id}/publications

curl https://api.spot-thought.com/screeners/scr_123/publications \
  -H "X-Spot-Api-Key: acct_123" \
  -H "X-Spot-Api-Secret": 'sk_live_abcd' \
  -H "X-Spot-Api-Version: 1.0.0"

Response

{
  "total": 2,
  "limit": 20,
  "offset": 0,
  "items": [
    {
      "_type": "ScreenerPublication",
      "id": "scpub_456",
      "screenerId": "scr_123",
      "version": 3,
      "status": "ACTIVE",
      "targetQualifiedParticipants": 120,
      "tags": [
        {
          "_type": "Tag",
          "id": "tag_priority",
          "category": "recruiting",
          "value": "priority"
        }
      ],
      "createdBy": {
        "_type": "TenantUserActor",
        "id": "user_789",
        "name": "Alex Lee"
      },
      "createdAt": "2024-05-30T15:10:09Z",
      "updatedBy": {
        "_type": "TenantUserActor",
        "id": "user_789",
        "name": "Alex Lee"
      },
      "updatedAt": "2024-05-30T15:10:09Z"
    },
    {
      "_type": "ScreenerPublication",
      "id": "scpub_123",
      "screenerId": "scr_123",
      "version": 2,
      "status": "ARCHIVED",
      "targetQualifiedParticipants": null,
      "tags": [],
      "createdBy": {
        "_type": "TenantUserActor",
        "id": "user_502",
        "name": "Morgan Rivera"
      },
      "createdAt": "2024-04-12T12:02:18Z",
      "updatedBy": {
        "_type": "TenantUserActor",
        "id": "user_502",
        "name": "Morgan Rivera"
      },
      "updatedAt": "2024-05-30T15:08:01Z"
    }
  ]
}

POST/screener-publications

Publish a screener

Publishing locks in the current screener definition and activates a new version number. Call this endpoint after making changes so that new screener sessions reference the latest questionnaire. The API clones the current screener content, assigns the next sequential version, and returns the publication metadata.

Required attributes

Name
screenerId
Type
string
Description
Identifier of the screener you want to publish.

Request

POST

/screener-publications

curl https://api.spot-thought.com/screener-publications \
  -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"
  }'

Response

{
  "_type": "ScreenerPublication",
  "id": "scpub_789",
  "screenerId": "scr_123",
  "version": 4,
  "status": "ACTIVE",
  "targetQualifiedParticipants": null,
  "tags": [
    {
      "_type": "Tag",
      "id": "tag_priority",
      "category": "recruiting",
      "value": "priority"
    }
  ],
  "createdBy": {
    "_type": "TenantUserActor",
    "id": "user_789",
    "name": "Alex Lee"
  },
  "createdAt": "2024-06-05T09:44:11Z",
  "updatedBy": {
    "_type": "TenantUserActor",
    "id": "user_789",
    "name": "Alex Lee"
  },
  "updatedAt": "2024-06-05T09:44:11Z"
}

GET/screener-publications/{id}

Retrieve a screener publication

Fetch a single publication by id to inspect its version number, tags, and audit metadata. This is helpful when you store references to activePublicationId and need to hydrate UI or analytics views with full details.

Path parameters

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

Request

GET

/screener-publications/{id}

curl https://api.spot-thought.com/screener-publications/scpub_456 \
  -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": "ScreenerPublication",
  "id": "scpub_456",
  "screenerId": "scr_123",
  "version": 3,
  "status": "ACTIVE",
  "targetQualifiedParticipants": 120,
  "tags": [
    {
      "_type": "Tag",
      "id": "tag_priority",
      "category": "recruiting",
      "value": "priority"
    }
  ],
  "createdBy": {
    "_type": "TenantUserActor",
    "id": "user_789",
    "name": "Alex Lee"
  },
  "createdAt": "2024-05-30T15:10:09Z",
  "updatedBy": {
    "_type": "TenantUserActor",
    "id": "user_789",
    "name": "Alex Lee"
  },
  "updatedAt": "2024-05-30T15:10:09Z"
}