# Update a lead (/api-reference/leads/updateLead)

## PUT /api/v1/leads/{lead_id}

Operation ID: `updateLead`
Update a lead
Changes only the fields you send. Send `If-Match` with the lead's `updatedAt` to refuse the write (`lead_changed`) when someone changed the lead after you read it. A new `phone` is stored in E.164 form like on create. Campaign IDs you cannot access are skipped.

### Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `lead_id` | path | yes | Lead ID. |
| `If-Match` | header | no |  |

### Request body

`application/json` (required)

```json
{
  "additionalProperties": true,
  "description": "Send only the fields to change.",
  "properties": {
    "assignedToUserId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "A team member's user ID, or null to unassign.",
      "title": "Assignedtouserid"
    },
    "attributes": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "description": "Profile facts to set; a null value clears that fact. Other facts stay.",
      "title": "Attributes"
    },
    "campaignIds": {
      "anyOf": [
        {
          "items": {},
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "description": "Replaces the lead's campaigns: campaigns missing from the list are removed.",
      "title": "Campaignids"
    },
    "company": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Company name.",
      "title": "Company"
    },
    "dismissIssues": {
      "anyOf": [
        {
          "items": {},
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "description": "Attribute keys whose kept-aside values (`attributeIssues`) should be dropped.",
      "title": "Dismississues"
    },
    "email": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Email address.",
      "title": "Email"
    },
    "externalId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Your business id for this person.",
      "title": "Externalid"
    },
    "leadSourceId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "ID of a lead source, or empty to clear.",
      "title": "Leadsourceid"
    },
    "name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Full name.",
      "title": "Name"
    },
    "notes": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Deprecated: adds one note (never replaces notes). Use `POST /leads/{leadId}/notes`.",
      "title": "Notes"
    },
    "phone": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Phone number, saved in E.164 form: `+919876543210`, `9876543210` and `098765 43210` all save as `+919876543210` (a number without a country code is taken as Indian). A value that is not a phone number returns 422 `invalid_phone_number`.",
      "title": "Phone"
    },
    "source": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Free-text source label.",
      "title": "Source"
    },
    "status": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Pipeline status key.",
      "title": "Status"
    },
    "tags": {
      "anyOf": [
        {
          "items": {},
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "description": "Replaces the lead's tags.",
      "title": "Tags"
    },
    "timezone": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "IANA time zone such as `Asia/Kolkata` for dial windows.",
      "title": "Timezone"
    },
    "title": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Job title.",
      "title": "Title"
    }
  },
  "title": "LeadUpdate",
  "type": "object"
}
```

Example:

```json
{
  "attributes": {
    "city": "Mumbai"
  },
  "status": "qualified",
  "tags": [
    "vip"
  ]
}
```

### Responses

#### 200 OK

Schema:

```json
{
  "additionalProperties": true,
  "description": "The lead after the change.",
  "properties": {
    "lead": {
      "additionalProperties": true,
      "description": "A person you can call, with their latest call state and profile facts.",
      "properties": {
        "assignedToUserId": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Team member who owns the lead, or null.",
          "title": "Assignedtouserid"
        },
        "assigneeName": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "That team member's name.",
          "title": "Assigneename"
        },
        "attributeIssues": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "description": "Values that did not fit their field's type, kept aside: `{key: {raw, reason, at}}`.",
          "title": "Attributeissues"
        },
        "attributes": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "description": "Current profile facts, for example `{\"ward_no\": \"8\", \"age\": 31}`.",
          "title": "Attributes"
        },
        "callAttempts": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "description": "Calls attempted so far.",
          "title": "Callattempts"
        },
        "callStatus": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Latest dialing state, for example `not_called`, `calling`, `called`, `no_answer`.",
          "title": "Callstatus"
        },
        "campaignCallStatus": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "description": "Per-campaign dialing state keyed by campaign ID: status, attempts, lastAttempt, nextScheduled.",
          "title": "Campaigncallstatus"
        },
        "campaignIds": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "description": "Campaigns the lead is in.",
          "title": "Campaignids"
        },
        "campaignNames": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "description": "Names of those campaigns, same order.",
          "title": "Campaignnames"
        },
        "company": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Company name.",
          "title": "Company"
        },
        "createdAt": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "When the lead was created.",
          "format": "date-time",
          "title": "Createdat"
        },
        "dncOptOut": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "description": "True when the number must never be dialed.",
          "title": "Dncoptout"
        },
        "dncReason": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Why the lead is on do-not-call.",
          "title": "Dncreason"
        },
        "dncUpdatedAt": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "When do-not-call last changed.",
          "format": "date-time",
          "title": "Dncupdatedat"
        },
        "email": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Email address.",
          "title": "Email"
        },
        "externalId": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Your business id (EPIC, patient id, order id). Unique inside a lead source.",
          "title": "Externalid"
        },
        "id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Lead ID.",
          "title": "Id"
        },
        "lastCallAttempt": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "When the last call was attempted.",
          "format": "date-time",
          "title": "Lastcallattempt"
        },
        "lastContactDate": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Last time the lead was reached.",
          "format": "date-time",
          "title": "Lastcontactdate"
        },
        "leadSourceId": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Lead source the lead belongs to, or empty.",
          "title": "Leadsourceid"
        },
        "merchantOutcome": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Outcome of the latest result, for example `interested`, `callback` or `no_answer`.",
          "title": "Merchantoutcome"
        },
        "name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Full name.",
          "title": "Name"
        },
        "nextCallScheduled": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "When the next automatic attempt is due.",
          "format": "date-time",
          "title": "Nextcallscheduled"
        },
        "notes": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Deprecated: use the notes endpoints. The latest 20 notes as text, newest first; only on single-lead responses.",
          "title": "Notes"
        },
        "notesCount": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "description": "Live notes on the lead.",
          "title": "Notescount"
        },
        "phone": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Phone number as stored.",
          "title": "Phone"
        },
        "pinnedNotePreview": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Start of the newest pinned note.",
          "title": "Pinnednotepreview"
        },
        "source": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Where the lead came from.",
          "title": "Source"
        },
        "status": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Pipeline status key, one of your workspace's statuses (default `new`).",
          "title": "Status"
        },
        "tags": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "description": "Tags on the lead.",
          "title": "Tags"
        },
        "title": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Job title.",
          "title": "Title"
        },
        "updatedAt": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Last change. Send it as `If-Match` on update to avoid overwriting someone's edit.",
          "format": "date-time",
          "title": "Updatedat"
        }
      },
      "title": "Lead",
      "type": "object"
    },
    "success": {
      "default": true,
      "description": "Always true on a 2xx response.",
      "title": "Success",
      "type": "boolean"
    },
    "warnings": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "description": "A value that was not saved as sent; the rest of the write succeeded.",
            "properties": {
              "key": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Field key, for example `status` or an attribute key.",
                "title": "Key"
              },
              "label": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Field label.",
                "title": "Label"
              },
              "reason": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "What happened to the value.",
                "title": "Reason"
              },
              "value": {
                "description": "The value you sent.",
                "title": "Value"
              }
            },
            "title": "FieldWarning",
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "description": "Values saved differently than sent (for example an unknown status).",
      "title": "Warnings"
    }
  },
  "required": [
    "lead"
  ],
  "title": "LeadResult",
  "type": "object"
}
```

#### 400 Bad request: `bad_request`.

Example (The request could not be processed.):

```json
{
  "detail": "The request could not be processed.",
  "error": {
    "code": "bad_request",
    "docUrl": "https://docs.callmitra.ai/errors/bad_request",
    "message": "The request could not be processed.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

#### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`.

Example (The API key has expired.):

```json
{
  "detail": "The API key has expired.",
  "error": {
    "code": "api_key_expired",
    "docUrl": "https://docs.callmitra.ai/errors/api_key_expired",
    "message": "The API key has expired.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

Example (The API key is invalid or has been revoked.):

```json
{
  "detail": "The API key is invalid or has been revoked.",
  "error": {
    "code": "invalid_api_key",
    "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key",
    "message": "The API key is invalid or has been revoked.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

Example (Authentication required.):

```json
{
  "detail": "Authentication required.",
  "error": {
    "code": "unauthenticated",
    "docUrl": "https://docs.callmitra.ai/errors/unauthenticated",
    "message": "Authentication required.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

#### 403 Forbidden: `api_key_scope_denied`, `permission_denied`.

Example (The API key does not have the scope required for this request.):

```json
{
  "detail": "The API key does not have the scope required for this request.",
  "error": {
    "code": "api_key_scope_denied",
    "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied",
    "message": "The API key does not have the scope required for this request.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "permission_error"
  }
}
```

Example (You do not have permission to perform this action.):

```json
{
  "detail": "You do not have permission to perform this action.",
  "error": {
    "code": "permission_denied",
    "docUrl": "https://docs.callmitra.ai/errors/permission_denied",
    "message": "You do not have permission to perform this action.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "permission_error"
  }
}
```

#### 404 Not found: `lead_not_found`.

Example (Lead not found.):

```json
{
  "detail": "Lead not found.",
  "error": {
    "code": "lead_not_found",
    "docUrl": "https://docs.callmitra.ai/errors/lead_not_found",
    "message": "Lead not found.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "not_found_error"
  }
}
```

#### 409 Conflict: `lead_changed`.

Example (This lead changed since you opened it.):

```json
{
  "detail": "This lead changed since you opened it.",
  "error": {
    "code": "lead_changed",
    "docUrl": "https://docs.callmitra.ai/errors/lead_changed",
    "message": "This lead changed since you opened it.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "conflict_error"
  }
}
```

#### 422 Invalid parameters: `invalid_phone_number`, `parameter_invalid`.

Example (The phone number is not valid.):

```json
{
  "detail": [
    {
      "loc": [
        "body",
        "phone"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ],
  "error": {
    "code": "invalid_phone_number",
    "docUrl": "https://docs.callmitra.ai/errors/invalid_phone_number",
    "message": "The phone number is not valid.",
    "param": "phone",
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

Example (One or more parameters are invalid.):

```json
{
  "detail": [
    {
      "loc": [
        "body",
        "phone"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ],
  "error": {
    "code": "parameter_invalid",
    "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid",
    "message": "One or more parameters are invalid.",
    "param": "phone",
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

#### 429 Too many requests: `rate_limit_exceeded`.

Example (Too many requests. Slow down and retry later.):

```json
{
  "detail": "Too many requests. Slow down and retry later.",
  "error": {
    "code": "rate_limit_exceeded",
    "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded",
    "message": "Too many requests. Slow down and retry later.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "rate_limit_error"
  }
}
```

#### 500 Server error: `internal_error`.

Example (Something went wrong on our side.):

```json
{
  "detail": "Something went wrong on our side.",
  "error": {
    "code": "internal_error",
    "docUrl": "https://docs.callmitra.ai/errors/internal_error",
    "message": "Something went wrong on our side.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "api_error"
  }
}
```

### Error codes

- [`bad_request`](/errors/bad_request)
- [`api_key_expired`](/errors/api_key_expired)
- [`invalid_api_key`](/errors/invalid_api_key)
- [`unauthenticated`](/errors/unauthenticated)
- [`api_key_scope_denied`](/errors/api_key_scope_denied)
- [`permission_denied`](/errors/permission_denied)
- [`lead_not_found`](/errors/lead_not_found)
- [`lead_changed`](/errors/lead_changed)
- [`invalid_phone_number`](/errors/invalid_phone_number)
- [`parameter_invalid`](/errors/parameter_invalid)
- [`rate_limit_exceeded`](/errors/rate_limit_exceeded)
- [`internal_error`](/errors/internal_error)
