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

# Get Places

> Retrieve places (locations/sites) for your organization.

Use this endpoint to retrieve places/locations associated with your organization. Places can represent customer sites, warehouses, offices, or any fixed locations relevant to your operations.

### REQUEST

```shell theme={null}
POST https://api.hellotracks.com/api/getplaces

{
  "data": {
    "query": "<place-name>",    // optional
    "uids": ["<place-uid>"],    // optional
    "max": 500                  // optional, defaults to 500
  }
}
```

<ParamField body="query" type="string">
  Optional filter to search places by name. Case-insensitive substring match. Minimum 3 characters recommended.
</ParamField>

<ParamField body="uids" type="array">
  Optional array of specific place UIDs to retrieve. When provided, only these places will be returned (subject to permissions).
</ParamField>

<ParamField body="max" type="integer" default={500}>
  Maximum number of places to return. Default is 500. Some accounts may have different limits.
</ParamField>

### Permissions & Filtering

* **Workers** with `workers_view_places` disabled can only see places from their assigned teams
* Places are automatically filtered by distance from your location (closest first)
* Only places you have permission to view will be returned

### RESPONSE

```shell theme={null}
{
  "status": 0,
  "places": [
    {
      "uid": "<place-uid>",
      "name": "Place name",
      "address": "Full address",
      "city": "City",
      "state": "State/Region",
      "postalcode": "Postal code",
      "country_code": "US",
      "phone": "+1234567890",
      "email": "email@example.com",
      "location": {
        "lat": 37.7749,
        "lng": -122.4194
      },
      "radius": 100,
      "color": "#22c328",
      "linkedForms": "",
      "creator": "Acme Dispatch",
      "data": []
    }
  ]
}
```

<ResponseField name="status" type="integer" required>
  Status code. `0` indicates success.
</ResponseField>

<ResponseField name="places" type="array" required>
  Array of place objects. Each place contains:

  * `uid` (string): Unique place identifier
  * `name` (string): Place name
  * `address` (string): Street address
  * `city` (string): City name
  * `state` (string): State or region
  * `postalcode` (string): Postal/ZIP code
  * `country_code` (string): ISO country code
  * `phone` (string): Contact phone number
  * `email` (string): Contact email address
  * `location` (object): Coordinates with `lat` and `lng`
  * `radius` (integer): Check-in radius in meters
  * `color` (string): Color code in hex format
  * `linkedForms` (string): Linked form IDs
  * `creator` (string): Creator name when available
  * `data` (array): Extended custom data as single-key objects
</ResponseField>

<RequestExample>
  ```bash Example Request theme={null}
  curl -X POST https://api.hellotracks.com/api/getplaces --header 'API-Key: ...' -d '
  {
      "data": {}
  }
  '
  ```
</RequestExample>

<ResponseExample>
  ```
  {
      "places":[
          {
              "address":"1199 East Beach Road, San Francisco, California 94129, United States",
              "color":"",
              "creator":"Acme Dispatch",
              "data":[
              ],
              "city":"San Francisco",
              "uid":"n1ub11",
              "country_code":"US",
              "phone":"",
              "postalcode":"94129",
              "name":"East beach",
              "location":{
              "lng":-122.449046,
              "lat":37.8059467
          },
              "state":"California",
              "radius":50,
              "email":"",
              "linkedForms":""
          }
      ],
      "status":0
  }
  ```
</ResponseExample>