Skip to main content
Formalingo

Manage Questions

Add and configure questions in your form.

Questions

GET/api/v1/forms/{id}/questions
Required scope:read:forms
POST/api/v1/forms/{id}/questions

Create a question

Required scope:write:forms
PUT/api/v1/forms/{id}/questions/{qid}

Update a question

Required scope:write:forms
DELETE/api/v1/forms/{id}/questions/{qid}

Delete a question

Required scope:write:forms

Question types

Text

TypeDescription
short_textSingle-line text input
long_textMulti-line text area
emailEmail address with validation
phonePhone number
urlURL with validation

Choice

TypeDescription
mcqMultiple choice (single answer)
multi_selectMultiple choice (multiple answers)
dropdownDropdown select
yes_noBoolean yes/no
checkboxSingle checkbox (e.g. agreement/consent)
picture_choiceImage-based choice with optional labels
rankingDrag-to-rank a list of items
matrixGrid of rows and columns

Rating & Scale

TypeDescription
ratingStar or numeric rating
opinion_scaleNumbered scale (e.g. 0–10) with labels
sliderDraggable slider with min/max/step

Number & Calculation

TypeDescription
numberNumeric input with optional min/max
currencyCurrency amount with currency code selector
calculationComputed field using formulas referencing other fields

Date & Time

TypeDescription
dateDate picker
timeTime picker (12h or 24h format)
date_rangeStart and end date range picker

Contact

TypeDescription
addressStructured address with configurable sub-fields

Upload & Signature

TypeDescription
file_uploadFile attachment
digital_signatureDraw or upload signature
initialsDraw initials

Payment

TypeDescription
paymentCollect payments via Stripe

Layout

TypeDescription
headingSection heading (no input collected)
dividerVisual separator (no input collected)

Type-specific options reference

Each question type accepts an options object with type-specific fields. All fields are optional unless noted.

short_text / long_text / email / phone / url

FieldTypeDescription
min_lengthintegerMinimum character count
max_lengthintegerMaximum character count
patternstringCustom regex pattern for validation (max 200 chars)
validation_messagestringCustom error message when validation fails

mcq / multi_select / dropdown

FieldTypeDescription
choicesstring[]Required. Array of option labels
max_selectionsinteger(multi_select only) Maximum selections allowed

picture_choice

FieldTypeDescription
picture_choicesobject[]Required. Array of { label, image_url? } objects

Each item in picture_choices:

FieldTypeDescription
labelstringRequired. Display text for the choice
image_urlstringImage URL (optional — text-only if omitted)

yes_no

FieldTypeDescription
yes_labelstringCustom "yes" text (default: "Yes")
no_labelstringCustom "no" text (default: "No")

rating

FieldTypeDescription
minintegerScale minimum (default: 1)
maxintegerScale maximum (default: 5)
min_labelstringLabel for lowest value (e.g. "Poor")
max_labelstringLabel for highest value (e.g. "Excellent")

opinion_scale

FieldTypeDescription
minintegerScale minimum (default: 1)
maxintegerScale maximum (default: 10)
min_labelstringLabel for lowest value
max_labelstringLabel for highest value

slider

FieldTypeDescription
min_valuenumberSlider minimum (default: 0)
max_valuenumberSlider maximum (default: 100)
stepnumberIncrement size (default: 1)
show_valuebooleanShow current value while dragging (default: true)

number

FieldTypeDescription
min_valuenumberMinimum allowed value
max_valuenumberMaximum allowed value

currency

FieldTypeDescription
currency_codestringISO 4217 code (default: "USD")
decimal_placesintegerPrecision 0–3 (default: 2)
min_valuenumberMinimum amount
max_valuenumberMaximum amount

date

FieldTypeDescription
min_datestringEarliest selectable date (YYYY-MM-DD)
max_datestringLatest selectable date (YYYY-MM-DD)

date_range

FieldTypeDescription
min_datestringEarliest start date allowed (YYYY-MM-DD)
max_datestringLatest end date allowed (YYYY-MM-DD)

Response value: { "start": "YYYY-MM-DD", "end": "YYYY-MM-DD" }

time

FieldTypeDescription
time_formatstring"12h" or "24h" (default: "24h")

address

FieldTypeDescription
address_fieldsstring[]Sub-fields to include: "street", "city", "state", "zip", "country". All included by default.

Response value: { "street": "...", "city": "...", "state": "...", "zip": "...", "country": "..." }

ranking

FieldTypeDescription
choicesstring[]Required. Items to rank via drag-and-drop

Response value: ordered array of choice labels.

matrix

FieldTypeDescription
rowsstring[]Required. Row labels
columnsstring[]Required. Column labels

Response value: { "row_label": "selected_column", ... }

file_upload

FieldTypeDescription
allowed_typesstring[]Accepted extensions: pdf, doc, docx, jpg, jpeg, png, gif, xlsx, csv
max_size_mbnumberMax file size in MB (1–100)

digital_signature / initials

FieldTypeDescription
signature_modestring"draw", "upload", or "both" (default: "both")

calculation

FieldTypeDescription
formulastringRequired. Arithmetic expression referencing other fields via {{Field Label}}. Supports +, -, *, /, ().
decimal_placesintegerPrecision 0–3 (default: 2)

Calculation questions are display-only and should not be marked as required.

payment

FieldTypeDescription
stripe_publishable_keystringRequired. Stripe publishable key (pk_live_… or pk_test_…)
amountintegerRequired. Amount in cents (e.g. 2999 = $29.99)
currency_codestringISO 4217 code (default: "USD")
payment_descriptionstringDescription shown to customer (defaults to question text)

heading / divider / checkbox

No options. heading uses question_text as the heading content. checkbox uses question_text as the agreement statement.


Quiz mode options

When quiz mode is enabled in form settings (quiz_mode: true), scorable question types accept additional fields in options:

Choice-based types (mcq, dropdown, multi_select, picture_choice, yes_no)

FieldTypeDescription
correct_answersstring[]Correct option label(s)
choice_scoresobjectLabel-to-points mapping: { "Option A": 10, "Option B": 5 }
correct_answer_pointsnumberFlat points for a correct answer (used when choice_scores is not set)

Numeric types (number, currency, rating, slider, opinion_scale)

FieldTypeDescription
correct_answer_valuenumberExact correct numeric answer
correct_answer_pointsnumberPoints awarded for a correct answer

Text type (short_text)

FieldTypeDescription
correct_answer_textstringExpected answer (case-insensitive match)
correct_answer_pointsnumberPoints awarded for a correct answer

Create a question

Request Body
NameTypeDescription
question_textstringThe question labelWhat is your full name?
typeQuestionTypeOne of the question types above
is_requiredbooleanWhether an answer is requiredfalse
section_iduuidAssign to a section
orderintegerPosition within the form (auto-appended if omitted)
optionsobjectType-specific options — see reference above

Examples

Text question

curl -X POST https://formalingo.com/api/v1/forms/FORM_ID/questions \
  -H "Authorization: Bearer af_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question_text": "What is your full name?",
    "type": "short_text",
    "is_required": true
  }'

Multiple choice

curl -X POST https://formalingo.com/api/v1/forms/FORM_ID/questions \
  -H "Authorization: Bearer af_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question_text": "How did you hear about us?",
    "type": "mcq",
    "options": { "choices": ["Social media", "Friend", "Search engine", "Other"] }
  }'

Picture choice

curl -X POST https://formalingo.com/api/v1/forms/FORM_ID/questions \
  -H "Authorization: Bearer af_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question_text": "Which design do you prefer?",
    "type": "picture_choice",
    "options": {
      "picture_choices": [
        { "label": "Modern", "image_url": "https://example.com/modern.jpg" },
        { "label": "Classic", "image_url": "https://example.com/classic.jpg" },
        { "label": "Minimal" }
      ]
    }
  }'

Rating

curl -X POST https://formalingo.com/api/v1/forms/FORM_ID/questions \
  -H "Authorization: Bearer af_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question_text": "Rate your overall experience",
    "type": "rating",
    "options": { "min": 1, "max": 5, "min_label": "Poor", "max_label": "Excellent" }
  }'

Slider

curl -X POST https://formalingo.com/api/v1/forms/FORM_ID/questions \
  -H "Authorization: Bearer af_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question_text": "How likely are you to recommend us?",
    "type": "slider",
    "options": { "min_value": 0, "max_value": 100, "step": 5, "show_value": true }
  }'

Matrix

curl -X POST https://formalingo.com/api/v1/forms/FORM_ID/questions \
  -H "Authorization: Bearer af_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question_text": "Rate each aspect of our service",
    "type": "matrix",
    "options": {
      "rows": ["Speed", "Quality", "Support"],
      "columns": ["Poor", "Fair", "Good", "Excellent"]
    }
  }'

Opinion scale

curl -X POST https://formalingo.com/api/v1/forms/FORM_ID/questions \
  -H "Authorization: Bearer af_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question_text": "How satisfied are you?",
    "type": "opinion_scale",
    "options": { "min": 0, "max": 10, "min_label": "Not at all", "max_label": "Extremely" }
  }'

Ranking

curl -X POST https://formalingo.com/api/v1/forms/FORM_ID/questions \
  -H "Authorization: Bearer af_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question_text": "Rank these features by importance",
    "type": "ranking",
    "options": { "choices": ["Performance", "Ease of use", "Price", "Support"] }
  }'

Currency

curl -X POST https://formalingo.com/api/v1/forms/FORM_ID/questions \
  -H "Authorization: Bearer af_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question_text": "What is your monthly budget?",
    "type": "currency",
    "options": { "currency_code": "EUR", "decimal_places": 2, "min_value": 0 }
  }'

Address

curl -X POST https://formalingo.com/api/v1/forms/FORM_ID/questions \
  -H "Authorization: Bearer af_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question_text": "Shipping address",
    "type": "address",
    "is_required": true,
    "options": { "address_fields": ["street", "city", "state", "zip", "country"] }
  }'

File upload

curl -X POST https://formalingo.com/api/v1/forms/FORM_ID/questions \
  -H "Authorization: Bearer af_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question_text": "Upload your resume",
    "type": "file_upload",
    "is_required": true,
    "options": { "allowed_types": ["pdf", "doc", "docx"], "max_size_mb": 10 }
  }'

Digital signature

curl -X POST https://formalingo.com/api/v1/forms/FORM_ID/questions \
  -H "Authorization: Bearer af_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question_text": "Please sign below",
    "type": "digital_signature",
    "is_required": true,
    "options": { "signature_mode": "both" }
  }'

Calculation

curl -X POST https://formalingo.com/api/v1/forms/FORM_ID/questions \
  -H "Authorization: Bearer af_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question_text": "Total Cost",
    "type": "calculation",
    "options": { "formula": "{{Quantity}} * {{Unit Price}}", "decimal_places": 2 }
  }'

Payment

curl -X POST https://formalingo.com/api/v1/forms/FORM_ID/questions \
  -H "Authorization: Bearer af_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question_text": "Registration fee",
    "type": "payment",
    "is_required": true,
    "options": {
      "stripe_publishable_key": "pk_live_YOUR_KEY",
      "amount": 4999,
      "currency_code": "USD",
      "payment_description": "Conference registration"
    }
  }'

Date range

curl -X POST https://formalingo.com/api/v1/forms/FORM_ID/questions \
  -H "Authorization: Bearer af_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question_text": "Preferred travel dates",
    "type": "date_range",
    "options": { "min_date": "2026-04-01", "max_date": "2026-12-31" }
  }'

Quiz: scored multiple choice

curl -X POST https://formalingo.com/api/v1/forms/FORM_ID/questions \
  -H "Authorization: Bearer af_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question_text": "What is the capital of France?",
    "type": "mcq",
    "is_required": true,
    "options": {
      "choices": ["London", "Berlin", "Paris", "Madrid"],
      "correct_answers": ["Paris"],
      "choice_scores": { "Paris": 10, "London": 0, "Berlin": 0, "Madrid": 0 }
    }
  }'

On this page