Organizations API

REST endpoints for organizations in ServFlo: 5 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
Update organization	`PATCH /organizations/{organizationId}`	`write`
Name the business (first run)	`POST /organizations/{organizationId}/name`	`write`
Create logo upload URL	`POST /organizations/logo-upload-url`	`write`
Your role and permissions in an organization	`GET /organizations/{organizationId}/permissions`	`read`
Set the business logo (content in the request)	`POST /organizations/{organizationId}/logo/content`	`write`

Update organization

PATCH /organizations/{organizationId}

Renames the organization (in Base316 first), sets its logo path from POST /organizations/logo-upload-url (null removes it) and/or its IANA timezone (today, overdue dates, the membership scheduler, report days and on-time arrival are counted in it from then on) and/or its trade (what the website builder, the AI receptionist and the pricebook's starter items start from, and what Flo is told; changing it changes no existing records). Returns the organization.


Permission	`organization.manage` (Owner, Admin)
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`organizations_update` (toolset `settings`)

Request body

Field	Type	Required	Description
`name`	string	No	Up to 64 characters.
`logo`	string or null	No
`timezone`	string	No	IANA timezone, e.g. America/Chicago. Up to 100 characters.
`trade`	enum	No	The business's trade, e.g. hvac, plumbing, car-detailing (the website builder's trades), or "other". Starts the pricebook, website and AI receptionist from that trade. One of `hvac`, `plumbing`, `electrical`, `roofing`, `lawn-care`, `landscaping`, `tree-care`, `pest-control`, `house-cleaning`, `carpet-cleaning`, `window-cleaning`, `pressure-washing`, `pool-spa`, `painting`, `handyman`, `garage-doors`, `appliance-repair`, `locksmith`, `junk-removal`, `moving`, `flooring`, `remodeling`, `solar`, `septic-drain`, `chimney-fireplace`, `irrigation`, `car-detailing`, `other`.

Example

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

Response

200: the answer's fields

Field	Type	Description
`id`	string
`name`	string
`needsName`	boolean	Made at sign-up with the person's name and not named yet: POST /organizations/{organizationId}/name.
`needsPlan`	boolean	Named but no plan chosen yet (first run): GET /billing/plan-options, then POST /billing/choose-plan (plan "trial" keeps the free trial).
`slug`	string
`logo`	string or null
`trade`	string or null	The business's trade key (e.g. hvac, car-detailing, "other"); null = not chosen yet.
`equipmentLabels`	object	What equipment is called here, e.g. Vehicle / Vehicles (GET /equipment-labels).
`equipmentLabels.singular`	string
`equipmentLabels.plural`	string
`timezone`	string	The business's IANA timezone (e.g. America/Chicago): today, due dates, the scheduler and report days are counted in it.
`role`	string	The caller's Base316 role key here: owner, admin, dispatcher, technician or member.
`permissions`	array of string	The caller's effective permissions here.
`memberCount`	integer

Name the business (first run)

POST /organizations/{organizationId}/name

The first step after sign-up: sets the business's name (in Base316 first) and its timezone, and makes its URL slug from the name. With trade (stored on the business), the pricebook gets that trade's starter services, materials and fees in place of the generic starter items (see POST /pricebook/starter). Naming also queues the business's automatic texting number (bought by the worker in its ServFlo account, included on every plan) and makes ServFlo email its email provider unless one was chosen; neither happens before the business is named. Once named, use PATCH /organizations/{organizationId} to rename (the slug then stays). 409 when the business was named already.


Permission	`organization.manage` (Owner, Admin)
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`organizations_name` (toolset `settings`)

Request body

Field	Type	Required	Description
`name`	string	Yes	Up to 64 characters.
`timezone`	string	No	IANA timezone, e.g. America/Chicago. Up to 100 characters.
`trade`	enum	No	The business's trade, e.g. hvac, plumbing, car-detailing (the website builder's trades), or "other". Starts the pricebook, website and AI receptionist from that trade. One of `hvac`, `plumbing`, `electrical`, `roofing`, `lawn-care`, `landscaping`, `tree-care`, `pest-control`, `house-cleaning`, `carpet-cleaning`, `window-cleaning`, `pressure-washing`, `pool-spa`, `painting`, `handyman`, `garage-doors`, `appliance-repair`, `locksmith`, `junk-removal`, `moving`, `flooring`, `remodeling`, `solar`, `septic-drain`, `chimney-fireplace`, `irrigation`, `car-detailing`, `other`.

Example

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

Response

200: the answer's fields

Field	Type	Description
`id`	string
`name`	string
`needsName`	boolean	Made at sign-up with the person's name and not named yet: POST /organizations/{organizationId}/name.
`needsPlan`	boolean	Named but no plan chosen yet (first run): GET /billing/plan-options, then POST /billing/choose-plan (plan "trial" keeps the free trial).
`slug`	string
`logo`	string or null
`trade`	string or null	The business's trade key (e.g. hvac, car-detailing, "other"); null = not chosen yet.
`equipmentLabels`	object	What equipment is called here, e.g. Vehicle / Vehicles (GET /equipment-labels).
`equipmentLabels.singular`	string
`equipmentLabels.plural`	string
`timezone`	string	The business's IANA timezone (e.g. America/Chicago): today, due dates, the scheduler and report days are counted in it.
`role`	string	The caller's Base316 role key here: owner, admin, dispatcher, technician or member.
`permissions`	array of string	The caller's effective permissions here.
`memberCount`	integer

Create logo upload URL

POST /organizations/logo-upload-url

Step 1 of changing the logo: returns a signed URL to PUT a PNG to, and its path. Then save the path with PATCH /organizations/{organizationId} (logo).


Permission	`organization.manage` (Owner, Admin)
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`organizations_createLogoUploadUrl` (toolset `settings`)

Request body

Field	Type	Required	Description
`organizationId`	string	Yes	The organization whose logo is changing.

Example

curl -X POST "https://app.servflo.ai/api/organizations/logo-upload-url" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"organizationId":"organization_id"}'

Response

200: the answer's fields

Field	Type	Description
`signedUploadUrl`	string (uri)
`path`	string

Your role and permissions in an organization

GET /organizations/{organizationId}/permissions

The caller's role in the organization and every permission it grants, with the catalog's descriptions. Check this before attempting writes: a call needing a permission you lack is refused with 403. Read-only.


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

Example

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

Response

200: the answer's fields

Field	Type	Description
`role`	string
`roleName`	string
`permissions`	array of string

Set the business logo (content in the request)

POST /organizations/{organizationId}/logo/content

Replaces the business's logo in one call: send contentBase64 or a public sourceUrl (a PNG, JPEG or WebP image, up to 10 MB). It appears in the app, on customer pages, quotes and invoices. Returns the logo path.


Permission	`organization.manage` (Owner, Admin)
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`organizations_uploadLogo` (toolset `settings`)

Request body

Field	Type	Required	Description
`fileName`	string	No	The file's name, e.g. receipt.jpg (default: from the URL, else 'file'). Up to 500 characters.
`contentType`	string	No	MIME type, e.g. image/jpeg or application/pdf. Optional: taken from a data: URL, the URL's answer or the file's first bytes. Up to 200 characters.
`contentBase64`	string	No	The file's bytes as base64 (a data: URL is accepted too). Up to 10 MB. Give this or sourceUrl.
`sourceUrl`	string (uri)	No	A public http(s) URL ServFlo downloads the file from (up to 10 MB, 20 s, 3 redirects; private and internal addresses are refused). Give this or contentBase64. Up to 2000 characters.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/logo/content" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"string","contentType":"string","contentBase64":"string"}'

Response

200: the answer's fields

Field	Type	Description
`logo`	string	The logo's storage path (the organization's `logo`).

On this page