> 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/tag.md).

# Tag

Labels applied across entity types, used to group and find things that belong together.

A tag is a label attached to an entity so that related things can be found together. One tag can span types, so a "north depot" tag can sit on places, geofences, employees, tasks, trackers, and vehicles at once, and [`tag/search`](#post-tag-search) then returns all of them grouped by type.

For a walkthrough, see [how to use tags](/docs/navixy-api/user-api/guides/fleet-management/use-tags.md).

## Tag object

## The Tag object

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"components":{"schemas":{"Tag":{"type":"object","description":"A label used to find things quickly. Tags can be applied to place, task, task_schedule, employee, vehicle, zone, tracker.","properties":{"id":{"type":"integer","description":"Tag ID."},"avatar_file_name":{"type":["string","null"],"description":"Optional. File name of the uploaded avatar, with extension. **Cannot be set here**: use `tag/avatar/upload`."},"name":{"type":"string","description":"Name of the tag."},"color":{"type":"string","description":"Tag colour, as a three-byte RGB hex value such as `FF0000`."}}}}}}
```

#### Tagged entity types

A tag can be bound to any of these:

* `place`
* `task`
* `task_schedule`
* `employee`
* `vehicle`
* `zone`
* `tracker`

## API actions

API base path: `/tag`.

Operations that list no errors of their own return only the [general error codes](/docs/navixy-api/general/errors.md#error-codes).

***

*Required sub-user rights:* `tag_update`.

## Create tag

> Create a tag, and return its ID.\
> \
> Also accepts GET with the same parameters as query-string values.\
> \
> Requires the \`tag\_update\` right.

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Tags","description":"Labels applied across places, tasks, employees, vehicles, geofences and trackers, and the search that finds records by them. All resources under the /tag/ 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":{"Tag":{"type":"object","description":"A label used to find things quickly. Tags can be applied to place, task, task_schedule, employee, vehicle, zone, tracker.","properties":{"id":{"type":"integer","description":"Tag ID."},"avatar_file_name":{"type":["string","null"],"description":"Optional. File name of the uploaded avatar, with extension. **Cannot be set here**: use `tag/avatar/upload`."},"name":{"type":"string","description":"Name of the tag."},"color":{"type":"string","description":"Tag colour, as a three-byte RGB hex value such as `FF0000`."}}}},"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":{"/tag/create":{"post":{"tags":["Tags"],"summary":"Create tag","description":"Create a tag, and return its ID.\n\nAlso accepts GET with the same parameters as query-string values.\n\nRequires the `tag_update` right.","operationId":"tagCreate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tag":{"allOf":[{"$ref":"#/components/schemas/Tag"}],"description":"The tag to create, without the `id` field."}},"required":["tag"]}}}},"responses":{"200":{"description":"The created tag","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"id":{"type":"integer","description":"ID of the new tag."}}}}}},"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"}}}}}}
```

***

*Required sub-user rights:* `tag_update`.

## Delete tags

> Delete one tag or several by ID.\
> \
> \*\*Give either \`tag\_id\` or \`tag\_ids\`.\*\* A request with neither reports a missing parameter named \`has\_at\_least\_one\_tag\_id\`, which is the internal name of the validation group rather than a parameter you can send; it carries a message naming the two real choices.\
> \
> The two forms differ in more than shape. \*\*\`tag\_id\` reports error 201 when the tag does not exist, and \`tag\_ids\` does not\*\*: bulk deletion is silent about IDs it could not find.\
> \
> Also accepts GET with the same parameters as query-string values.\
> \
> Requires the \`tag\_update\` right.

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Tags","description":"Labels applied across places, tasks, employees, vehicles, geofences and trackers, and the search that finds records by them. All resources under the /tag/ 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"}},"responses":{"OK":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true}}}}}},"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":{"/tag/delete":{"post":{"tags":["Tags"],"summary":"Delete tags","description":"Delete one tag or several by ID.\n\n**Give either `tag_id` or `tag_ids`.** A request with neither reports a missing parameter named `has_at_least_one_tag_id`, which is the internal name of the validation group rather than a parameter you can send; it carries a message naming the two real choices.\n\nThe two forms differ in more than shape. **`tag_id` reports error 201 when the tag does not exist, and `tag_ids` does not**: bulk deletion is silent about IDs it could not find.\n\nAlso accepts GET with the same parameters as query-string values.\n\nRequires the `tag_update` right.","operationId":"tagDelete","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tag_id":{"type":"integer","description":"ID of a single tag to delete. Use this or `tag_ids`, not both."},"tag_ids":{"type":"array","description":"IDs of tags to delete. Use this or `tag_id`, not both. Missing IDs are ignored rather than reported.","items":{"type":"integer"}}}}}}},"responses":{"200":{"description":"Tags deleted","$ref":"#/components/responses/OK"},"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 tag has the given ID. This does not occur when `tag_ids` is given, because deletion is silent in that case.

***

## List tags

> List the tags of the current user.\
> \
> Callable with an empty body. Also accepts GET.

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Tags","description":"Labels applied across places, tasks, employees, vehicles, geofences and trackers, and the search that finds records by them. All resources under the /tag/ 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":{"Tag":{"type":"object","description":"A label used to find things quickly. Tags can be applied to place, task, task_schedule, employee, vehicle, zone, tracker.","properties":{"id":{"type":"integer","description":"Tag ID."},"avatar_file_name":{"type":["string","null"],"description":"Optional. File name of the uploaded avatar, with extension. **Cannot be set here**: use `tag/avatar/upload`."},"name":{"type":"string","description":"Name of the tag."},"color":{"type":"string","description":"Tag colour, as a three-byte RGB hex value such as `FF0000`."}}}},"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":{"/tag/list":{"post":{"tags":["Tags"],"summary":"List tags","description":"List the tags of the current user.\n\nCallable with an empty body. Also accepts GET.","operationId":"tagList","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"filter":{"type":"string","description":"Optional. Filter over the tag name. 3 to 60 characters, or null.","minLength":3,"maxLength":60}}}}}},"responses":{"200":{"description":"Matching tags","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/Tag"}},"count":{"type":"integer","description":"Total number of tags found. Returned live, and not listed in the published response example."}}}}}},"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"}}}}}}
```

***

The result is grouped by [tagged entity type](#tagged-entity-types) rather than returned as one list.

## Search entities by tag

> Find the entities carrying \*\*all\*\* of the given tags.\
> \
> The result is grouped by entity type rather than returned as one list, so each group holds objects of that type. Restrict which groups come back with \`entity\_types\`.\
> \
> 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":"Tags","description":"Labels applied across places, tasks, employees, vehicles, geofences and trackers, and the search that finds records by them. All resources under the /tag/ 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":{"Place":{"type":"object","description":"A point of interest: a business-specific place such as a shop, delivery point or warehouse that employees visit.\n\nPOIs can carry custom fields. A POI with a custom field of type \"responsible employee\" appears in the Mobile Tracker App for the employee it names.","properties":{"id":{"type":"integer","description":"ID of the POI."},"icon_id":{"type":["integer","null"],"description":"Optional. ID of the assigned icon, 1 to 255. **Cannot be set here**: use `place/avatar/assign`.","minimum":1,"maximum":255},"avatar_file_name":{"type":["string","null"],"description":"Optional. Name of the uploaded avatar file, set by `place/avatar/upload`."},"location":{"type":"object","description":"Where the POI is. Required.","properties":{"lat":{"type":"number","description":"Latitude. Required."},"lng":{"type":"number","description":"Longitude. Required."},"address":{"type":"string","description":"Address of the POI. Required, up to 255 characters.","maxLength":255},"radius":{"type":"integer","description":"Radius of the POI in metres. Required, 1 to 300000.","minimum":1,"maximum":300000}}},"fields":{"type":"object","description":"Optional. Custom field values, keyed by custom field ID **as a string**.","additionalProperties":true},"label":{"type":"string","description":"Name of the POI."},"description":{"type":["string","null"],"description":"Optional. Description of the POI."},"tags":{"type":"array","description":"Optional. IDs of tags applied to the POI. Non-empty when present.","items":{"type":"integer"},"minItems":1},"external_id":{"type":["string","null"],"description":"Optional. Free text tying this POI to an external system. Up to 32 characters.","maxLength":32},"files":{"type":"array","description":"Files associated with the POI. **Read-only**, and not listed in the published object description.","items":{"type":"object","additionalProperties":true},"readOnly":true}}},"Task":{"type":"object","description":"A task: a place to visit, a window to visit it in, and the conditions that decide whether it was done.","properties":{"id":{"type":"integer","description":"Primary key. Used when updating; **ignored when creating**."},"user_id":{"type":"integer","description":"ID of the owning user, the office. **Read-only.**","readOnly":true},"tracker_id":{"type":["integer","null"],"description":"ID of the tracker this task is assigned to. **Ignored on update**, where reassignment goes through a separate operation.","minimum":1},"location":{"type":"object","description":"The circular geofence for this task. Entering and leaving it are what the platform watches. Cannot be null.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"address":{"type":"string","description":"Address of the location. Set this to associate the task with an address."},"radius":{"type":"integer","description":"Radius of the zone in metres, from 1 to 300000.","minimum":1,"maximum":300000}}},"label":{"type":"string","description":"Name of the task. 1 to 200 characters, and not blank.","minLength":1,"maxLength":200},"description":{"type":"string","description":"Description of the task. Up to 1024 characters. **Required**, but may be an empty string.","maxLength":1024},"creation_date":{"type":"string","description":"When the task was created. **Read-only.**","readOnly":true},"from":{"type":"string","description":"Date after which the zone must be visited."},"to":{"type":"string","description":"Date before which the zone must be visited. Required, and cannot be in the past."},"external_id":{"type":["string","null"],"description":"Free text tying this record to an external system, such as an order number. 1 to 100 characters. For reference only.","minLength":1,"maxLength":100},"status":{"type":"string","description":"Current status. **Ignored on create and update.** `arrived` means the performer reached the geofence without completing the task, and `faulty` means it completed with problems.","enum":["unassigned","assigned","done","failed","delayed","arrived","faulty"]},"status_change_date":{"type":"string","description":"When the status last changed. **Ignored on create and update.**"},"max_delay":{"type":"integer","description":"Maximum allowed completion delay, in minutes. Default 0, up to 512000.","minimum":0,"maximum":512000},"min_stay_duration":{"type":"integer","description":"Minimum time that must be spent inside the zone for completion, in minutes. Default 0, up to 512000.","minimum":0,"maximum":512000},"min_arrival_duration":{"type":"integer","description":"Visits shorter than this do not count as an arrival, in minutes. Default 0, up to 512000. Not listed in the published object description.","minimum":0,"maximum":512000},"arrival_date":{"type":["string","null"],"description":"When the tracker reached the zone, or null if it has not. **Read-only.**","readOnly":true},"stay_duration":{"type":"integer","description":"Seconds spent inside the zone. **Read-only.**","readOnly":true},"origin":{"type":"string","description":"How this record was created. **Ignored on create and update.** `imported` means it came from a spreadsheet.","enum":["manual","scheduled","imported"]},"tags":{"type":"array","description":"IDs of tags applied to this record.","items":{"type":"integer"}},"type":{"type":"string","description":"Which kind of record this is.","enum":["task","checkpoint","route"]},"form":{"allOf":[{"$ref":"#/components/schemas/Form"}],"description":"The attached form, when there is one."},"form_template_id":{"type":"integer","description":"ID of a form template. Read on create and update **only when `create_form` is `true`**."},"fields":{"type":"object","description":"Custom field values. Each key is a custom field ID **as a string**, and each value carries the field `type` and its `value`.","additionalProperties":true},"files":{"type":"array","description":"Files associated with this record. **Read-only**, and not listed in the published object description.","items":{"type":"object","additionalProperties":true},"readOnly":true}}},"Form":{"type":"object","description":"A filled-in or fillable form. A form is created from a template and used once: after submission it is kept with its values for reference and cannot be reused.","properties":{"id":{"type":"integer","description":"Form ID."},"label":{"type":"string","description":"Form label, 1 to 100 characters.","minLength":1,"maxLength":100},"description":{"type":"string","description":"Form description. May be empty."},"fields":{"type":"array","description":"The form fields. See the form fields and values reference for the shape of each type.","items":{"type":"object","additionalProperties":true}},"created":{"type":"string","description":"When this form was created, or attached to its task. **Read-only.**","readOnly":true},"submit_in_zone":{"type":"boolean","description":"When `true`, the form can only be submitted inside the task zone."},"task_id":{"type":["integer","null"],"description":"ID of the task this form is attached to."},"checkin_id":{"type":["integer","null"],"description":"ID of the check-in this form belongs to, when it came from one."},"tracker_id":{"type":["integer","null"],"description":"ID of the tracker involved."},"template_id":{"type":["integer","null"],"description":"ID of the template this form was built from. **Null when that template has been deleted.**"},"template_version":{"type":["integer","null"],"description":"Version of the template at the time this form was created."},"values":{"type":["object","null"],"description":"The submitted values, keyed by field ID. **Null when the form has not been filled in.** See the form fields and values reference.","additionalProperties":true},"submitted":{"type":["string","null"],"description":"When the values were last submitted."},"submit_location":{"type":["object","null"],"description":"Where the values were last submitted.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"address":{"type":"string","description":"Address at that point."}}}}},"TaskScheduleEntry":{"type":"object","description":"A recurring task. Very like a task, except that the specific `from` and `to` of a task are replaced by `from_time`, `duration` and `parameters`, which together say when each generated task runs.","properties":{"id":{"type":"integer","description":"Primary key. Used when updating; **ignored when creating**."},"user_id":{"type":"integer","description":"ID of the owning user. **Read-only.**","readOnly":true},"tracker_id":{"type":["integer","null"],"description":"ID of the tracker every task generated from this schedule is assigned to. Null leaves them unassigned.","minimum":1},"label":{"type":"string","description":"Name. 1 to 200 characters.","minLength":1,"maxLength":200},"description":{"type":"string","description":"Description. Up to 1024 characters. **Required**, but may be an empty string.","maxLength":1024},"location":{"type":"object","description":"The circular geofence for the generated task. Cannot be null.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"address":{"type":"string","description":"Address of the location."},"radius":{"type":"integer","description":"Radius of the zone in metres, from 1 to 300000.","minimum":1,"maximum":300000}}},"from_time":{"type":"string","description":"Time of day at which the generated task starts, as `HH:MM:SS`."},"duration":{"type":"integer","description":"Total duration in minutes between the generated task's `from` and `to`. From 1 to 46080, which is 32 days.","minimum":1,"maximum":46080},"max_delay":{"type":"integer","description":"Maximum allowed completion delay, in minutes. Default 0, up to 512000.","minimum":0,"maximum":512000},"min_stay_duration":{"type":"integer","description":"Minimum time that must be spent inside the zone for completion, in minutes. Default 0, up to 512000.","minimum":0,"maximum":512000},"min_arrival_duration":{"type":"integer","description":"Visits shorter than this do not count as an arrival, in minutes. Default 0, up to 512000.","minimum":0,"maximum":512000},"parameters":{"$ref":"#/components/schemas/ScheduleParameters"},"tags":{"type":"array","description":"IDs of tags applied to this schedule.","items":{"type":"integer"}},"form_template_id":{"type":["integer","null"],"description":"ID of a form template to build a form from on each generated task. Nullable.","minimum":1},"fields":{"type":"object","description":"Custom field values, keyed by custom field ID as a string. Not listed in the published object description.","additionalProperties":true},"type":{"type":"string","description":"Which kind of schedule this is. **Read-only**, and not listed in the published object description.","enum":["task","route","checkpoint"],"readOnly":true},"files":{"type":"array","description":"Files associated with this schedule. **Read-only**, and not listed in the published object description.","items":{"type":"object","additionalProperties":true},"readOnly":true}}},"ScheduleParameters":{"type":"object","description":"When a schedule fires. `type` selects which of the two forms applies, and the matching array must not be empty.","properties":{"type":{"type":"string","description":"Which form this is. `weekdays` repeats on days of the week, `month_days` on days of the month.","enum":["weekdays","month_days"]},"weekdays":{"type":"array","description":"Days of the week to create tasks on, where 1 is Monday and 7 is Sunday. Used when `type` is `weekdays`.","items":{"type":"integer","minimum":1,"maximum":7},"minItems":1,"maxItems":7},"month_days":{"type":"array","description":"Days of the month to create tasks on, from 1 to 31. Used when `type` is `month_days`.","items":{"type":"integer","minimum":1,"maximum":31},"minItems":1,"maxItems":31}},"required":["type"]},"Employee":{"type":"object","description":"A person working at the organization: an employee or a driver. Employees can be linked to trackers, vehicles and places.","properties":{"id":{"type":["integer","null"],"description":"Internal ID. May be null or absent when creating."},"tracker_id":{"type":["integer","null"],"description":"ID of the tracker currently assigned to this employee. Null means none."},"first_name":{"type":"string","description":"First name. **Cannot be empty.** Up to 100 characters.","minLength":1,"maxLength":100},"middle_name":{"type":"string","description":"Middle name. May be empty but **not null**. Up to 100 characters.","maxLength":100},"last_name":{"type":"string","description":"Last name. May be empty but **not null**. Up to 100 characters.","maxLength":100},"email":{"type":"string","description":"Email address, which must be valid when given. May be empty but **not null**. Up to 100 characters.","maxLength":100},"phone":{"type":"string","description":"Phone number **without the leading `+`**. May be empty but not null. Up to 32 characters.","maxLength":32},"driver_license_number":{"type":"string","description":"Driver licence number. May be empty but not null. Up to 32 characters.","maxLength":32},"driver_license_cats":{"type":"string","description":"Driver licence categories. Up to 32 characters.","maxLength":32},"driver_license_issue_date":{"type":["string","null"],"description":"Issue date of the driver licence, as `yyyy-MM-dd`."},"driver_license_valid_till":{"type":["string","null"],"description":"Date the driver licence is valid until, as `yyyy-MM-dd`."},"hardware_key":{"type":["string","null"],"description":"Hardware key, such as an iButton or RFID identifier. Up to 64 characters.","maxLength":64},"icon_id":{"type":["integer","null"],"description":"ID of the assigned icon. **Cannot be set here**: use `employee/avatar/assign`."},"avatar_file_name":{"type":["string","null"],"description":"Name of the uploaded avatar file. **Cannot be set here**: use `employee/avatar/upload`."},"department_id":{"type":["integer","null"],"description":"ID of the department this employee belongs to."},"location":{"type":["object","null"],"description":"Optional. Location associated with this employee. Must be a valid location or null.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"address":{"type":"string","description":"Address at that point."},"radius":{"type":"integer","description":"Radius in metres around that point."}}},"personnel_number":{"type":"string","description":"Optional. Personnel number. Up to 15 characters.","maxLength":15},"ssn":{"type":"string","description":"Optional. Social security number. Up to 32 characters.","maxLength":32},"tags":{"type":"array","description":"IDs of tags applied to the employee.","items":{"type":"integer"}}}},"Vehicle":{"type":"object","description":"A vehicle in the fleet.","properties":{"id":{"type":"integer","description":"ID of the vehicle. Omit when creating."},"tracker_id":{"type":"integer","description":"ID of the tracker, also known as object_id. Must belong to the authorized user and not be blocked."},"tracker_label":{"type":"string","description":"Optional. Tracker's label."},"label":{"type":"string","description":"Vehicle's label."},"icon_color":{"type":["string","null"],"description":"Colour of the vehicle icon, as six hex digits without a leading `#`."},"status_id":{"type":["integer","null"],"description":"ID of the vehicle status currently assigned, or null when none is. Set it with `vehicle/status/*`."},"trailer_reg_number":{"type":"string","description":"Registration number of the attached trailer. Empty string when there is none."},"max_speed":{"type":["integer","null"],"description":"Maximum speed of the vehicle."},"model":{"type":"string","description":"Vehicle's model."},"type":{"type":"string","description":"Vehicle's type.","enum":["truck","car","bus","special"]},"subtype":{"type":["string","null"],"description":"Optional. Depends on `type`; null means undefined. For `car`: sedan, universal, hatchback, liftback, limousine, pickup, minivan, coupe, coupe4d, muscle, convertible, phaeton, lando, crossover, roadster, suv. For `truck`: tipper, board, covered, awning, mixer, tanker, refrigerator, transporter, container, tractor. For `bus`: city, shuttle, platform, school, intercity, sightseeing. For `special`: mobile_crane, racing, buggy, ambulance, firefighter, hearse, shop, harvester, snowplow, tractor, grader, excavator, bulldozer, armored, amphibian, boat."},"garage_id":{"type":["integer","null"],"description":"ID of a garage."},"garage_organization_name":{"type":"string","description":"Optional. Garage organization name."},"trailer":{"type":"string","description":"Optional. Information about a trailer."},"manufacture_year":{"type":["integer","null"],"description":"Optional. Manufacture year."},"color":{"type":"string","description":"Optional. Colour of the vehicle, as free text rather than RGB."},"additional_info":{"type":"string","description":"Optional. Additional info."},"reg_number":{"type":"string","description":"Registration number or licence plate."},"vin":{"type":"string","description":"VIN of the vehicle."},"chassis_number":{"type":"string","description":"Chassis number."},"frame_number":{"type":"string","description":"Optional. Frame number."},"payload_weight":{"type":["integer","null"],"description":"Payload weight in kilograms."},"payload_height":{"type":["number","null"],"description":"Payload height in millimetres."},"payload_length":{"type":["number","null"],"description":"Payload length in millimetres."},"payload_width":{"type":["number","null"],"description":"Payload width in millimetres."},"passengers":{"type":["integer","null"],"description":"Maximum number of passengers."},"gross_weight":{"type":["integer","null"],"description":"Optional. Gross weight in kilograms."},"fuel_type":{"type":["string","null"],"description":"Fuel type.","enum":["petrol","diesel","gas"]},"fuel_grade":{"type":"string","description":"Grade of fuel used."},"norm_avg_fuel_consumption":{"type":["number","null"],"description":"Normal average fuel consumption, litres per 100 km."},"fuel_tank_volume":{"type":["integer","null"],"description":"Fuel tank capacity in litres."},"fuel_cost":{"type":["number","null"],"description":"Optional. Cost of fuel per litre."},"wheel_arrangement":{"type":"string","description":"Wheel arrangement, for example `4x2`."},"tyre_size":{"type":"string","description":"Tyre size."},"tyres_number":{"type":["integer","null"],"description":"Number of tyres."},"liability_insurance_policy_number":{"type":"string","description":"Liability insurance policy number."},"liability_insurance_valid_till":{"type":["string","null"],"description":"Date the liability insurance is valid until."},"free_insurance_policy_number":{"type":"string","description":"Free insurance policy number."},"free_insurance_valid_till":{"type":["string","null"],"description":"Date the free insurance is valid until."},"icon_id":{"type":["integer","null"],"description":"ID of the icon. **Read-only here**: change it through `vehicleAvatarAssign`."},"avatar_file_name":{"type":["string","null"],"description":"File name of the uploaded avatar."},"tags":{"type":"array","description":"IDs of tags applied to the vehicle.","items":{"type":"integer"}}}}},"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":{"/tag/search":{"post":{"tags":["Tags"],"summary":"Search entities by tag","description":"Find the entities carrying **all** of the given tags.\n\nThe result is grouped by entity type rather than returned as one list, so each group holds objects of that type. Restrict which groups come back with `entity_types`.\n\nAlso accepts GET with the same parameters as query-string values.","operationId":"tagSearch","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tag_ids":{"type":"array","description":"Tags to search for. An entity must carry **all** of them to match. Must not be empty.","items":{"type":"integer"},"minItems":1},"entity_types":{"type":"array","description":"Optional. Restrict the result to these entity types.","items":{"type":"string","enum":["place","task","task_schedule","employee","vehicle","zone","tracker"]}}},"required":["tag_ids"]}}}},"responses":{"200":{"description":"Entities carrying all the given tags","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"result":{"type":"object","description":"The matching entities, grouped by type. Each group holds objects of that type, shaped as that resource documents them.","properties":{"place":{"type":"array","description":"Matching places.","items":{"$ref":"#/components/schemas/Place"}},"task":{"type":"array","description":"Matching tasks.","items":{"$ref":"#/components/schemas/Task"}},"task_schedule":{"type":"array","description":"Matching task schedules.","items":{"$ref":"#/components/schemas/TaskScheduleEntry"}},"employee":{"type":"array","description":"Matching employees.","items":{"$ref":"#/components/schemas/Employee"}},"vehicle":{"type":"array","description":"Matching vehicles.","items":{"$ref":"#/components/schemas/Vehicle"}},"zone":{"type":"array","description":"Matching geofences. See the geofence documentation for the object shape.","items":{"type":"object","additionalProperties":true}},"tracker":{"type":"array","description":"Matching trackers. See the tracker documentation for the object shape.","items":{"type":"object","additionalProperties":true}}}}}}}}},"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"}}}}}}
```

***

*Required sub-user rights:* `tag_update`.

## Update tag

> Update a tag. Pass a full tag object including its \`id\`.\
> \
> \`avatar\_file\_name\` cannot be set here: it is changed through \`tag/avatar/upload\`.\
> \
> Also accepts GET with the same parameters as query-string values.\
> \
> Requires the \`tag\_update\` right.

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Tags","description":"Labels applied across places, tasks, employees, vehicles, geofences and trackers, and the search that finds records by them. All resources under the /tag/ 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":{"Tag":{"type":"object","description":"A label used to find things quickly. Tags can be applied to place, task, task_schedule, employee, vehicle, zone, tracker.","properties":{"id":{"type":"integer","description":"Tag ID."},"avatar_file_name":{"type":["string","null"],"description":"Optional. File name of the uploaded avatar, with extension. **Cannot be set here**: use `tag/avatar/upload`."},"name":{"type":"string","description":"Name of the tag."},"color":{"type":"string","description":"Tag colour, as a three-byte RGB hex value such as `FF0000`."}}}},"responses":{"OK":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true}}}}}},"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":{"/tag/update":{"post":{"tags":["Tags"],"summary":"Update tag","description":"Update a tag. Pass a full tag object including its `id`.\n\n`avatar_file_name` cannot be set here: it is changed through `tag/avatar/upload`.\n\nAlso accepts GET with the same parameters as query-string values.\n\nRequires the `tag_update` right.","operationId":"tagUpdate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tag":{"allOf":[{"$ref":"#/components/schemas/Tag"}],"description":"The tag to update, including its `id`."}},"required":["tag"]}}}},"responses":{"200":{"description":"Tag updated","$ref":"#/components/responses/OK"},"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 tag has the given ID.

## More in this section

#### Tag avatar

| Endpoint                                                                                                     | Method | What it does      |
| ------------------------------------------------------------------------------------------------------------ | ------ | ----------------- |
| [`/tag/avatar/assign`](/docs/navixy-api/user-api/resources/commons/tag/tag_avatar.md#post-tag-avatar-assign) | POST   | Assign tag icon   |
| [`/tag/avatar/upload`](/docs/navixy-api/user-api/resources/commons/tag/tag_avatar.md#post-tag-avatar-upload) | POST   | Upload tag avatar |


---

# 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/tag.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.