---
title: "Scanning questions"
description: "Manage sponsor-owned questions and choice options used when collecting leads."
lastModified: "2026-10-09"
---

> **Release timing:** This page includes changes planned for 9 October 2026. See the [deployment note](https://docs.brella.io/changelog/update-2026-10-09-sponsor-scanning-and-qr) before using the updated operations or inputs.

Scanning questions belong to sponsors in the URL event and define questions asked during lead collection. Configure a separate `ScanningQuestion` scope; event-owned custom field definitions are a [different resource](https://docs.brella.io/reference/custom-field-definitions).

## Operations


### GET scanning-questions

Requires an enabled event-level scope, context access, and Read permission. Response fields, query filters and included associations are scope-controlled.


```shell
curl --fail-with-body --silent --show-error --globoff --max-time 30 --request GET \
  --url "${BRELLA_API_BASE_URL}"'/api/core/organizations/123/events/456/scanning-questions' \
  --header "Accept: application/vnd.brella.v4+json" \
  --header "Brella-API-Access-Token: ${BRELLA_API_ACCESS_TOKEN}"
```

For an individual record, append its Brella ID to the path. List responses use a data array and pagination metadata. Default page size 30, maximum 100.

Errors: 400 invalid parameters; 403 invalid token or disallowed action; 404 inaccessible context/record; 422 validation or business rules; 429 rate limit. See [responses and errors](https://docs.brella.io/concepts/responses-and-errors).

### POST scanning-questions

Requires an enabled event-level scope, context access, and Write permission with the create action. Every input must be mapped in Writable fields.


```shell
curl --fail-with-body --silent --show-error --globoff --max-time 30 --request POST \
  --url "${BRELLA_API_BASE_URL}"'/api/core/organizations/123/events/456/scanning-questions' \
  --header "Accept: application/vnd.brella.v4+json" \
  --header "Brella-API-Access-Token: ${BRELLA_API_ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "sponsor_id": 103705,
  "title": "When will you purchase?",
  "field_type": "SingleChoice",
  "options": [
    "This quarter",
    "Next quarter"
  ]
}'
```

Success: 201 Created. Save data.id; attributes follow Write-response fields.

Errors: 400 invalid parameters; 403 invalid token or disallowed action; 404 inaccessible context/record; 422 validation or business rules; 429 rate limit. See [responses and errors](https://docs.brella.io/concepts/responses-and-errors).

### PATCH scanning-questions

Requires an enabled event-level scope, context access, and Write permission with the update action. Every input must be mapped in Writable fields.


```shell
curl --fail-with-body --silent --show-error --globoff --max-time 30 --request PATCH \
  --url "${BRELLA_API_BASE_URL}"'/api/core/organizations/123/events/456/scanning-questions/901' \
  --header "Accept: application/vnd.brella.v4+json" \
  --header "Brella-API-Access-Token: ${BRELLA_API_ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "title": "When do you expect to purchase?"
}'
```

Success: 200 OK. PATCH collection inputs can replace existing data; read the field notes.

Errors: 400 invalid parameters; 403 invalid token or disallowed action; 404 inaccessible context/record; 422 validation or business rules; 429 rate limit. See [responses and errors](https://docs.brella.io/concepts/responses-and-errors).

### DELETE scanning-questions

Requires an enabled event-level scope, context access, and Write permission with the delete action. Every input must be mapped in Writable fields.


```shell
curl --fail-with-body --silent --show-error --globoff --max-time 30 --request DELETE \
  --url "${BRELLA_API_BASE_URL}"'/api/core/organizations/123/events/456/scanning-questions/1201' \
  --header "Accept: application/vnd.brella.v4+json" \
  --header "Brella-API-Access-Token: ${BRELLA_API_ACCESS_TOKEN}"
```

Success: 204 No Content. Deletion can remove related data or be refused by constraints.

Errors: 400 invalid parameters; 403 invalid token or disallowed action; 404 inaccessible context/record; 422 validation or business rules; 429 rate limit. See [responses and errors](https://docs.brella.io/concepts/responses-and-errors).


**Path:** `events/{event_id}/scanning-questions`

**Methods:** GET collection/record, POST, PATCH, DELETE. Response type: `scanning-question`.

## Fields, filters and restrictions


Response fields are selected by the token scope. ID is always included.

- `sponsor-id` (scope: `sponsor_id`)
- `key` (scope: `key`)
- `title` (scope: `title`)
- `field-type` (scope: `field_type`)
- `options` (scope: `options`)
- `position` (scope: `position`)
- `created-at` (scope: `created_at`)
- `updated-at` (scope: `updated_at`)


Optional filters: `sponsor_id`, `field_type`. There are no included associations. A named `sponsor` row restriction limits reads and writes to selected sponsors; inaccessible questions return 404. Every sponsor ID must belong to the URL event.

```text
GET .../scanning-questions?sponsor_id=103705&field_type=SingleChoice
```

## Writing and validation

Create requires `sponsor_id`, `title` and `field_type`. Titles contain 1–1,000 characters. Types are `Text`, `SingleChoice` and `MultipleChoice`; `CustomValues` definitions are excluded. The API generates the `key` and sets the lead-scanning role and target type. Client-supplied `key`, `role` and `customizable_type` are not writable here.

Choice types require `options`: at most 50 non-empty strings, each at most 1,000 characters. Numeric and boolean options are rejected. Non-empty options are invalid for `Text`. A supplied options array replaces the current options. When changing to a choice type, supply valid options in the same PATCH; when changing to `Text`, clear the options with `[]`.

PATCH can update only `title`, `field_type`, `options` and `position`. A mapped `sponsor_id` supplied on PATCH returns 400; the question cannot move to another sponsor. Omitted fields remain unchanged. A title-only PATCH can preserve legacy options that exceed today's bounds; changing options or field type applies the current validation rules.

`position` is a non-null integer within the signed 32-bit range, normalized to the valid list insertion range starting at 1. Order is within that sponsor's lead-scanning questions. Omit it on create to append or on PATCH to retain the current position.

**DELETE removes the question and its collected answers.** Confirm that data loss before using the delete action. Questions referenced by other rules may be refused by validation constraints.

See [complete scanning-question write inputs and examples](https://docs.brella.io/cookbook/scanning-questions) and [lead answer updates](https://docs.brella.io/cookbook/leads).

### sponsor_id

Type: Scalar ID. POST: Required. PATCH: Rejected when mapped and supplied.

Sponsor in the URL event. The question cannot move to another sponsor; mapped sponsor_id on PATCH returns 400. Sponsor row restrictions also apply.

### title

Type: Scalar string. POST: Required. PATCH: Optional.

Question title, 1–1,000 characters.

### field_type

Type: Scalar string. POST: Required. PATCH: Optional.

Text, SingleChoice or MultipleChoice. CustomValues is unavailable. A transition to a choice type needs valid options in the same request.

### options

Type: Array of strings. POST: Required for choice types. PATCH: Optional; replaces options.

At most 50 non-empty strings, each at most 1,000 characters. Numeric and boolean values are rejected. Non-empty options are allowed only for choice types. Use [] when changing to Text. Title-only PATCH can preserve legacy options.

### position

Type: Scalar number. POST: Optional; appended when omitted. PATCH: Optional.

Non-null integer within the signed 32-bit range; normalized to the valid list insertion range starting at 1. Order is within the sponsor's lead-scanning questions.