--- title: "Update custom field configurations" method: PUT path: "/accounts/{id}/custom-fields" tags: ["Accounts"] --- # Update custom field configurations `PUT /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` Replace the account's custom field definitions. The `customFields` array you send replaces the entire existing set, so any field you omit is removed from the account. Every field must carry a `fieldId` — new fields cannot be added here — and a field's `key`, `type`, `object` and `displayName` are fixed at creation and cannot be changed. Returns the account's complete custom field list. ## Path parameters - `id` string, required ## Request body - object - `customFields` union[]: **IMPORTANT NOTE:** every existing custom field must be included, not only the ones you are changing. In practice only `options`, `isPublic` and `isRequired` can be modified — `key`, `type` and `object` are immutable and are read from the stored field. - 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. - `fieldId` string, required: The unique identifier of the custom field being updated. - 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. - `fieldId` string, required: The unique identifier of the custom field being updated. ## 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. - `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/put.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)