> ## 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 `channel` and a delay — use `delayValue` with `delayUnit` (preferred), or legacy `hours`.
```json theme={null}
{
"useStrategiesForFollowUps": true,
"followUpConfig": {
"1": { "delayValue": 24, "delayUnit": "hours", "channel": "text", "strategyIds": "auto" },
"2": { "delayValue": 30, "delayUnit": "minutes", "channel": "email" },
"3": { "delayValue": 168, "delayUnit": "hours", "channel": "call", "voicemailEnabled": true, "strategyIds": ["550e8400-e29b-41d4-a716-446655440000"] }
}
}
```
**Properties:**
* `delayValue` (number) - positive integer value. Minutes must be between 1 and 60 inclusive. Amount of time to wait before this follow-up step runs. Use with delayUnit.
* `delayUnit` (string) — preferred delay format. either "hours" or "minutes".
* `hours` (number) - see note below.
* `channel` — the outreach channel for this step
Each follow-up step must use either `delayValue` and `delayUnit` (preferred), or hours — not both.
**Legacy `hours` field:**
Still supported, but deprecated in favor of `delayValue` + `delayUnit`. Must be greater than 0.
```json theme={null}
{
"followUpConfig": {
"1": { "hours": 24, "channel": "text" }
}
}
```
**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 + the step's configured delay**:
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).
state:
type: string
description: >-
The US state or Canadian province for the lead. Accepts the
full name or two-letter abbreviation and is stored as the
canonical two-letter code. Unrecognized values are ignored.
example: CA
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.). Each step must include `channel` and either
`delayValue` + `delayUnit` (preferred) or legacy `hours` —
not both.
additionalProperties:
type: object
properties:
delayValue:
type: number
description: >-
Delay until this follow-up step. Must be greater than
0. For delayUnit "minutes", must be a positive integer
between 1 and 60.
delayUnit:
type: string
enum:
- hours
- minutes
description: >-
Unit for delayValue. Value must be either "hours" or
"minutes". Use with delayValue instead of legacy
hours.
hours:
type: number
description: >-
Hours until this follow-up step. Must be greater than
0. Deprecated — use delayValue with delayUnit instead.
Cannot be sent alongside delayValue or delayUnit.
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:
- 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
state: CA
additionalInfo:
newField: newValue
existingField: updatedValue
fieldToRemove: null
followUpConfig:
'1':
delayValue: 24
delayUnit: hours
channel: text
strategyIds: auto
'2':
delayValue: 30
delayUnit: minutes
channel: email
'3':
delayValue: 168
delayUnit: hours
channel: call
voicemailEnabled: true
strategyIds:
- 550e8400-e29b-41d4-a716-446655440000
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
````