Locations

Reference for the locations resource. Requests follow the conventions in Requests and Responses; fields you receive and may write are filtered by your user's permissions, so responses can contain a subset of the fields below.

Operations

Operation	Request
List	`GET /{profile}/user/v4/locations`
Fetch	`GET /{profile}/user/v4/locations/{id}`
Create	`POST /{profile}/user/v4/locations`
Update	`PATCH /{profile}/user/v4/locations/{id}`
Delete	`DELETE /{profile}/user/v4/locations/{id}`

How it works

locations are your company's locations (offices/branches) — the location_id half of a user_to_group_location assignment and the location_id on customers and other records. You have full CRUD on the identity/address/contact set; the operational internals (scheduling defaults, inventory settings, dealer numbers, timezone) are managed in the SecurityTrax location editor and are not exposed here.

Reading requires the Location admin permission or the User Groups assignment permission; creating, editing, and deleting require the Location admin permission.

Creating / editing a location

curl -X POST "https://portal.securitytrax.com/acme/user/v4/locations" \
  -H "Authorization: Bearer stx_acme_..." \
  -H "Content-Type: application/json" \
  -d '{"data":{"attributes":{"name":"Salt Lake City","address1":"123 S Main St","city":"Salt Lake City","state":"UT","zip":"84101","phone":"801-555-0100"}}}'

Field	Required	Notes
`name`	Yes	≤ 255 chars.
`city`	Yes	≤ 100 chars.
`state`	Yes	Two-letter state.
`address1`, `address2`, `zip`, `phone`, `fax`, `email`	No	Contact/address details.
`active`	No	`true` (default) / `false`.

Note. A created location's timezone and operational settings (scheduling defaults, inventory, dealer numbers) start at their defaults — configure them in the SecurityTrax location editor. To make the location usable for permission assignment, also configure its groups there (groups ?location_id= shows what's configured).

Deleting a location — guard

DELETE /locations/{id} soft-deletes a location, but a location that still has active customers cannot be deleted — 422. Move or cancel its customers first. (Prefer setting active: false to retire a location without deleting it.)

Listing locations

Filters: name (matches anywhere), state (exact), active (true/false). Sort by id, name, city, state, or created_at (default name); ?count_only=true for the total. GET /locations/{id} fetches one.

Tip. The assignment discovery flow is: GET /locations to pick a location → GET /groups?location_id={id}&assignable=true to see what's assignable there → POST /user_to_group_location/set.

Fields

Fields are grouped by the permission that gates them. A group you may not view is absent from responses; a group you may not write is rejected with 422 when sent in a write.

Location

View: any of: special access rules; special access rules. Create: Location. Update: Location.

Field	Type	Writable	Validation
`name`	string	Create, update	Required on create; max length 255
`address1`	string (nullable)	Create, update	max length 255
`address2`	string (nullable)	Create, update	max length 255
`city`	string (nullable)	Create, update	Required on create; max length 100
`state`	string (nullable)	Create, update	Required on create; max length 2
`zip`	string (nullable)	Create, update	max length 50
`phone`	string (nullable)	Create, update	max length 15
`fax`	string (nullable)	Create, update	max length 15
`email`	string (nullable)	Create, update	max length 100; email format
`active`	boolean (nullable)	Create, update	—
`status`	string (nullable)	Read-only	one of: `active`, `deleted`
`created_at`	string (nullable)	Read-only	—
`created_by`	integer (nullable)	Read-only	—
`updated_at`	string (nullable)	Read-only	—
`updated_by`	integer (nullable)	Read-only	—

Pagination

The list endpoint uses client-controlled offset pagination: ?page= (1-based) and ?per_page= (default 25, max 100). The response mirrors meta.pagination (page, per_page, total, last_page) and sends an RFC5988 Link header; follow rel="next" to walk pages. See Pagination.

Filters

The list endpoint accepts these query-param filters: name, state, active. An unsupported filter parameter returns 422. See Filtering collections for matching semantics.

Sorting

GET .../locations?sort= orders the list by: id, name, city, state, created_at. Prefix a field with - for descending; comma-separate for tie-breakers. An unsupported field returns 422. See Sorting collections.

Requests and Responses — envelope, errors, pagination, and rate limits.
Authentication — tokens and the Authorization header.