Place API Object

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",
  "linkedForms": "form1,form2",
  "creator": "Acme Dispatch",
  "data": [
    {"manager": "John Doe"},
    {"capacity": "50"}
  ]
}

Core Properties

string

required

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

string

required

Read/Write. Name of the place. This is the only required field when creating a place.Example: "Downtown Office", "Customer Site #101"

string

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

Location & Address

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.

string

Read/Write. Street address.Example: "123 Main Street", "Suite 400, 456 Market Street"

string

Read/Write. City name.

string

Read/Write. State, province, or region.Example: "California", "CA", "Ontario"

string

Read/Write. Postal code or ZIP code.

string

Read/Write. ISO country code (2 letters).Example: "US", "GB", "DE", "CA"

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

string

Read/Write. Contact phone number for this location.Example: "+14155551234"

string

Read/Write. Contact email address for this location.Example: "contact@location.com"

Visual & Configuration

string

Read/Write. Color code in hexadecimal format for display in maps and lists.Example: "#22c328", "#FF5733"

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

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:

[
  {"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

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:

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:

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:

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
Team Assignment:
- Places can be restricted to specific teams
- Workers only see places from their teams (when restricted)
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

{
  "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

{
  "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

{
  "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"}
  ]
}

Get Places - Retrieve places
Create Place - Create a new place
Edit Place - Update place properties
Get Jobs - Jobs can be associated with places

Notes

Geocoding: When creating places without coordinates, provide at least address + city + country_code or city + state + country_code for best geocoding results.

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.

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.

API Documentation

Job Management

Dispatch and Routing

Location

Account Management

Place Management

Reports

No-Code Integrations

Place Object Structure

Core Properties

Location & Address

Contact Information

Visual & Configuration

Team Assignment & Access

Custom Data Fields

Usage in API Endpoints

Creating Places

Editing Places

Retrieving Places

Permissions & Visibility

Common Use Cases

Customer Sites

Service Locations

Warehouses

Notes

​Place Object Structure

​Core Properties

​Location & Address

​Contact Information

​Visual & Configuration

​Team Assignment & Access

​Custom Data Fields

​Usage in API Endpoints

​Creating Places

​Editing Places

​Retrieving Places

​Permissions & Visibility

​Common Use Cases

​Customer Sites

​Service Locations

​Warehouses

​Related Endpoints

​Notes

Place Object Structure

Core Properties

Location & Address

Contact Information

Visual & Configuration

Team Assignment & Access

Custom Data Fields

Usage in API Endpoints

Creating Places

Editing Places

Retrieving Places

Permissions & Visibility

Common Use Cases

Customer Sites

Service Locations

Warehouses

Related Endpoints

Notes