Follow-Ups API

Follow-ups represent scheduled touchpoints (calls, WhatsApp messages, virtual meetings) assigned to sales executives or telecallers. BrokerOS tracks pending follow-ups to ensure zero lead drop-off and powers the daily telecalling queue on mobile.

BASE URL: /api/leads

Endpoints Summary

Method	Path	Description	Access
`GET`	`/api/leads/:id/follow-ups`	List all follow-up tasks for a lead	Authenticated
`POST`	`/api/leads/:id/follow-ups`	Schedule a new follow-up task	Authenticated
`PATCH`	`/api/leads/follow-ups/:followUpId`	Update follow-up status, remarks, or date	Authenticated
`DELETE`	`/api/leads/follow-ups/:followUpId`	Delete a scheduled follow-up	Authenticated

List Lead Follow-Ups

GET /api/leads/:id/follow-ups

Returns all historical and upcoming follow-ups associated with a specific lead, ordered chronologically.

Response Example

[
  {
    "id": "cm123fu001",
    "leadId": "cm123lead001",
    "userId": "cm123user002",
    "scheduledDate": "2026-10-02T10:00:00.000Z",
    "type": "CALL",
    "status": "PENDING",
    "remarks": "Check if client reviewed project brochure and pricing sheet",
    "completedAt": null,
    "createdAt": "2026-09-30T09:00:00.000Z"
  }
]

Create Follow-Up

POST /api/leads/:id/follow-ups

Schedules a new follow-up for a lead. When scheduled, the lead’s nextFollowUpDate field is automatically synced, ensuring it surfaces in the executive’s daily priority dialer queue.

Request Body

Field	Type	Required	Description
`userId`	`string`	Yes	ID of the agent or executive responsible for this follow-up
`scheduledDate`	`string`	Yes	ISO 8601 timestamp for the reminder (e.g. `2026-10-03T14:30:00Z`)
`type`	`string`	No	Follow-up channel: `CALL`, `WHATSAPP`, `EMAIL`, `MEETING`, `SITE_VISIT`
`remarks`	`string`	No	Instructions or discussion context from previous touchpoint

Request Example

{
  "userId": "cm123user002",
  "scheduledDate": "2026-10-03T15:00:00.000Z",
  "type": "CALL",
  "remarks": "Discuss 10:90 subvention payment scheme requested by client"
}

Update Follow-Up

PATCH /api/leads/follow-ups/:followUpId

Updates a follow-up task. Used to mark a follow-up as completed, reschedule the reminder, or append discussion remarks.

Request Body

Field	Type	Required	Description
`status`	`string`	No	`PENDING`, `COMPLETED`, `CANCELLED`, `MISSED`
`remarks`	`string`	No	Updated call notes or outcome summary
`scheduledDate`	`string`	No	New ISO timestamp if rescheduling
`type`	`string`	No	Updated contact medium
`completedAt`	`string`	No	ISO timestamp when the call or task was finished

Request Example (Mark Completed)

{
  "status": "COMPLETED",
  "remarks": "Client agreed to schedule a site visit for Saturday morning",
  "completedAt": "2026-10-02T10:14:22.000Z"
}

Delete Follow-Up

DELETE /api/leads/follow-ups/:followUpId

Permanently removes a follow-up record.

System Architecture

API Reference

Endpoints Summary

List Lead Follow-Ups

Response Example

Create Follow-Up

Request Body

Request Example

Update Follow-Up

Request Body

Request Example (Mark Completed)

Delete Follow-Up

​Endpoints Summary

​List Lead Follow-Ups

​Response Example

​Create Follow-Up

​Request Body

​Request Example

​Update Follow-Up

​Request Body

​Request Example (Mark Completed)

​Delete Follow-Up

Endpoints Summary

List Lead Follow-Ups

Response Example

Create Follow-Up

Request Body

Request Example

Update Follow-Up

Request Body

Request Example (Mark Completed)

Delete Follow-Up