Settings API

REST endpoints for settings in ServFlo: 12 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 lead sources	`GET /organizations/{organizationId}/lead-sources`	`read`
Create a lead source	`POST /organizations/{organizationId}/lead-sources`	`write`
Rename or (de)activate a lead source	`PATCH /organizations/{organizationId}/lead-sources/{leadSourceId}`	`write`
Delete a lead source	`DELETE /organizations/{organizationId}/lead-sources/{leadSourceId}`	`sensitive`
List custom field definitions	`GET /organizations/{organizationId}/custom-fields`	`read`
Define a custom field	`POST /organizations/{organizationId}/custom-fields`	`write`
Update a custom field	`PATCH /organizations/{organizationId}/custom-fields/{fieldId}`	`write`
Delete a custom field	`DELETE /organizations/{organizationId}/custom-fields/{fieldId}`	`sensitive`
Show a custom field to customers, or mark it sensitive	`POST /organizations/{organizationId}/custom-fields/{fieldId}/flags`	`sensitive`
Reveal a sensitive custom field value	`POST /organizations/{organizationId}/custom-fields/reveal`	`sensitive`
What customers agree to when they sign	`GET /organizations/{organizationId}/signing-terms`	`read`
Change what customers agree to when they sign	`PATCH /organizations/{organizationId}/signing-terms`	`sensitive`

List lead sources

GET /organizations/{organizationId}/lead-sources

Where customers hear about the business (Google, referral …), active and hidden, with customer counts. Read by anyone who can read customers, since customers point at them. Read-only.


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

Example

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

Response

200: the answer's fields

An array of objects:

Field	Type	Description
`id`	string	Lead source id (a customer's `leadSourceId`).
`organizationId`	string
`name`	string
`active`	boolean
`createdAt`	string (date-time)
`_count`	object	Customers from this source.
`_count.customers`	integer

Create a lead source

POST /organizations/{organizationId}/lead-sources

Adds a lead source to pick on customers (PATCH /customers leadSourceId). Names are unique (409). Returns it.


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

Request body

Field	Type	Required	Description
`name`	string	Yes	Up to 200 characters.
`active`	boolean	No

Example

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

Response

201: the answer's fields

Field	Type	Description
`id`	string	Lead source id (a customer's `leadSourceId`).
`organizationId`	string
`name`	string
`active`	boolean
`createdAt`	string (date-time)

Rename or (de)activate a lead source

PATCH /organizations/{organizationId}/lead-sources/{leadSourceId}

Renames it and/or hides it from forms (active: false) while customers keep the link. Returns it.


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

Parameters

Name	In	Type	Required	Description
`leadSourceId`	path	string	Yes

Request body

Field	Type	Required	Description
`name`	string	No	Up to 200 characters.
`active`	boolean	No

Example

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

Response

200: the answer's fields

Field	Type	Description
`id`	string	Lead source id (a customer's `leadSourceId`).
`organizationId`	string
`name`	string
`active`	boolean
`createdAt`	string (date-time)

Delete a lead source

DELETE /organizations/{organizationId}/lead-sources/{leadSourceId}

Destructive: deletes the lead source; customers keep existing with their lead source cleared. Deactivate instead to keep the link.


Permission	`settings.manage` (Owner, Admin)
Risk	`sensitive`, OAuth scope `servflo.sensitive`. Sensitive: moves money, deletes, sends or shows something to a customer, or grants or revokes access.
MCP tool	`leadSources_delete` (toolset `settings`)
Approval	Over MCP, this tool always waits for your approval in ServFlo. See Approvals.

Parameters

Name	In	Type	Required	Description
`leadSourceId`	path	string	Yes

Example

curl -X DELETE "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/lead-sources/{leadSourceId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`ok`	true

List custom field definitions

GET /organizations/{organizationId}/custom-fields

The extra fields the business defined (key, label, type, options, required, visibleToCustomer, sensitive) for customers, properties, equipment, jobs, visits, quotes, invoices or technicians; archived ones with includeArchived. For equipment, equipmentTypeId gives the fields for every type plus that type's own (what a piece of that type carries); allEquipmentTypes lists every type's. Needed to read and write customFields on those records. Values of sensitive fields read as •••• without customFields.sensitive.read (POST /custom-fields/reveal for one). Read-only.


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

Parameters

Name	In	Type	Required	Description
`entity`	query	enum	No	The record type: CUSTOMER, PROPERTY, EQUIPMENT (all types or one, `equipmentTypeId`), JOB, VISIT, QUOTE, INVOICE or TECHNICIAN. One of `CUSTOMER`, `PROPERTY`, `EQUIPMENT`, `JOB`, `VISIT`, `QUOTE`, `INVOICE`, `TECHNICIAN`.
`includeArchived`	query	boolean	No
`equipmentTypeId`	query	string	No	Equipment: the fields for every type plus this type's own.
`allEquipmentTypes`	query	boolean	No	Equipment: every type's fields too (Settings).

Example

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

Response

200: the answer's fields

An array of objects:

Field	Type	Description
`id`	string	Custom field id.
`organizationId`	string
`entity`	enum	The record type the field is on. One of `CUSTOMER`, `PROPERTY`, `EQUIPMENT`, `JOB`, `VISIT`, `QUOTE`, `INVOICE`, `TECHNICIAN`.
`key`	string	The key its values are stored under in the record's `customFields`; fixed. Two equipment types may share a key.
`label`	string
`type`	enum	One of `TEXT`, `TEXTAREA`, `NUMBER`, `DATE`, `CHECKBOX`, `SELECT`, `MULTI_SELECT`, `URL`, `EMAIL`, `PHONE`.
`options`	array of string	The choices of a SELECT or MULTI_SELECT field.
`required`	boolean
`sortOrder`	integer
`archived`	boolean
`equipmentTypeId`	string or null	EQUIPMENT only: the equipment type the field belongs to; null = every type.
`sensitive`	boolean	Sensitive (gate codes, medical notes): values read as •••• without customFields.sensitive.read; POST /custom-fields/reveal for one.
`visibleToCustomer`	boolean	Shown to the customer: printed on quote/invoice documents, their emails and pages, and in the customer portal.
`createdAt`	string (date-time)

Define a custom field

POST /organizations/{organizationId}/custom-fields

Defines a custom field on customers, properties, equipment (every type, or one with equipmentTypeId), jobs, visits, quotes, invoices or technicians. Its key is derived from the label once and never changes; SELECT and MULTI_SELECT need options. visibleToCustomer prints it on quote and invoice documents and their emails and shows it in the customer portal (customer-visible); sensitive (gate, alarm or lockbox codes, medical notes) masks its values for anyone without customFields.sensitive.read and can't be combined with visibleToCustomer. A new field has no values yet, so both flags may be set here; change them later with POST /custom-fields/{fieldId}/flags. Returns the definition.


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

Request body

Field	Type	Required	Description
`entity`	enum	Yes	The record type: CUSTOMER, PROPERTY, EQUIPMENT (all types or one, `equipmentTypeId`), JOB, VISIT, QUOTE, INVOICE or TECHNICIAN. One of `CUSTOMER`, `PROPERTY`, `EQUIPMENT`, `JOB`, `VISIT`, `QUOTE`, `INVOICE`, `TECHNICIAN`.
`label`	string	Yes	Up to 200 characters.
`type`	enum	Yes	One of `TEXT`, `TEXTAREA`, `NUMBER`, `DATE`, `CHECKBOX`, `SELECT`, `MULTI_SELECT`, `URL`, `EMAIL`, `PHONE`.
`options`	array of string	No	Up to 200 items.
`required`	boolean	No
`sortOrder`	integer	No
`equipmentTypeId`	string or null	No	EQUIPMENT only: the type the field belongs to; unset = every type.
`visibleToCustomer`	boolean	No	Show it to the customer (documents, emails, portal). Default false.
`sensitive`	boolean	No	Sensitive (gate codes, medical notes): values masked as •••• for callers without customFields.sensitive.read. Default false.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/custom-fields" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entity":"CUSTOMER","label":"string","type":"TEXT"}'

Response

201: the answer's fields

Field	Type	Description
`id`	string	Custom field id.
`organizationId`	string
`entity`	enum	The record type the field is on. One of `CUSTOMER`, `PROPERTY`, `EQUIPMENT`, `JOB`, `VISIT`, `QUOTE`, `INVOICE`, `TECHNICIAN`.
`key`	string	The key its values are stored under in the record's `customFields`; fixed. Two equipment types may share a key.
`label`	string
`type`	enum	One of `TEXT`, `TEXTAREA`, `NUMBER`, `DATE`, `CHECKBOX`, `SELECT`, `MULTI_SELECT`, `URL`, `EMAIL`, `PHONE`.
`options`	array of string	The choices of a SELECT or MULTI_SELECT field.
`required`	boolean
`sortOrder`	integer
`archived`	boolean
`equipmentTypeId`	string or null	EQUIPMENT only: the equipment type the field belongs to; null = every type.
`sensitive`	boolean	Sensitive (gate codes, medical notes): values read as •••• without customFields.sensitive.read; POST /custom-fields/reveal for one.
`visibleToCustomer`	boolean	Shown to the customer: printed on quote/invoice documents, their emails and pages, and in the customer portal.
`createdAt`	string (date-time)

Update a custom field

PATCH /organizations/{organizationId}/custom-fields/{fieldId}

Changes label, options, required or order, or archives it. The type and the equipment type cannot change. Archived fields keep their saved values but leave forms. Whether customers see it or it is sensitive: POST /custom-fields/{fieldId}/flags.


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

Parameters

Name	In	Type	Required	Description
`fieldId`	path	string	Yes

Request body

Field	Type	Required	Description
`label`	string	No	Up to 200 characters.
`options`	array of string	No	Up to 200 items.
`required`	boolean	No
`sortOrder`	integer	No
`archived`	boolean	No

Example

curl -X PATCH "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/custom-fields/{fieldId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"string","options":["string"],"required":true}'

Response

200: the answer's fields

Field	Type	Description
`id`	string	Custom field id.
`organizationId`	string
`entity`	enum	The record type the field is on. One of `CUSTOMER`, `PROPERTY`, `EQUIPMENT`, `JOB`, `VISIT`, `QUOTE`, `INVOICE`, `TECHNICIAN`.
`key`	string	The key its values are stored under in the record's `customFields`; fixed. Two equipment types may share a key.
`label`	string
`type`	enum	One of `TEXT`, `TEXTAREA`, `NUMBER`, `DATE`, `CHECKBOX`, `SELECT`, `MULTI_SELECT`, `URL`, `EMAIL`, `PHONE`.
`options`	array of string	The choices of a SELECT or MULTI_SELECT field.
`required`	boolean
`sortOrder`	integer
`archived`	boolean
`equipmentTypeId`	string or null	EQUIPMENT only: the equipment type the field belongs to; null = every type.
`sensitive`	boolean	Sensitive (gate codes, medical notes): values read as •••• without customFields.sensitive.read; POST /custom-fields/reveal for one.
`visibleToCustomer`	boolean	Shown to the customer: printed on quote/invoice documents, their emails and pages, and in the customer portal.
`createdAt`	string (date-time)

Delete a custom field

DELETE /organizations/{organizationId}/custom-fields/{fieldId}

Destructive: deletes the definition; saved values can no longer be seen. Archive instead to keep them.


Permission	`settings.manage` (Owner, Admin)
Risk	`sensitive`, OAuth scope `servflo.sensitive`. Sensitive: moves money, deletes, sends or shows something to a customer, or grants or revokes access.
MCP tool	`customFields_delete` (toolset `settings`)
Approval	Over MCP, this tool always waits for your approval in ServFlo. See Approvals.

Parameters

Name	In	Type	Required	Description
`fieldId`	path	string	Yes

Example

curl -X DELETE "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/custom-fields/{fieldId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`ok`	true

Show a custom field to customers, or mark it sensitive

POST /organizations/{organizationId}/custom-fields/{fieldId}/flags

EXPOSES TO CUSTOMERS / CHANGES WHO SEES IT: visibleToCustomer: true prints the field's saved values on quotes and invoices, their emails and the customer portal; sensitive: true masks its values (••••) for everyone without customFields.sensitive.read, false shows them to every role that reads the record. A field can't be both (400). Returns the definition.


Permission	`settings.manage` (Owner, Admin)
Risk	`sensitive`, OAuth scope `servflo.sensitive`. Sensitive: moves money, deletes, sends or shows something to a customer, or grants or revokes access.
MCP tool	`customFields_setFlags` (toolset `settings`)
Approval	Over MCP, this tool asks for your OK first (in the AI app when it supports it, otherwise in ServFlo). See Approvals.

Parameters

Name	In	Type	Required	Description
`fieldId`	path	string	Yes

Request body

Field	Type	Required	Description
`visibleToCustomer`	boolean	No
`sensitive`	boolean	No

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/custom-fields/{fieldId}/flags" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"visibleToCustomer":true,"sensitive":true}'

Response

200: the answer's fields

Field	Type	Description
`id`	string	Custom field id.
`organizationId`	string
`entity`	enum	The record type the field is on. One of `CUSTOMER`, `PROPERTY`, `EQUIPMENT`, `JOB`, `VISIT`, `QUOTE`, `INVOICE`, `TECHNICIAN`.
`key`	string	The key its values are stored under in the record's `customFields`; fixed. Two equipment types may share a key.
`label`	string
`type`	enum	One of `TEXT`, `TEXTAREA`, `NUMBER`, `DATE`, `CHECKBOX`, `SELECT`, `MULTI_SELECT`, `URL`, `EMAIL`, `PHONE`.
`options`	array of string	The choices of a SELECT or MULTI_SELECT field.
`required`	boolean
`sortOrder`	integer
`archived`	boolean
`equipmentTypeId`	string or null	EQUIPMENT only: the equipment type the field belongs to; null = every type.
`sensitive`	boolean	Sensitive (gate codes, medical notes): values read as •••• without customFields.sensitive.read; POST /custom-fields/reveal for one.
`visibleToCustomer`	boolean	Shown to the customer: printed on quote/invoice documents, their emails and pages, and in the customer portal.
`createdAt`	string (date-time)

Reveal a sensitive custom field value

POST /organizations/{organizationId}/custom-fields/reveal

Exposes a secret: one sensitive value (a gate or lockbox code, a medical note) of one record, which other answers show as ••••. Recorded in the activity log. Technicians: only the customers, properties, equipment, jobs and visits of their own jobs (404 otherwise). Get the field's key from GET /custom-fields.

Permission: customFields.sensitive.read (Owner, Admin, Dispatcher, Technician (own jobs)); risk sensitive (OAuth scope servflo.sensitive).


Permission	`customFields.sensitive.read`
Risk	`sensitive`, OAuth scope `servflo.sensitive`. Sensitive: moves money, deletes, sends or shows something to a customer, or grants or revokes access.
MCP tool	`customFields_reveal` (toolset `settings`)
Approval	Over MCP, this tool always waits for your approval in ServFlo. See Approvals.

Request body

Field	Type	Required	Description
`entity`	enum	Yes	The record type: CUSTOMER, PROPERTY, EQUIPMENT (all types or one, `equipmentTypeId`), JOB, VISIT, QUOTE, INVOICE or TECHNICIAN. One of `CUSTOMER`, `PROPERTY`, `EQUIPMENT`, `JOB`, `VISIT`, `QUOTE`, `INVOICE`, `TECHNICIAN`.
`recordId`	string	Yes	The customer, property, equipment, job, visit, quote, invoice or technician id.
`key`	string	Yes	The sensitive field's key. Up to 200 characters.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/custom-fields/reveal" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entity":"CUSTOMER","recordId":"record_id","key":"string"}'

Response

200: the answer's fields

Field	Type	Description
`key`	string
`label`	string
`type`	string
`value`	any	The stored value; null when empty.

What customers agree to when they sign

GET /organizations/{organizationId}/signing-terms

The job sign-off statement, the quote terms and the membership agreement: the business's wording (null = ServFlo's default), the defaults, and the resolved text customers see ({business} replaced by the business's name). Read-only.


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

Example

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

Response

200: the answer's fields

Field	Type	Description
`signOffTerms`	string or null	The business's sign-off statement; null = the default.
`quoteTerms`	string or null	The business's quote terms; null = the default.
`membershipTerms`	string or null	The membership agreement signed on a technician's phone; null = the default.
`defaults`	object
`defaults.signOffTerms`	string
`defaults.quoteTerms`	string
`defaults.membershipTerms`	string
`resolved`	object	What customers see now, `{business}` filled in.
`resolved.signOffTerms`	string
`resolved.quoteTerms`	string
`resolved.membershipTerms`	string

Change what customers agree to when they sign

PATCH /organizations/{organizationId}/signing-terms

Changes what customers agree to: sets the job sign-off statement, the quote terms and/or the membership agreement (up to 5000 characters each; {business} is replaced by the business's name). Null or empty restores the default. Signatures already given keep the text they were shown.


Permission	`settings.manage` (Owner, Admin)
Risk	`sensitive`, OAuth scope `servflo.sensitive`. Sensitive: moves money, deletes, sends or shows something to a customer, or grants or revokes access.
MCP tool	`signingTerms_update` (toolset `settings`)
Approval	Over MCP, this tool asks for your OK first (in the AI app when it supports it, otherwise in ServFlo). See Approvals.

Request body

Field	Type	Required	Description
`signOffTerms`	string or null	No	Up to 5000 characters.
`quoteTerms`	string or null	No	Up to 5000 characters.
`membershipTerms`	string or null	No	Up to 5000 characters.

Example

curl -X PATCH "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/signing-terms" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"signOffTerms":"string","quoteTerms":"string","membershipTerms":"string"}'

Response

200: the answer's fields

Field	Type	Description
`signOffTerms`	string or null	The business's sign-off statement; null = the default.
`quoteTerms`	string or null	The business's quote terms; null = the default.
`membershipTerms`	string or null	The membership agreement signed on a technician's phone; null = the default.
`defaults`	object
`defaults.signOffTerms`	string
`defaults.quoteTerms`	string
`defaults.membershipTerms`	string
`resolved`	object	What customers see now, `{business}` filled in.
`resolved.signOffTerms`	string
`resolved.quoteTerms`	string
`resolved.membershipTerms`	string

On this page