> 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/field-service/place/work-with-poi.md).

# Places (POI)

Business locations that employees visit, called points of interest in the interface and places in the API.

A place is a location the business cares about and employees visit: a shop, a delivery point, a warehouse.

{% hint style="info" %}
**Places and points of interest are the same thing.** The Navixy interface, the user documentation, and the guides in this section call them points of interest, or POIs. The API calls them places at every level: the path is `/place`, the object is `Place`, and anything referring to one does so through `place_id`.

This page uses "place" throughout, because that is what the API says. Reading POI wherever it appears elsewhere loses nothing.
{% endhint %}

Places do two things beyond sitting on a map. An event that happens inside one is labelled with the place name after the address in reports, and a place can be extended with [custom fields](/docs/navixy-api/user-api/resources/commons/entity/fields.md) so it carries whatever else the business needs.

One custom field type changes what field staff see. When a place carries a responsible-employee field, and that [employee](/docs/navixy-api/user-api/resources/field-service/employee.md) is [assigned](/docs/navixy-api/user-api/resources/tracking/tracker/employee.md#post-tracker-employee-assign) to a device running the Mobile Tracker App, for [Android](https://play.google.com/store/apps/details?id=com.navixy.xgps.tracker\&hl=ru) or [iOS](https://apps.apple.com/us/app/x-gps-tracker/id802887190), the place appears in the app for them. That is how a driver sees the places they are expected to visit.

For a walkthrough, see [how to manage POIs](/docs/navixy-api/user-api/guides/places/manage-pois.md).

## Place object

## The Place object

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"components":{"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}}}}}}
```

Custom field values are keyed by custom field ID as a string. See [entity/fields](/docs/navixy-api/user-api/resources/commons/entity/fields.md). The avatar fields `icon_id` and `avatar_file_name` are set through [avatar/assign and avatar/upload](/docs/navixy-api/user-api/resources/field-service/place/avatar.md), not here.

## API actions

API base path: `/place`.

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

***

## Read place

> Return one point of interest by ID.\
> \
> 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":"Places","description":"Points of interest: the business-specific places employees visit, their avatars, spreadsheet import and bulk upload. All resources under the /place/ 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}}}},"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":{"/place/read":{"post":{"tags":["Places"],"summary":"Read place","description":"Return one point of interest by ID.\n\nAlso accepts GET with the same parameters as query-string values.","operationId":"placeRead","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"place_id":{"type":"integer","description":"ID of the POI.","minimum":1}},"required":["place_id"]}}}},"responses":{"200":{"description":"The POI","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"value":{"$ref":"#/components/schemas/Place"}}}}}},"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 place has the given ID.

***

The `conditions` parameter takes [search conditions](/docs/navixy-api/user-api/resources/commons/entity/search_conditions.md), and `order_by` takes either a built-in field name or a custom field ID as a string, see [entity](/docs/navixy-api/user-api/resources/commons/entity.md).

## List places

> List the points of interest of the current user, with filtering, sorting and pagination.\
> \
> Callable with an empty body. 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":"Places","description":"Points of interest: the business-specific places employees visit, their avatars, spreadsheet import and bulk upload. All resources under the /place/ 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}}}},"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":{"/place/list":{"post":{"tags":["Places"],"summary":"List places","description":"List the points of interest of the current user, with filtering, sorting and pagination.\n\nCallable with an empty body. Also accepts GET with the same parameters as query-string values.","operationId":"placeList","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"place_ids":{"type":"array","description":"Optional. Return only these POIs.","items":{"type":"integer"}},"filter":{"type":"string","description":"Optional. Filter over all built-in and custom fields. Used together with `conditions`: both must match for a POI to be returned."},"conditions":{"type":"array","description":"Optional. Search conditions to apply. See the search conditions reference.","items":{"type":"object","additionalProperties":true}},"order_by":{"type":"string","description":"Optional. Field to sort by. Either a built-in name such as `label`, or a custom field ID as a string such as `\"123\"`."},"ascending":{"type":"boolean","description":"Optional. Sort direction. `false` sorts descending."},"limit":{"type":"integer","description":"Optional. Number of POIs to return.","minimum":0},"offset":{"type":"integer","description":"Optional. Default 0. Offset into the results, for pagination.","minimum":0},"tag_ids":{"type":"array","description":"Optional. Tag IDs. A POI must carry **all** the tags in the list to be returned.","items":{"type":"integer"}}}}}}},"responses":{"200":{"description":"Matching POIs","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/Place"}},"count":{"type":"integer","description":"Total number of POIs found, ignoring pagination."}}}}}},"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:* `place_update`.

## Create place

> Create a point of interest, and return its ID.\
> \
> \`icon\_id\` cannot be set here: it is changed through \`place/avatar/assign\`.\
> \
> Requires the \`place\_update\` right.

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Places","description":"Points of interest: the business-specific places employees visit, their avatars, spreadsheet import and bulk upload. All resources under the /place/ 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}}}},"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":{"/place/create":{"post":{"tags":["Places"],"summary":"Create place","description":"Create a point of interest, and return its ID.\n\n`icon_id` cannot be set here: it is changed through `place/avatar/assign`.\n\nRequires the `place_update` right.","operationId":"placeCreate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"place":{"allOf":[{"$ref":"#/components/schemas/Place"}],"description":"The POI to create, without the `id` field."},"ignore_missing_fields":{"type":"boolean","description":"Optional. Default `false`. When `true`, the POI is created even if a required custom field is missing."}},"required":["place"]}}}},"responses":{"200":{"description":"The created POI","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 POI."}}}}}},"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"},"402":{"description":"Error 268: the user's quota for POIs is exhausted.","$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):

* 268 - Over quota, when the user's quota for places is exceeded.

***

## Search places by location

> Return the ID and name of every point of interest whose zone contains the given coordinates.\
> \
> Only \`lat\` and \`lng\` are used, so no radius is needed on the request.

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Places","description":"Points of interest: the business-specific places employees visit, their avatars, spreadsheet import and bulk upload. All resources under the /place/ 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":{"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":{"/place/search_location":{"post":{"tags":["Places"],"summary":"Search places by location","description":"Return the ID and name of every point of interest whose zone contains the given coordinates.\n\nOnly `lat` and `lng` are used, so no radius is needed on the request.","operationId":"placeSearchLocation","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"location":{"type":"object","description":"The point to test.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."}}}},"required":["location"]}}}},"responses":{"200":{"description":"POIs containing the point","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"list":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"ID of a POI containing the searched location."},"label":{"type":"string","description":"Name of that POI."}}}}}}}}},"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 place has the given ID.

***

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

## Update place

> Update a point of interest. Pass a full place object including its \`id\`.\
> \
> \*\*The avatar cannot be changed here.\*\* Use \`place/avatar/assign\` for a preset icon, or \`place/avatar/upload\` for an image.\
> \
> Requires the \`place\_update\` right.

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Places","description":"Points of interest: the business-specific places employees visit, their avatars, spreadsheet import and bulk upload. All resources under the /place/ 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}}}},"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":{"/place/update":{"post":{"tags":["Places"],"summary":"Update place","description":"Update a point of interest. Pass a full place object including its `id`.\n\n**The avatar cannot be changed here.** Use `place/avatar/assign` for a preset icon, or `place/avatar/upload` for an image.\n\nRequires the `place_update` right.","operationId":"placeUpdate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"place":{"allOf":[{"$ref":"#/components/schemas/Place"}],"description":"The POI to update, including its `id`."},"ignore_missing_fields":{"type":"boolean","description":"Optional. Default `false`. When `true`, the POI is updated even if a required custom field is missing."}},"required":["place"]}}}},"responses":{"200":{"description":"POI 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 place has the given ID.

***

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

## Delete place

> Delete a point of interest by ID.\
> \
> Also accepts GET with the same parameters as query-string values.\
> \
> Requires the \`place\_update\` right.

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Places","description":"Points of interest: the business-specific places employees visit, their avatars, spreadsheet import and bulk upload. All resources under the /place/ 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":{"/place/delete":{"post":{"tags":["Places"],"summary":"Delete place","description":"Delete a point of interest by ID.\n\nAlso accepts GET with the same parameters as query-string values.\n\nRequires the `place_update` right.","operationId":"placeDelete","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"place_id":{"type":"integer","description":"ID of the POI to delete.","minimum":1}},"required":["place_id"]}}}},"responses":{"200":{"description":"POI 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 place has the given ID.

***

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

## Convert place batch

> Parse a tab-delimited batch of points of interest and return them checked, with per-row errors. \*\*Creates nothing.\*\*\
> \
> Give either \`batch\` or \`file\_id\`. \*\*If \`file\_id\` is set, \`batch\` is ignored.\*\* A request with neither returns error 7 with the message "The 'batch' or 'file\_id' parameter must be specified".\
> \
> Requires the \`place\_update\` right.

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Places","description":"Points of interest: the business-specific places employees visit, their avatars, spreadsheet import and bulk upload. All resources under the /place/ 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":{"CheckedPlace":{"type":"object","description":"A POI parsed from a batch, with the same fields as a POI plus any per-row problems found while checking it.","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},"errors":{"type":"array","description":"Optional. Problems found in this row.","items":{"type":"object","additionalProperties":true}},"tag_names":{"type":"array","description":"Optional. Tag names of the POI, as written in the batch.","items":{"type":"string"}}},"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":{"/place/batch_convert":{"post":{"tags":["Places"],"summary":"Convert place batch","description":"Parse a tab-delimited batch of points of interest and return them checked, with per-row errors. **Creates nothing.**\n\nGive either `batch` or `file_id`. **If `file_id` is set, `batch` is ignored.** A request with neither returns error 7 with the message \"The 'batch' or 'file_id' parameter must be specified\".\n\nRequires the `place_update` right.","operationId":"placeBatchConvert","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"batch":{"type":"string","description":"Batch of tab-delimited POIs."},"file_id":{"type":"string","description":"Preloaded file ID. Takes precedence over `batch`."},"fields":{"type":"array","description":"Optional. Column names, in order. Defaults to `[\"label\", \"address\", \"lat\", \"lng\", \"radius\", \"description\", \"tags\"]`.","items":{"type":"string"}},"geocoder":{"type":"string","description":"Geocoder type to use for resolving addresses."},"default_radius":{"type":"integer","description":"Optional. Default 100. Zone radius in metres for a row that gives no `radius`."}}}}}},"responses":{"200":{"description":"The checked batch","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/CheckedPlace"}},"limit_exceeded":{"type":"boolean","description":"`true` if the given batch was constrained by a limit."}}}}}},"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):

* 234 - Invalid data format.

***

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

## Upload places

> Create points of interest in bulk from a CSV file.\
> \
> \*\*This is a multipart request\*\*, not JSON: \`multipart/form-data\` with the CSV in a part named \`file\`.\
> \
> The CSV separator is a semicolon and a header row is required, naming \`label;address;lat;lng;radius;external\_id;description\`.\
> \
> If \`redirect\_target\` is passed, the response is a redirect to that URL with \`response=\<urlencoded response json>\` appended.\
> \
> Requires the \`place\_update\` right.

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Places","description":"Points of interest: the business-specific places employees visit, their avatars, spreadsheet import and bulk upload. All resources under the /place/ 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":{"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":{"/place/upload":{"post":{"tags":["Places"],"summary":"Upload places","description":"Create points of interest in bulk from a CSV file.\n\n**This is a multipart request**, not JSON: `multipart/form-data` with the CSV in a part named `file`.\n\nThe CSV separator is a semicolon and a header row is required, naming `label;address;lat;lng;radius;external_id;description`.\n\nIf `redirect_target` is passed, the response is a redirect to that URL with `response=<urlencoded response json>` appended.\n\nRequires the `place_update` right.","operationId":"placeUpload","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","description":"The CSV file of POIs.","format":"binary"},"error_policy":{"type":"string","description":"What to do with a row that fails validation.","enum":["ignore","fail"]},"duplicate_policy":{"type":"string","description":"What to do when an uploaded POI carries an `external_id` that already exists. **Applies to `external_id` duplicates only.**","enum":["skip","update","fail"]},"default_radius":{"type":"integer","description":"Optional. Default 100. Zone radius in metres for a row that gives no radius."},"geocoder":{"type":"string","description":"Geocoder type to use for resolving addresses."},"redirect_target":{"type":"string","description":"Optional. URL to redirect to after the upload."}},"required":["file"]}}}},"responses":{"200":{"description":"The upload result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"total":{"type":"integer","description":"Number of POIs processed."},"errors":{"type":"integer","description":"Number of rows that failed."}}}}}},"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"},"402":{"description":"Error 234: the file could not be parsed. Error 268: the user's quota for POIs is exhausted.","$ref":"#/components/responses/ResponseError"},"409":{"description":"Error 247: an uploaded POI carries an `external_id` that already exists and `duplicate_policy` is `fail`.","$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):

* 233 - No data file, when the `file` part is missing.
* 234 - Invalid data format.
* 247 - Entity already exists, when an uploaded place carries an `external_id` that a place already uses and `duplicate_policy` is `fail`.
* 268 - Over quota, when the user's quota for places is exceeded.


---

# 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/field-service/place/work-with-poi.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.