Settings API

REST endpoints for settings in SKUFlow: 12 operations with parameters, request and response fields, permissions and curl examples.

Base URL: https://app.skuflow.ai/api. Every call needs Authorization: Bearer skf_… (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 approve a quote	`GET /organizations/{organizationId}/signing-terms`	`read`
Change what customers agree to when they approve a quote	`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, Staff, Member)
Risk	`read`, OAuth scope `skuflow.read`. Read: reads only.
MCP tool	`leadSources_list` (toolset `settings`)

Example

curl "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/lead-sources" \
  -H "Authorization: Bearer $SKUFLOW_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 `skuflow.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.skuflow.ai/api/organizations/$ORGANIZATION_ID/lead-sources" \
  -H "Authorization: Bearer $SKUFLOW_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 `skuflow.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.skuflow.ai/api/organizations/$ORGANIZATION_ID/lead-sources/{leadSourceId}" \
  -H "Authorization: Bearer $SKUFLOW_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 `skuflow.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 SKUFlow. See Approvals.

Parameters

Name	In	Type	Required	Description
`leadSourceId`	path	string	Yes

Example

curl -X DELETE "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/lead-sources/{leadSourceId}" \
  -H "Authorization: Bearer $SKUFLOW_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 (customer addresses), quotes or invoices; archived ones with includeArchived. 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, Staff, Member)
Risk	`read`, OAuth scope `skuflow.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 (a customer address), QUOTE or INVOICE. One of `CUSTOMER`, `PROPERTY`, `QUOTE`, `INVOICE`.
`includeArchived`	query	boolean	No

Example

curl "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/custom-fields" \
  -H "Authorization: Bearer $SKUFLOW_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`, `QUOTE`, `INVOICE`.
`key`	string	The key its values are stored under in the record's `customFields`; fixed, unique per record type.
`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
`sensitive`	boolean	Sensitive (account numbers, private 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 (customer addresses), quotes or invoices. 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 (account numbers, private 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 `skuflow.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 (a customer address), QUOTE or INVOICE. One of `CUSTOMER`, `PROPERTY`, `QUOTE`, `INVOICE`.
`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
`visibleToCustomer`	boolean	No	Show it to the customer (documents, emails, portal). Default false.
`sensitive`	boolean	No	Sensitive (account numbers, private notes): values masked as •••• for callers without customFields.sensitive.read. Default false.

Example

curl -X POST "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/custom-fields" \
  -H "Authorization: Bearer $SKUFLOW_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`, `QUOTE`, `INVOICE`.
`key`	string	The key its values are stored under in the record's `customFields`; fixed, unique per record type.
`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
`sensitive`	boolean	Sensitive (account numbers, private 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 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 `skuflow.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.skuflow.ai/api/organizations/$ORGANIZATION_ID/custom-fields/{fieldId}" \
  -H "Authorization: Bearer $SKUFLOW_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`, `QUOTE`, `INVOICE`.
`key`	string	The key its values are stored under in the record's `customFields`; fixed, unique per record type.
`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
`sensitive`	boolean	Sensitive (account numbers, private 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 `skuflow.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 SKUFlow. See Approvals.

Parameters

Name	In	Type	Required	Description
`fieldId`	path	string	Yes

Example

curl -X DELETE "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/custom-fields/{fieldId}" \
  -H "Authorization: Bearer $SKUFLOW_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 `skuflow.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 SKUFlow). 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.skuflow.ai/api/organizations/$ORGANIZATION_ID/custom-fields/{fieldId}/flags" \
  -H "Authorization: Bearer $SKUFLOW_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`, `QUOTE`, `INVOICE`.
`key`	string	The key its values are stored under in the record's `customFields`; fixed, unique per record type.
`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
`sensitive`	boolean	Sensitive (account numbers, private 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 (an account number, a private note) of one record, which other answers show as ••••. Recorded in the activity log. Get the field's key from GET /custom-fields.


Permission	`customFields.sensitive.read` (Owner, Admin, Staff)
Risk	`sensitive`, OAuth scope `skuflow.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 SKUFlow. See Approvals.

Request body

Field	Type	Required	Description
`entity`	enum	Yes	The record type: CUSTOMER, PROPERTY (a customer address), QUOTE or INVOICE. One of `CUSTOMER`, `PROPERTY`, `QUOTE`, `INVOICE`.
`recordId`	string	Yes	The customer, property, quote or invoice id.
`key`	string	Yes	The sensitive field's key. Up to 200 characters.

Example

curl -X POST "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/custom-fields/reveal" \
  -H "Authorization: Bearer $SKUFLOW_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 approve a quote

GET /organizations/{organizationId}/signing-terms

The quote terms: the business's wording (null = SKUFlow's default), the default, and the resolved text customers see ({business} replaced by the business's name). Read-only.


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

Example

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

Response

200: the answer's fields

Field	Type	Description
`quoteTerms`	string or null	The business's quote terms; null = the default.
`defaults`	object
`defaults.quoteTerms`	string
`resolved`	object	What customers see now, `{business}` filled in.
`resolved.quoteTerms`	string

Change what customers agree to when they approve a quote

PATCH /organizations/{organizationId}/signing-terms

Changes what customers agree to: sets the quote terms (up to 5000 characters; {business} is replaced by the business's name). Null or empty restores the default. Approvals already given keep the text they were shown.


Permission	`settings.manage` (Owner, Admin)
Risk	`sensitive`, OAuth scope `skuflow.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 SKUFlow). See Approvals.

Request body

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

Example

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

Response

200: the answer's fields

Field	Type	Description
`quoteTerms`	string or null	The business's quote terms; null = the default.
`defaults`	object
`defaults.quoteTerms`	string
`resolved`	object	What customers see now, `{business}` filled in.
`resolved.quoteTerms`	string

List lead sourcesCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

Create a lead sourceCopy Anchor Link

Request bodyCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

Rename or (de)activate a lead sourceCopy Anchor Link

ParametersCopy Anchor Link

Request bodyCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

Delete a lead sourceCopy Anchor Link

ParametersCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

List custom field definitionsCopy Anchor Link

ParametersCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

Define a custom fieldCopy Anchor Link

Request bodyCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

Update a custom fieldCopy Anchor Link

ParametersCopy Anchor Link

Request bodyCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

Delete a custom fieldCopy Anchor Link

ParametersCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

Show a custom field to customers, or mark it sensitiveCopy Anchor Link

ParametersCopy Anchor Link

Request bodyCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

Reveal a sensitive custom field valueCopy Anchor Link

Request bodyCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

What customers agree to when they approve a quoteCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

Change what customers agree to when they approve a quoteCopy Anchor Link

Request bodyCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

On this page

List lead sources

Example

Response

Create a lead source

Request body

Example

Response

Rename or (de)activate a lead source

Parameters

Request body

Example

Response

Delete a lead source

Parameters

Example

Response

List custom field definitions

Parameters

Example

Response

Define a custom field

Request body

Example

Response

Update a custom field

Parameters

Request body

Example

Response

Delete a custom field

Parameters

Example

Response

Show a custom field to customers, or mark it sensitive

Parameters

Request body

Example

Response

Reveal a sensitive custom field value

Request body

Example

Response

What customers agree to when they approve a quote

Example

Response

Change what customers agree to when they approve a quote

Request body

Example

Response