leads

Update lead

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

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

Path parameters

idstring required

Request body

namestring

The lead's name

companystring

The lead's company

statusNotestring

A free-text status note

customField1string

Custom field 1

customField2string

Custom field 2

customField3string

Custom field 3

customAttributesobject

Custom key-value attributes (replaces the existing object)

Response

idstring required

The unique identifier of the lead

namestring required

The name of the lead

linkedinProfilestring required

The LinkedIn profile URL of the lead

companystring nullable

The lead's company

jobstring nullable

The lead's job title

campaignIdstring nullable

The campaign this lead belongs to, if any

listIdstring nullable

The list this lead belongs to, if any

campaignStatusstring 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.

hasRepliedboolean required

Whether the lead has replied

hasUnreadReplyboolean required

Whether the lead has an unread reply

isSkippedboolean required

Whether the lead was skipped

skippedReasonstring nullable

Why the lead was skipped, if applicable

createdAtstring date-time required

When the lead was created

invitedAtstring date-time nullable

When the invite was sent

connectedAtstring date-time nullable

When the lead connected

repliedAtstring date-time nullable

When the lead replied

withdrawnAtstring date-time nullable

When the invitation was withdrawn

stoppedAtstring 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.

locationstring nullable

The lead's location

lastMessagestring nullable

The most recent message in the conversation

chatIdstring 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.

statusNotestring nullable

A free-text status note

customField1string nullable
customField2string nullable
customField3string nullable
customAttributesobject nullable

Custom key-value attributes supplied when the lead was added

updatedAtstring date-time required

When the lead was last updated

Example response

{
  "name": "Jane Doe",
  "linkedinProfile": "https://www.linkedin.com/in/jane-doe",
  "events": [
    {
      "type": "INVITE_SENT"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.