Public Lead API: Manage Lead 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.

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.

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.