Back to Integration

Public Lead API: List Leads, Manage Tags and AI Handling


This guide is for customers and integration partners using the ABC Sales AI Public API to manage leads from an external system.


Use it when your CRM, form builder, workflow tool, or custom app needs to update a lead after it has been created in ABC Sales AI.


List and poll leads


Use GET /v1/leads with your Bearer API key to read your company's leads and custom fields. For example: GET /v1/leads?limit=100&tags=VIP. The response contains leads in data and pagination information in meta. Results are ordered by updated_at ascending, then by id.


Filters and pagination


  • search: partial match on name, phone or email; source: filter by lead source.
  • tags: match any listed tag; repeat the parameter or use commas.
  • automation_id: numeric automation ID from GET /v1/automations, not its slug.
  • date_from and date_to: inclusive creation-date filters in YYYY-MM-DD format. timezone accepts an IANA zone such as Asia/Kuala_Lumpur; it defaults to the company timezone, then UTC.
  • ai_enabled and from_ad: boolean filters.
  • messaging_channel: channel type; messaging_channel_connection_ids: connection IDs, repeated or comma-separated.
  • limit: 1 to 100 leads per page, default 50.
  • cursor: send meta.next_cursor from the previous response until meta.has_more is false. The cursor carries the original filters, so subsequent page requests need only the cursor.

Poll with updated_since


  1. For the first sync, omit updated_since and process all pages, updating or inserting records by id.
  2. After every page has been processed successfully, save the last processed lead's updated_at exactly as returned, including microseconds.
  3. On the next poll, send that RFC 3339 timestamp as updated_since. It returns leads changed strictly after the timestamp. URL-encode the value, especially any + in a timezone offset.
  4. Follow all pages again before advancing the saved timestamp. If no leads are returned, keep the previous timestamp. Use cursors only to finish a page sequence; keep the timestamp for future polls.

ℹ️
Writes from the last 30 seconds are held back for a later call. Adding or removing tags and assigning or unassigning staff advance the lead's updated_at, so these changes can appear in a later updated_since poll. Polling does not return deletion records or reliably track conversation activity; this endpoint is not a complete change log.

File custom fields include attachment metadata and a download_url for the attachment API. Download with the same API key; do not persist the short-lived redirect target.


Lead listing has a separate limit of 300 requests per 10 minutes per company. Back off on 429. See the developer guide and interactive API reference for the full reference.


What you can do


The Public Lead API supports these lead-management actions:


  • Use the lead ID returned from lead creation directly in supported lead API routes
  • Remove tags from an individual lead
  • Turn AI handling on or off for an individual lead

For the full API map, authentication details, and Swagger reference, start with the Public API overview.


Use the returned lead ID


When a lead is created with POST /v1/webhooks/leads, the response includes data.id.


You can use that value as {leadID} in these supported routes:


  • GET /v1/leads/{leadID}/conversations
  • POST /v1/leads/{leadID}/conversations/reply
  • DELETE /v1/leads/{leadID}/tags
  • PUT /v1/leads/{leadID}/ai-handling

If you need to make the ID type explicit, add one of these query parameters:


  • ?id_type=lead_id
  • ?id_type=external_id

For example, use GET /v1/leads/customer-123/conversations?id_type=external_id when customer-123 is your external lead ID.


Important note after lead creation


Lead creation is asynchronous. This means POST /v1/webhooks/leads can return before the lead is fully available to the other lead API routes.


If you call a lead API route immediately after creating a lead and receive 404, retry before treating the lead as missing.


Recommended retry timing:


  • 1 second
  • 2 seconds
  • 4 seconds
  • 8 seconds

Remove tags from a lead


Use DELETE /v1/leads/{leadID}/tags to remove one or more tags from a lead.


Request body: {"tags":["VIP","Follow Up"]}


Example response: {"data":{"lead_id":123,"external_id":"customer-123","removed":["VIP"],"not_attached":["Follow Up"],"tags":["Interested"]},"meta":null}


removed means the tag was attached to the lead and was removed.


not_attached means the tag was not attached to the lead, or the tag does not exist for the company.


Repeating the same request is safe. If the tag is already gone, it is returned under not_attached.


Turn AI handling on or off


Use PUT /v1/leads/{leadID}/ai-handling to control whether the AI Employee can reply to one lead.


Request body: {"handled_by_ai":false}


Example response: {"data":{"lead_id":123,"external_id":"customer-123","handled_by_ai":false},"meta":null}


Set handled_by_ai to false to stop AI replies for that lead.


Set handled_by_ai to true to allow AI replies for that lead again.


ℹ️
Turning AI handling on for one lead does not override company-level or channel-level AI settings. The AI Employee replies only when company-level AI, channel-level AI, and lead-level AI handling are all on.

Ambiguous lead IDs


External IDs are not always unique.


If the API cannot safely determine which lead you mean, it returns 409 Conflict with error_code: lead_ambiguous.


No lead is updated when this happens.


To avoid ambiguity, use ?id_type=lead_id or ?id_type=external_id when your system knows which kind of ID it is sending.


Rate limit


Tag removal and AI handling updates share a mutation limit of 600 requests per 10 minutes per company and client IP address.


If you receive 429, slow down the integration and retry later.


Common errors


  • 400: invalid ID type, invalid request body, missing required field, or invalid tag list
  • 401: missing or invalid API key
  • 404: lead not found, or the lead is not available yet after asynchronous creation
  • 409: ambiguous lead identifier
  • 429: rate limit exceeded
  • 500: internal error

Webhook loop warning


Removing tags or changing AI handling can trigger lead update events.


If your system listens to lead updates and calls the same API again, make sure your integration is idempotent so it does not create a loop.


Still need help?

Our support team is ready to assist you.

Contact Support