> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apten.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Update lead
> Updates properties of a specific lead
## Usage Notes
### Updating additionalInfo
The `additionalInfo` field uses merge/upsert behavior:
* New keys are added to the existing additionalInfo
* Existing keys are updated with new values
* To **delete** a key, set its value to `null`
```json theme={null}
{
"additionalInfo": {
"newKey": "newValue", // Adds new key
"existingKey": "updated", // Updates existing key
"oldKey": null // Removes this key
}
}
```
### Follow-up Configuration
The `followUpConfig` defines the follow-up schedule. Each step must include both `hours` and `channel`:
```json theme={null}
{
"useStrategiesForFollowUps": true,
"followUpConfig": {
"1": { "hours": 24, "channel": "text", "strategyIds": "auto" },
"2": { "hours": 72, "channel": "email" },
"3": { "hours": 168, "channel": "call", "voicemailEnabled": true, "strategyIds": ["550e8400-e29b-41d4-a716-446655440000", "7c9e6679-7425-40de-944b-e07fc1f90ae7"] }
}
}
```
**Allowed channels:** `text`, `call`, `email`
**Optional properties:**
* `voicemailEnabled` (boolean): Only valid for `call` channel. If true, leaves a voicemail when call is not answered.
* `strategyIds` (string or string array): Strategy IDs to use for this follow-up step. Use `"auto"` for automatic selection, or provide an array of specific strategy IDs. Requires `useStrategiesForFollowUps` to be set to `true` on the lead.
Channel requirements: - **text**: Always available (SMS) - **call**: Requires
voice to be enabled on the customer profile - **email**: Requires email to be
enabled on both the customer profile and organization
To stop all follow-ups for a lead, set `followUpConfig` to an empty object `{}
`. This will cancel any scheduled follow-ups and set the lead to STOPPED state.
### Follow-up Scheduling Behavior
When updating `followUpStep` and/or `followUpConfig`, the timer always resets to `now + hours`:
1. **Update followUpStep only**: Schedules that specific step
2. **Update followUpConfig only**: Reschedules with new timing, preserving the current step
3. **Update both**: Full reset with the new config starting at the specified step
#### Special followUpStep Values
* **Positive integers (1, 2, 3, ...)**: Schedule that specific follow-up step
* **-1 (STOPPED)**: Stops all follow-ups for this lead
* **-2 (LONG\_TERM)**: Moves lead to long-term nurture mode
## OpenAPI
````yaml patch /leads/{leadId}
openapi: 3.0.1
info:
title: AttentPublicAPI
version: '2024-05-17T21:09:13Z'
servers:
- url: https://api.attent.app/v1
security: []
paths:
/leads/{leadId}:
patch:
description: Updates properties of a specific lead
parameters:
- name: leadId
in: path
required: true
schema:
type: string
description: The ID of the lead to update
requestBody:
description: Fields to update on the lead. All fields are optional.
content:
application/json:
schema:
type: object
properties:
email:
type: string
description: The email address of the lead. Must be a valid email format.
timeZone:
type: string
description: >-
The timezone of the lead in tz database format (e.g.
America/New_York).
additionalInfo:
type: object
nullable: true
description: >-
Key-value object to merge with existing additionalInfo. Set
a value to null to remove that key.
additionalProperties: true
followUpConfig:
type: object
description: >-
Follow-up schedule configuration. Keys are step numbers (1,
2, 3, etc.), values are objects with hours and channel.
additionalProperties:
type: object
properties:
hours:
type: number
description: >-
Hours until this follow-up step. Must be greater than
0.
channel:
type: string
description: >-
Channel for this follow-up. Each channel requires
specific features to be enabled on the customer
profile.
enum:
- text
- call
- email
voicemailEnabled:
type: boolean
description: >-
Whether to leave a voicemail if the call is not
answered. Only valid for channel "call".
strategyIds:
description: >-
Strategy IDs to use for this follow-up step. Use
"auto" for automatic selection, or provide an array of
specific strategy IDs.
oneOf:
- type: string
enum:
- auto
- type: array
items:
type: string
required:
- hours
- channel
followUpStep:
type: integer
description: >-
The follow-up step to schedule. Use positive integers (1, 2,
3, ...) for specific steps, -1 for STOPPED, or -2 for
LONG_TERM.
useStrategiesForFollowUps:
type: boolean
description: >-
Enable strategy-based follow-ups for this lead. Must be true
for strategyIds in followUpConfig steps to take effect.
example:
email: newemail@example.com
timeZone: America/Los_Angeles
additionalInfo:
newField: newValue
existingField: updatedValue
fieldToRemove: null
followUpConfig:
'1':
hours: 24
channel: text
strategyIds: auto
'2':
hours: 72
channel: email
'3':
hours: 168
channel: call
voicemailEnabled: true
strategyIds:
- 550e8400-e29b-41d4-a716-446655440000
- 7c9e6679-7425-40de-944b-e07fc1f90ae7
followUpStep: 1
useStrategiesForFollowUps: true
responses:
'200':
description: Lead updated successfully.
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: >-
Returns "Lead updated successfully." when the update
completes.
example:
message: Lead updated successfully.
'400':
description: Bad request - validation error.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: >-
Invalid format for field: email must be a valid email
address
'403':
$ref: '#/components/responses/403'
'404':
description: Lead not found.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: 'Resource not found: Lead'
'500':
$ref: '#/components/responses/500'
security:
- api_key: []
components:
responses:
'403':
description: Forbidden API key
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: Forbidden
'500':
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: Internal Server Error
securitySchemes:
api_key:
type: apiKey
name: x-api-key
in: header
````