Leads - Help Genie

All requests use a single endpoint: 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.

string

required

Must be "leads"

string

required

Must be "stats"

object

Show properties

object

Show properties

string

Filter by a specific agent ID.

string[]

Filter by multiple agent IDs.

string

Filter by priority (exact match).

string

Search in name, email, and phone fields (partial match).

string

Filter by creation date. One of "7d", "30d", "90d", or "all".

boolean

Internal admins only. Bypass user scoping to see all leads.

string

Internal admins only. View statistics for a specific user.

Response

boolean

object

Show properties

object

Show properties

number

Total number of leads matching the filters.

object

Show properties

number

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.

const response = await ApiService.invoke<{
  stats: {
    total: number;
    by_status: { new: number; contacted: number; qualified: number; converted: number };
  };
}>({
  resource: "leads",
  action: "stats",
  data: {
    filters: {
      agentIds: ["agent-1", "agent-2"],
      dateRange: "30d",
    },
  },
});

{
  "success": true,
  "data": {
    "stats": {
      "total": 47,
      "by_status": {
        "new": 12,
        "contacted": 18,
        "qualified": 15,
        "converted": 2
      }
    }
  }
}

List all leads

Retrieves all leads with full field details and relations.

string

required

Must be "leads"

string

required

Must be "all"

object

Show properties

object

Show properties

string

Filter by a specific agent ID.

string[]

Filter by multiple agent IDs.

string

Filter by status (exact match).

string

Filter by priority (exact match).

string

Search in name, email, and phone fields (partial match).

string

Filter by creation date. One of "7d", "30d", "90d", or "all".

number

Number of results to return. Default: 50, max: 500.

number

Pagination offset. Default: 0.

boolean

Internal admins only. Bypass user scoping.

string

Internal admins only. View leads for a specific user.

Response

boolean

object

Show properties

Lead[]

Array of lead objects with all fields. See lead object below.

number

Total number of leads matching the filters.

number

const response = await ApiService.invoke<{
  leads: Lead[];
  count: number;
  limit: number;
  offset: number;
}>({
  resource: "leads",
  action: "all",
  data: {
    filters: {
      agentId: "agent-123",
      status: "qualified",
      dateRange: "90d",
    },
    limit: 25,
    offset: 0,
  },
});

curl -X POST https://api.helpgenie.ai/v1/leads \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "all",
    "data": {
      "filters": {
        "agentId": "agent-123",
        "status": "qualified",
        "priority": "high",
        "dateRange": "90d"
      },
      "limit": 25,
      "offset": 0
    }
  }'

List leads (summary)

Retrieves leads with basic fields only, optimized for table views. Accepts the same parameters as all.

string

required

Must be "leads"

string

required

Must be "list"

object

Same parameters as all (filters, pagination, admin options).

Response

Same response structure as all, but each lead contains only summary fields:

object

Show properties

object[]

Show Lead summary fields

number

string

string | null

string

string | null

object

Show properties

string

number

const response = await ApiService.invoke<{
  leads: Lead[];
  count: number;
}>({
  resource: "leads",
  action: "list",
  data: {
    filters: {
      searchTerm: "john",
      priority: "high",
    },
    limit: 25,
  },
});

Get a lead

Retrieves a specific lead by ID with all fields and relations.

string

required

Must be "leads"

string

required

Must be "get"

string | number

required

The lead ID.

Response

boolean

object

Show properties

Lead

Full lead object. See lead object.

const response = await ApiService.invoke<{ lead: Lead }>({
  resource: "leads",
  action: "get",
  id: 42,
});

Create a lead

Creates a new lead associated with an agent.

string

required

Must be "leads"

string

required

Must be "create"

object

required

Show properties

string

required

The agent this lead belongs to. Validated against agent ownership.

string

Lead name.

string

Lead email address.

string

Lead phone number.

string

Lead status (e.g. "new", "contacted", "qualified", "converted").

string

Lead priority level.

string

Budget information.

string

Timeline information.

object

Address data as a JSON object.

string

Free-text notes.

string

User ID of the assigned team member.

number

Link to a conversation record.

number

Link to a primary lead (for grouping related leads).

boolean

Whether this lead is a decision maker.

Whether the lead has given email consent.

Whether the lead has given SMS consent.

string

Preferred method of contact.

string

Preferred time for contact.

object

Arbitrary metadata as a JSON object.

string

Override user attribution for this lead.

string

Admin only. Create the lead as if this user created it.

Response (status 201)

boolean

object

Show properties

Lead

The created lead object.

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.

const response = await ApiService.invoke<{ lead: Lead }>(
  {
    resource: "leads",
    action: "create",
    data: {
      agent_id: "agent-123",
      name: "Jane Doe",
      email: "jane@example.com",
      status: "new",
      priority: "high",
    },
  },
  201
);

curl -X POST https://api.helpgenie.ai/v1/leads \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create",
    "data": {
      "agent_id": "agent-123",
      "name": "Jane Doe",
      "email": "jane@example.com",
      "phone": "+1234567890",
      "status": "new",
      "priority": "high",
      "preferred_contact_method": "email",
      "budget": "50000",
      "timeline": "Q2 2026",
      "notes": "Interested in enterprise plan"
    }
  }'

Update a lead

Updates an existing lead. This is a partial update — only include the fields you want to change.

string

required

Must be "leads"

string

required

Must be "update"

string | number

required

The lead ID.

object

required

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

boolean

object

Show properties

Lead

The updated lead object.

const response = await ApiService.invoke<{ lead: Lead }>({
  resource: "leads",
  action: "update",
  id: 42,
  data: {
    status: "qualified",
    priority: "high",
    notes: "Spoke with decision maker, very interested",
  },
});

Delete a lead

Permanently deletes a lead. This is a hard delete with no recovery.

string

required

Must be "leads"

string

required

Must be "delete"

string | number

required

The lead ID.

Response

boolean

object

Show properties

boolean

string

This permanently deletes the lead. The user must have access to the lead’s agent.

const response = await ApiService.invoke<{
  success: boolean;
  message: string;
}>({
  resource: "leads",
  action: "delete",
  id: 42,
});

Log lead activity

Records an activity entry against a lead. Used to track interactions like calls, emails, and status changes.

string

required

Must be "leads"

string

required

Must be "log"

string | number

required

The lead ID.

object

required

Activity fields to record. Common fields include type, description, metadata. The data is inserted into the lead_activities table.

boolean

object

The created activity record.

{
  "resource": "leads",
  "action": "log",
  "id": 42,
  "data": {
    "type": "email_sent",
    "description": "Sent follow-up proposal"
  }
}

{
  "success": true,
  "data": {
    "activity": {
      "id": 123,
      "lead_id": 42,
      "user_id": "user-uuid",
      "type": "email_sent",
      "description": "Sent follow-up proposal",
      "created_at": "2024-01-15T10:30:00.000Z"
    }
  }
}

Get lead activity logs

Retrieves the activity history for a specific lead, ordered by most recent first.

string

required

Must be "leads"

string

required

Must be "getLogs"

string | number

required

The lead ID.

object

Show properties

number

default:"50"

Results per page.

number

default:"0"

Number of results to skip.

boolean

array

Array of activity records for this lead.

{
  "resource": "leads",
  "action": "getLogs",
  "id": 42,
  "data": {
    "limit": 25
  }
}

{
  "success": true,
  "data": {
    "activities": [
      {
        "id": 123,
        "lead_id": 42,
        "user_id": "user-uuid",
        "type": "email_sent",
        "description": "Sent follow-up proposal",
        "created_at": "2024-01-15T10:30:00.000Z"
      }
    ]
  }
}

Lead object

The full lead object returned by all, get, create, and update actions.

number

string

string | null

object | null

string | null

number | null

boolean | null

string | null

object | null

string

string | null

object

Show properties

string

Enum values reference

`status`

Value	Description
`"new"`	Lead has been captured but not yet contacted
`"contacted"`	Initial outreach has been made
`"qualified"`	Lead has been vetted and meets criteria
`"converted"`	Lead has been successfully converted

`priority`

Value	Description
`"low"`	Low urgency
`"medium"`	Standard urgency
`"high"`	Requires immediate attention

`preferred_contact_method`

Value	Description
`"email"`	Contact via email
`"phone"`	Contact via phone call
`"sms"`	Contact via text message

Filtering reference

All list-style actions (stats, all, list) accept a filters object with the following fields:

Filter	Type	Description
`agentId`	`string`	Filter by a single agent
`agentIds`	`string[]`	Filter by multiple agents
`status`	`string`	Exact match on lead status (not available on `stats`)
`priority`	`string`	Exact match on lead priority
`searchTerm`	`string`	Partial match across name, email, and phone
`dateRange`	`string`	One of `"7d"`, `"30d"`, `"90d"`, `"all"`

Admin operations

Admin operations require the internal_admin role. Regular users receive a 403 Forbidden response.

View all leads across all users

const response = await ApiService.invoke<{ leads: Lead[]; count: number }>({
  resource: "leads",
  action: "all",
  data: {
    adminMode: true,
  },
});

View a specific user’s leads

const response = await ApiService.invoke<{ leads: Lead[]; count: number }>({
  resource: "leads",
  action: "list",
  data: {
    adminMode: true,
    userId: "user-456",
  },
});

Create a lead as another user

const response = await ApiService.invoke<{ lead: Lead }>(
  {
    resource: "leads",
    action: "create",
    data: {
      agent_id: "agent-123",
      name: "Jane Doe",
      email: "jane@example.com",
      userId: "user-456",
    },
  },
  201
);

Error responses

Status	Code	Description
400	`VALIDATION_ERROR`	Missing or invalid required parameters
401	`UNAUTHORIZED`	Invalid or missing authentication token
403	`FORBIDDEN`	User does not have access to the agent
404	`NOT_FOUND`	Lead not found
500	`INTERNAL_ERROR`	Server error

​Access control

​Get lead statistics

​Response

​List all leads

​Response

​List leads (summary)

​Response

​Get a lead

​Response

​Create a lead

​Response (status 201)

​Update a lead

​Response

​Delete a lead

​Response

​Log lead activity

​Get lead activity logs

​Lead object

​Enum values reference

​status

​priority

​preferred_contact_method

​Filtering reference

​Admin operations

​View all leads across all users

​View a specific user’s leads

​Create a lead as another user

​Error responses

Access control

Get lead statistics

Response

List all leads

Response

List leads (summary)

Response

Get a lead

Response

Create a lead

Response (status 201)

Update a lead

Response

Delete a lead

Response

Log lead activity

Get lead activity logs

Lead object

Enum values reference

`status`

`priority`

`preferred_contact_method`

Filtering reference

Admin operations

View all leads across all users

View a specific user’s leads

Create a lead as another user

Error responses