Customer messaging API

REST endpoints for customer messaging in ServFlo: 2 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 customer's messaging consent	`GET /organizations/{organizationId}/customers/{customerId}/messaging`	`read`
Change a contact method's consent	`PATCH /organizations/{organizationId}/customers/{customerId}/messaging/consent`	`sensitive`

A customer's messaging consent

GET /organizations/{organizationId}/customers/{customerId}/messaging

For each contact method of the customer: OK to text, suppression (bounce, complaint, STOP), marketing and service-email choices with who made them, and whether an automation may send transactional and marketing messages there (with the reason when not). The message history is GET /messages?customerId=…. Read-only.


Permission	`engagement.read` (Owner, Admin, Dispatcher)
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`customerMessaging_get` (toolset `customers`)

Parameters

Name	In	Type	Required	Description
`customerId`	path	string	Yes

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/customers/{customerId}/messaging" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`preferences`	object
`preferences.allowEmail`	boolean
`preferences.allowSms`	boolean
`preferences.allowMarketing`	boolean
`preferences.status`	string
`preferences.doNotService`	boolean
`methods`	array of object
`methods[].contactId`	string
`methods[].contactName`	string or null
`methods[].isPrimaryContact`	boolean
`methods[].roles`	array of string
`methods[].contactMethodId`	string
`methods[].channel`	enum	One of `EMAIL`, `SMS`.
`methods[].label`	string
`methods[].value`	string
`methods[].smsConsent`	enum or null	OK to text (phones). One of `UNKNOWN`, `GRANTED`, `DENIED`.
`methods[].suppression`	enum or null	One of `BOUNCE`, `COMPLAINT`, `UNSUBSCRIBE`, `STOP`, `MANUAL`.
`methods[].marketing`	enum or null	One of `OPTED_IN`, `OPTED_OUT`.
`methods[].marketingSource`	string or null
`methods[].transactional`	enum or null	One of `OPTED_IN`, `OPTED_OUT`.
`methods[].transactionalSource`	string or null
`methods[].canGrantSms`	boolean	False after a STOP reply: only the customer can opt back in.
`methods[].canOptInMarketing`	boolean	False after the person unsubscribed themselves.
`methods[].transactionalAllowed`	boolean
`methods[].transactionalReason`	string or null
`methods[].marketingAllowed`	boolean
`methods[].marketingReason`	string or null

Change a contact method's consent

PATCH /organizations/{organizationId}/customers/{customerId}/messaging/consent

Records the customer's consent as told to staff: OK to text (sms), marketing (marketing), service emails (transactionalEmail). Turning anything off is always allowed. Refused (409): switching texts on for a number that replied STOP (only the customer can, by texting START), and opting back into marketing or service emails an address that unsubscribed itself. Emits consent.changed.


Permission	`customers.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	`customerMessaging_setConsent` (toolset `customers`)
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
`customerId`	path	string	Yes

Request body

Field	Type	Required	Description
`contactMethodId`	string	Yes	From GET /customers/{customerId}/messaging.
`sms`	boolean	No	OK to text (phones).
`marketing`	boolean	No
`transactionalEmail`	boolean	No	Service emails (reminders, invoices) to this address.

Example

curl -X PATCH "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/customers/{customerId}/messaging/consent" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contactMethodId":"contactMethod_id"}'

Response

200: the answer's fields

Field	Type	Description
`preferences`	object
`preferences.allowEmail`	boolean
`preferences.allowSms`	boolean
`preferences.allowMarketing`	boolean
`preferences.status`	string
`preferences.doNotService`	boolean
`methods`	array of object
`methods[].contactId`	string
`methods[].contactName`	string or null
`methods[].isPrimaryContact`	boolean
`methods[].roles`	array of string
`methods[].contactMethodId`	string
`methods[].channel`	enum	One of `EMAIL`, `SMS`.
`methods[].label`	string
`methods[].value`	string
`methods[].smsConsent`	enum or null	OK to text (phones). One of `UNKNOWN`, `GRANTED`, `DENIED`.
`methods[].suppression`	enum or null	One of `BOUNCE`, `COMPLAINT`, `UNSUBSCRIBE`, `STOP`, `MANUAL`.
`methods[].marketing`	enum or null	One of `OPTED_IN`, `OPTED_OUT`.
`methods[].marketingSource`	string or null
`methods[].transactional`	enum or null	One of `OPTED_IN`, `OPTED_OUT`.
`methods[].transactionalSource`	string or null
`methods[].canGrantSms`	boolean	False after a STOP reply: only the customer can opt back in.
`methods[].canOptInMarketing`	boolean	False after the person unsubscribed themselves.
`methods[].transactionalAllowed`	boolean
`methods[].transactionalReason`	string or null
`methods[].marketingAllowed`	boolean
`methods[].marketingReason`	string or null

On this page