Service areas

Base URL: $BUSINESS_API

The object

idstring · required
tenant_idstring · required
namestring · required
statusstring · required
The object
{
  "id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "name": "Ana Matsinhe",
  "status": "active"
}

List utility service areas

Logs

GET /service-areas

Returns a cursor-paginated page of the tenant's service areas, the geographic zones used to group properties and reading routes. You can also pass q to match part of the name (case-insensitive), and limit and after to page. Requires business:service-areas:read.

Parameters

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

qstring · query · optional

Resource-specific text search.

statusstring · query · optional

Returns only service areas with this exact status, for example active; omit it to return all.

Returns

200 Service areas in the authenticated utility tenant

Show attributes
dataarray of ServiceArea · required
Show child attributes
idstring · required
tenant_idstring · required
namestring · required
statusstring · required
has_moreboolean · required
next_cursorstring · optional

Errors 400 · 403

Permissions business:service-areas:read · Roles: admin, analyst, billing_clerk, customer_service, field_reader, field_supervisor, finance, operations, owner, viewer

curl -X GET "$BUSINESS_API/service-areas" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "name": "Ana Matsinhe",
      "status": "active"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Create a utility service area

Logs

POST /service-areas

Creates a service area in the caller's tenant with the given name and returns it with status active. The name is trimmed and must not be empty (400 otherwise). Properties and reading routes can then reference the area by its ID. Requires business:service-areas:create.

Body application/json

namestring · required

Returns

201 Service area created

Show attributes
idstring · required
tenant_idstring · required
namestring · required
statusstring · required

Errors 400 · 403

Permissions business:service-areas:create · Roles: admin, owner

curl -X POST "$BUSINESS_API/service-areas" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ana Matsinhe"
}'
Response 201
{
  "id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "name": "Ana Matsinhe",
  "status": "active"
}