Properties

Base URL: $BUSINESS_API

The object

cadastral_codestring · optional

Unique per tenant.

service_area_idstring · optional
address_line_2string · optional
neighbourhoodstring · optional
citystring · optional
postal_codestring · optional
premise_typestring · optional

one of residential, commercial, industrial, institutional, government, mixed, other

idstring · required
tenant_idstring · required
customer_idstring · required
customer_namestring · optional

Display name of the referenced customer. Omitted when unknown.

referencestring · optional
address_linestring · required
localitystring · optional
districtstring · optional
provincestring · optional
latitudenumber · optional · nullable
longitudenumber · optional · nullable
statusstring · required
The object
{
  "cadastral_code": "CAD-2026-000142",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "address_line_2": "address line 2",
  "neighbourhood": "neighbourhood",
  "city": "Maputo",
  "postal_code": "POS-2026-000142",
  "premise_type": "residential",
  "id": "prp_2ZbuIh1k2RvWMVPQCJD2yPrsOJ3",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "customer_name": "Ana Matsinhe",
  "reference": "REF-2026-000142",
  "address_line": "address line",
  "locality": "locality",
  "district": "district",
  "province": "province",
  "latitude": -25.9653,
  "longitude": 32.5892,
  "status": "active"
}

List tenant-scoped properties

Logs

GET /properties

Returns a cursor-paginated page of the tenant's properties (premises), each with its owning customer, address and cadastral details. Besides the filters below you can pass q for a text search, service_area_id, cadastral_code, limit (default 20, maximum 100) and after (the next_cursor of the previous page). Requires the business:properties:read permission.

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.

customer_idstring · query · optional

Returns only properties owned by this customer ID; omit it to list properties of every customer in the tenant.

statusstring · query · optional

Returns only properties in this status, either active or closed; omit it to include both.

Returns

200 Utility properties

Show attributes
dataarray of Property · required
Show child attributes
cadastral_codestring · optional

Unique per tenant.

service_area_idstring · optional
address_line_2string · optional
neighbourhoodstring · optional
citystring · optional
postal_codestring · optional
premise_typestring · optional

one of residential, commercial, industrial, institutional, government, mixed, other

idstring · required
tenant_idstring · required
customer_idstring · required
customer_namestring · optional

Display name of the referenced customer. Omitted when unknown.

referencestring · optional
address_linestring · required
localitystring · optional
districtstring · optional
provincestring · optional
latitudenumber · optional · nullable
longitudenumber · optional · nullable
statusstring · required
has_moreboolean · required
next_cursorstring · optional

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

curl -X GET "$BUSINESS_API/properties" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "cadastral_code": "CAD-2026-000142",
      "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
      "address_line_2": "address line 2",
      "neighbourhood": "neighbourhood",
      "city": "Maputo",
      "postal_code": "POS-2026-000142",
      "premise_type": "residential",
      "id": "prp_2ZbuIh1k2RvWMVPQCJD2yPrsOJ3",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
      "customer_name": "Ana Matsinhe",
      "reference": "REF-2026-000142",
      "address_line": "address line",
      "locality": "locality",
      "district": "district",
      "province": "province",
      "latitude": -25.9653,
      "longitude": 32.5892,
      "status": "active"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Register a property for an existing utility customer

Logs

POST /properties

Registers a new property for an existing customer of the tenant and returns it with status active and a generated ID. customer_id and address_line are required, latitude and longitude must be sent together and within valid ranges, premise_type must be one of residential, commercial, industrial, institutional, government, mixed or other, and service_area_id must name one of the tenant's own service areas; any of these failures returns 400, and an unknown customer returns 404. The initial ownership is recorded as a property transfer event to the customer.

Body application/json

customer_idstring · required
referencestring · optional
address_linestring · required
localitystring · optional
districtstring · optional
provincestring · optional
latitudenumber · optional
longitudenumber · optional

Returns

201 Property registered

Show attributes
cadastral_codestring · optional

Unique per tenant.

service_area_idstring · optional
address_line_2string · optional
neighbourhoodstring · optional
citystring · optional
postal_codestring · optional
premise_typestring · optional

one of residential, commercial, industrial, institutional, government, mixed, other

idstring · required
tenant_idstring · required
customer_idstring · required
customer_namestring · optional

Display name of the referenced customer. Omitted when unknown.

referencestring · optional
address_linestring · required
localitystring · optional
districtstring · optional
provincestring · optional
latitudenumber · optional · nullable
longitudenumber · optional · nullable
statusstring · required

Permissions business:properties:create · Roles: admin, customer_service, owner

curl -X POST "$BUSINESS_API/properties" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "reference": "REF-2026-000142",
  "address_line": "address line",
  "locality": "locality",
  "district": "district",
  "province": "province",
  "latitude": -25.9653,
  "longitude": 32.5892
}'
Response 201
{
  "cadastral_code": "CAD-2026-000142",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "address_line_2": "address line 2",
  "neighbourhood": "neighbourhood",
  "city": "Maputo",
  "postal_code": "POS-2026-000142",
  "premise_type": "residential",
  "id": "prp_2ZbuIh1k2RvWMVPQCJD2yPrsOJ3",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "customer_name": "Ana Matsinhe",
  "reference": "REF-2026-000142",
  "address_line": "address line",
  "locality": "locality",
  "district": "district",
  "province": "province",
  "latitude": -25.9653,
  "longitude": 32.5892,
  "status": "active"
}

Get the metadata of a property

Logs

GET /properties/{id}/metadata

Returns the free-form key-value metadata attached to a property, as a map of string keys to string values together with the resource type and ID. The property must exist in the caller's tenant, otherwise the call returns 404. Requires the business:metadata:read permission.

Parameters

idstring · path · required

ID of the property whose metadata to read; at most 120 characters.

Returns

200 Metadata

Show attributes
resource_typestring · optional
resource_idstring · optional
metadataobject · optional

Errors 404

Permissions business:metadata:read · Roles: admin, customer_service, owner

curl -X GET "$BUSINESS_API/properties/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}

Merge metadata

Logs

PUT /properties/{id}/metadata

Merge metadata; an empty value deletes the key

Merges the metadata object in the body into the property's existing metadata and returns the full resulting map. A key with a non-empty value is created or overwritten, a key sent with an empty string is deleted, and keys you do not send are left as they are. Keys must be non-blank, at most 40 characters and free of square brackets and control characters, values at most 500 characters, and a resource may hold at most 50 keys after the merge; violations return 400 with the offending keys. The property must exist in the caller's tenant (404 otherwise) and the caller needs business:metadata:write.

Parameters

idstring · path · required

ID of the property whose metadata to change; at most 120 characters.

Body application/json

metadataobject · required

Returns

200 Resulting metadata

Show attributes
resource_typestring · optional
resource_idstring · optional
metadataobject · optional

Errors 400 · 404

Permissions business:metadata:write · Roles: admin, owner

curl -X PUT "$BUSINESS_API/properties/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "metadata": {
    "key": "value"
  }
}'
Response 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}

Get one property

Logs

GET /properties/{id}

Returns one of the tenant's properties by ID, including its owning customer, address, coordinates, cadastral details and status. A property that does not exist or belongs to another tenant returns 404. Requires the business:properties:read permission.

Parameters

idstring · path · required

Property identifier

Returns

200 Property

Show attributes
cadastral_codestring · optional

Unique per tenant.

service_area_idstring · optional
address_line_2string · optional
neighbourhoodstring · optional
citystring · optional
postal_codestring · optional
premise_typestring · optional

one of residential, commercial, industrial, institutional, government, mixed, other

idstring · required
tenant_idstring · required
customer_idstring · required
customer_namestring · optional

Display name of the referenced customer. Omitted when unknown.

referencestring · optional
address_linestring · required
localitystring · optional
districtstring · optional
provincestring · optional
latitudenumber · optional · nullable
longitudenumber · optional · nullable
statusstring · required

Errors 404

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

curl -X GET "$BUSINESS_API/properties/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "cadastral_code": "CAD-2026-000142",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "address_line_2": "address line 2",
  "neighbourhood": "neighbourhood",
  "city": "Maputo",
  "postal_code": "POS-2026-000142",
  "premise_type": "residential",
  "id": "prp_2ZbuIh1k2RvWMVPQCJD2yPrsOJ3",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "customer_name": "Ana Matsinhe",
  "reference": "REF-2026-000142",
  "address_line": "address line",
  "locality": "locality",
  "district": "district",
  "province": "province",
  "latitude": -25.9653,
  "longitude": 32.5892,
  "status": "active"
}

Update a premise's cadastral attributes

Logs

PATCH /properties/{id}

Completes or corrects a property's cadastral attributes (cadastral code, service area, second address line, neighbourhood, city, postal code, premise type and coordinates) and returns the updated property. The body replaces these attributes as a set: an attribute you omit is cleared, except latitude and longitude, which are only changed when both are sent. The owner, the main address line and the status are not changed here. Invalid lengths, an unknown premise_type or a service area outside the tenant return 400, and an unknown property returns 404.

Body application/json

cadastral_codestring · optional
service_area_idstring · optional
address_line_2string · optional
neighbourhoodstring · optional
citystring · optional
postal_codestring · optional
premise_typestring · optional
latitudenumber · optional
longitudenumber · optional

Returns

200 Updated property

Permissions business:properties:write · Roles: admin, customer_service, owner

curl -X PATCH "$BUSINESS_API/properties/{id}" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "cadastral_code": "CAD-2026-000142",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "address_line_2": "address line 2",
  "neighbourhood": "neighbourhood",
  "city": "Maputo",
  "postal_code": "POS-2026-000142",
  "premise_type": "premise type",
  "latitude": -25.9653,
  "longitude": 32.5892
}'
Response 200

Updated property

Move a property to another customer

Logs

POST /properties/{id}/transfer

Only the property moves. Existing accounts keep their holder, because their open balances and consumer access belong to that customer; affected_accounts names the open accounts needing follow-up.

Parameters

idstring · path · required

Property identifier

Body application/json

customer_idstring · required

Returns

200 The transferred property and the accounts left on the previous holder

Show attributes
cadastral_codestring · optional

Unique per tenant.

service_area_idstring · optional
address_line_2string · optional
neighbourhoodstring · optional
citystring · optional
postal_codestring · optional
premise_typestring · optional

one of residential, commercial, industrial, institutional, government, mixed, other

idstring · required
tenant_idstring · required
customer_idstring · required
customer_namestring · optional

Display name of the referenced customer. Omitted when unknown.

referencestring · optional
address_linestring · required
localitystring · optional
districtstring · optional
provincestring · optional
latitudenumber · optional · nullable
longitudenumber · optional · nullable
statusstring · required
previous_customer_idstring · optional
affected_accountsarray of object · optional
Show child attributes
idstring · optional
account_numberstring · optional
customer_idstring · optional
statusstring · optional

Permissions business:properties:write · Roles: admin, customer_service, owner

curl -X POST "$BUSINESS_API/properties/{id}/transfer" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck"
}'
Response 200
{
  "cadastral_code": "CAD-2026-000142",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "address_line_2": "address line 2",
  "neighbourhood": "neighbourhood",
  "city": "Maputo",
  "postal_code": "POS-2026-000142",
  "premise_type": "residential",
  "id": "prp_2ZbuIh1k2RvWMVPQCJD2yPrsOJ3",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "customer_name": "Ana Matsinhe",
  "reference": "REF-2026-000142",
  "address_line": "address line",
  "locality": "locality",
  "district": "district",
  "province": "province",
  "latitude": -25.9653,
  "longitude": 32.5892,
  "status": "active",
  "previous_customer_id": "pre_2KsLTGM5XAi1DiCFTC6jnOybVGK",
  "affected_accounts": [
    {
      "id": "idx_2xBW8Tr0oR5YsrNoIdzQO7t4Gjn",
      "account_number": "ACC-2026-000142",
      "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
      "status": "active"
    }
  ]
}