# Create questions

URL: /docs/developers/questions/create

You do not build a survey in Orvelt. You add questions to the project's library, and Orvelt asks each customer the few that matter most right now ([how that works](/docs/research/how-questions-are-picked)). In Orvelt Business, setting a goal adds related questions for you. Create questions through the API when they come from your own system, such as a new product line, or when you keep many projects in sync.

![The Create question dialog shows a multiple-choice question and its customer preview, with Save as draft and Set active buttons.](/hc/screenshots/business-question-editor.png)

## Write a question worth asking [#write-a-question-worth-asking]

### What works [#what-works]

- **Ask about one thing.** "How was the wait?" gets clearer answers than "How was the wait and the food?"
- **Ask what the customer experienced,** not what they predict or would rate in general.
- **Offer choices when you want to count answers,** and free text when you want to hear why.
- **Tag it honestly.** Tags tell Orvelt what an answer reveals, such as `Trust` or `Experience`. They drive [Auto priority](/docs/developers/questions/priority), so a wrong tag makes Orvelt ask the question at the wrong times.

## Add the question [#add-the-question]

Questions need the `questions` create permission, which new API keys include.

### Example [#example]

**TypeScript SDK**

```ts
import { questions } from '@orvelt/business';

const result = await questions.create({
  projectId: 'PROJECT_ID',
  question: 'What would make your next visit better?',
  tags: ['Experience'],
  priority: 50,
  isAutoPriority: true,
  answerMode: 'single_select',
  answers: {
    options: [
      { id: crypto.randomUUID(), option: 'Speed' },
      { id: crypto.randomUUID(), option: 'Price' },
      { id: crypto.randomUUID(), option: 'Service', description: 'Staff and support' },
    ],
  },
  status: 'active',
  responseVisibility: 'default',
});

if (result.error) throw new Error(result.error.message);
const questionId = result.data.question.id;
```

**Python SDK**

```python
import os
from uuid import uuid4
from orvelt_business import Orvelt

with Orvelt(business_api_key=os.environ["ORVELT_BUSINESS_API_KEY"]) as client:
    result = client.questions.create(
        project_id="PROJECT_ID",
        question="What would make your next visit better?",
        tags=["Experience"],
        priority=50,
        is_auto_priority=True,
        answer_mode="single_select",
        answers={
            "options": [
                {"id": str(uuid4()), "option": "Speed"},
                {"id": str(uuid4()), "option": "Price"},
                {"id": str(uuid4()), "option": "Service", "description": "Staff and support"},
            ],
        },
        status="active",
        response_visibility="default",
    )
    question_id = result.question.id
```

Field names below use the HTTP API's camelCase. Python uses snake_case, such as `is_auto_priority`, `answer_mode`, and `response_visibility`.

Save `question.id`: you need it to [read the answers](/docs/developers/questions/results) and to change the question later. Creating an active question beyond the plan's limit returns `403 PLAN_LIMIT_REACHED`.

### Choose how customers answer [#choose-how-customers-answer]

- `text_only`: customers answer in their own words. Do not send `answers.options`.
- `single_select`: customers choose one option.
- `multi_select`: customers choose any number of options.

Select questions need 2 to 6 options in `answers.options`. Each has a unique `id` of up to 64 characters, unique `option` text, and an optional `description`. Answers report the chosen option's text, not its `id`.

### Keep sensitive answers private [#keep-sensitive-answers-private]

Set `responseVisibility: 'private'` when answers should stay with your team, such as questions about staff or safety. Private answers are never available through public storefront reads. `default` answers follow the opinion they come with: public when the customer's opinion is public, and never shown publicly when the customer answers without writing an opinion. Both visibilities consume the same monthly answer allowance; no fresh questions are offered once it runs out.

## Check it is being asked [#check-it-is-being-asked]

### Confirm the setup [#confirm-the-setup]

1. Call [`questions.list`](/docs/developers/questions/results#see-your-question-library) and confirm the question is `active` and `activeCount` is within `activeLimit`.
2. Open your project as a customer who has not answered it yet. Expect up to three questions, not necessarily this one: Orvelt picks a fresh set for each customer.
3. If it never appears, check its status, your plan's active-question limit, the shared answer allowance, and whether that customer already answered it.

## All fields [#all-fields]

### `questions.create` [#questionscreate]

| Field | Required | Values |
| --- | --- | --- |
| `question` | Yes | `1` through `500` characters. |
| `tags` | No | At least 1 of `Trust`, `Reliability`, `Experience`, `Safety`, `Personalization`, `Fairness`, `Identity`, or `Outcome`. Omit it to let Orvelt choose. |
| `isAutoTags` | No | `true` lets Orvelt choose `tags` from the question and its options, and choose again when they change. Defaults to `true` when `tags` is omitted; it can't be `true` alongside `tags`. |
| `priority` | No | `1` through `100`: where Auto starts, or the fixed value in manual mode. Defaults to `50`. |
| `isAutoPriority` | No | Defaults to `true`, letting Orvelt manage `priority`; `false` keeps it fixed. |
| `answerMode` | Yes | `text_only`, `single_select`, or `multi_select`. |
| `status` | Yes | `active` or `archived`. |
| `responseVisibility` | Yes | `default` or `private`. Set once: `questions.update` cannot change it. |
| `answers` | No | Defaults to `{}`. Select questions need `answers.options`. |

Omit `tags`, `isAutoTags`, `priority`, and `isAutoPriority` to let Orvelt choose tags and manage priority automatically, starting at 50. On `questions.update`, omitted fields preserve the existing settings; sending `tags` switches the question to manual tags.