Location
Location Object
| Field | Type | Description |
|---|---|---|
| id | snowflake | the location's id |
| organisation_id | snowflake | the organisation's id |
| code | string? | a short code for the location (up to 12 characters) |
| name | string? | the name of the location (up to 200 characters) |
| colour | string | the location's colour in hex format |
| color | string | the location's colour in hex format (alias of colour) |
| latitude | double? | the latitude of the location |
| longitude | double? | the longitude of the location |
| radius | double? | the geofencing radius in metres |
| address | string? | the address of the location |
| delivery | boolean | whether the location is a delivery location |
| timezone_code | string? | the timezone code of the location |
| sub_locations | array<sub_location> | array of sub locations |
Sub Location Object
| Field | Type | Description |
|---|---|---|
| id | snowflake | the sub location's id |
| organisation_id | snowflake | the organisation's id |
| location_id | snowflake | the location's id |
| code | string? | a short code for the sub location (up to 12 characters) |
| name | string? | the sub location's name (up to 200 characters) |
| asset_capacity | integer? | optionally limits the number of assets that can be allocated to the sub location |
| enabled | boolean | whether the sub location is enabled |
Create Location
POST /organisations/{organisation.id}/locations
Creates a new location in the organisation. Requires the MANAGE_LOCATIONS permission.
Parameters
| Field | Type | Description | Default |
|---|---|---|---|
| code | string? | a short code for the location (up to 12 characters) | |
| name | string? | the name of the location (up to 200 characters) | new location |
| colour | string? | the location's colour in hex format | |
| latitude | double? | the latitude of the location (must be provided with longitude) | null |
| longitude | double? | the longitude of the location (must be provided with latitude) | null |
| radius | double? | the geofencing radius in metres | null |
| address | string? | the address of the location | |
| timezone_code | string? | the timezone code of the location | |
| delivery | boolean? | whether the location is a delivery location |
Error Responses
| Status Code | Description |
|---|---|
| 400 | Bad request (organisation not found) |
| 400 | Bad request (latitude and longitude must be provided together) |
| 403 | Forbidden (user lacks the MANAGE_LOCATIONS permission) |
List Locations
GET /organisations/{organisation.id}/locations
Returns an array of location objects for the organisation. Each location includes nested sub_location objects. Requires membership in the organisation, or an accepted fleet share from the organisation.
Query Parameters
| Field | Type | Description | Default |
|---|---|---|---|
| delivery | boolean | when set, filters locations by delivery status | null |
Error Responses
| Status Code | Description |
|---|---|
| 400 | Bad request (organisation not found) |
| 403 | Forbidden (user is not a member and has no fleet share) |
Get Location
GET /locations/{location.id}
Returns the location object for the given location id. Requires membership in the organisation that owns the location. The response includes nested sub_location objects.
Error Responses
| Status Code | Description |
|---|---|
| 400 | Bad request (organisation not found) |
| 403 | Forbidden (user is not a member of the organisation) |
| 404 | Not found (location does not exist) |
Update Location
PATCH /locations/{location.id}
Updates a location's properties. Requires the MANAGE_LOCATIONS permission for the organisation.
All parameters for this method are optional. Only the fields provided will be updated.
Parameters
| Field | Type | Description |
|---|---|---|
| code | string? | a short code for the location (up to 12 characters) |
| name | string? | the name of the location (up to 200 characters) |
| colour | string? | the location's colour in hex format |
| address | string? | the address of the location |
| latitude | double? | the latitude of the location |
| longitude | double? | the longitude of the location |
| radius | double? | the geofencing radius in metres |
| timezone_code | string? | the timezone code of the location (must be a valid IANA timezone) |
| delivery | boolean? | whether the location is a delivery location |
Error Responses
| Status Code | Description |
|---|---|
| 400 | Bad request (invalid timezone code) |
| 403 | Forbidden (user lacks the MANAGE_LOCATIONS permission) |
| 404 | Not found (location does not exist) |
Create Sub Location
POST /locations/{location.id}/sub-locations
Creates a new sub_location under the given location. Requires the MANAGE_LOCATIONS permission for the organisation.
Parameters
| Field | Type | Description | Default |
|---|---|---|---|
| code | string? | a short code for the sub location (up to 12 characters) | |
| name | string? | the sub location's name (up to 200 characters) | new sub location |
| asset_capacity | integer? | limits the number of assets that can be allocated to the sub location | null |
Error Responses
| Status Code | Description |
|---|---|
| 400 | Bad request (organisation not found) |
| 403 | Forbidden (user lacks the MANAGE_LOCATIONS permission) |
List Sub Locations
GET /locations/{location.id}/sub-locations
Returns an array of sub_location objects for the given location. Requires membership in the organisation that owns the location, or an accepted fleet share from that organisation.
Error Responses
| Status Code | Description |
|---|---|
| 400 | Bad request (organisation not found) |
| 403 | Forbidden (user is not a member and has no fleet share) |