Skip to main content
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

{
  "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",
  "creator": "Top Services",
  "linkedForms": "form1,form2",
  "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.

​
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: 0Common 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/Write. Array of custom key-value pair objects for storing additional information.Each object contains one key-value pair:
[
  {"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

​
Usage in API Endpoints

​
Creating Places

When creating a place with /api/createplace:
  • Only name is required
  • If location coordinates are not provided, geocoding will attempt to resolve them from address fields
  • extended_data parameter is used instead of data in requests

​
Editing Places

When editing with /api/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:
  • 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 can be shared with network using visibility: "network"

​
Common Use Cases

​
Customer Sites

{
  "name": "Acme Corp HQ",
  "address": "123 Business Ave",
  "city": "San Francisco",
  "radius": 100,
  "data": [
    {"contact": "Jane Smith"},
    {"access_code": "1234"}
  ]
}

​
Service Locations

{
  "name": "Maintenance Zone 5",
  "location": {"lat": 37.7749, "lng": -122.4194},
  "radius": 500,
  "linkedForms": "inspection_form",
  "data": [
    {"zone_manager": "Bob Johnson"},
    {"equipment": "HVAC"}
  ]
}

​
Warehouses

{
  "name": "Distribution Center North",
  "address": "456 Industrial Pkwy",
  "radius": 200,
  "phone": "+14155559999",
  "data": [
    {"manager": "Mike Davis"},
    {"capacity": "10000 sq ft"},
    {"dock_doors": "12"}
  ]
}

​
Notes

Geocoding: When creating places without coordinates, provide at least address + city + country_code or city + state + country_code for best geocoding results.
Extended Data: In API requests, use extended_data parameter with objects containing key and val properties. In responses, this appears as the data array with single key-value objects.
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.
⌘I