Agreements API

REST endpoints for agreements 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
A job's agreements	`GET /organizations/{organizationId}/jobs/{jobId}/agreements`	`read`
Prepare a job's agreement	`POST /organizations/{organizationId}/jobs/{jobId}/agreements`	`write`
Send a job's agreement to sign	`POST /organizations/{organizationId}/jobs/{jobId}/agreements/send`	`sensitive`
Record a client's agreement signature	`POST /organizations/{organizationId}/jobs/{jobId}/agreements/{agreementId}/sign`	`write`
Withdraw an unsigned agreement	`POST /organizations/{organizationId}/jobs/{jobId}/agreements/{agreementId}/void`	`sensitive`

A job's agreements

GET /organizations/{organizationId}/jobs/{jobId}/agreements

The job's pre-service agreements (pending, signed with name, time and IP, or withdrawn) with the frozen wording. Technicians: their own jobs. Read-only.


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

Parameters

Name	In	Type	Required	Description
`jobId`	path	string	Yes

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/jobs/{jobId}/agreements" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

An array of objects:

Field	Type	Description
`id`	string
`jobId`	string
`agreementTemplateId`	string or null
`status`	enum	One of `PENDING`, `SIGNED`, `VOID`.
`title`	string
`text`	string	The exact wording, frozen when it was made (safe HTML).
`textHash`	string
`signerName`	string or null
`signerIp`	string or null
`signedAt`	string (date-time) or null
`signedByStaff`	boolean
`sentAt`	string (date-time) or null
`url`	string or null	The signing link while pending.

Prepare a job's agreement

POST /organizations/{organizationId}/jobs/{jobId}/agreements

The job's pending agreement, or a new one with its wording frozen now (the chosen template, else the service type's, else the default). Returns it with its signing link; nothing is sent (POST …/agreements/send sends it). Technicians: their own jobs (to sign on site).


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

Parameters

Name	In	Type	Required	Description
`jobId`	path	string	Yes

Request body

Field	Type	Required	Description
`agreementTemplateId`	string or null	No

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/jobs/{jobId}/agreements" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agreementTemplateId":"agreementTemplate_id"}'

Response

201: the answer's fields

Field	Type	Description
`id`	string
`jobId`	string
`agreementTemplateId`	string or null
`status`	enum	One of `PENDING`, `SIGNED`, `VOID`.
`title`	string
`text`	string	The exact wording, frozen when it was made (safe HTML).
`textHash`	string
`signerName`	string or null
`signerIp`	string or null
`signedAt`	string (date-time) or null
`signedByStaff`	boolean
`sentAt`	string (date-time) or null
`url`	string or null	The signing link while pending.

Send a job's agreement to sign

POST /organizations/{organizationId}/jobs/{jobId}/agreements/send

Sends to the customer: emails and/or texts the job's customer the agreement's signing link (made as in POST …/agreements if needed). Consent and quiet hours apply. Returns the agreement and how each channel went.


Permission	`serviceReports.publish` (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	`agreements_send` (toolset `serviceReports`)
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
`jobId`	path	string	Yes

Request body

Field	Type	Required	Description
`agreementTemplateId`	string or null	No
`channels`	array of enum	No	Default both; each is subject to the customer's consent and quiet hours. Up to 2 items.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/jobs/{jobId}/agreements/send" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agreementTemplateId":"agreementTemplate_id","channels":["EMAIL"]}'

Response

200: the answer's fields

Field	Type	Description
`agreement`	object
`agreement.id`	string
`agreement.jobId`	string
`agreement.agreementTemplateId`	string or null
`agreement.status`	enum	One of `PENDING`, `SIGNED`, `VOID`.
`agreement.title`	string
`agreement.text`	string	The exact wording, frozen when it was made (safe HTML).
`agreement.textHash`	string
`agreement.signerName`	string or null
`agreement.signerIp`	string or null
`agreement.signedAt`	string (date-time) or null
`agreement.signedByStaff`	boolean
`agreement.sentAt`	string (date-time) or null
`agreement.url`	string or null	The signing link while pending.
`outcomes`	array of object
`outcomes[].channel`	enum	One of `EMAIL`, `SMS`.
`outcomes[].accessId`	string or null
`outcomes[].status`	string	The message's status: QUEUED, SENT, SENT_TEST, DEFERRED (quiet hours), SKIPPED (consent) …
`outcomes[].messageId`	string or null
`outcomes[].reason`	string or null

Record a client's agreement signature

POST /organizations/{organizationId}/jobs/{jobId}/agreements/{agreementId}/sign

The client signs on the technician's device (or on paper): typed name and an optional drawn signature (PNG data URL). Marked as recorded by staff. Pass the textHash of the wording the client was shown (GET …/agreements, or the offline packet): if the agreement's wording is no longer that, nothing is signed (409) and the client must be shown the current wording. 409 also when it is already signed or withdrawn. Re-checks the job's reports (one waiting for the agreement may open and be sent to the client). Emits agreement.signed. The technician app replays it with X-ServFlo-Occurred-At (signed when it happened).


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

Parameters

Name	In	Type	Required	Description
`jobId`	path	string	Yes
`agreementId`	path	string	Yes

Request body

Field	Type	Required	Description
`name`	string	Yes	The signer's full name. Up to 200 characters.
`signatureDataUrl`	string or null	No	Drawn signature, PNG data URL.
`textHash`	string or null	No	The agreement's `textHash` as the client was shown it. Recommended: a signature made against older wording is refused (409).

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/jobs/{jobId}/agreements/{agreementId}/sign" \
  -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
`jobId`	string
`agreementTemplateId`	string or null
`status`	enum	One of `PENDING`, `SIGNED`, `VOID`.
`title`	string
`text`	string	The exact wording, frozen when it was made (safe HTML).
`textHash`	string
`signerName`	string or null
`signerIp`	string or null
`signedAt`	string (date-time) or null
`signedByStaff`	boolean
`sentAt`	string (date-time) or null
`url`	string or null	The signing link while pending.

Withdraw an unsigned agreement

POST /organizations/{organizationId}/jobs/{jobId}/agreements/{agreementId}/void

Withdraws a pending agreement: its link stops working. A signed agreement cannot be withdrawn (409).


Permission	`serviceReports.publish` (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	`agreements_void` (toolset `serviceReports`)
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
`jobId`	path	string	Yes
`agreementId`	path	string	Yes

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/jobs/{jobId}/agreements/{agreementId}/void" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`id`	string
`jobId`	string
`agreementTemplateId`	string or null
`status`	enum	One of `PENDING`, `SIGNED`, `VOID`.
`title`	string
`text`	string	The exact wording, frozen when it was made (safe HTML).
`textHash`	string
`signerName`	string or null
`signerIp`	string or null
`signedAt`	string (date-time) or null
`signedByStaff`	boolean
`sentAt`	string (date-time) or null
`url`	string or null	The signing link while pending.

On this page