Create a new lead

Create a new lead with the provided data. If teams exist in the account, a team ID is required unless skipTeamAndSourceRequirement=true. If a team has lead sources, a lead source ID is required. If a lead rotation exists for the team or a default lead rotation exists, the lead will be automatically assigned to the next user in the rotation if no assignedTo is specified.

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

skipTeamAndSourceRequirement   query boolean

Optional flag to skip the team and lead source requirement, even if teams exist in the account

Request Body

Minimum Required

{
  "firstName": "string",
  "lastName": "string"
}

All Properties

{
  "teamId": 0,
  "leadSourceId": 0,
  "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"
}

Try it out

Loading...

Run Code (Cmd + Enter)Reset CodeVIM Disabled

Output:

Responses

201

Description

Lead created successfully

{
  "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"
    }
  ]
}

400

Description

Bad request - may occur if teamId is required but missing, or if leadSourceId is required for a team but missing

{
  "error": "team ID is required when teams exist in the account"
}

401

Description

Unauthorized - User not authenticated

403

Description

Forbidden - User does not have the required permissions

500

Description

Internal server error

References

#/components/parameters/xAccountIdHeader#/components/schemas/LeadInput#/components/schemas/Lead

#/components/parameters/xAccountIdHeader

OpenAPI

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

TypeScript

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

#/components/schemas/LeadInput

OpenAPI

type: object
description: Input for creating a new lead
properties:
  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.
  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
    description: Whether the lead is archived
  createdBy:
    type: string
    description: Email of the user who created the lead. If not provided, will be
      set to the current user's email.
required:
  - firstName
  - lastName

TypeScript

>
export interface LeadInput {
  /** 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;
  /** 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. If not provided, will be set to the current user's email. */
  createdBy?: string;
}

#/components/schemas/Lead

OpenAPI

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

TypeScript

>
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;
  }[];
}

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

Authentication Required

Required Parameters

Optional Parameters

Request Body

Try it out

Responses

References

• components-parameters-xAccountIdHeader
• components-schemas-LeadInput
• components-schemas-Lead

Route Source Code