Entity
Classes of object whose fields and layout an account can customize.
An entity is a class of object whose presentation and editable fields an account can customize. Adding a custom field to places, or reordering the fields already there, is done through this resource.
More than one entity type exists. A plain account lists both place and task. Reading or updating one needs the right mapped to that type, so an account can see an entity in the list and still get error 13 when it tries to read it.
Entity object
The place type is the same object the place API works with. Its built-in fields are label, location, tags, and description.
API actions
API base path: /entity.
Operations that list no errors of their own return only the general error codes.
List the entity classes whose presentation and fields can be customized.
More than one type exists. A plain account lists both place and task. Reading or updating one requires the right mapped to that type, so an account without a product's rights can see its entity in this list and get error 13 on entity/read.
Callable with an empty body. Also accepts GET.
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.
The customizable entities
true if request finished successfully.
trueBad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.
Error response object
POST /v2/entity/list HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Accept: */*
{
"success": true,
"list": [
{
"id": 1,
"type": "text",
"settings": {
"layout": {
"sections": [
{
"label": "text",
"field_order": [
"text"
]
}
]
}
}
}
]
}Give exactly one of id and type. Both null or both set is rejected. The fields that come back are described in the field object.
Return one entity together with its custom fields, by ID or by type.
Exactly one of id and type must be given. Neither is accepted and so is both: the errors say "cannot be null if type is null" and "cannot be non-null if type is not null" respectively, which is unusually self-explaining for this API.
Reading an entity requires the right that governs its type, so type values belonging to other products return error 13 rather than data.
Also accepts GET with the same parameters as query-string values.
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.
ID of the entity. Use this or type, not both.
Type of the entity. Use this or id, not both.
The entity and its fields
true if request finished successfully.
trueBad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.
Error 13: the caller lacks the right that governs this entity type.
Error response object
POST /v2/entity/read HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 22
{
"id": 1,
"type": "text"
}{
"success": true,
"entity": {
"id": 1,
"type": "text",
"settings": {
"layout": {
"sections": [
{
"label": "text",
"field_order": [
"text"
]
}
]
}
}
},
"fields": [
{
"id": null,
"label": "text",
"type": "text",
"required": true,
"description": "text",
"params": {
"responsible": true,
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
]
}Errors
These errors come in addition to the general error codes:
201 - Not found in the database, when no entity has the given ID.
The entity must carry a valid ID.
entity.settings.layout.sections must contain the IDs of every built-in and custom field associated with the entity. No field can be left out of the layout, only reordered, and no field can appear twice even in different sections.
Required sub-user rights: places_custom_fields_update for entities with type place.
Update the settings of a customizable entity. The entity must carry a valid id.
The layout must account for every field. settings.layout.sections has to contain every built-in and custom field associated with the entity: nothing may be omitted, and nothing may appear twice, even in different sections. Only reordering is allowed.
The required right depends on the entity type rather than on the operation, so it is not a fixed rights line: place needs places_custom_fields_update, and other types need the right their own product defines.
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.
Entity updated
true if request finished successfully.
trueBad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.
Error 13: the caller lacks the right that governs this entity type.
Error response object
POST /v2/entity/update HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 110
{
"entity": {
"id": 1,
"type": "text",
"settings": {
"layout": {
"sections": [
{
"label": "text",
"field_order": [
"text"
]
}
]
}
}
}
}{
"success": true
}Errors
These errors come in addition to the general error codes:
7 - Invalid parameters, when the entity object violates the layout restrictions above.
201 - Not found in the database, when no entity has the given ID.
More in this section
Entity fields
Last updated
Was this helpful?