/leads

GET /leads

Get all leads

Retrieve a paginated list of leads with optional filtering

Authentication Required

Authorization: Bearer {token} header string

This header is required to access this endpoint

Required Parameters

x-account-id header string

Account ID for the request

Optional Parameters

Click here to view an exhaustive list of all available parameters

page query integer

Page number

pageSize query integer

Number of leads per page

search query string

Search all leads for any text that matches the search query (not case sensitive)

sort query string

Comma separated list of fields to sort by, prefix with - for descending order. (ie. sort=firstName,-email)

archived query boolean

Filter leads by archived status. By default, only non-archived leads are shown.

teamId query integer

Filter leads by team ID

leadSourceId query integer

Filter leads by lead source ID

firstName query string

Filter leads by first name (All fields can be used for filtering)

lastName query string

Filter leads by last name (All fields can be used for filtering)

email query string

Filter leads by email (All fields can be used for filtering, email is just an example)

createdAt query string

Filter leads by ISO 8601 date range. ie. createdAt=2021-01-01,2021-12-31 or single day ie. createdAt=2021-01-01

Try it out

Output:

Responses

Description

Successful response

{
  "data": [
    {
      "id": 0,
      "accountId": "string",
      "teamId": 0,
      "leadSourceId": 0,
      "applicationId": "string",
      "firstName": "string",
      "lastName": "string",
      "imgSrc": "string",
      "email": "string",
      "phone": "string",
      "company": "string",
      "jobTitle": "string",
      "branch": "string",
      "source": "string",
      "position": "string",
      "location": "string",
      "productsServicesSold": "string",
      "numberOfEmployees": 0,
      "currentPaymentProcessor": "string",
      "monthlyTransactionVolume": 0,
      "interestedInSwitching": false,
      "processStage": "string",
      "buyingRole": "string",
      "assignedTo": "string",
      "notes": "string",
      "lastContacted": "string",
      "archived": false,
      "createdBy": "string",
      "createdAt": "string",
      "updatedAt": "string",
      "auditLog": [
        {
          "id": 0,
          "event": "string",
          "user": "string",
          "apiKey": "string",
          "data": {},
          "created": "string",
          "requestMethod": "string",
          "requestPath": "string",
          "requestHeaders": {},
          "requestIpAddress": "string",
          "account_id": "string"
        }
      ]
    }
  ],
  "totalCount": 0,
  "totalPages": 0,
  "currentPage": 0
}

References

#/components/parameters/xAccountIdHeader #/components/schemas/Lead #/components/schemas/LeadList

in: header
name: x-account-id
schema:
  type: string
description: Account ID for the request
required: true
example: "2311"

|
export type xAccountIdHeader = any; // Schema type not fully supported

#/components/schemas/Lead

OpenAPI
TypeScript

type: object
description: Lead object representing a potential customer or client
properties:
  id:
    type: integer
    description: Unique identifier for the lead
    readOnly: true
  accountId:
    type: string
    description: ID of the account that owns this lead
  teamId:
    type: integer
    description: ID of the team associated with this lead. Required if teams exist
      in the account, unless skipTeamAndSourceRequirement=true.
  leadSourceId:
    type: integer
    description: ID of the lead source associated with this lead. Required if the
      team has lead sources, unless skipTeamAndSourceRequirement=true.
  applicationId:
    type: string
    description: Optional application ID associated with this lead
  firstName:
    type: string
    description: Lead's first name
  lastName:
    type: string
    description: Lead's last name
  imgSrc:
    type: string
    description: URL to lead's profile image
  email:
    type: string
    description: Lead's email address
  phone:
    type: string
    description: Lead's phone number
  company:
    type: string
    description: Company name
  jobTitle:
    type: string
    description: Lead's job title
  branch:
    type: string
    description: Branch location
  source:
    type: string
    description: Text description of lead source
  position:
    type: string
    description: Position within company
  location:
    type: string
    description: Geographic location
  productsServicesSold:
    type: string
    description: Products or services the lead sells
  numberOfEmployees:
    type: integer
    description: Number of employees at the lead's company
  currentPaymentProcessor:
    type: string
    description: Lead's current payment processor
  monthlyTransactionVolume:
    type: integer
    description: Monthly transaction volume in dollars
  interestedInSwitching:
    type: boolean
    description: Whether the lead is interested in switching services
  processStage:
    type: string
    description: Current stage in the sales process
  buyingRole:
    type: string
    description: Lead's role in buying decisions
  assignedTo:
    type: string
    description: User assigned to this lead. If not provided, will be automatically
      assigned using lead rotation if available.
  notes:
    type: string
    description: General notes about the lead
  lastContacted:
    type: string
    format: date-time
    description: Date and time of last contact with this lead
  archived:
    type: boolean
    default: false
    description: Whether the lead is archived
  createdBy:
    type: string
    description: Email of the user who created the lead
  createdAt:
    type: string
    format: date-time
    description: When the lead was created
    readOnly: true
  updatedAt:
    type: string
    format: date-time
    description: When the lead was last updated
    readOnly: true
  auditLog:
    type: array
    description: Comprehensive audit log of all significant events and actions
      performed on the lead
    readOnly: true
    items:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the audit log entry
        event:
          type: string
          description: Type of event (e.g., lead_created, lead_updated, lead_archived,
            lead_converted)
        user:
          type: string
          description: Email address or identifier of the user who performed the action
        apiKey:
          type: string
          nullable: true
          description: API key identifier if the action was performed via API key
            authentication
        data:
          type: object
          description: Event-specific data containing details about what was changed or
            accessed (structure varies by event type)
        created:
          type: string
          format: date-time
          description: Timestamp when the event occurred
        requestMethod:
          type: string
          description: HTTP method used (GET, POST, PATCH, DELETE)
        requestPath:
          type: string
          description: API endpoint path that was called
        requestHeaders:
          type: object
          description: Sanitized HTTP headers from the request (sensitive values are masked)
        requestIpAddress:
          type: string
          description: IP address of the request origin
        account_id:
          type: string
          description: Account ID associated with the action
required:
  - id
  - firstName
  - lastName

>
export interface Lead {
  /** Unique identifier for the lead */
  id: number;
  /** ID of the account that owns this lead */
  accountId?: string;
  /** ID of the team associated with this lead. Required if teams exist in the account, unless skipTeamAndSourceRequirement=true. */
  teamId?: number;
  /** ID of the lead source associated with this lead. Required if the team has lead sources, unless skipTeamAndSourceRequirement=true. */
  leadSourceId?: number;
  /** Optional application ID associated with this lead */
  applicationId?: string;
  /** Lead's first name */
  firstName: string;
  /** Lead's last name */
  lastName: string;
  /** URL to lead's profile image */
  imgSrc?: string;
  /** Lead's email address */
  email?: string;
  /** Lead's phone number */
  phone?: string;
  /** Company name */
  company?: string;
  /** Lead's job title */
  jobTitle?: string;
  /** Branch location */
  branch?: string;
  /** Text description of lead source */
  source?: string;
  /** Position within company */
  position?: string;
  /** Geographic location */
  location?: string;
  /** Products or services the lead sells */
  productsServicesSold?: string;
  /** Number of employees at the lead's company */
  numberOfEmployees?: number;
  /** Lead's current payment processor */
  currentPaymentProcessor?: string;
  /** Monthly transaction volume in dollars */
  monthlyTransactionVolume?: number;
  /** Whether the lead is interested in switching services */
  interestedInSwitching?: boolean;
  /** Current stage in the sales process */
  processStage?: string;
  /** Lead's role in buying decisions */
  buyingRole?: string;
  /** User assigned to this lead. If not provided, will be automatically assigned using lead rotation if available. */
  assignedTo?: string;
  /** General notes about the lead */
  notes?: string;
  /** Date and time of last contact with this lead */
  lastContacted?: Date;
  /** Whether the lead is archived */
  archived?: boolean;
  /** Email of the user who created the lead */
  createdBy?: string;
  /** When the lead was created */
  createdAt?: Date;
  /** When the lead was last updated */
  updatedAt?: Date;
  /** Comprehensive audit log of all significant events and actions performed on the lead */
  auditLog?: {
    id?: number;
    event?: string;
    user?: string;
    apiKey?: string;
    data?: {};
    created?: Date;
    requestMethod?: string;
    requestPath?: string;
    requestHeaders?: {};
    requestIpAddress?: string;
    account_id?: string;
  }[];
}

#/components/schemas/LeadList

OpenAPI
TypeScript

type: object
description: Paginated list of leads
properties:
  data:
    type: array
    items:
      $ref: "#/components/schemas/Lead"
    description: Array of leads
  totalCount:
    type: integer
    description: Total number of leads matching the query
  totalPages:
    type: integer
    description: Total number of pages
  currentPage:
    type: integer
    description: Current page number

|
export interface LeadList {
  /** Array of leads */
  data?: Lead[];
  /** Total number of leads matching the query */
  totalCount?: number;
  /** Total number of pages */
  totalPages?: number;
  /** Current page number */
  currentPage?: number;
}

Route Source Code

Check out the source code for this route entrypoint here: /leads/route.ts

Or the swagger.yaml spec this documentation was generated from: /leads/swagger.yaml