> ## Documentation Index
> Fetch the complete documentation index at: https://docs.convocore.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Update Lead
> Updates a lead with the specified configuration, this route must use the new V3 [endpoints](/api-reference/v3/intro).
## Example Request
```json theme={null}
{
"lead": {
"name": "John Smith",
"metaData": {
"notes": "Follow up scheduled for next week"
}
}
}
```
Uses partial updates - only provided fields are changed. The `ts` timestamp is automatically updated.
You cannot change the `agentId` after creation. Create a new lead if you need to reassign.
## OpenAPI
````yaml PATCH /leads/{id}
openapi: 3.0.3
info:
title: Convocore OpenAPI
description: Full API reference for Convocore
version: 1.0.4
servers:
- url: https://eu-gcp-api.vg-stuff.com/v3
description: EU Node.js API server
- url: https://na-gcp-api.vg-stuff.com/v3
description: NA Node.js API server
security: []
paths:
/leads/{id}:
patch:
tags:
- Leads
summary: Update Lead
description: Updates an existing lead. Requires agentId in the request body.
operationId: leadsRouter-updateLead
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The unique identifier of the lead
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
agentId:
type: string
description: The agent ID that owns this lead (required in request body)
lead:
type: object
properties:
email:
type: string
nullable: true
description: The email of the lead.
name:
type: string
nullable: true
description: The name of the lead.
phone:
type: string
nullable: true
description: The phone number of the lead.
metaData:
type: object
properties:
address:
type: string
description: The address of the lead.
company:
type: string
description: The company of the lead.
website:
type: string
description: The website of the lead.
notes:
type: string
description: The notes of the lead.
source:
type: string
default: chat
description: The source of the lead.
currency:
type: string
description: The currency associated with the lead value.
value:
anyOf:
- type: number
- type: string
description: The budget or deal value of the lead.
stage:
type: string
enum:
- new
- engaged
- email_sent
- follow_up
- info_req
- demo_req
- demo_conf
- demo_done
- proposal
- negotiation
- trial
- won
- lost
description: The CRM stage of the lead.
expectedCloseDate:
type: string
description: Expected close date of the lead.
subIndustry:
type: string
description: The sub-industry of the lead.
language:
type: string
description: Preferred language of the lead.
linkedIn:
type: string
description: LinkedIn profile or company page.
facebook:
type: string
description: Facebook profile or company page.
instagram:
type: string
description: Instagram handle or profile link.
demoDate:
type: string
description: Scheduled demo date.
demoTime:
type: string
description: Scheduled demo time.
demoLink:
type: string
description: Scheduled demo meeting link.
lostReason:
type: string
description: Reason the lead was marked as lost.
additionalProperties: false
convoId:
anyOf:
- type: string
- type: number
description: The convo id of the lead.
ts:
anyOf:
- type: number
- type: string
description: The timestamp of the lead.
assignedTo:
type: object
properties:
userId:
type: string
name:
type: string
email:
type: string
photoUrl:
type: string
note:
type: string
assignedAt:
anyOf:
- type: string
- type: number
status:
type: string
enum:
- pending
- accepted
- done
required:
- userId
additionalProperties: false
description: Current assignee for the lead.
hotScore:
type: number
description: Computed lead heat score from 0-100.
hotLabel:
type: string
enum:
- hot
- warm
- cold
description: Computed heat label for the lead.
lastActivityDate:
anyOf:
- type: string
- type: number
description: Most recent lead activity timestamp.
crmActivities:
type: array
items:
type: object
properties:
id:
type: string
title:
type: string
type:
type: string
enum:
- Message
- Call
- Email
- Demo
- Meeting
- Follow-Up
- Note
- Stage Change
- Handoff
- System
date:
anyOf:
- type: string
- type: number
dueDate:
anyOf:
- type: string
- type: number
completed:
type: boolean
responded:
type: boolean
firstChannel:
type: string
enum:
- LinkedIn
- WhatsApp
- Instagram
- Facebook
- Email
- Phone/Call
- Zoom/Video
- In Person
- Referral
- Web Chat
- Unknown
firstEngaged:
type: boolean
secondChannel:
type: string
enum:
- LinkedIn
- WhatsApp
- Instagram
- Facebook
- Email
- Phone/Call
- Zoom/Video
- In Person
- Referral
- Web Chat
- Unknown
secondEngaged:
type: boolean
note:
type: string
notesHistory:
type: array
items:
type: object
properties:
agentId:
type: string
agentName:
type: string
text:
type: string
timestamp:
anyOf:
- type: string
- type: number
required:
- text
additionalProperties: false
metadata:
type: object
additionalProperties: {}
required:
- type
additionalProperties: false
description: Structured CRM activity timeline for the lead.
additionalProperties: false
description: Lead data to update (all fields optional)
required:
- agentId
- lead
additionalProperties: false
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
data: {}
required:
- success
- message
additionalProperties: false
default:
$ref: '#/components/responses/error'
security:
- Authorization: []
components:
responses:
error:
description: Error response
content:
application/json:
schema:
type: object
properties:
message:
type: string
code:
type: string
issues:
type: array
items:
type: object
properties:
message:
type: string
required:
- message
additionalProperties: false
required:
- message
- code
additionalProperties: false
securitySchemes:
Authorization:
type: http
scheme: bearer
````