> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.hellotracks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Place API Object

> Complete reference for the Place object structure used in API responses and requests.

The Place object represents a fixed location such as customer sites, warehouses, offices, or service locations. Places are used for job assignments, check-ins, and territory management.

## Place Object Structure

```json theme={null}
{
  "uid": "p1q2r3",
  "name": "East Beach Station",
  "address": "1199 East Beach Road",
  "city": "San Francisco",
  "state": "California",
  "postalcode": "94129",
  "country_code": "US",
  "phone": "+14155551234",
  "email": "station@example.com",
  "location": {
    "lat": 37.8059467,
    "lng": -122.449046
  },
  "radius": 50,
  "color": "#22c328",
  "linkedForms": "form1,form2",
  "creator": "Acme Dispatch",
  "data": [
    {"manager": "John Doe"},
    {"capacity": "50"}
  ]
}
```

## Core Properties

**uid** `string` *required*

**Read-only.** Unique identifier for the place. Automatically generated by the system.

**name** `string` *required*

**Read/Write.** Name of the place. This is the only required field when creating a place.

Example: `"Downtown Office"`, `"Customer Site #101"`

**creator** `string`

**Read-only.** Name of the user or company that created this place, when available.

## Location & Address

**location** `object`

**Read/Write.** Geographic coordinates of the place.

* `lat` (DOUBLE): Latitude
* `lng` (DOUBLE): Longitude

If not provided during creation, the system will attempt to geocode based on address fields.

**address** `string`

**Read/Write.** Street address.

Example: `"123 Main Street"`, `"Suite 400, 456 Market Street"`

**city** `string`

**Read/Write.** City name.

**state** `string`

**Read/Write.** State, province, or region.

Example: `"California"`, `"CA"`, `"Ontario"`

**postalcode** `string`

**Read/Write.** Postal code or ZIP code.

**country\_code** `string`

**Read/Write.** ISO country code (2 letters).

Example: `"US"`, `"GB"`, `"DE"`, `"CA"`

**radius** `integer`

**Read/Write.** Check-in radius in meters. Determines how close a worker needs to be to check in at this location.

Default: `0`

Common values: `50`, `100`, `200`

## Contact Information

**phone** `string`

**Read/Write.** Contact phone number for this location.

Example: `"+14155551234"`

**email** `string`

**Read/Write.** Contact email address for this location.

Example: `"contact@location.com"`

## Visual & Configuration

**color** `string`

**Read/Write.** Color code in hexadecimal format for display in maps and lists.

Example: `"#22c328"`, `"#FF5733"`

**linkedForms** `string`

**Read/Write.** Comma-separated list of form IDs linked to this place. When a job is created at this location, these forms can be automatically attached.

Example: `"form1,form2,form3"`

## Team Assignment & Access

Places can be assigned to specific teams within your organization. This is managed through:

* **teams** (ARRAY of integers): Team numbers that have access to this place
* Team-based filtering applies when retrieving places
* Workers may only see places from their assigned teams (based on company settings)

## Custom Data Fields

**data** `array`

**Read-only response field.** Array of custom key-value objects returned by the `/api/getplaces` and `/api/createplace` response object.

Each object contains one custom field name and its value:

```json theme={null}
[
  {"manager": "John Smith"},
  {"capacity": "50"},
  {"hours": "9AM-5PM"},
  {"notes": "Ring doorbell"}
]
```

Use this for storing:

* Manager or contact names
* Operating hours
* Capacity information
* Special instructions
* Custom business data

**extended\_data** `array`

**Write-only for place create/edit requests.** Send custom data as key/value objects, for example `[{"key": "manager", "val": "John Smith"}]`. The `/api` place response serializes those values back as `data`.

## Usage in API Endpoints

### Creating Places

When creating a place with [`/api/createplace`](https://api-docs.hellotracks.com/api-reference/endpoint/createplace):

* Only `name` is required
* If `location` coordinates are not provided, geocoding will attempt to resolve them from address fields
* Send `extended_data` for custom place data; the response returns those fields under `data`

### Editing Places

When editing with [`/api/editplace`](https://api-docs.hellotracks.com/api-reference/endpoint/editplace):

* Include only the fields you want to update
* Use `uid` to identify the place
* Or use `uids` array for batch updates

### Retrieving Places

When retrieving with [`/api/getplaces`](https://api-docs.hellotracks.com/api-reference/endpoint/getplaces):

* Returns array of complete place objects
* Automatically filtered by permissions and teams
* Sorted by distance from your location

## Permissions & Visibility

Place visibility and access is controlled by:

1. **Company Settings:**
   * `workers_create_places`: Controls if workers can create new places
   * `workers_view_places`: Controls if workers can see all places or only team-assigned ones

2. **Team Assignment:**
   * Places can be restricted to specific teams
   * Workers only see places from their teams (when restricted)

3. **Personal vs. Company Places:**
   * Company places belong to the organization
   * Personal places are managed by the owning account and can be visible through existing network/place relationships

## Common Use Cases

### Customer Sites

```json theme={null}
{
  "name": "Acme Corp HQ",
  "address": "123 Business Ave",
  "city": "San Francisco",
  "radius": 100,
  "extended_data": [
    {"key": "contact", "val": "Jane Smith"},
    {"key": "access_code", "val": "1234"}
  ]
}
```

### Service Locations

```json theme={null}
{
  "name": "Maintenance Zone 5",
  "location": {"lat": 37.7749, "lng": -122.4194},
  "radius": 500,
  "linkedForms": "inspection_form",
  "extended_data": [
    {"key": "zone_manager", "val": "Bob Johnson"},
    {"key": "equipment", "val": "HVAC"}
  ]
}
```

### Warehouses

```json theme={null}
{
  "name": "Distribution Center North",
  "address": "456 Industrial Pkwy",
  "radius": 200,
  "phone": "+14155559999",
  "extended_data": [
    {"key": "manager", "val": "Mike Davis"},
    {"key": "capacity", "val": "10000 sq ft"},
    {"key": "dock_doors", "val": "12"}
  ]
}
```

## Related Endpoints

* [Get Places](https://api-docs.hellotracks.com/api-reference/endpoint/getplaces.md) - Retrieve places
* [Create Place](https://api-docs.hellotracks.com/api-reference/endpoint/createplace.md) - Create a new place
* [Edit Place](https://api-docs.hellotracks.com/api-reference/endpoint/editplace.md) - Update place properties
* [Get Jobs](https://api-docs.hellotracks.com/api-reference/endpoint/getjobs.md) - Jobs can be associated with places

## Notes

> [!NOTE]
>
> **Geocoding:** When creating places without coordinates, provide at least `address + city + country_code` or `city + state + country_code` for best geocoding results.

> [!NOTE]
>
> **Custom Data:** In `/api` place create/edit requests, send `extended_data` with objects containing `key` and `val` properties. Place responses return the same data under `data`.

> [!TIP]
>
> **Check-in Radius:** Set an appropriate radius for your use case. Smaller radii (50-100m) for precise locations, larger radii (200-500m) for general areas or zones.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.