POST https://api.helpgenie.ai/v1 with resource: "leads".
Access control
Regular users can only access leads from agents they own. Internal admins can access all leads using
adminMode: true and optionally scope to a specific user with userId.Get lead statistics
Retrieves aggregated statistics about leads, including total count and breakdown by status. Aggregation happens at the database level for optimal performance.Response
Leads with a
null status or a status outside the four standard values are not counted in any by_status category but are included in total.List all leads
Retrieves all leads with full field details and relations.Response
List leads (summary)
Retrieves leads with basic fields only, optimized for table views. Accepts the same parameters asall.
Response
Same response structure asall, but each lead contains only summary fields:
Get a lead
Retrieves a specific lead by ID with all fields and relations.Response
Create a lead
Creates a new lead associated with an agent.Response (status 201)
The
user_id on the created lead is resolved in this order: (1) provided user_id parameter, (2) agent’s owning user, (3) current authenticated user.Update a lead
Updates an existing lead. This is a partial update — only include the fields you want to change.Any combination of lead fields. All fields except
id and created_at can be updated. See the create action for the full list of fields.Response
Delete a lead
Permanently deletes a lead. This is a hard delete with no recovery.Response
Lead object
The full lead object returned byall, get, create, and update actions.
Enum values reference
status
priority
preferred_contact_method
Filtering reference
All list-style actions (stats, all, list) accept a filters object with the following fields:
Admin operations
Admin operations require the
internal_admin role. Regular users receive a 403 Forbidden response.
