> ## 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": "n1ub11",
  "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

<ResponseField name="uid" type="string" required>
  **Read-only.** Unique identifier for the place. Automatically generated by the system.
</ResponseField>

<ResponseField name="name" type="string" required>
  **Read/Write.** Name of the place. This is the only required field when creating a place.

  Example: `"Downtown Office"`, `"Customer Site #101"`
</ResponseField>

<ResponseField name="creator" type="string">
  **Read-only.** Name of the user or company that created this place, when available.
</ResponseField>

## Location & Address

<ResponseField name="location" type="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.
</ResponseField>

<ResponseField name="address" type="string">
  **Read/Write.** Street address.

  Example: `"123 Main Street"`, `"Suite 400, 456 Market Street"`
</ResponseField>

<ResponseField name="city" type="string">
  **Read/Write.** City name.
</ResponseField>

<ResponseField name="state" type="string">
  **Read/Write.** State, province, or region.

  Example: `"California"`, `"CA"`, `"Ontario"`
</ResponseField>

<ResponseField name="postalcode" type="string">
  **Read/Write.** Postal code or ZIP code.
</ResponseField>

<ResponseField name="country_code" type="string">
  **Read/Write.** ISO country code (2 letters).

  Example: `"US"`, `"GB"`, `"DE"`, `"CA"`
</ResponseField>

<ResponseField name="radius" type="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`
</ResponseField>

## Contact Information

<ResponseField name="phone" type="string">
  **Read/Write.** Contact phone number for this location.

  Example: `"+14155551234"`
</ResponseField>

<ResponseField name="email" type="string">
  **Read/Write.** Contact email address for this location.

  Example: `"contact@location.com"`
</ResponseField>

## Visual & Configuration

<ResponseField name="color" type="string">
  **Read/Write.** Color code in hexadecimal format for display in maps and lists.

  Example: `"#22c328"`, `"#FF5733"`
</ResponseField>

<ResponseField name="linkedForms" type="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"`
</ResponseField>

## 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

<ResponseField name="data" type="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
</ResponseField>

<ResponseField name="extended_data" type="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`.
</ResponseField>

## Usage in API Endpoints

### Creating Places

When creating a place with [`/api/createplace`](/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`](/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`](/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](/api-reference/endpoint/getplaces) - Retrieve places
* [Create Place](/api-reference/endpoint/createplace) - Create a new place
* [Edit Place](/api-reference/endpoint/editplace) - Update place properties
* [Get Jobs](/api-reference/endpoint/getjobs) - 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>

<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`.
</Note>

<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.
</Tip>