> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/navixy-api/user-api/resources/commons/entity/fields.md).

# Entity fields

Custom fields added to an entity, and the types they can take.

A field adds custom information to an [entity](/docs/navixy-api/user-api/resources/commons/entity.md). Each field belongs to exactly one entity, so a custom field defined on places exists only on places.

## Field object

## The CustomField object

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"components":{"schemas":{"CustomField":{"type":"object","description":"A custom field added to an entity, so records of that entity can carry information the platform does not define.\n\nThe `type` fixes what the field accepts and **cannot be changed** once the field exists.","properties":{"id":{"type":["integer","null"],"description":"Field identifier. **Null when creating**, which is how a new field is signalled."},"label":{"type":"string","description":"Name of the field. Must be unique among the fields of one entity."},"type":{"type":"string","description":"What the field holds. `text` takes up to 700 Unicode characters. `bigtext` takes up to 20000 but has reduced search and sorting. `email` and `phone` are validated as such. `decimal` runs from -999999999999.999999 to 999999999999.999999 and stores six decimal places. `integer` runs from -2^63 to 2^63-1. `employee` links to an employee and is the only type taking `params`.","enum":["text","bigtext","email","phone","decimal","integer","employee"]},"required":{"type":"boolean","description":"Whether the field must be filled in."},"description":{"type":"string","description":"Additional information about the field, up to 512 characters.","maxLength":512},"params":{"type":"object","description":"Type-specific parameters. **Omit when the type needs none**, which is every type except `employee`.","properties":{"responsible":{"type":"boolean","description":"For an `employee` field. When `true`, records carrying this field can be shown to that employee in the Mobile Tracker App. **Only one employee field per entity may set this.**"}},"additionalProperties":true}}}}}}
```

### Field types without special parameters

* `text` - text of up to 700 Unicode characters.
* `bigtext` - text of up to 20,000 Unicode characters, with reduced search and sorting.
* `email` - an email address, validated as one.
* `phone` - a phone number, validated as one.
* `decimal` - a decimal from -999999999999.999999 to 999999999999.999999, stored to six decimal places.
* `integer` - an integer from `-2^63` to `2^63 - 1`.

### Field types with special parameters

`employee` links the entity to an employee. It takes one special parameter:

```json
{
  "responsible": true
}
```

* `responsible` - boolean. Only one employee field per entity can set this to `true`.

Setting `responsible` has an effect in the Mobile Tracker App, for [Android](https://play.google.com/store/apps/details?id=com.navixy.xgps.tracker\&hl=ru) and [iOS](https://apps.apple.com/us/app/x-gps-tracker/id802887190). When an [employee is assigned](/docs/navixy-api/user-api/resources/tracking/tracker/employee.md#post-tracker-employee-assign) to a device running the app, and a [place](/docs/navixy-api/user-api/resources/field-service/place/work-with-poi.md) carries a responsible-employee field naming them, that place becomes visible to them in the app. This is what lets an employee see the places they are expected to visit.

## API actions

API base path: `/entity/fields`.

The entity ID comes from [`entity/list`](/docs/navixy-api/user-api/resources/commons/entity.md#post-entity-list).

***

## Read entity fields

> Return the custom fields associated with an entity.\
> \
> The entity ID comes from \`entity/list\`.\
> \
> Also accepts GET with the same parameters as query-string values.

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Entities","description":"Customizable record classes and the custom fields added to them. All resources under the /entity/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"Either a user session hash or an API key, with the \"NVX \" prefix, for example \"NVX 22eac1c27af4be7b9d04da2ce1af111b\". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.","name":"Authorization","in":"header"}},"schemas":{"CustomField":{"type":"object","description":"A custom field added to an entity, so records of that entity can carry information the platform does not define.\n\nThe `type` fixes what the field accepts and **cannot be changed** once the field exists.","properties":{"id":{"type":["integer","null"],"description":"Field identifier. **Null when creating**, which is how a new field is signalled."},"label":{"type":"string","description":"Name of the field. Must be unique among the fields of one entity."},"type":{"type":"string","description":"What the field holds. `text` takes up to 700 Unicode characters. `bigtext` takes up to 20000 but has reduced search and sorting. `email` and `phone` are validated as such. `decimal` runs from -999999999999.999999 to 999999999999.999999 and stores six decimal places. `integer` runs from -2^63 to 2^63-1. `employee` links to an employee and is the only type taking `params`.","enum":["text","bigtext","email","phone","decimal","integer","employee"]},"required":{"type":"boolean","description":"Whether the field must be filled in."},"description":{"type":"string","description":"Additional information about the field, up to 512 characters.","maxLength":512},"params":{"type":"object","description":"Type-specific parameters. **Omit when the type needs none**, which is every type except `employee`.","properties":{"responsible":{"type":"boolean","description":"For an `employee` field. When `true`, records carrying this field can be shown to that employee in the Mobile Tracker App. **Only one employee field per entity may set this.**"}},"additionalProperties":true}}}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/entity/fields/read":{"post":{"tags":["Entities"],"summary":"Read entity fields","description":"Return the custom fields associated with an entity.\n\nThe entity ID comes from `entity/list`.\n\nAlso accepts GET with the same parameters as query-string values.","operationId":"entityFieldsRead","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"entity_id":{"type":"integer","description":"ID of the entity.","minimum":1}},"required":["entity_id"]}}}},"responses":{"200":{"description":"The custom fields","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"list":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}}}}}}},"400":{"description":"Bad request. The response body carries the API-level error code in `status.code`. Validation failures also include an `errors` array naming each offending parameter.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}}
```

#### Errors

These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#error-codes):

* 201 - Not found in the database, when no entity has the given ID.

***

A field sent with `id` set to `null` is created. A field sent with an existing `id` keeps its `type`, which cannot be changed. Every field on one entity must have a different `label`, and an `id` belonging to no field, or to a field on another entity, is rejected.

{% hint style="danger" %}
When `delete_missing` is `true`, every existing field left out of the `fields` list is **permanently deleted**. When it is `false`, those fields are untouched.
{% endhint %}

*Required sub-user rights:* `places_custom_fields_update` for fields on the `place` entity.

## Update entity fields

> Create, update and optionally delete the custom fields of an entity in one call, and return \*\*all\*\* of the entity's fields afterwards, with new IDs filled in.\
> \
> Four rules govern what may be sent. A field with \`id\` null is created. A field that already exists keeps its \`type\`, which cannot be changed. All fields on one entity must have different \`label\` values. An \`id\` that does not exist, or belongs to another entity, is an error.\
> \
> \*\*\`delete\_missing\` is destructive.\*\* When \`true\`, every existing field absent from \`fields\` is permanently deleted. It defaults to \`false\`, which leaves them alone.\
> \
> The required right depends on the entity type: \`place\` needs \`places\_custom\_fields\_update\`, and other types need the right their own product defines.

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Entities","description":"Customizable record classes and the custom fields added to them. All resources under the /entity/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"Either a user session hash or an API key, with the \"NVX \" prefix, for example \"NVX 22eac1c27af4be7b9d04da2ce1af111b\". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.","name":"Authorization","in":"header"}},"schemas":{"CustomField":{"type":"object","description":"A custom field added to an entity, so records of that entity can carry information the platform does not define.\n\nThe `type` fixes what the field accepts and **cannot be changed** once the field exists.","properties":{"id":{"type":["integer","null"],"description":"Field identifier. **Null when creating**, which is how a new field is signalled."},"label":{"type":"string","description":"Name of the field. Must be unique among the fields of one entity."},"type":{"type":"string","description":"What the field holds. `text` takes up to 700 Unicode characters. `bigtext` takes up to 20000 but has reduced search and sorting. `email` and `phone` are validated as such. `decimal` runs from -999999999999.999999 to 999999999999.999999 and stores six decimal places. `integer` runs from -2^63 to 2^63-1. `employee` links to an employee and is the only type taking `params`.","enum":["text","bigtext","email","phone","decimal","integer","employee"]},"required":{"type":"boolean","description":"Whether the field must be filled in."},"description":{"type":"string","description":"Additional information about the field, up to 512 characters.","maxLength":512},"params":{"type":"object","description":"Type-specific parameters. **Omit when the type needs none**, which is every type except `employee`.","properties":{"responsible":{"type":"boolean","description":"For an `employee` field. When `true`, records carrying this field can be shown to that employee in the Mobile Tracker App. **Only one employee field per entity may set this.**"}},"additionalProperties":true}}}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/entity/fields/update":{"post":{"tags":["Entities"],"summary":"Update entity fields","description":"Create, update and optionally delete the custom fields of an entity in one call, and return **all** of the entity's fields afterwards, with new IDs filled in.\n\nFour rules govern what may be sent. A field with `id` null is created. A field that already exists keeps its `type`, which cannot be changed. All fields on one entity must have different `label` values. An `id` that does not exist, or belongs to another entity, is an error.\n\n**`delete_missing` is destructive.** When `true`, every existing field absent from `fields` is permanently deleted. It defaults to `false`, which leaves them alone.\n\nThe required right depends on the entity type: `place` needs `places_custom_fields_update`, and other types need the right their own product defines.","operationId":"entityFieldsUpdate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"entity_id":{"type":"integer","description":"ID of the entity.","minimum":1},"fields":{"type":"array","description":"The fields to create or update. A field with `id` null is created.","items":{"$ref":"#/components/schemas/CustomField"}},"delete_missing":{"type":"boolean","description":"Optional. Default `false`. When `true`, existing fields absent from `fields` are **permanently deleted**."}},"required":["entity_id","fields"]}}}},"responses":{"200":{"description":"All fields of the entity, after the change","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"list":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}}}}}}},"400":{"description":"Bad request. The response body carries the API-level error code in `status.code`. Validation failures also include an `errors` array naming each offending parameter.","$ref":"#/components/responses/ResponseError"},"403":{"description":"Error 13: the caller lacks the right that governs this entity type.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}}
```

#### Errors

These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#error-codes):

* 7 - Invalid parameters, when the fields violate the restrictions above.
* 201 - Not found in the database, when no entity has the given ID.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://navixy.com/docs/navixy-api/user-api/resources/commons/entity/fields.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.