Team chat API REST endpoints for team chat in ServFlo: 8 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 .
GET /organizations/{organizationId}/badges
The counts behind the red badges in the web and mobile apps: unread team chat messages (and which conversations), unread notifications, customers' texts waiting (messages: unread customer-text notifications, engagement.read), unread Inbox conversations (inboxUnread, engagement.read), and for the office what waits in the inbox: new requests and technicians' leads (requests.read), parts requests not yet handled (inventory.manage), technicians with time waiting for approval (timesheets.approve). Counts the caller may not see are 0. Read-only.
Permission organization.read (Owner, Admin, Dispatcher, Technician, Member)Risk read, OAuth scope servflo.read. Read: reads only.MCP tool chat_badges (toolset team)
curl "https://app.servflo.ai/api/organizations/ $ORGANIZATION_ID /badges" \ -H "Authorization: Bearer $SERVFLO_API_KEY " 200: the answer's fields Field Type Description chatinteger chatConversationsarray of string notificationsinteger messagesinteger Unread customer-text notifications in this business; already counted in notifications. inboxUnreadinteger Inbox conversations nobody on the team has opened since the customer's newest text, email, missed call, request or review (inbox.read; a technician's own line, read by them): the Inbox badge. inboxobject inbox.requestsinteger inbox.partsinteger inbox.timesheetsinteger inbox.totalinteger totalinteger chat + notifications + inbox.total: the app icon's badge.
GET /organizations/{organizationId}/chat
The caller's team chat, most recent first: the whole team, their direct messages and job conversations (a technician's own jobs; for the office every job with messages in the last 30 days), each with a title, the last message and the caller's unread count. Read-only.
Permission organization.read (Owner, Admin, Dispatcher, Technician, Member)Risk read, OAuth scope servflo.read. Read: reads only.MCP tool chat_conversations (toolset team)
curl "https://app.servflo.ai/api/organizations/ $ORGANIZATION_ID /chat" \ -H "Authorization: Bearer $SERVFLO_API_KEY " 200: the answer's fields An array of objects:
Field Type Description idstring Conversation id (for …/chat/{conversationId}/messages). kindenum One of TEAM, DIRECT, JOB. jobIdstring or null The job a JOB conversation is about. titlestring Team, the other person's name, or JOB-n · customer. lastMessageobject or null The latest message (first 200 characters). lastMessage.bodystring lastMessage.authorstring lastMessage.atstring (date-time) unreadinteger Messages from others since the caller last read it.
GET /organizations/{organizationId}/chat/people
The business's members (name and role) to start a direct message with; not the caller. Read-only.
Permission organization.read (Owner, Admin, Dispatcher, Technician, Member)Risk read, OAuth scope servflo.read. Read: reads only.MCP tool chat_people (toolset team)
curl "https://app.servflo.ai/api/organizations/ $ORGANIZATION_ID /chat/people" \ -H "Authorization: Bearer $SERVFLO_API_KEY " 200: the answer's fields An array of objects:
Field Type Description userIdstring The member's user id (for POST /chat/direct). namestring rolestring
POST /organizations/{organizationId}/chat/direct
The caller's conversation with another member of the business (made on first use). 404 for someone who isn't a member.
Permission organization.read (Owner, Admin, Dispatcher, Technician, Member)Risk write, OAuth scope servflo.write. Write: creates or changes records inside the business; nothing leaves it.MCP tool chat_openDirect (toolset team)
Field Type Required Description userIdstring Yes Up to 200 characters.
curl -X POST "https://app.servflo.ai/api/organizations/ $ORGANIZATION_ID /chat/direct" \ -H "Authorization: Bearer $SERVFLO_API_KEY " \ -H "Content-Type: application/json" \ -d '{"userId":"user_id"}' 200: the answer's fields Field Type Description idstring kindenum One of TEAM, DIRECT, JOB. jobIdstring or null
POST /organizations/{organizationId}/jobs/{jobId}/chat
The conversation about a job: its crew and the office (made on first use). Technicians: their own jobs (404 otherwise).
Permission: jobs.read (Owner, Admin, Dispatcher, Technician (own jobs), Member); risk write (OAuth scope servflo.write).
Permission jobs.readRisk write, OAuth scope servflo.write. Write: creates or changes records inside the business; nothing leaves it.MCP tool chat_openJob (toolset team)
Name In Type Required Description jobIdpath string Yes
curl -X POST "https://app.servflo.ai/api/organizations/ $ORGANIZATION_ID /jobs/{jobId}/chat" \ -H "Authorization: Bearer $SERVFLO_API_KEY " 200: the answer's fields Field Type Description idstring kindenum One of TEAM, DIRECT, JOB. jobIdstring or null
GET /organizations/{organizationId}/chat/{conversationId}/messages
The latest messages, oldest first (before for older ones), with who wrote each. 404 for a conversation the caller can't see. Read-only.
Permission organization.read (Owner, Admin, Dispatcher, Technician, Member)Risk read, OAuth scope servflo.read. Read: reads only.MCP tool chat_messages (toolset team)
Name In Type Required Description conversationIdpath string Yes beforequery string (date-time) No limitquery integer No 1–100.
curl "https://app.servflo.ai/api/organizations/ $ORGANIZATION_ID /chat/{conversationId}/messages" \ -H "Authorization: Bearer $SERVFLO_API_KEY " 200: the answer's fields An array of objects:
Field Type Description idstring userIdstring The author's user id. bodystring createdAtstring (date-time) authorstring The author's name. mineboolean Sent by the caller.
POST /organizations/{organizationId}/chat/{conversationId}/messages
Posts a message (up to 4000 characters); the others in the conversation are told on their phones. Returns it.
Permission organization.read (Owner, Admin, Dispatcher, Technician, Member)Risk write, OAuth scope servflo.write. Write: creates or changes records inside the business; nothing leaves it.MCP tool chat_send (toolset team)
Name In Type Required Description conversationIdpath string Yes
Field Type Required Description bodystring Yes Up to 4000 characters.
curl -X POST "https://app.servflo.ai/api/organizations/ $ORGANIZATION_ID /chat/{conversationId}/messages" \ -H "Authorization: Bearer $SERVFLO_API_KEY " \ -H "Content-Type: application/json" \ -d '{"body":"string"}' 201: the answer's fields Field Type Description idstring userIdstring The author's user id. bodystring createdAtstring (date-time) mineboolean Sent by the caller.
POST /organizations/{organizationId}/chat/{conversationId}/read
Everything in it up to now counts as read for the caller.
Permission organization.read (Owner, Admin, Dispatcher, Technician, Member)Risk write, OAuth scope servflo.write. Write: creates or changes records inside the business; nothing leaves it.MCP tool chat_read (toolset team)
Name In Type Required Description conversationIdpath string Yes
curl -X POST "https://app.servflo.ai/api/organizations/ $ORGANIZATION_ID /chat/{conversationId}/read" \ -H "Authorization: Bearer $SERVFLO_API_KEY " 200: the answer's fields Field Type Description oktrue
