API Setup
Leads API
API reference for managing leads associated with AI agents
List Leads
Retrieve a list of all leads associated with a specific agent.
GET /api/public/v1/agents/{agent_id}/leadsParameters
| Parameter | Type | Description |
|---|---|---|
| agent_id | string | The ID of the agent to get leads for |
Response
[
{
"id": "lead_id",
"name": "Lead Name",
"email": "lead@example.com",
"phone": "+911234567890",
"description": "Lead description",
"agentId": "agent_id",
"organizationId": "org_id",
"createdById": "user_id"
}
]Create Lead
Create a new lead for a specific agent.
POST /api/public/v1/agents/{agent_id}/leadsParameters
| Parameter | Type | Description |
|---|---|---|
| agent_id | string | The ID of the agent to create lead for |
Request Body
{
"name": "Lead Name",
"email": "lead@example.com",
"phone": "+911234567890",
"description": "Lead description"
}Response
{
"id": "lead_id",
"name": "Lead Name",
"email": "lead@example.com",
"phone": "+911234567890",
"description": "Lead description",
"agentId": "agent_id",
"organizationId": "org_id",
"createdById": "user_id"
}Get Lead
Retrieve details of a specific lead.
GET /api/public/v1/agents/{agent_id}/leads/{lead_id}Parameters
| Parameter | Type | Description |
|---|---|---|
| agent_id | string | The ID of the agent |
| lead_id | string | The ID of the lead to retrieve |
Response
{
"id": "lead_id",
"name": "Lead Name",
"email": "lead@example.com",
"phone": "+911234567890",
"description": "Lead description",
"agentId": "agent_id",
"organizationId": "org_id",
"createdById": "user_id"
}Update Lead
Update an existing lead's details.
PUT /api/public/v1/agents/{agent_id}/leads/{lead_id}Parameters
| Parameter | Type | Description |
|---|---|---|
| agent_id | string | The ID of the agent |
| lead_id | string | The ID of the lead to update |
Request Body
{
"name": "Updated Lead Name",
"email": "updated@example.com",
"phone": "+911234567890",
"description": "Updated description"
}Response
{
"id": "lead_id",
"name": "Updated Lead Name",
"email": "updated@example.com",
"phone": "+911234567890",
"description": "Updated description",
"agentId": "agent_id",
"organizationId": "org_id",
"createdById": "user_id"
}Delete Lead
Delete an existing lead.
DELETE /api/public/v1/agents/{agent_id}/leads/{lead_id}Parameters
| Parameter | Type | Description |
|---|---|---|
| agent_id | string | The ID of the agent |
| lead_id | string | The ID of the lead to delete |
Response
{
"message": "Lead deleted successfully"
}Lead Schema
| Field | Type | Mandatory | Description |
|---|---|---|---|
| id | string | Generated | The unique identifier of the lead |
| name | string | Required | The name of the lead |
| string | Required | The email address of the lead | |
| phone | string | Required | The phone number of the lead |
| description | string | Required | Additional information about the lead |
Validation Rules
- Email must be a valid email address format
- Phone number must be a valid phone number
- All fields (name, email, phone, description) are required
- Lead must be associated with an existing agent
Error Responses
| Status Code | Description |
|---|---|
| 400 | Bad Request - Invalid input parameters |
| 401 | Unauthorized - Invalid or missing API key |
| 404 | Not Found - Agent or lead not found |
| 500 | Internal Server Error |
Security
- All endpoints require authentication
- Leads are organization-specific
- Access is restricted to authorized users only
- API keys must have appropriate permissions
- Each lead is associated with a specific agent and organization