Skip to content
Pulse Docs

Leads

The leads endpoints provide functionality for managing potential customers in your CRM system. The model represents individuals or businesses that have shown interest in your products or services.

Example Lead Object

{
  "id": 42,
  "accountId": "6591739253089529",
  "applicationId": "APP123456",
  "firstName": "John",
  "lastName": "Doe",
  "imgSrc": "https://example.com/profiles/johndoe.jpg",
  "email": "john.doe@example.com",
  "phone": "+15555555555",
  "company": "Acme Inc",
  "jobTitle": "CTO",
  "branch": "Technology",
  "source": "Website",
  "position": "Decision Maker",
  "location": "New York, NY",
  "productsServicesSold": "Payment Processing, POS Systems",
  "numberOfEmployees": 50,
  "currentPaymentProcessor": "OldProcessor Inc",
  "monthlyTransactionVolume": 75000,
  "interestedInSwitching": true,
  "processStage": "Initial Contact",
  "buyingRole": "Decision Maker",
  "assignedTo": "agent@example.com",
  "notes": "Reached out through contact form. Interested in learning more about our payment processing solutions.",
  "lastContacted": "2023-06-15T14:30:00Z",
  "archived": false,
  "createdAt": "2023-06-01T09:00:00Z",
  "updatedAt": "2023-06-15T14:30:00Z",
  "auditLog": [
    {
      "id": 2001,
      "event": "lead_created",
      "user": "agent@example.com",
      "apiKey": null,
      "data": {
        "leadId": "42"
      },
      "created": "2023-06-01T09:00:00Z",
      "requestMethod": "POST",
      "requestPath": "/api/leads",
      "requestHeaders": {
        "content-type": "application/json",
        "x-account-id": "6591739253089529"
      },
      "requestIpAddress": "192.168.1.100",
      "account_id": "6591739253089529"
    }
  ]
}

Properties

id

  • Type: integer
  • Description: The unique identifier for the lead in the database.
  • Required: Auto-generated

accountId

  • Type: string
  • Description: The account ID that this lead belongs to.
  • Required: Yes

applicationId

  • Type: string | null
  • Description: The ID of an application associated with this lead, if any.
  • Required: No

firstName

  • Type: string
  • Description: The first name of the lead contact.
  • Required: Yes

lastName

  • Type: string
  • Description: The last name of the lead contact.
  • Required: Yes
  • Default: Empty string

imgSrc

  • Type: string | null
  • Description: URL to the lead’s profile image or avatar.
  • Required: No

email

  • Type: string | null
  • Description: The email address of the lead contact.
  • Required: No

phone

  • Type: string | null
  • Description: The phone number of the lead contact.
  • Required: No

company

  • Type: string | null
  • Description: The company or business name that the lead represents.
  • Required: No

jobTitle

  • Type: string | null
  • Description: The job title or position of the lead contact within their organization.
  • Required: No

branch

  • Type: string | null
  • Description: The branch or department within the company.
  • Required: No

source

  • Type: string | null
  • Description: How the lead was acquired (e.g., “Website”, “Referral”, “Trade Show”).
  • Required: No

position

  • Type: string | null
  • Description: The lead’s position or role in the purchasing process.
  • Required: No

location

  • Type: string | null
  • Description: Geographic location of the lead or their business.
  • Required: No

productsServicesSold

  • Type: string | null
  • Description: Products or services that the lead’s business sells.
  • Required: No

numberOfEmployees

  • Type: integer | null
  • Description: The number of employees at the lead’s company.
  • Required: No

currentPaymentProcessor

  • Type: string | null
  • Description: The payment processor the lead is currently using.
  • Required: No

monthlyTransactionVolume

  • Type: integer | null
  • Description: The lead’s approximate monthly transaction volume in dollars.
  • Required: No

interestedInSwitching

  • Type: boolean | null
  • Description: Indicates if the lead has expressed interest in switching service providers.
  • Required: No

processStage

  • Type: string | null
  • Description: The current stage in the sales process (e.g., “Initial Contact”, “Demo Scheduled”, “Proposal Sent”).
  • Required: No

buyingRole

  • Type: string | null
  • Description: The lead’s role in the buying decision process (e.g., “Decision Maker”, “Influencer”).
  • Required: No

assignedTo

  • Type: string | null
  • Description: The user or agent that this lead is assigned to.
  • Required: No

notes

  • Type: string | null
  • Description: Additional notes or information about the lead.
  • Required: No

lastContacted

  • Type: string (ISO 8601 datetime) | null
  • Description: The timestamp of the last contact with this lead.
  • Required: No

archived

  • Type: boolean
  • Description: Indicates whether the lead is archived.
  • Required: Yes
  • Default: false

createdAt

  • Type: string (ISO 8601 datetime)
  • Description: The timestamp of when the lead was created.
  • Required: Auto-generated

updatedAt

  • Type: string (ISO 8601 datetime)
  • Description: The timestamp of the last update to the lead.
  • Required: Auto-generated

auditLog

  • Type: array of audit event objects
  • Description: A comprehensive log of all significant events and actions performed on the lead. Each event captures who performed the action, when it occurred, and relevant details.
  • Required: Auto-generated
  • Read-only: Yes

Each audit log entry contains:

  • id: Unique identifier for the audit log entry
  • event: The type of event (e.g., lead_created, lead_updated, lead_archived, lead_converted)
  • user: Email address or identifier of the user who performed the action
  • apiKey: API key identifier if the action was performed via API key authentication (null for regular user sessions)
  • data: Event-specific data containing details about what was changed or accessed (structure varies by event type)
  • created: Timestamp when the event occurred (ISO 8601 format)
  • requestMethod: HTTP method used (GET, POST, PATCH, DELETE)
  • requestPath: API endpoint path that was called
  • requestHeaders: Sanitized HTTP headers from the request (sensitive values like authorization are masked)
  • requestIpAddress: IP address of the request origin
  • account_id: Account ID associated with the action

Common Audit Events for Leads

lead_created

  • Triggered when a new lead is created
  • Captures the initial lead data and who created it

lead_updated

  • Triggered when lead data is modified
  • Contains details of fields that were changed

lead_archived

  • Triggered when a lead is archived
  • Records who archived the lead and when

lead_unarchived

  • Triggered when a lead is restored from archived status

lead_deleted

  • Triggered when a lead is permanently deleted
  • Records who deleted the lead and when

lead_converted

  • Triggered when a lead is converted to an application
  • Contains the application ID that was created

Example audit log entry:

{
  "id": 1850,
  "event": "lead_updated",
  "data": {
    "leadId": "42"
  },
  "user": "manager@example.com",
  "apiKey": null,
  "created": "2025-10-13T18:48:19.739Z",
  "requestMethod": "PATCH",
  "requestPath": "/api/leads/42",
  "requestHeaders": {
    "host": "api.pulsecrm.com",
    "content-type": "application/json",
    "x-account-id": "2311",
    "authorization": "********"
  },
  "requestIpAddress": "192.168.1.100",
  "account_id": "2311"
}

Note: The data field structure varies by event type and contains event-specific information. For example, lead_created events include the created lead data, while lead_converted events include the resulting application ID.

The following endpoints are available for working with leads:

List Leads

GET /leads

Returns a paginated list of leads with support for filtering, sorting, and searching.

Create Lead

POST /leads

Creates a new lead with the provided data.

Get Lead by ID

GET /leads/{leadId}

Retrieves a specific lead by its ID.

Update Lead

PATCH /leads/{leadId}

Updates an existing lead with new data.

Delete Lead

DELETE /leads/{leadId}

Permanently deletes a lead from the system.

Archive Lead

POST /leads/{leadId}/archive

Marks a lead as archived without deleting it.

Unarchive Lead

DELETE /leads/{leadId}/archive

Restores a previously archived lead.

Associated Models

Leads can have relationships with the following models:

Contact Extra Info

Additional contact information for a lead, such as secondary phone numbers, social media profiles, or addresses.

Contacts

A more comprehensive contact record that can be associated with multiple leads, accounts, and users.

Best Practices

  • Use the archived flag rather than deleting leads to maintain historical data.
  • Ensure basic contact information (name, email or phone) is provided when creating leads.
  • When filtering by date fields, use ISO 8601 format (YYYY-MM-DDTHH:mm:ss.sssZ).
  • For date ranges, separate the start and end dates with a comma (e.g., 2023-01-01,2023-12-31).