---
title: "Update lead"
method: PATCH
path: "/v1/leads/{id}"
tags: ["leads"]
---

# Update lead

`PATCH /v1/leads/{id}`

## Request

- Base URL: `https://api.botdog.co`
- URL: `https://api.botdog.co/v1/leads/{id}`
- Auth: API key in header `x-api-key`

Update a lead’s editable metadata (notes, custom fields, name, company). Does not change campaign or workflow status.

## Path parameters

- `id` string, required

## Request body

- UpdateLeadDto
  - `name` string: The lead's name
  - `company` string: The lead's company
  - `statusNote` string: A free-text status note
  - `customField1` string: Custom field 1
  - `customField2` string: Custom field 2
  - `customField3` string: Custom field 3
  - `customAttributes` object: Custom key-value attributes (replaces the existing object)

## Response `200`

- LeadDetailDto
  - `id` string, required: The unique identifier of the lead
  - `name` string, required: The name of the lead
  - `linkedinProfile` string, required: The LinkedIn profile URL of the lead
  - `company` string, nullable: The lead's company
  - `job` string, nullable: The lead's job title
  - `campaignId` string, nullable: The campaign this lead belongs to, if any
  - `listId` string, nullable: The list this lead belongs to, if any
  - `campaignStatus` string, nullable: The campaign's status when this lead was added to it. It is not updated as the lead moves through its sequence, so it does not show whether the lead's sequence is still running, has finished, failed or was stopped. For that, read the lead's `events` on GET /v1/leads/{id}: `WORKFLOW_CLEANUP` means the sequence finished, `WORKFLOW_FAILED` means it failed, and `stoppedAt` is set when it was stopped through the API.
  - `hasReplied` boolean, required: Whether the lead has replied
  - `hasUnreadReply` boolean, required: Whether the lead has an unread reply
  - `isSkipped` boolean, required: Whether the lead was skipped
  - `skippedReason` string, nullable: Why the lead was skipped, if applicable
  - `createdAt` string, date-time, required: When the lead was created
  - `invitedAt` string, date-time, nullable: When the invite was sent
  - `connectedAt` string, date-time, nullable: When the lead connected
  - `repliedAt` string, date-time, nullable: When the lead replied
  - `withdrawnAt` string, date-time, nullable: When the invitation was withdrawn
  - `stoppedAt` string, date-time, nullable: When the lead was stopped, if it was. This is the authoritative confirmation that a stop took effect: it is written only after the lead’s sequence has been torn down, so a non-null value means no further steps — including any message already waiting on a delay — can run. Poll this after DELETE /v1/leads/{id} rather than the `stopped` flag on the stop response.
  - `location` string, nullable: The lead's location
  - `lastMessage` string, nullable: The most recent message in the conversation
  - `chatId` string, nullable: Id of the lead’s standard LinkedIn conversation — the `id` that POST /v1/conversations/{id}/reply expects. Null until Botdog has linked one; POST /v1/messages does not need it, and records it on first use.
  - `statusNote` string, nullable: A free-text status note
  - `customField1` string, nullable
  - `customField2` string, nullable
  - `customField3` string, nullable
  - `customAttributes` object, nullable: Custom key-value attributes supplied when the lead was added
  - `updatedAt` string, date-time, required: When the lead was last updated
  - `events` LeadEventDto[], required: Chronological event history for the lead
    - `id` string, required: The unique identifier of the event
    - `type` string, required: The event type
    - `createdAt` string, date-time, required: When the event occurred
    - `scheduledAt` string, date-time, nullable: When the underlying action was scheduled, if applicable
    - `details` string, nullable: Human-readable details about the event
    - `cancellationReason` string, nullable: Reason an action was cancelled, if applicable

## Other responses

- `401`: Unauthorized. API key is missing or invalid.
- `403`: The key owner has no seat assigned (write endpoints only), the team is on Botdog Managed and so may only read (write endpoints only), or the subscription/plan does not permit this.
- `404`: Lead not found
- `429`: Rate limit exceeded. Retry after cooldown.

---

[API](https://skmtc.dev/botdog/apis/botdog-api.md) · [All operations](https://skmtc.dev/botdog/apis/botdog-api/llms.txt) · [OpenAPI document](https://skmtc.dev/botdog/apis/botdog-api/revisions/6c0213d8a608?raw)