---
title: "Add a field"
method: POST
path: "/sheets/{sheetId}/fields"
tags: ["fields"]
---

# Add a field

`POST /sheets/{sheetId}/fields`

## Request

- Base URL: `https://api.orcascan.com/v1`
- URL: `https://api.orcascan.com/v1/sheets/{sheetId}/fields`
- Auth: HTTP bearer

## Request body

- NewField: Writable field configuration properties
  - `label` string, required: Field display name
  - `format` 'text' | 'barcode' | 'number' | 'number (auto increase on scan)' | 'number (auto decrease on scan)' | 'date' | 'date (automatic)' | 'date time' | 'date time (automatic)' | 'time' | 'email' | 'gps location' | 'gps location (automatic)' | 'true/false' | 'currency' | 'drop-down list' | 'formula' | 'signature' | 'unique id' | 'photo' | 'attachment' | 'url' | 'created by' | 'created date' | 'last modified by' | 'last modified date', required: Field data type
  - `default` string: Default value for new rows
  - `listOptions` union: Options for drop-down list fields
    - string
    - string[]
  - `multiSelect` boolean: Allow multiple selections for drop-down list fields
  - `formula` string: Formula for formula fields, using column names in square brackets, e.g. `[Quantity] * [Price]` (numbers only)
  - `currencyType` string: 3-letter currency code for currency fields
  - `locked` boolean: Prevent field from being edited
  - `minLength` integer: Minimum text length
  - `maxLength` integer: Maximum text length
  - `minimum` number: Minimum numeric value
  - `maximum` number: Maximum numeric value
  - `placeholder` string: Placeholder text shown when field is empty
  - `prefix` string: Text prefix displayed before the value
  - `suffix` string: Text suffix displayed after the value
  - `length` integer: Fixed length for unique ID fields
  - `required` boolean: Whether the field must have a value
  - `autofocus` boolean: Automatically focus this field on mobile
  - `autoselect` boolean: Automatically select field content on focus
  - `emptyOnEdit` boolean: Clear field value when editing a row
  - `emptyOnScan` boolean: Clear field value when scanning a barcode
  - `hiddenMobile` boolean: Hide field on mobile devices
  - `hiddenWeb` boolean: Hide field in web interface
  - `readonlyWeb` boolean: Make field read-only in web interface
  - `readonlyMobile` boolean: Make field read-only on mobile devices
  - `useInMobileSearch` boolean: Include field in mobile search results
  - `useValueInList` boolean: Show field value in mobile list view
  - `allowDuplicates` boolean: Allow duplicate values (barcode field only)
  - `index` integer: Display order position

## Response `200`

Created field wrapped in data envelope

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key
- `409`: Resource already exists
- `429`: Rate limit exceeded (15 requests/sec per IP). Retry after the specified delay.

---

[API](https://skmtc.dev/orcascan/apis/orca-scan-rest-api.md) · [All operations](https://skmtc.dev/orcascan/apis/orca-scan-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/orcascan/apis/orca-scan-rest-api/revisions/13236cc773c3?raw)