Properties API

REST endpoints for properties in ServFlo: 9 operations with parameters, request and response fields, permissions and curl examples.

Base URL: https://app.servflo.ai/api. Every call needs Authorization: Bearer sfk_… (Authentication); {organizationId} ($ORGANIZATION_ID in the examples) is your business's id.

Operation	Endpoint	Risk
List properties	`GET /organizations/{organizationId}/properties`	`read`
Create a property	`POST /organizations/{organizationId}/properties`	`write`
Get a property with its occupancy history	`GET /organizations/{organizationId}/properties/{propertyId}`	`read`
Update a property	`PATCH /organizations/{organizationId}/properties/{propertyId}`	`write`
Link a customer to a property	`POST /organizations/{organizationId}/properties/{propertyId}/occupancies`	`write`
Change a current occupant's role or make them primary	`PATCH /organizations/{organizationId}/properties/{propertyId}/occupancies/{occupancyId}`	`write`
End a customer's link to a property	`POST /organizations/{organizationId}/properties/{propertyId}/occupancies/{occupancyId}/end`	`write`
Transfer a property (sale or move)	`POST /organizations/{organizationId}/properties/{propertyId}/transfer`	`write`
Re-geocode a property	`POST /organizations/{organizationId}/properties/{propertyId}/geocode`	`write`

List properties

GET /organizations/{organizationId}/properties

Properties (service addresses) with their current occupants, filtered by text, type, tag, or customerId (that customer's current properties); paged with a total. A technician sees only properties where they have a job. Read-only.


Permission	`properties.read` (Owner, Admin, Dispatcher, Technician, Member)
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`properties_list` (toolset `customers`, in the default set)

Parameters

Name	In	Type	Required	Description
`query`	query	string	No	Free-text search over the list's names, numbers and contact details. Up to 200 characters.
`customerId`	query	string	No
`propertyType`	query	enum	No	One of `RESIDENTIAL`, `COMMERCIAL`, `MULTI_FAMILY`, `INDUSTRIAL`.
`tag`	query	string	No	Up to 200 characters.
`limit`	query	integer	No	Page size, 1–200. Default `50`.
`offset`	query	integer	No	Rows to skip; the answer's `total` counts every match. Default `0`.

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/properties" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`items`	array of object
`items[].id`	string	Property id.
`items[].organizationId`	string
`items[].name`	string or null
`items[].address`	string or null
`items[].address2`	string or null
`items[].city`	string or null
`items[].state`	string or null
`items[].zip`	string or null
`items[].country`	string or null
`items[].propertyType`	enum	One of `RESIDENTIAL`, `COMMERCIAL`, `MULTI_FAMILY`, `INDUSTRIAL`.
`items[].contactName`	string or null	Who to ask for on site.
`items[].contactPhone`	string or null
`items[].contactEmail`	string or null
`items[].timezone`	string	IANA timezone of the property.
`items[].accessInstructions`	string or null
`items[].safetyNotes`	string or null
`items[].gateCode`	string or null
`items[].petsOnSite`	boolean
`items[].petNotes`	string or null
`items[].yearBuilt`	integer or null
`items[].squareFeet`	integer or null
`items[].tags`	array of string
`items[].latitude`	number or null
`items[].longitude`	number or null
`items[].geocodeSource`	string or null	Where the coordinates came from: GEOCODER (the address), GEOCODER_STREET / GEOCODER_AREA (approximate: only its street or town is on the map; visit safety then searches the ZIP), MANUAL (pinned by hand).
`items[].geocodedAt`	string (date-time) or null
`items[].taxRate`	number or null	Tax rate in percent for work here; null = the business default.
`items[].customFields`	any	Custom field values by key (definitions: GET /custom-fields).
`items[].createdAt`	string (date-time)
`items[].updatedAt`	string (date-time)
`items[].occupancies`	array of object	Current occupants, primary first.
`items[].occupancies[].id`	string	Occupancy id (for PATCH …/occupancies/{occupancyId}).
`items[].occupancies[].propertyId`	string
`items[].occupancies[].customerId`	string
`items[].occupancies[].role`	enum	One of `OWNER`, `TENANT`, `LANDLORD`, `PROPERTY_MANAGER`.
`items[].occupancies[].isPrimary`	boolean	The property's primary current occupant.
`items[].occupancies[].startedOn`	string	First day of the link, YYYY-MM-DD.
`items[].occupancies[].endedOn`	string or null	Last day, YYYY-MM-DD; null = current.
`items[].occupancies[].createdAt`	string (date-time)
`items[].occupancies[].customer`	object
`items[].assetCount`	integer	Equipment registered at the property.
`total`	integer	How many match the filters, across all pages.

Create a property

POST /organizations/{organizationId}/properties

Creates a property (service address). With customerId it is linked to that customer from startedOn or today (default role OWNER, primary). Returns the property.


Permission	`properties.write` (Owner, Admin, Dispatcher)
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`properties_create` (toolset `customers`, in the default set)

Request body

Field	Type	Required	Description
`name`	string or null	No	Up to 500 characters.
`address`	string or null	No	Up to 500 characters.
`address2`	string or null	No	Up to 500 characters.
`city`	string or null	No	Up to 500 characters.
`state`	string or null	No	Up to 500 characters.
`zip`	string or null	No	Up to 500 characters.
`country`	string or null	No	Up to 500 characters.
`propertyType`	enum	No	One of `RESIDENTIAL`, `COMMERCIAL`, `MULTI_FAMILY`, `INDUSTRIAL`.
`contactName`	string or null	No	Up to 500 characters.
`contactPhone`	string or null	No	Up to 500 characters.
`contactEmail`	empty string or string (email) or null	No
`timezone`	string	No	An IANA timezone, e.g. America/Chicago. Up to 100 characters.
`accessInstructions`	string or null	No	Up to 5000 characters.
`safetyNotes`	string or null	No	Up to 5000 characters.
`gateCode`	string or null	No	Up to 500 characters.
`petsOnSite`	boolean	No
`petNotes`	string or null	No	Up to 5000 characters.
`yearBuilt`	integer or null	No	1000–3000.
`squareFeet`	integer or null	No	0–100000000.
`tags`	array of string	No	Up to 100 items.
`taxRate`	number or null	No	-1000–1000.
`latitude`	number or null	No	Geocode (WGS84), pinned by hand. Leave out to have the address geocoded after saving; the map, route planning and My day's distances use it. -90–90.
`longitude`	number or null	No	-180–180.
`customFields`	object	No
`customerId`	string	No
`role`	enum	No	One of `OWNER`, `TENANT`, `LANDLORD`, `PROPERTY_MANAGER`.
`startedOn`	string	No	A calendar date in the business's own calendar, YYYY-MM-DD.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/properties" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Dana Whitfield","address":"string","address2":"string"}'

Response

201: the answer's fields

Field	Type	Description
`id`	string	Property id.
`organizationId`	string
`name`	string or null
`address`	string or null
`address2`	string or null
`city`	string or null
`state`	string or null
`zip`	string or null
`country`	string or null
`propertyType`	enum	One of `RESIDENTIAL`, `COMMERCIAL`, `MULTI_FAMILY`, `INDUSTRIAL`.
`contactName`	string or null	Who to ask for on site.
`contactPhone`	string or null
`contactEmail`	string or null
`timezone`	string	IANA timezone of the property.
`accessInstructions`	string or null
`safetyNotes`	string or null
`gateCode`	string or null
`petsOnSite`	boolean
`petNotes`	string or null
`yearBuilt`	integer or null
`squareFeet`	integer or null
`tags`	array of string
`latitude`	number or null
`longitude`	number or null
`geocodeSource`	string or null	Where the coordinates came from: GEOCODER (the address), GEOCODER_STREET / GEOCODER_AREA (approximate: only its street or town is on the map; visit safety then searches the ZIP), MANUAL (pinned by hand).
`geocodedAt`	string (date-time) or null
`taxRate`	number or null	Tax rate in percent for work here; null = the business default.
`customFields`	any	Custom field values by key (definitions: GET /custom-fields).
`createdAt`	string (date-time)
`updatedAt`	string (date-time)

Get a property with its occupancy history

GET /organizations/{organizationId}/properties/{propertyId}

One property with every occupancy (owner, tenant … with dates), its equipment count and custom fields. A technician gets 404 unless they have a job there. Read-only.


Permission	`properties.read` (Owner, Admin, Dispatcher, Technician, Member)
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`properties_get` (toolset `customers`)

Parameters

Name	In	Type	Required	Description
`propertyId`	path	string	Yes

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/properties/{propertyId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`id`	string	Property id.
`organizationId`	string
`name`	string or null
`address`	string or null
`address2`	string or null
`city`	string or null
`state`	string or null
`zip`	string or null
`country`	string or null
`propertyType`	enum	One of `RESIDENTIAL`, `COMMERCIAL`, `MULTI_FAMILY`, `INDUSTRIAL`.
`contactName`	string or null	Who to ask for on site.
`contactPhone`	string or null
`contactEmail`	string or null
`timezone`	string	IANA timezone of the property.
`accessInstructions`	string or null
`safetyNotes`	string or null
`gateCode`	string or null
`petsOnSite`	boolean
`petNotes`	string or null
`yearBuilt`	integer or null
`squareFeet`	integer or null
`tags`	array of string
`latitude`	number or null
`longitude`	number or null
`geocodeSource`	string or null	Where the coordinates came from: GEOCODER (the address), GEOCODER_STREET / GEOCODER_AREA (approximate: only its street or town is on the map; visit safety then searches the ZIP), MANUAL (pinned by hand).
`geocodedAt`	string (date-time) or null
`taxRate`	number or null	Tax rate in percent for work here; null = the business default.
`customFields`	any	Custom field values by key (definitions: GET /custom-fields).
`createdAt`	string (date-time)
`updatedAt`	string (date-time)
`occupancies`	array of object	Every occupancy, current ones first (`endedOn` null), then past ones.
`occupancies[].id`	string	Occupancy id (for PATCH …/occupancies/{occupancyId}).
`occupancies[].propertyId`	string
`occupancies[].customerId`	string
`occupancies[].role`	enum	One of `OWNER`, `TENANT`, `LANDLORD`, `PROPERTY_MANAGER`.
`occupancies[].isPrimary`	boolean	The property's primary current occupant.
`occupancies[].startedOn`	string	First day of the link, YYYY-MM-DD.
`occupancies[].endedOn`	string or null	Last day, YYYY-MM-DD; null = current.
`occupancies[].createdAt`	string (date-time)
`occupancies[].customer`	object
`occupancies[].customer.id`	string	Customer id.
`occupancies[].customer.name`	string
`occupancies[].customer.type`	enum	One of `RESIDENTIAL`, `COMMERCIAL`.
`occupancies[].customer.phone`	string or null
`occupancies[].customer.email`	string or null
`_count`	object	Equipment and jobs at the property.
`_count.assets`	integer
`_count.jobs`	integer

Update a property

PATCH /organizations/{organizationId}/properties/{propertyId}

Changes the fields sent (address, access notes, gate code, tax rate, custom fields …). Returns the property.


Permission	`properties.write` (Owner, Admin, Dispatcher)
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`properties_update` (toolset `customers`)

Parameters

Name	In	Type	Required	Description
`propertyId`	path	string	Yes

Request body

Field	Type	Required	Description
`name`	string or null	No	Up to 500 characters.
`address`	string or null	No	Up to 500 characters.
`address2`	string or null	No	Up to 500 characters.
`city`	string or null	No	Up to 500 characters.
`state`	string or null	No	Up to 500 characters.
`zip`	string or null	No	Up to 500 characters.
`country`	string or null	No	Up to 500 characters.
`propertyType`	enum	No	One of `RESIDENTIAL`, `COMMERCIAL`, `MULTI_FAMILY`, `INDUSTRIAL`.
`contactName`	string or null	No	Up to 500 characters.
`contactPhone`	string or null	No	Up to 500 characters.
`contactEmail`	empty string or string (email) or null	No
`timezone`	string	No	An IANA timezone, e.g. America/Chicago. Up to 100 characters.
`accessInstructions`	string or null	No	Up to 5000 characters.
`safetyNotes`	string or null	No	Up to 5000 characters.
`gateCode`	string or null	No	Up to 500 characters.
`petsOnSite`	boolean	No
`petNotes`	string or null	No	Up to 5000 characters.
`yearBuilt`	integer or null	No	1000–3000.
`squareFeet`	integer or null	No	0–100000000.
`tags`	array of string	No	Up to 100 items.
`taxRate`	number or null	No	-1000–1000.
`latitude`	number or null	No	Geocode (WGS84), pinned by hand. Leave out to have the address geocoded after saving; the map, route planning and My day's distances use it. -90–90.
`longitude`	number or null	No	-180–180.
`customFields`	object	No

Example

curl -X PATCH "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/properties/{propertyId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Dana Whitfield","address":"string","address2":"string"}'

Response

200: the answer's fields

Field	Type	Description
`id`	string	Property id.
`organizationId`	string
`name`	string or null
`address`	string or null
`address2`	string or null
`city`	string or null
`state`	string or null
`zip`	string or null
`country`	string or null
`propertyType`	enum	One of `RESIDENTIAL`, `COMMERCIAL`, `MULTI_FAMILY`, `INDUSTRIAL`.
`contactName`	string or null	Who to ask for on site.
`contactPhone`	string or null
`contactEmail`	string or null
`timezone`	string	IANA timezone of the property.
`accessInstructions`	string or null
`safetyNotes`	string or null
`gateCode`	string or null
`petsOnSite`	boolean
`petNotes`	string or null
`yearBuilt`	integer or null
`squareFeet`	integer or null
`tags`	array of string
`latitude`	number or null
`longitude`	number or null
`geocodeSource`	string or null	Where the coordinates came from: GEOCODER (the address), GEOCODER_STREET / GEOCODER_AREA (approximate: only its street or town is on the map; visit safety then searches the ZIP), MANUAL (pinned by hand).
`geocodedAt`	string (date-time) or null
`taxRate`	number or null	Tax rate in percent for work here; null = the business default.
`customFields`	any	Custom field values by key (definitions: GET /custom-fields).
`createdAt`	string (date-time)
`updatedAt`	string (date-time)

Link a customer to a property

POST /organizations/{organizationId}/properties/{propertyId}/occupancies

Links a customer to the property as owner, tenant, landlord or property manager from a date. A new primary demotes the current one. Returns the occupancy.


Permission	`properties.write` (Owner, Admin, Dispatcher)
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`properties_addOccupant` (toolset `customers`)

Parameters

Name	In	Type	Required	Description
`propertyId`	path	string	Yes

Request body

Field	Type	Required	Description
`customerId`	string	Yes
`role`	enum	No	One of `OWNER`, `TENANT`, `LANDLORD`, `PROPERTY_MANAGER`.
`isPrimary`	boolean	No
`startedOn`	string	No	A calendar date in the business's own calendar, YYYY-MM-DD.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/properties/{propertyId}/occupancies" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customerId":"customer_id"}'

Response

201: the answer's fields

Field	Type	Description
`id`	string	Occupancy id (for PATCH …/occupancies/{occupancyId}).
`propertyId`	string
`customerId`	string
`role`	enum	One of `OWNER`, `TENANT`, `LANDLORD`, `PROPERTY_MANAGER`.
`isPrimary`	boolean	The property's primary current occupant.
`startedOn`	string	First day of the link, YYYY-MM-DD.
`endedOn`	string or null	Last day, YYYY-MM-DD; null = current.
`createdAt`	string (date-time)

Change a current occupant's role or make them primary

PATCH /organizations/{organizationId}/properties/{propertyId}/occupancies/{occupancyId}

Changes an open occupancy's role and/or makes it the primary one. Occupancy ids come from GET /properties/{propertyId}.


Permission	`properties.write` (Owner, Admin, Dispatcher)
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`properties_updateOccupancy` (toolset `customers`)

Parameters

Name	In	Type	Required	Description
`propertyId`	path	string	Yes
`occupancyId`	path	string	Yes

Request body

Field	Type	Required	Description
`role`	enum	No	One of `OWNER`, `TENANT`, `LANDLORD`, `PROPERTY_MANAGER`.
`isPrimary`	boolean	No

Example

curl -X PATCH "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/properties/{propertyId}/occupancies/{occupancyId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role":"OWNER","isPrimary":true}'

Response

200: the answer's fields

Field	Type	Description
`id`	string	Occupancy id (for PATCH …/occupancies/{occupancyId}).
`propertyId`	string
`customerId`	string
`role`	enum	One of `OWNER`, `TENANT`, `LANDLORD`, `PROPERTY_MANAGER`.
`isPrimary`	boolean	The property's primary current occupant.
`startedOn`	string	First day of the link, YYYY-MM-DD.
`endedOn`	string or null	Last day, YYYY-MM-DD; null = current.
`createdAt`	string (date-time)

End a customer's link to a property

POST /organizations/{organizationId}/properties/{propertyId}/occupancies/{occupancyId}/end

Ends the customer's link on endedOn (default today). The history row stays; the next current occupant becomes primary.


Permission	`properties.write` (Owner, Admin, Dispatcher)
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`properties_endOccupancy` (toolset `customers`)

Parameters

Name	In	Type	Required	Description
`propertyId`	path	string	Yes
`occupancyId`	path	string	Yes

Request body

Field	Type	Required	Description
`endedOn`	string	No	A calendar date in the business's own calendar, YYYY-MM-DD.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/properties/{propertyId}/occupancies/{occupancyId}/end" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"endedOn":"2026-11-03"}'

Response

200: the answer's fields

Field	Type	Description
`id`	string	Occupancy id (for PATCH …/occupancies/{occupancyId}).
`propertyId`	string
`customerId`	string
`role`	enum	One of `OWNER`, `TENANT`, `LANDLORD`, `PROPERTY_MANAGER`.
`isPrimary`	boolean	The property's primary current occupant.
`startedOn`	string	First day of the link, YYYY-MM-DD.
`endedOn`	string or null	Last day, YYYY-MM-DD; null = current.
`createdAt`	string (date-time)

Transfer a property (sale or move)

POST /organizations/{organizationId}/properties/{propertyId}/transfer

For a sale or move: ends every current link on onDate (default today) and makes toCustomerId the primary occupant. Equipment and history stay with the property. Returns the new occupancy.


Permission	`properties.write` (Owner, Admin, Dispatcher)
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`properties_transfer` (toolset `customers`)

Parameters

Name	In	Type	Required	Description
`propertyId`	path	string	Yes

Request body

Field	Type	Required	Description
`toCustomerId`	string	Yes
`role`	enum	No	One of `OWNER`, `TENANT`, `LANDLORD`, `PROPERTY_MANAGER`.
`onDate`	string	No	A calendar date in the business's own calendar, YYYY-MM-DD.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/properties/{propertyId}/transfer" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"toCustomerId":"toCustomer_id"}'

Response

200: the answer's fields

Field	Type	Description
`id`	string	Occupancy id (for PATCH …/occupancies/{occupancyId}).
`propertyId`	string
`customerId`	string
`role`	enum	One of `OWNER`, `TENANT`, `LANDLORD`, `PROPERTY_MANAGER`.
`isPrimary`	boolean	The property's primary current occupant.
`startedOn`	string	First day of the link, YYYY-MM-DD.
`endedOn`	string or null	Last day, YYYY-MM-DD; null = current.
`createdAt`	string (date-time)

Re-geocode a property

POST /organizations/{organizationId}/properties/{propertyId}/geocode

Looks the property's address up again now with the configured geocoder (SERVFLO_GEOCODER: OpenStreetMap Nominatim, a self-hosted server or the test fake; answers are cached by address) and stores the coordinates, replacing a hand-placed pin. found: false keeps the old coordinates (nothing found, or geocoding is off). Waits for the answer (Nominatim allows one request a second).


Permission	`properties.write` (Owner, Admin, Dispatcher)
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`properties_geocode` (toolset `customers`)

Parameters

Name	In	Type	Required	Description
`propertyId`	path	string	Yes

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/properties/{propertyId}/geocode" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`found`	boolean
`latitude`	number or null
`longitude`	number or null
`geocodeSource`	string or null	GEOCODER, GEOCODER_STREET or GEOCODER_AREA (approximate), or MANUAL.
`geocodedAt`	string (date-time) or null

On this page