Subcontracts API

REST endpoints for subcontracts 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
Subcontractor bids, bills and payments on a project	`GET /organizations/{organizationId}/projects/{projectId}/subcontracts`	`read`
Record a sub's bid	`POST /organizations/{organizationId}/projects/{projectId}/subcontracts/bids`	`write`
Accept, decline or change a bid	`PATCH /organizations/{organizationId}/projects/{projectId}/subcontracts/bids/{bidId}`	`write`
Delete a bid	`DELETE /organizations/{organizationId}/projects/{projectId}/subcontracts/bids/{bidId}`	`sensitive`
Record a sub's bill	`POST /organizations/{organizationId}/projects/{projectId}/subcontracts/bills`	`write`
Change a sub's bill	`PATCH /organizations/{organizationId}/projects/{projectId}/subcontracts/bills/{billId}`	`write`
Delete a sub's bill	`DELETE /organizations/{organizationId}/projects/{projectId}/subcontracts/bills/{billId}`	`sensitive`
Record a payment to a sub	`POST /organizations/{organizationId}/projects/{projectId}/subcontracts/bills/{billId}/payments`	`write`
Delete a recorded payment to a sub	`DELETE /organizations/{organizationId}/projects/{projectId}/subcontracts/payments/{subPaymentId}`	`sensitive`
Subcontractors' view-only links	`GET /organizations/{organizationId}/projects/{projectId}/sub-links`	`read`
Give a sub a view-only link	`POST /organizations/{organizationId}/projects/{projectId}/sub-links`	`sensitive`
Turn off a sub's link	`POST /organizations/{organizationId}/projects/{projectId}/sub-links/revoke`	`sensitive`

Subcontractor bids, bills and payments on a project

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

Bids (accepted ones are committed), bills with the payments recorded and lien waivers, and per sub: committed, billed, paid and owed. ServFlo records payments; it never pays a sub. Read-only.


Permission	`subcontractors.bills` (Owner, Admin)
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`subcontracts_get` (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}/subcontracts" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`bids`	array of object
`bids[].id`	string
`bids[].vendorId`	string
`bids[].amountCents`	integer
`bids[].status`	string
`bills`	array of object
`bills[].id`	string
`bills[].vendorId`	string
`bills[].amountCents`	integer
`bills[].paidCents`	integer
`bills[].owedCents`	integer
`bills[].payments`	array of object
`bills[].payments[].id`	string
`bills[].payments[].amountCents`	integer
`bills[].payments[].hasLienWaiver`	boolean
`bySubcontractor`	array of object
`bySubcontractor[].vendorId`	string
`bySubcontractor[].owedCents`	integer
`totals`	object
`totals.owedCents`	integer

Record a sub's bid

POST /organizations/{organizationId}/projects/{projectId}/subcontracts/bids

A subcontractor's price for work on the project (optionally a phase). Accept it with PATCH …/bids/{bidId}.


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

Parameters

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

Request body

Field	Type	Required	Description
`vendorId`	string	Yes	The subcontractor (a vendor; GET /subcontractors).
`phaseId`	string or null	No
`amountCents`	integer	Yes	Money in integer cents (12500 = 125.00). -100000000–100000000.
`scope`	string or null	No	Up to 5000 characters.
`receivedOn`	empty string or string or null	No

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/projects/{projectId}/subcontracts/bids" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"vendorId":"vendor_id","amountCents":12500}'

Response

201: the answer's fields

Field	Type	Description
`bids`	array of object
`bids[].id`	string
`bids[].vendorId`	string
`bids[].amountCents`	integer
`bids[].status`	string
`bills`	array of object
`bills[].id`	string
`bills[].vendorId`	string
`bills[].amountCents`	integer
`bills[].paidCents`	integer
`bills[].owedCents`	integer
`bills[].payments`	array of object
`bills[].payments[].id`	string
`bills[].payments[].amountCents`	integer
`bills[].payments[].hasLienWaiver`	boolean
`bySubcontractor`	array of object
`bySubcontractor[].vendorId`	string
`bySubcontractor[].owedCents`	integer
`totals`	object
`totals.owedCents`	integer

Accept, decline or change a bid

PATCH /organizations/{organizationId}/projects/{projectId}/subcontracts/bids/{bidId}

ACCEPTED commits the amount (and puts the sub on the bid's phase when it has none); DECLINED; or change the amount, scope or phase.


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

Parameters

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

Request body

Field	Type	Required	Description
`status`	enum	No	One of `SUBMITTED`, `ACCEPTED`, `DECLINED`.
`amountCents`	integer	No	Money in integer cents (12500 = 125.00). -100000000–100000000.
`scope`	string or null	No	Up to 5000 characters.
`phaseId`	string or null	No

Example

curl -X PATCH "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/projects/{projectId}/subcontracts/bids/{bidId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"SUBMITTED","amountCents":12500,"scope":"string"}'

Response

200: the answer's fields

Field	Type	Description
`bids`	array of object
`bids[].id`	string
`bids[].vendorId`	string
`bids[].amountCents`	integer
`bids[].status`	string
`bills`	array of object
`bills[].id`	string
`bills[].vendorId`	string
`bills[].amountCents`	integer
`bills[].paidCents`	integer
`bills[].owedCents`	integer
`bills[].payments`	array of object
`bills[].payments[].id`	string
`bills[].payments[].amountCents`	integer
`bills[].payments[].hasLienWaiver`	boolean
`bySubcontractor`	array of object
`bySubcontractor[].vendorId`	string
`bySubcontractor[].owedCents`	integer
`totals`	object
`totals.owedCents`	integer

Delete a bid

DELETE /organizations/{organizationId}/projects/{projectId}/subcontracts/bids/{bidId}

Destructive: removes a subcontractor's bid from the project (an accepted bid stops counting as committed).


Permission	`subcontractors.bills` (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	`subcontracts_deleteBid` (toolset `projects`)
Approval	Over MCP, this tool always waits for your approval in ServFlo. See Approvals.

Parameters

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

Example

curl -X DELETE "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/projects/{projectId}/subcontracts/bids/{bidId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`bids`	array of object
`bids[].id`	string
`bids[].vendorId`	string
`bids[].amountCents`	integer
`bids[].status`	string
`bills`	array of object
`bills[].id`	string
`bills[].vendorId`	string
`bills[].amountCents`	integer
`bills[].paidCents`	integer
`bills[].owedCents`	integer
`bills[].payments`	array of object
`bills[].payments[].id`	string
`bills[].payments[].amountCents`	integer
`bills[].payments[].hasLienWaiver`	boolean
`bySubcontractor`	array of object
`bySubcontractor[].vendorId`	string
`bySubcontractor[].owedCents`	integer
`totals`	object
`totals.owedCents`	integer

Record a sub's bill

POST /organizations/{organizationId}/projects/{projectId}/subcontracts/bills

What a subcontractor billed for the project: it counts in SUBCONTRACTORS actuals and in what the sub is owed.


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

Parameters

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

Request body

Field	Type	Required	Description
`vendorId`	string	Yes	The subcontractor (a vendor; GET /subcontractors).
`phaseId`	string or null	No
`number`	string or null	No	Up to 100 characters.
`billDate`	empty string or string or null	No
`dueDate`	empty string or string or null	No
`amountCents`	integer	Yes	Money in integer cents (12500 = 125.00). -100000000–100000000.
`description`	string or null	No	Up to 5000 characters.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/projects/{projectId}/subcontracts/bills" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"vendorId":"vendor_id","amountCents":12500}'

Response

201: the answer's fields

Field	Type	Description
`bids`	array of object
`bids[].id`	string
`bids[].vendorId`	string
`bids[].amountCents`	integer
`bids[].status`	string
`bills`	array of object
`bills[].id`	string
`bills[].vendorId`	string
`bills[].amountCents`	integer
`bills[].paidCents`	integer
`bills[].owedCents`	integer
`bills[].payments`	array of object
`bills[].payments[].id`	string
`bills[].payments[].amountCents`	integer
`bills[].payments[].hasLienWaiver`	boolean
`bySubcontractor`	array of object
`bySubcontractor[].vendorId`	string
`bySubcontractor[].owedCents`	integer
`totals`	object
`totals.owedCents`	integer

Change a sub's bill

PATCH /organizations/{organizationId}/projects/{projectId}/subcontracts/bills/{billId}

Number, dates, amount (not below what was paid), description or phase.


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

Parameters

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

Request body

Field	Type	Required	Description
`phaseId`	string or null	No
`number`	string or null	No	Up to 100 characters.
`billDate`	string	No	A calendar date in the business's own calendar, YYYY-MM-DD.
`dueDate`	empty string or string or null	No
`amountCents`	integer	No	Money in integer cents (12500 = 125.00). -100000000–100000000.
`description`	string or null	No	Up to 5000 characters.

Example

curl -X PATCH "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/projects/{projectId}/subcontracts/bills/{billId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phaseId":"phase_id","number":"string","billDate":"2026-11-03"}'

Response

200: the answer's fields

Field	Type	Description
`bids`	array of object
`bids[].id`	string
`bids[].vendorId`	string
`bids[].amountCents`	integer
`bids[].status`	string
`bills`	array of object
`bills[].id`	string
`bills[].vendorId`	string
`bills[].amountCents`	integer
`bills[].paidCents`	integer
`bills[].owedCents`	integer
`bills[].payments`	array of object
`bills[].payments[].id`	string
`bills[].payments[].amountCents`	integer
`bills[].payments[].hasLienWaiver`	boolean
`bySubcontractor`	array of object
`bySubcontractor[].vendorId`	string
`bySubcontractor[].owedCents`	integer
`totals`	object
`totals.owedCents`	integer

Delete a sub's bill

DELETE /organizations/{organizationId}/projects/{projectId}/subcontracts/bills/{billId}

Destructive: removes a bill without payments.


Permission	`subcontractors.bills` (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	`subcontracts_deleteBill` (toolset `projects`)
Approval	Over MCP, this tool always waits for your approval in ServFlo. See Approvals.

Parameters

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

Example

curl -X DELETE "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/projects/{projectId}/subcontracts/bills/{billId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`bids`	array of object
`bids[].id`	string
`bids[].vendorId`	string
`bids[].amountCents`	integer
`bids[].status`	string
`bills`	array of object
`bills[].id`	string
`bills[].vendorId`	string
`bills[].amountCents`	integer
`bills[].paidCents`	integer
`bills[].owedCents`	integer
`bills[].payments`	array of object
`bills[].payments[].id`	string
`bills[].payments[].amountCents`	integer
`bills[].payments[].hasLienWaiver`	boolean
`bySubcontractor`	array of object
`bySubcontractor[].vendorId`	string
`bySubcontractor[].owedCents`	integer
`totals`	object
`totals.owedCents`	integer

Record a payment to a sub

POST /organizations/{organizationId}/projects/{projectId}/subcontracts/bills/{billId}/payments

Records a payment the business made outside ServFlo (check, ACH, cash, card): NEVER moves money. Not more than is left on the bill. Attach the lien waiver with POST …/files (category LIEN_WAIVER, subPaymentId).


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

Parameters

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

Request body

Field	Type	Required	Description
`amountCents`	integer	Yes	Money in integer cents (12500 = 125.00). -100000000–100000000.
`paidOn`	empty string or string or null	No
`method`	enum	No	One of `CHECK`, `ACH`, `CASH`, `CARD`, `OTHER`. Default `CHECK`.
`reference`	string or null	No	Up to 100 characters.
`note`	string or null	No	Up to 2000 characters.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/projects/{projectId}/subcontracts/bills/{billId}/payments" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amountCents":12500}'

Response

201: the answer's fields

Field	Type	Description
`bids`	array of object
`bids[].id`	string
`bids[].vendorId`	string
`bids[].amountCents`	integer
`bids[].status`	string
`bills`	array of object
`bills[].id`	string
`bills[].vendorId`	string
`bills[].amountCents`	integer
`bills[].paidCents`	integer
`bills[].owedCents`	integer
`bills[].payments`	array of object
`bills[].payments[].id`	string
`bills[].payments[].amountCents`	integer
`bills[].payments[].hasLienWaiver`	boolean
`bySubcontractor`	array of object
`bySubcontractor[].vendorId`	string
`bySubcontractor[].owedCents`	integer
`totals`	object
`totals.owedCents`	integer
`paymentId`	string

Delete a recorded payment to a sub

DELETE 
/organizations/{organizationId}/projects/{projectId}/subcontracts/payments/{subPaymentId}

Destructive: removes a recorded payment (its lien waiver stays in the files).


Permission	`subcontractors.bills` (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	`subcontracts_deletePayment` (toolset `projects`)
Approval	Over MCP, this tool always waits for your approval in ServFlo. See Approvals.

Parameters

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

Example

curl -X DELETE "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/projects/{projectId}/subcontracts/payments/{subPaymentId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`bids`	array of object
`bids[].id`	string
`bids[].vendorId`	string
`bids[].amountCents`	integer
`bids[].status`	string
`bills`	array of object
`bills[].id`	string
`bills[].vendorId`	string
`bills[].amountCents`	integer
`bills[].paidCents`	integer
`bills[].owedCents`	integer
`bills[].payments`	array of object
`bills[].payments[].id`	string
`bills[].payments[].amountCents`	integer
`bills[].payments[].hasLienWaiver`	boolean
`bySubcontractor`	array of object
`bySubcontractor[].vendorId`	string
`bySubcontractor[].owedCents`	integer
`totals`	object
`totals.owedCents`	integer

Subcontractors' view-only links

GET /organizations/{organizationId}/projects/{projectId}/sub-links

The live view-only links of subs on the project. Read-only.


Permission	`subcontractors.read` (Owner, Admin, Dispatcher, Member)
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`subcontracts_links` (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}/sub-links" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

An array of objects:

Field	Type	Description
`id`	string
`vendorId`	string
`url`	string

Give a sub a view-only link

POST /organizations/{organizationId}/projects/{projectId}/sub-links

Grants access: a link (/sub/{token}) where the subcontractor sees the project's name and address, their phases and the files shared with subs; never prices or the customer's details. Returns the live link when there is one.


Permission	`subcontractors.manage` (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	`subcontracts_createLink` (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
`projectId`	path	string	Yes	The project (GET /projects).

Request body

Field	Type	Required	Description
`vendorId`	string	Yes	The subcontractor (a vendor; GET /subcontractors).

Example

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

Response

201: the answer's fields

Field	Type	Description
`id`	string
`url`	string

Turn off a sub's link

POST /organizations/{organizationId}/projects/{projectId}/sub-links/revoke

Revokes access: the sub's link stops working.


Permission	`subcontractors.manage` (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	`subcontracts_revokeLink` (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
`projectId`	path	string	Yes	The project (GET /projects).

Request body

Field	Type	Required	Description
`vendorId`	string	Yes	The subcontractor (a vendor; GET /subcontractors).

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/projects/{projectId}/sub-links/revoke" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"vendorId":"vendor_id"}'

Response

200: the answer's fields

Field	Type	Description
`ok`	true

On this page