Selections API

REST endpoints for selections in ServFlo: 6 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
A project's selections	`GET /organizations/{organizationId}/projects/{projectId}/selections`	`read`
Add a selection	`POST /organizations/{organizationId}/projects/{projectId}/selections`	`write`
Change a selection	`PATCH /organizations/{organizationId}/selections/{selectionId}`	`write`
Delete a selection	`DELETE /organizations/{organizationId}/selections/{selectionId}`	`sensitive`
Let the customer choose again	`POST /organizations/{organizationId}/selections/{selectionId}/reopen`	`write`
Record the customer's choice	`POST /organizations/{organizationId}/selections/{selectionId}/choose`	`sensitive`

A project's selections

GET /organizations/{organizationId}/projects/{projectId}/selections

The choices the customer makes (flooring, cabinets, fixtures) with the allowance, options and what was chosen. Read-only.


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

Parameters

Name	In	Type	Required	Description
`projectId`	path	string	Yes	The project (GET /projects).

Example

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

Response

200: the answer's fields

An array of objects:

Field	Type	Description
`id`	string
`projectId`	string
`title`	string
`allowanceCents`	integer
`status`	enum	One of `OPEN`, `SELECTED`.
`dueDate`	string or null
`chosenOptionId`	string or null
`changeOrderId`	string or null
`options`	array of object
`options[].id`	string
`options[].name`	string
`options[].priceCents`	integer
`options[].differenceCents`	integer	Price − allowance: positive is an upgrade.

Add a selection

POST /organizations/{organizationId}/projects/{projectId}/selections

A choice for the customer with its allowance (what the contract includes), a due date and options (each with a price and a photo from the project's files). The customer picks in the portal; a pick over or under the allowance becomes an approved change order for the difference.


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

Parameters

Name	In	Type	Required	Description
`projectId`	path	string	Yes	The project (GET /projects).

Request body

Field	Type	Required	Description
`title`	string	Yes	Up to 200 characters.
`category`	string or null	No	Up to 100 characters.
`description`	string or null	No	Up to 5000 characters.
`dueDate`	empty string or string or null	No
`allowanceCents`	integer	No	Money in integer cents (12500 = 125.00). -100000000–100000000. Default `0`.
`options`	array of object	No	Up to 30 items. Default `[]`.
`options[].name`	string	Yes	Up to 200 characters.
`options[].description`	string or null	No	Up to 2000 characters.
`options[].priceCents`	integer	Yes	Money in integer cents (12500 = 125.00). -100000000–100000000.
`options[].fileId`	string or null	No	A photo from the project's files (GET …/files).

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/projects/{projectId}/selections" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"string"}'

Response

201: the answer's fields

Field	Type	Description
`id`	string
`projectId`	string
`title`	string
`allowanceCents`	integer
`status`	enum	One of `OPEN`, `SELECTED`.
`dueDate`	string or null
`chosenOptionId`	string or null
`changeOrderId`	string or null
`options`	array of object
`options[].id`	string
`options[].name`	string
`options[].priceCents`	integer
`options[].differenceCents`	integer	Price − allowance: positive is an upgrade.

Change a selection

PATCH /organizations/{organizationId}/selections/{selectionId}

Title, category, description, due date; the allowance and options (all of them) only while it is OPEN.


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

Parameters

Name	In	Type	Required	Description
`selectionId`	path	string	Yes

Request body

Field	Type	Required	Description
`title`	string	No	Up to 200 characters.
`category`	string or null	No	Up to 100 characters.
`description`	string or null	No	Up to 5000 characters.
`dueDate`	empty string or string or null	No
`allowanceCents`	integer	No	Money in integer cents (12500 = 125.00). -100000000–100000000.
`options`	array of object	No	Up to 30 items.
`options[].name`	string	Yes	Up to 200 characters.
`options[].description`	string or null	No	Up to 2000 characters.
`options[].priceCents`	integer	Yes	Money in integer cents (12500 = 125.00). -100000000–100000000.
`options[].fileId`	string or null	No	A photo from the project's files (GET …/files).

Example

curl -X PATCH "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/selections/{selectionId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"string","category":"string","description":"string"}'

Response

200: the answer's fields

Field	Type	Description
`id`	string
`projectId`	string
`title`	string
`allowanceCents`	integer
`status`	enum	One of `OPEN`, `SELECTED`.
`dueDate`	string or null
`chosenOptionId`	string or null
`changeOrderId`	string or null
`options`	array of object
`options[].id`	string
`options[].name`	string
`options[].priceCents`	integer
`options[].differenceCents`	integer	Price − allowance: positive is an upgrade.

Delete a selection

DELETE /organizations/{organizationId}/selections/{selectionId}

Destructive: deletes a selection that has not made a change order.


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

Parameters

Name	In	Type	Required	Description
`selectionId`	path	string	Yes

Example

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

Response

200: the answer's fields

Field	Type	Description
`ok`	true

Let the customer choose again

POST /organizations/{organizationId}/selections/{selectionId}/reopen

Opens a made choice again; the next pick is priced against the earlier one (a new change order for the difference).


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

Parameters

Name	In	Type	Required	Description
`selectionId`	path	string	Yes

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/selections/{selectionId}/reopen" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`id`	string
`projectId`	string
`title`	string
`allowanceCents`	integer
`status`	enum	One of `OPEN`, `SELECTED`.
`dueDate`	string or null
`chosenOptionId`	string or null
`changeOrderId`	string or null
`options`	array of object
`options[].id`	string
`options[].name`	string
`options[].priceCents`	integer
`options[].differenceCents`	integer	Price − allowance: positive is an upgrade.

Record the customer's choice

POST /organizations/{organizationId}/selections/{selectionId}/choose

Acts for the customer and changes the contract: records the option the customer chose (name: theirs, as they confirmed it). A price over or under the allowance becomes an APPROVED change order for the difference (contract, budget and progress billing follow).


Permission	`projects.write` (Owner, Admin, Dispatcher)
Risk	`sensitive`, OAuth scope `servflo.sensitive`. Sensitive: moves money, deletes, sends or shows something to a customer, or grants or revokes access.
MCP tool	`selections_choose` (toolset `projects`)
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
`selectionId`	path	string	Yes

Request body

Field	Type	Required	Description
`optionId`	string	Yes
`name`	string	Yes	Up to 200 characters.

Example

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

Response

200: the answer's fields

Field	Type	Description
`selection`	object
`selection.id`	string
`selection.projectId`	string
`selection.title`	string
`selection.allowanceCents`	integer
`selection.status`	enum	One of `OPEN`, `SELECTED`.
`selection.dueDate`	string or null
`selection.chosenOptionId`	string or null
`selection.changeOrderId`	string or null
`selection.options`	array of object
`selection.options[].id`	string
`selection.options[].name`	string
`selection.options[].priceCents`	integer
`selection.options[].differenceCents`	integer	Price − allowance: positive is an upgrade.
`changeOrderId`	string or null

On this page