PT EN

Imóveis

URL base: $BUSINESS_API

O objecto

cadastral_codestring · opcional

Unique per tenant.

service_area_idstring · opcional
address_line_2string · opcional
neighbourhoodstring · opcional
citystring · opcional
postal_codestring · opcional
premise_typestring · opcional

um de residential, commercial, industrial, institutional, government, mixed, other

idstring · obrigatório
tenant_idstring · obrigatório
customer_idstring · obrigatório
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

referencestring · opcional
address_linestring · obrigatório
localitystring · opcional
districtstring · opcional
provincestring · opcional
latitudenumber · opcional · anulável
longitudenumber · opcional · anulável
statusstring · obrigatório
O objecto
{
  "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"
}

Listar imóveis

Registos

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.

Parâmetros

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

qstring · consulta · opcional

Resource-specific text search.

customer_idstring · consulta · opcional

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

statusstring · consulta · opcional

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

Devolve

200 Utility properties

Mostrar atributos
dataarray of Property · obrigatório
Mostrar atributos filhos
cadastral_codestring · opcional

Unique per tenant.

service_area_idstring · opcional
address_line_2string · opcional
neighbourhoodstring · opcional
citystring · opcional
postal_codestring · opcional
premise_typestring · opcional

um de residential, commercial, industrial, institutional, government, mixed, other

idstring · obrigatório
tenant_idstring · obrigatório
customer_idstring · obrigatório
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

referencestring · opcional
address_linestring · obrigatório
localitystring · opcional
districtstring · opcional
provincestring · opcional
latitudenumber · opcional · anulável
longitudenumber · opcional · anulável
statusstring · obrigatório
has_moreboolean · obrigatório
next_cursorstring · opcional

Permissões business:properties:read · Funções: 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_..."
Resposta 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"
}

Registar um imóvel

Registos

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.

Corpo application/json

customer_idstring · obrigatório
referencestring · opcional
address_linestring · obrigatório
localitystring · opcional
districtstring · opcional
provincestring · opcional
latitudenumber · opcional
longitudenumber · opcional

Devolve

201 Property registered

Mostrar atributos
cadastral_codestring · opcional

Unique per tenant.

service_area_idstring · opcional
address_line_2string · opcional
neighbourhoodstring · opcional
citystring · opcional
postal_codestring · opcional
premise_typestring · opcional

um de residential, commercial, industrial, institutional, government, mixed, other

idstring · obrigatório
tenant_idstring · obrigatório
customer_idstring · obrigatório
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

referencestring · opcional
address_linestring · obrigatório
localitystring · opcional
districtstring · opcional
provincestring · opcional
latitudenumber · opcional · anulável
longitudenumber · opcional · anulável
statusstring · obrigatório

Permissões business:properties:create · Funções: 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
}'
Resposta 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"
}

Obter os metadados de um imóvel

Registos

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.

Parâmetros

idstring · caminho · obrigatório

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

Devolve

200 Metadata

Mostrar atributos
resource_typestring · opcional
resource_idstring · opcional
metadataobject · opcional

Erros 404

Permissões business:metadata:read · Funções: admin, customer_service, owner

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

Actualizar os metadados de um imóvel

Registos

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.

Parâmetros

idstring · caminho · obrigatório

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

Corpo application/json

metadataobject · obrigatório

Devolve

200 Resulting metadata

Mostrar atributos
resource_typestring · opcional
resource_idstring · opcional
metadataobject · opcional

Erros 400 · 404

Permissões business:metadata:write · Funções: admin, owner

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

Obter um imóvel

Registos

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.

Parâmetros

idstring · caminho · obrigatório

Property identifier

Devolve

200 Property

Mostrar atributos
cadastral_codestring · opcional

Unique per tenant.

service_area_idstring · opcional
address_line_2string · opcional
neighbourhoodstring · opcional
citystring · opcional
postal_codestring · opcional
premise_typestring · opcional

um de residential, commercial, industrial, institutional, government, mixed, other

idstring · obrigatório
tenant_idstring · obrigatório
customer_idstring · obrigatório
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

referencestring · opcional
address_linestring · obrigatório
localitystring · opcional
districtstring · opcional
provincestring · opcional
latitudenumber · opcional · anulável
longitudenumber · opcional · anulável
statusstring · obrigatório

Erros 404

Permissões business:properties:read · Funções: 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_..."
Resposta 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"
}

Actualizar os dados cadastrais de um imóvel

Registos

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.

Corpo application/json

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

Devolve

200 Updated property

Permissões business:properties:write · Funções: 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
}'
Resposta 200

Updated property

Transferir um imóvel para outro cliente

Registos

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.

Parâmetros

idstring · caminho · obrigatório

Property identifier

Corpo application/json

customer_idstring · obrigatório

Devolve

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

Mostrar atributos
cadastral_codestring · opcional

Unique per tenant.

service_area_idstring · opcional
address_line_2string · opcional
neighbourhoodstring · opcional
citystring · opcional
postal_codestring · opcional
premise_typestring · opcional

um de residential, commercial, industrial, institutional, government, mixed, other

idstring · obrigatório
tenant_idstring · obrigatório
customer_idstring · obrigatório
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

referencestring · opcional
address_linestring · obrigatório
localitystring · opcional
districtstring · opcional
provincestring · opcional
latitudenumber · opcional · anulável
longitudenumber · opcional · anulável
statusstring · obrigatório
previous_customer_idstring · opcional
affected_accountsarray of object · opcional
Mostrar atributos filhos
idstring · opcional
account_numberstring · opcional
customer_idstring · opcional
statusstring · opcional

Permissões business:properties:write · Funções: 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"
}'
Resposta 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"
    }
  ]
}