---
title: "Create a field"
method: POST
path: "/fields"
tags: ["Fields"]
---

# Create a field

`POST /fields`

## Request

- Base URL: `https://api.parley.so/v1`
- URL: `https://api.parley.so/v1/fields`
- Auth: HTTP bearer

Define a custom field for projects, accounts, contacts, or tasks. Set its values through the fields of that record type's create and update operations, keyed by field name or ID. Parley doesn't fill task fields, so their automation is off. Requires the owner or admin role.

## Request body

- object
  - `recordType` 'project' | 'account' | 'contact' | 'task', required: The kind of record the field belongs to.
  - `name` string, required: Field name. Unique among the fields of one record type.
  - `type` 'text' | 'number' | 'boolean' | 'datetime' | 'email' | 'url' | 'address' | 'single_select' | 'collection' | 'user', required: The field's value type. It can't be changed after the field is created.
  - `options` string[]: Option labels, in order. Required for single_select, and not allowed for other types. At most 100.
  - `automation` 'off' | 'suggest' | 'auto': Whether Parley fills the field from emails and documents: off, suggest (proposes values for someone to accept), or auto (sets values directly). Defaults to suggest, or to off for a task field, since Parley doesn't fill task fields.
  - `automationInstructions` string: Guidance Parley follows when it fills the field.

## Response `201`

Created.

- Field
  - `id` string, required: The field ID.
  - `name` string, required: Field name. Unique among the fields of one record type.
  - `recordType` 'project' | 'account' | 'contact' | 'task', required: The kind of record the field belongs to.
  - `type` 'text' | 'long_text' | 'number' | 'boolean' | 'datetime' | 'email' | 'url' | 'address' | 'single_select' | 'collection' | 'user', required: The field's value type. It can't be changed after the field is created.
  - `options` string[], required: Option labels of a single_select field, in order. Empty for other types.
  - `automation` 'off' | 'suggest' | 'auto', required: Whether Parley fills the field from emails and documents: off, suggest (proposes values for someone to accept), or auto (sets values directly).
  - `automationInstructions` string, nullable, required: Guidance Parley follows when it fills the field.
  - `system` boolean, required: A built-in field. It can't be renamed, reconfigured, or deleted, but its values can be set like any other field's.
  - `readOnly` boolean, required: Parley maintains the field's values, so they can't be set through fields on a record.
  - `createdAt` string, date-time, required: When the field was created.
  - `updatedAt` string, date-time, required: When the field definition was last updated. Setting values on records does not change it.

## Other responses

- `400`: The request was invalid. VALIDATION_FAILED.
- `401`: Missing or invalid credentials. UNAUTHORIZED.
- `403`: You don't have permission. FORBIDDEN.
- `409`: The request conflicts with the current state. NAME_TAKEN.
- `429`: Too many requests, or a usage limit was reached. TOO_MANY_REQUESTS.

## Changes

- **2026-11-02** `6b78aeee07bc`: 1 breaking
  - added the pattern `^[^\p{Cc}\p{Bidi_Control}]*$` to the request property `name`

[Operation history](https://skmtc.dev/parley/apis/parley-api/changes/fields/post.md)

---

[API](https://skmtc.dev/parley/apis/parley-api.md) - [All operations](https://skmtc.dev/parley/apis/parley-api/llms.txt) - [OpenAPI document](https://skmtc.dev/parley/apis/parley-api/revisions/6b78aeee07bc?raw)