Questions API reference
Manage choice and input questions, answer options, synchronization, and nested input settings.
Use questions to collect answers in a flow or form. Question configuration is separate from the segment group that an answer can assign.
Authentication and question operations
Paths below follow https://api.rightmessage.com/v1/{teamPid}. GET requires read or write; mutations require write. The * ability satisfies both. The shared request conventions cover bearer authentication, headers, project access, and rate limits.
| Method and path | Request | Success |
|---|---|---|
GET /questions | No filters or pagination parameters | 200, {"data":[RESOURCE]} |
GET /questions/{question} | Resource ID from the list | 200, {"data":RESOURCE} |
POST /questions | Create body below | 201, {"data":RESOURCE} |
PUT or PATCH /questions/{question} | Partial body below | 200, {"data":RESOURCE} |
DELETE /questions/{question} | No body | 204, empty body |
PUT and PATCH have the same partial-update behavior. An omitted top-level field retains its value. A collection with no resources returns {"data":[]}. Reads return the draft when one exists, otherwise the stable configuration.
Errors and draft effects
The shared error contract applies. Invalid request fields return 422 with message and field-keyed errors. Full-configuration validation can return 500 instead.
Mutations save a draft, not live changes. Publishing applies the whole project draft, including edits made elsewhere. The draft contract covers snapshots, dashboard updates, and save failures.
Question fields
Only text is required on create. All fields are optional on update.
| Field | Type and validation | Create default |
|---|---|---|
text | Nonempty string, maximum 500 | Required |
name | String, maximum 255 | Omitted |
description | Nullable string | Omitted |
sync_to | HTTP accepts a nullable string; the stored schema accepts only customField, variable, or null. This is not a provider name. | null |
sync_to_field | Nullable destination-field or variable-name string | null |
display_options | Object | {} |
segment_group_id | Nullable string identifying an existing group | null |
display_type | buttons, image, list, radio, or input | buttons |
input_type | Nullable string: text, textarea, number, email, phone, name, address, country, url, date, rating, or nps | null |
input_settings | Nullable object, detailed below | null in response |
randomize_options | Boolean | false |
options | Array of option objects | [] |
other_option | Object, detailed below | Disabled, with repaired labels below |
A non-input question stores input_type as null, even if supplied. It retains shared input_settings, including next-button behavior.
Answer options
Each options[] object accepts required label, a string up to 255 characters; optional string id; nullable string segment_id; optional string image_url; and optional objects or arrays conditions and scores.
New option IDs use rqo_. When segment_group_id is supplied, every nonempty option segment_id must belong to that group. Invalid references return 422 at the group or option field path.
The stored option schema requires a non-null segment_id matching seg_ followed by word characters, or the reserved $everyone value. Omitting it or sending null passes the shallow optional/nullable request rule but fails full-configuration validation. The request only checks group membership when a nonempty segment_group_id is included in that same request; it does not use the question's existing group to validate an options-only update.
conditions is a logic object with recursive and, or, or not conditions. An empty input becomes {}. Answer-based conditions use $source: "answers", questionId, operator, and an operator-specific value. Stored condition validation also checks question dependencies.
scores is an array of {"score":"score-name","amount":1} objects. score must be a nonempty string and amount numeric. The service drops malformed entries and converts numeric strings to numbers.
Supplying options replaces all options. Preserve option IDs that must remain stable. Supplying input_settings, display_options, or other_option replaces that object rather than merging its omitted children.
Answer condition operators
An answer condition is a closed object containing $source: "answers", a raq_-prefixed questionId, operator, and value only when required below. The server also validates whether the operator fits the referenced question.
| Operator | Value contract |
|---|---|
has answered, has not answered, is empty, is not empty, is a business email, is a personal email, has last name, has no last name, in the past, in the future | value must be absent |
equals | Required number or string |
does not equal, greater than, greater than or equal to, less than, less than or equal to | Required number |
contains, starts with | Required string |
before, after, on | Required valid YYYY-MM-DD date string |
between | Required array of exactly two numbers or exactly two valid YYYY-MM-DD strings |
is, is not, country is, country is not | Required uppercase two-letter string |
is any of, country is any of | Required nonempty array of uppercase two-letter strings |
domain is, domain is not, domain ends with | Required hostname string, maximum 253 characters, with at least one dot. Labels use letters, digits, and internal hyphens; the last label starts with a letter. No scheme, path, or port. |
domain is any of | Required nonempty array of hostnames with the same constraints |
region equals, city equals, postal code starts with, first name equals, first name contains | Required string containing a non-whitespace character |
within the next days, within the last days | Required integer, 0 through 9,007,199,254,740,991 |
The referenced question must exist and use display_type: "input". Both presence operators work for every input type. Other operators are restricted as follows:
| Input type | Additional operators |
|---|---|
number, rating, nps | equals, does not equal, greater than, greater than or equal to, less than, less than or equal to, between |
date | before, after, on, between, in the past, in the future, within the next days, within the last days |
country | is, is not, is any of |
phone | country is, country is not, country is any of |
email | domain is, domain is not, domain is any of, domain ends with, is a business email, is a personal email |
address | country is, country is not, country is any of, region equals, city equals, postal code starts with |
name | first name equals, first name contains, has last name, has no last name |
url | equals, contains, starts with, is empty, is not empty, domain is, domain ends with |
text, textarea | equals, contains, starts with, is empty, is not empty |
Numeric questions require numeric values; text and URL comparisons require strings. Date ranges require dates. The first value in a between range must not exceed the second.
Input settings
All fields below are optional inside input_settings, unless a nested object's presence makes a child required. CamelCase is intentional.
| Keys | Type and restrictions |
|---|---|
placeholder | String, maximum 255 |
validation, currency, prefix, suffix, minLabel, maxLabel, defaultCountry | Strings |
required, detectCountry, mobileOnly, suggestTypoFixes, identify | Booleans |
nextButtonLabel, skipButtonLabel | Nullable strings |
numberType | plain, currency, or percentage |
min, max, step, defaultValue | Nullable numbers. No request-level min/max relationship check. |
display | field or slider |
ratingMax | Integer, 3 through 10 |
nameFormat | first_last or full |
dateRange | any, past, or future |
dateRangeDays | Integer, 1 through 36,500 |
partLabels | Object of string values. Only first, last, street, city, region, postcode, and country keys. |
partPlaceholders | Same allowed keys as partLabels, plus full. String values. |
pinnedCountries, excludedCountries | Arrays of two-letter strings matching ^[A-Za-z]{2}$ |
syncFieldMap | Object of string values |
contactAction | Nullable object. When present, requires type, settings, and settings.partnerName. |
contactAction.type | contact, form, list, or tag |
contactAction.settings.partnerName | Provider-name string |
contactAction.settings.formIds, listIds, tagIds | Optional arrays of strings inside contactAction.settings |
consent | Object with optional disclosure and checkbox objects |
consent.disclosure | Requires boolean enabled and string text when supplied |
consent.checkbox | Requires boolean enabled and string label when supplied |
contactAction, its settings, consent, and its disclosure and checkbox objects are closed in the stored schema. Undeclared keys fail configuration validation even when request validation accepts them. The overall input_settings object is open.
The API has no per-field default for omitted input settings. It returns the stored object. Runtime control defaults are not automatically expanded into this response.
Other-answer settings
other_option accepts boolean enabled, string label up to 255, string input_type, string prompt up to 500, nullable string placeholder, and nullable string sync_to_custom_field. The HTTP request does not enumerate Other input types. Repair fills omitted values with enabled: false, label: "Other", input_type: "textarea", prompt: "Please share more", and placeholder: "". An empty object disables Other and restores those labels. A null placeholder is repaired to an empty string; a null custom-field mapping remains null.
Question responses and deletion behavior
The resource contains the question fields above plus id. Optional name and description appear only when stored. Options contain id, segment_id, label, conditions, and scores; image_url appears when stored. Empty input settings return null. Question IDs use raq_.
Deleting a question can fail if answer conditions still reference it. Successful deletion removes matching question fields from forms using the question ID or its group ID. It does not remove related resources in the same way as deleting a segment group. Review remaining flow references. Active question tests can also lock changes when saving configuration.
Illustrative requests and responses
These illustrative examples use the fictional WorkForge project. The same resource schema covers every CRUD response.
The PATCH example also works with PUT. The create, item-read, and update envelopes have this shape. The list places these resource objects in its data array. An update returns the updated values. DELETE returns no JSON.