API reference · WhatsApp

Leads (team inbox)

Every WhatsApp conversation in your team inbox is a lead. These endpoints let your CRM or routing logic read leads and hand them to the right agent or team — the same as dragging them in the dashboard.

To react the moment a customer writes, subscribe to the message.received webhook: it includes the lead id, whether the lead is new, and which campaign it came from.

List leads

GET/v1/whatsapp/leads

Your WhatsApp conversations, most recently active first. Page through with page until you get fewer than size results.

AuthServer keyX-Client-Id + X-Client-Secret

Query parameters

phonestringoptional
Customer number. Send it with country code (919876543210); formatting is ignored. A bare 10-digit number is tried as Indian. Returns at most one lead.
assignedTostringoptional
Only leads owned by this agent email.
unassignedOnlybooleanoptionaldefault false
Only leads with no agent.
pageintegeroptionaldefault 0
Page number, from 0.
sizeintegeroptionaldefault 50
Results per page, 1–200.

Response · 200

[ ]array
Leads. No total count is returned.

Errors

400INVALID_REQUESTassignedTo is not a member of your account.
401INVALID_CLIENT_CREDENTIALSX-Client-Id or X-Client-Secret is missing, unknown or wrong.
401CLIENT_INACTIVEYour account has been deactivated.

Request

curl -X GET "https://api.quickauth.in/v1/whatsapp/leads?unassignedOnly=true&page=0&size=50" \
  -H "X-Client-Id: YOUR_CLIENT_ID" \
  -H "X-Client-Secret: YOUR_CLIENT_SECRET"

Response200

[
  {
    "id": 90211,
    "contact": "919876543210",
    "name": "Asha",
    "status": "OPEN",
    "assignedTo": "ravi@acme.in",
    "teamName": "Sales",
    "origin": "CAMPAIGN",
    "lastMessageAt": "2026-10-16T12:44:09.551",
    "unreadCount": 2
  }
]

List agents

GET/v1/whatsapp/leads/agents

Your team members who can be assigned leads (removed members are left out).

AuthServer keyX-Client-Id + X-Client-Secret

Response · 200

[ ]array

Errors

401INVALID_CLIENT_CREDENTIALSX-Client-Id or X-Client-Secret is missing, unknown or wrong.
401CLIENT_INACTIVEYour account has been deactivated.

Request

curl -X GET "https://api.quickauth.in/v1/whatsapp/leads/agents" \
  -H "X-Client-Id: YOUR_CLIENT_ID" \
  -H "X-Client-Secret: YOUR_CLIENT_SECRET"

Response200

[
  {
    "id": 12,
    "email": "ravi@acme.in",
    "role": "AGENT",
    "status": "ACTIVE"
  }
]

List teams

GET/v1/whatsapp/leads/teams

Your inbox teams, by name. Create teams in the dashboard.

AuthServer keyX-Client-Id + X-Client-Secret

Response · 200

[ ]array

Errors

401INVALID_CLIENT_CREDENTIALSX-Client-Id or X-Client-Secret is missing, unknown or wrong.
401CLIENT_INACTIVEYour account has been deactivated.

Request

curl -X GET "https://api.quickauth.in/v1/whatsapp/leads/teams" \
  -H "X-Client-Id: YOUR_CLIENT_ID" \
  -H "X-Client-Secret: YOUR_CLIENT_SECRET"

Response200

[
  {
    "id": 3,
    "name": "Sales"
  },
  {
    "id": 4,
    "name": "Support"
  }
]

Assign a lead

POST/v1/whatsapp/leads/{leadId}/assign

Gives a lead to an agent — for example from your CRM’s routing rules. Send no agentEmail (or an empty one) to unassign.

AuthServer keyX-Client-Id + X-Client-Secret

Path parameters

leadIdintegerrequired

Request body

agentEmailstringoptional
An active team member’s email. Omit to unassign.

Response · 200

idinteger
Lead id — use it as leadId.
contactstring
Customer’s WhatsApp number, digits with country code (919876543210).
namestring | null
Customer’s WhatsApp profile name.
statusenum
OPENCLOSED
assignedTostring | null
Email of the agent who owns the lead.
teamNamestring | null
originenum
INBOUND — the customer messaged firstCAMPAIGN — started by a template you sentLEAD — created by an agent in the dashboard
lastMessageAtstring | null
India time (IST), no offset.
unreadCountinteger

Errors

404INVALID_REQUESTNo lead with that id on your account.
400INVALID_REQUESTagentEmail is not on your team, or that member is not active yet.
409INVALID_REQUESTAnother agent claimed this unassigned lead a moment before you. Fetch it again and decide.
401INVALID_CLIENT_CREDENTIALSX-Client-Id or X-Client-Secret is missing, unknown or wrong.
401CLIENT_INACTIVEYour account has been deactivated.

Request

curl -X POST "https://api.quickauth.in/v1/whatsapp/leads/90211/assign" \
  -H "X-Client-Id: YOUR_CLIENT_ID" \
  -H "X-Client-Secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "agentEmail": "ravi@acme.in"
}'

Response200

{
  "id": 90211,
  "contact": "919876543210",
  "name": "Asha",
  "status": "OPEN",
  "assignedTo": "ravi@acme.in",
  "teamName": "Sales",
  "origin": "CAMPAIGN",
  "lastMessageAt": "2026-10-16T12:44:09.551",
  "unreadCount": 2
}

Assign a lead by phone number

POST/v1/whatsapp/leads/assign

Same as Assign a lead, but finds the lead by the customer’s number — useful when your system knows the customer, not our lead id. One lead per call.

AuthServer keyX-Client-Id + X-Client-Secret

Request body

phonestringrequired
Customer number. Send it with country code (919876543210); formatting is ignored. A bare 10-digit number is tried as Indian.
agentEmailstringoptional
Omit to unassign.

Response · 200

idinteger
Lead id — use it as leadId.
contactstring
Customer’s WhatsApp number, digits with country code (919876543210).
namestring | null
Customer’s WhatsApp profile name.
statusenum
OPENCLOSED
assignedTostring | null
Email of the agent who owns the lead.
teamNamestring | null
originenum
INBOUND — the customer messaged firstCAMPAIGN — started by a template you sentLEAD — created by an agent in the dashboard
lastMessageAtstring | null
India time (IST), no offset.
unreadCountinteger

Errors

400INVALID_REQUESTphone missing.
404INVALID_REQUESTNo conversation with that number. Check the country code.
400INVALID_REQUESTagentEmail is not on your team, or that member is not active yet.
409INVALID_REQUESTAnother agent claimed this unassigned lead a moment before you. Fetch it again and decide.
401INVALID_CLIENT_CREDENTIALSX-Client-Id or X-Client-Secret is missing, unknown or wrong.
401CLIENT_INACTIVEYour account has been deactivated.

Request

curl -X POST "https://api.quickauth.in/v1/whatsapp/leads/assign" \
  -H "X-Client-Id: YOUR_CLIENT_ID" \
  -H "X-Client-Secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "919876543210",
  "agentEmail": "ravi@acme.in"
}'

Response200

{
  "id": 90211,
  "contact": "919876543210",
  "name": "Asha",
  "status": "OPEN",
  "assignedTo": "ravi@acme.in",
  "teamName": "Sales",
  "origin": "CAMPAIGN",
  "lastMessageAt": "2026-10-16T12:44:09.551",
  "unreadCount": 2
}

Move a lead to a team

POST/v1/whatsapp/leads/{leadId}/team

Puts a lead in a team’s queue. The assigned agent does not change. Send no teamName to remove it from its team.

AuthServer keyX-Client-Id + X-Client-Secret

Path parameters

leadIdintegerrequired

Request body

teamNamestringoptional
Team name, not case-sensitive. Max 100 characters.

Response · 200

idinteger
Lead id — use it as leadId.
contactstring
Customer’s WhatsApp number, digits with country code (919876543210).
namestring | null
Customer’s WhatsApp profile name.
statusenum
OPENCLOSED
assignedTostring | null
Email of the agent who owns the lead.
teamNamestring | null
originenum
INBOUND — the customer messaged firstCAMPAIGN — started by a template you sentLEAD — created by an agent in the dashboard
lastMessageAtstring | null
India time (IST), no offset.
unreadCountinteger

Errors

404INVALID_REQUESTNo lead with that id.
400INVALID_REQUESTNo team with that name on your account.
401INVALID_CLIENT_CREDENTIALSX-Client-Id or X-Client-Secret is missing, unknown or wrong.
401CLIENT_INACTIVEYour account has been deactivated.

Request

curl -X POST "https://api.quickauth.in/v1/whatsapp/leads/90211/team" \
  -H "X-Client-Id: YOUR_CLIENT_ID" \
  -H "X-Client-Secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "teamName": "Sales"
}'

Response200

{
  "id": 90211,
  "contact": "919876543210",
  "name": "Asha",
  "status": "OPEN",
  "assignedTo": "ravi@acme.in",
  "teamName": "Sales",
  "origin": "CAMPAIGN",
  "lastMessageAt": "2026-10-16T12:44:09.551",
  "unreadCount": 2
}

Move a lead to a team by phone number

POST/v1/whatsapp/leads/team

Same as Move a lead to a team, found by the customer’s number. One lead per call.

AuthServer keyX-Client-Id + X-Client-Secret

Request body

phonestringrequired
Customer number. Send it with country code (919876543210); formatting is ignored. A bare 10-digit number is tried as Indian.
teamNamestringoptional
Omit to remove from its team.

Response · 200

idinteger
Lead id — use it as leadId.
contactstring
Customer’s WhatsApp number, digits with country code (919876543210).
namestring | null
Customer’s WhatsApp profile name.
statusenum
OPENCLOSED
assignedTostring | null
Email of the agent who owns the lead.
teamNamestring | null
originenum
INBOUND — the customer messaged firstCAMPAIGN — started by a template you sentLEAD — created by an agent in the dashboard
lastMessageAtstring | null
India time (IST), no offset.
unreadCountinteger

Errors

400INVALID_REQUESTphone missing.
404INVALID_REQUESTNo conversation with that number.
400INVALID_REQUESTNo team with that name on your account.
401INVALID_CLIENT_CREDENTIALSX-Client-Id or X-Client-Secret is missing, unknown or wrong.
401CLIENT_INACTIVEYour account has been deactivated.
500INTERNAL_ERRORUnexpected server error, including a body that is not valid JSON. Retry; if it persists, send us the requestId.

Request

curl -X POST "https://api.quickauth.in/v1/whatsapp/leads/team" \
  -H "X-Client-Id: YOUR_CLIENT_ID" \
  -H "X-Client-Secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "919876543210",
  "teamName": "Sales"
}'

Response200

{
  "id": 90211,
  "contact": "919876543210",
  "name": "Asha",
  "status": "OPEN",
  "assignedTo": "ravi@acme.in",
  "teamName": "Sales",
  "origin": "CAMPAIGN",
  "lastMessageAt": "2026-10-16T12:44:09.551",
  "unreadCount": 2
}