---
title: "Create custom field configurations"
method: POST
path: "/accounts/{id}/custom-fields"
tags: ["Accounts"]
---

# Create custom field configurations

`POST /accounts/{id}/custom-fields`

## Request

- Base URL: `https://open-api.guesty.com/v1`
- URL: `https://open-api.guesty.com/v1/accounts/{id}/custom-fields`
- Auth: API key in header `authorization`

Add one or more custom fields to the account in a single request. Each field requires `key`, `object` and `type`; `displayName` is generated from the `key`, lowercased with spaces replaced by underscores, and any value you send for it is ignored. Keys and display names must be unique across the account, including across different object types. Returns the account's complete custom field list, not only the fields just created.

## Path parameters

- `id` string, required

## Request body

- object
  - `customFields` union[]: Custom Fields Array: all new fields
    - union
      - object: The properties shared by every custom field creation payload, whatever the field type.
        - `isPublic` boolean, required: Indicates whether the custom field is visible to all users or only those with custom field permissions.
        - `isRequired` boolean: Whether a value must be supplied for this field. Applies to reservation custom fields only — it is ignored for listing custom fields, which the Guesty UI always creates with `isRequired: false`. Sending `isRequired: true` together with `isPublic: false` is rejected with a 400.
        - `key` string, required: The plain text display name of the custom field
        - `object` 'listing' | 'reservation', required: Whether the custom field is for listings or reservations
        - `options` string[], required: Your custom list of options for the enum field type.
        - `type` 'enum', required: Indicates that this custom field accepts a value from list of options that you've defined. The 'options' property will contain the list of available options.
      - object: The properties shared by every custom field creation payload, whatever the field type.
        - `isPublic` boolean, required: Indicates whether the custom field is visible to all users or only those with custom field permissions.
        - `isRequired` boolean: Whether a value must be supplied for this field. Applies to reservation custom fields only — it is ignored for listing custom fields, which the Guesty UI always creates with `isRequired: false`. Sending `isRequired: true` together with `isPublic: false` is rejected with a 400.
        - `key` string, required: The plain text display name of the custom field
        - `object` 'listing' | 'reservation', required: Whether the custom field is for listings or reservations
        - `options` string[]: Not supplied by the caller for these field types. For `type: user` the system populates the options internally with the account's users; the API response still returns an empty array for such fields, which does not mean the account has no users. Accepted and ignored for the other non-enum types.
        - `type` 'boolean' | 'contact' | 'date' | 'dayofweek' | 'longtext' | 'number' | 'text' | 'time' | 'user', required: The data type of the custom field. Indicates the type of content that can be input into the field. The "Team member" option in the Guesty UI creates a field of type `user` — there is no separate `team_member` type, and both produce the same result.

## Response `200`

Custom Fields Array

- object[]
  - `displayName` string: The internal variable name of the custom field. Read-only: it is derived by the server from `key` (trimmed, whitespace replaced with underscores, lowercased), so a value sent by the client is ignored.
  - `isPublic` boolean: Indicates whether the custom field is visible to all users or only those with custom field permissions.
  - `isRequired` boolean: Whether a value must be supplied for this field. Applies to reservation custom fields only — it is ignored for listing custom fields, which the Guesty UI always creates with `isRequired: false`.
  - `key` string: The plain text display name of the custom field
  - `object` 'listing' | 'reservation': Whether the custom field is for listings or reservations
  - `options` string[]: Your custom list of options, for the `enum` field type. For `type: user` the system populates the options internally with the account's users, but this property is still returned as an empty array — an empty array here does not mean the account has no users.
  - `type` 'boolean' | 'contact' | 'date' | 'dayofweek' | 'enum' | 'longtext' | 'number' | 'text' | 'time' | 'user': The data type of the custom field. Indicates the type of content that can be input into the field. The "Team member" option in the Guesty UI creates a field of type `user` — there is no separate `team_member` type, and both produce the same result.
  - `fieldId` string: The unique identifier of the custom field

## Other responses

- `400`: Bad Request. The body has one of two shapes depending on which layer rejected the request: validation performed by the service returns the plain text error message, while the `isRequired`/`isPublic` rule returns a JSON object. That rule is applied only when `{id}` is `me` — the account ID form of this path does not run it.
- `401`: Unauthorized
- `403`: Forbidden. The token lacks the required custom field permission.
- `404`: Not Found. The account does not exist.
- `409`: Conflict. The field key or display name is already in use. The response body is the plain text error message.
- `500`: Unhandled exception. Something went wrong on server.

## Changes

- **2026-11-03** `3122b8618183`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/guesty/apis/guesty-open-api/changes/accounts/:id/custom-fields/post.md)

---

[API](https://skmtc.dev/guesty/apis/guesty-open-api.md) - [All operations](https://skmtc.dev/guesty/apis/guesty-open-api/llms.txt) - [OpenAPI document](https://skmtc.dev/guesty/apis/guesty-open-api/revisions/3122b8618183?raw)