Update Lead Status

​

Update the status of a specific lead.

This endpoint allows transitioning a lead through different stages of the qualification process. Different status values have specific requirements:

  • STUCK: Requires status_notes to explain why the lead is stuck
  • DISQUALIFIED: Requires disqualified_reason to specify why
  • CLOSED_QUALIFIED: Requires closed_as_qualified_reason to specify why

The endpoint also supports optional flags to disqualify the associated company or person.

Args:

  • lead_id: The unique identifier of the lead to update (format: 'l-xxxxx')
  • status_update: Status update details including new status and required fields
  • user: Authenticated user (automatically injected)

Returns:

  • Updated lead object with new status and metadata

Raises:

  • 400 Bad Request: If required fields are missing for the status
  • 404 Not Found: If the lead doesn't exist
  • 500 Internal Server Error: If the update fails

Example Request:

{
  "status": "STUCK",
  "statusNotes": "Waiting for budget approval from CFO"
}

Path Parameters

  • lead_id
    Type: string
    required

Body·

required
application/json

Input model for updating a lead's status.

This model is used when transitioning a lead through different stages of the qualification process. Different status values may require specific additional fields (e.g., STUCK requires status_notes, DISQUALIFIED requires disqualified_reason).

  • status
    Type: enum
    required

    New Status - The status to transition the lead to. Each status may have specific requirements for additional fields

    values
    123456
  • closedAsQualifiedReason
    Type: integernullable

    Qualification Reason - Required when status is CLOSED_QUALIFIED. Specifies why the lead was marked as qualified

  • disqualifiedCompanyReason
    Type: integernullable

    Company Disqualification Reason - Optional reason for disqualifying the entire company, not just this lead

  • disqualifiedReason
    Type: integernullable

    Disqualification Reason - Required when status is DISQUALIFIED. Specifies why the lead was disqualified

  • disqualifyCompany
    Type: booleannullable

    Disqualify Company Flag - If true, marks the entire company as disqualified, not just this lead

  • disqualifyPerson
    Type: booleannullable

    Disqualify Person Flag - If true, marks the contact person as disqualified for future leads

  • statusNotes
    Type: stringnullable

    Status Notes - Additional context about the status change. Required when status is STUCK. Maximum 8192 characters

Responses

  • application/json
  • application/json
Request Example for put/{lead_id}/status
curl 'https://crm.dreamhub.ai/api/v1/leads/{lead_id}/status' \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "status": 1,
  "disqualifiedReason": 1,
  "disqualifiedCompanyReason": 2,
  "closedAsQualifiedReason": 1,
  "statusNotes": "Waiting for budget approval",
  "disqualifyCompany": true,
  "disqualifyPerson": true
}'

{
  "name": "Acme Corp - Enterprise Platform Evaluation",
  "sdrOwner": "u-abc123",
  "aeOwner": "u-xyz789",
  "companyId": "c-company123",
  "contactId": "p-contact789",
  "status": 1,
  "createdAt": "2026-09-29T00:01:38.146Z",
  "engagementScore": 1,
  "conversionProbability": 0.75,
  "source": 1,
  "disqualifiedReason": 1,
  "disqualifiedCompanyReason": 2,
  "closedAsQualifiedReason": 1,
  "statusNotes": "Waiting for budget approval from CFO",
  "statusChangedBy": "u-user123",
  "statusChangedAt": "2024-01-20T14:45:00Z",
  "licenseId": "l-license123",
  "productId": "prod-platform",
  "numberOfLicenses": 10,
  "salesExplorationMeetingDate": "2024-02-01T15:00:00Z",
  "inboundCampaignType": 1,
  "outboundCampaignType": 2,
  "referringCompany": "c-referrer123",
  "referringPerson": "p-referrer456",
  "otherCompanyName": "Subsidiary Corp",
  "otherPersonName": "John Smith (Decision Maker)",
  "partnerId": "ptn-partner123",
  "partnerContactId": "ptc-contact789",
  "previousStatus": 1,
  "companyUpdated": false,
  "personUpdated": false,
  "tokenHolder": "string",
  "tokenHolderNextSteps": "string",
  "closedAt": "2026-09-29T00:01:38.146Z",
  "lastModifiedBy": "string",
  "salesExplorationStatus": "not_booked",
  "id": "l-logi-f47ac10b",
  "lastActivity": "2026-09-29T00:01:38.146Z",
  "openForDays": 1,
  "salesExplorationStatusDisplay": "string",
  "contactJobTitle": "string",
  "contactEmail": "string",
  "contactFirstName": "string",
  "contactLastName": "string",
  "companyName": "string",
  "productName": "string",
  "contact": "string",
  "additionalProperty": "anything"
}

Successful Response