Create a question

client.questions.create(, ?): Question

POST/v5/questions

Create a new question owned by the caller’s account.

The question is one of six types selected by the required question_type discriminator (categorical, rating, number, free_text, form, or timestamp), and each type carries its own configuration block; name and prompt are required for every type. Questions are the reusable units that are grouped into question sets and referenced by rubrics, so create them before assembling a question set. The created question is scoped to the caller’s account and records the creating identity. The question type and its configuration are set at creation time and cannot be changed afterward through the update endpoint.

ParametersExpand Collapse

params: QuestionCreateParams { question }

question: CategoricalQuestionRequest { configuration, name, prompt, 2 more } | RatingQuestionRequest { configuration, name, prompt, 2 more } | NumberQuestionRequest { name, prompt, conditions, 2 more } | 3 more

One of the following:

CategoricalQuestionRequest { configuration, name, prompt, 2 more }

configuration: CategoricalQuestionConfiguration { choices, dropdown, multi }

choices: Array<string>

Categorical answer choices (must contain at least one entry)

multi?: boolean

Whether the question allows multiple answers.

prompt: string

user-facing question prompt

conditions?: Array<Record<string, unknown>>

Conditions for the question to be shown

question_type?: "categorical"

RatingQuestionRequest { configuration, name, prompt, 2 more }

configuration: RatingQuestionConfiguration { max_label, min_label, steps }

max_label: string

Label shown for the maximum rating

min_label: string

Label shown for the minimum rating

steps: number

Number of discrete points on the scale (e.g., 5 for a 1–5 scale)

minimum1

prompt: string

user-facing question prompt

conditions?: Array<Record<string, unknown>>

Conditions for the question to be shown

question_type?: "rating"

NumberQuestionRequest { name, prompt, conditions, 2 more }

prompt: string

user-facing question prompt

conditions?: Array<Record<string, unknown>>

Conditions for the question to be shown

configuration?: NumberQuestionConfiguration { max, min }

max?: number

Maximum value for the number

min?: number

Minimum value for the number

question_type?: "number"

FreeTextQuestionRequest { name, prompt, conditions, 2 more }

prompt: string

user-facing question prompt

conditions?: Array<Record<string, unknown>>

Conditions for the question to be shown

configuration?: FreeTextQuestionConfiguration { max_length, min_length }

max_length?: number

Maximum characters allowed

minimum1

min_length?: number

Minimum characters required

minimum0

question_type?: "free_text"

FormQuestionRequest { configuration, name, prompt, 2 more }

configuration: FormQuestionConfiguration { form_schema }

form_schema: Record<string, unknown>

The JSON schema of the desired form object

prompt: string

user-facing question prompt

conditions?: Array<Record<string, unknown>>

Conditions for the question to be shown

question_type?: "form"

TimestampQuestionRequest { name, prompt, conditions, 2 more }

prompt: string

user-facing question prompt

conditions?: Array<Record<string, unknown>>

Conditions for the question to be shown

configuration?: TimestampQuestionConfiguration { multi }

multi?: boolean

Whether to allow multiple timestamps

question_type?: "timestamp"

ReturnsExpand Collapse

Question = CategoricalQuestion { id, configuration, created_at, 7 more } | RatingQuestion { id, configuration, created_at, 7 more } | NumberQuestion { id, created_at, created_by, 7 more } | 3 more

One of the following:

CategoricalQuestion { id, configuration, created_at, 7 more }

id: string

Unique identifier of the entity

configuration: CategoricalQuestionConfiguration { choices, dropdown, multi }

choices: Array<string>

Categorical answer choices (must contain at least one entry)

multi?: boolean

Whether the question allows multiple answers.

created_at: string

ISO-timestamp when the entity was created

formatdate-time

created_by: Identity { id, type, object }

The identity that created the entity.

id: string

type: "user" | "service_account"

One of the following:

"user"

"service_account"

object?: "identity"

prompt: string

user-facing question prompt

archived_at?: string

ISO-timestamp when the entity was archived

formatdate-time

conditions?: Array<Record<string, unknown>>

Conditions for the question to be shown

object?: "question"

question_type?: "categorical"

RatingQuestion { id, configuration, created_at, 7 more }

id: string

Unique identifier of the entity

configuration: RatingQuestionConfiguration { max_label, min_label, steps }

max_label: string

Label shown for the maximum rating

min_label: string

Label shown for the minimum rating

steps: number

Number of discrete points on the scale (e.g., 5 for a 1–5 scale)

minimum1

created_at: string

ISO-timestamp when the entity was created

formatdate-time

created_by: Identity { id, type, object }

The identity that created the entity.

id: string

type: "user" | "service_account"

One of the following:

"user"

"service_account"

object?: "identity"

prompt: string

user-facing question prompt

archived_at?: string

ISO-timestamp when the entity was archived

formatdate-time

conditions?: Array<Record<string, unknown>>

Conditions for the question to be shown

object?: "question"

question_type?: "rating"

NumberQuestion { id, created_at, created_by, 7 more }

id: string

Unique identifier of the entity

created_at: string

ISO-timestamp when the entity was created

formatdate-time

created_by: Identity { id, type, object }

The identity that created the entity.

id: string

type: "user" | "service_account"

One of the following:

"user"

"service_account"

object?: "identity"

prompt: string

user-facing question prompt

archived_at?: string

ISO-timestamp when the entity was archived

formatdate-time

conditions?: Array<Record<string, unknown>>

Conditions for the question to be shown

configuration?: NumberQuestionConfiguration { max, min }

max?: number

Maximum value for the number

min?: number

Minimum value for the number

object?: "question"

question_type?: "number"

FreeTextQuestion { id, created_at, created_by, 7 more }

id: string

Unique identifier of the entity

created_at: string

ISO-timestamp when the entity was created

formatdate-time

created_by: Identity { id, type, object }

The identity that created the entity.

id: string

type: "user" | "service_account"

One of the following:

"user"

"service_account"

object?: "identity"

prompt: string

user-facing question prompt

archived_at?: string

ISO-timestamp when the entity was archived

formatdate-time

conditions?: Array<Record<string, unknown>>

Conditions for the question to be shown

configuration?: FreeTextQuestionConfiguration { max_length, min_length }

max_length?: number

Maximum characters allowed

minimum1

min_length?: number

Minimum characters required

minimum0

object?: "question"

question_type?: "free_text"

FormQuestion { id, configuration, created_at, 7 more }

id: string

Unique identifier of the entity

configuration: FormQuestionConfiguration { form_schema }

form_schema: Record<string, unknown>

The JSON schema of the desired form object

created_at: string

ISO-timestamp when the entity was created

formatdate-time

created_by: Identity { id, type, object }

The identity that created the entity.

id: string

type: "user" | "service_account"

One of the following:

"user"

"service_account"

object?: "identity"

prompt: string

user-facing question prompt

archived_at?: string

ISO-timestamp when the entity was archived

formatdate-time

conditions?: Array<Record<string, unknown>>

Conditions for the question to be shown

object?: "question"

question_type?: "form"

TimestampQuestion { id, created_at, created_by, 7 more }

id: string

Unique identifier of the entity

created_at: string

ISO-timestamp when the entity was created

formatdate-time

created_by: Identity { id, type, object }

The identity that created the entity.

id: string

type: "user" | "service_account"

One of the following:

"user"

"service_account"

object?: "identity"

prompt: string

user-facing question prompt

archived_at?: string

ISO-timestamp when the entity was archived

formatdate-time

conditions?: Array<Record<string, unknown>>

Conditions for the question to be shown

configuration?: TimestampQuestionConfiguration { multi }

multi?: boolean

Whether to allow multiple timestamps

object?: "question"

question_type?: "timestamp"

Create a question

import SGPClient from 'scale-gp';

const client = new SGPClient({
  accountID: 'My Account ID',
  apiKey: process.env['SGP_API_KEY'], // This is the default and can be omitted
});

const question = await client.questions.create({
  question: {
    configuration: { choices: ['string'] },
    name: 'name',
    prompt: 'prompt',
    question_type: 'categorical',
  },
});

console.log(question);

{
  "id": "id",
  "configuration": {
    "choices": [
      "string"
    ],
    "dropdown": true,
    "multi": true
  },
  "created_at": "2019-12-27T18:11:19.117Z",
  "created_by": {
    "id": "id",
    "type": "user",
    "object": "identity"
  },
  "name": "name",
  "prompt": "prompt",
  "archived_at": "2019-12-27T18:11:19.117Z",
  "conditions": [
    {
      "foo": "bar"
    }
  ],
  "object": "question",
  "question_type": "categorical"
}

Returns Examples

{
  "id": "id",
  "configuration": {
    "choices": [
      "string"
    ],
    "dropdown": true,
    "multi": true
  },
  "created_at": "2019-12-27T18:11:19.117Z",
  "created_by": {
    "id": "id",
    "type": "user",
    "object": "identity"
  },
  "name": "name",
  "prompt": "prompt",
  "archived_at": "2019-12-27T18:11:19.117Z",
  "conditions": [
    {
      "foo": "bar"
    }
  ],
  "object": "question",
  "question_type": "categorical"
}