> ## Documentation Index > Fetch the complete documentation index at: https://developer.mailbeast.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update a lead > Update a lead’s fields, tags, custom fields, or status. The email address can only be changed while the lead has not been contacted yet. Reply-based statuses can only be set once the lead has replied. Requires one of the following scopes: `leads:write`, `leads:all`, `all:all`. ## OpenAPI ````yaml /openapi.json patch /v1/campaigns/{cid}/leads/{leadId} openapi: 3.0.0 info: title: MailBeast Public API description: >- Task-shaped REST API for campaigns, leads, deliverability, verification and lead discovery. Authenticate with an API key (`Authorization: Bearer mb_live_…`); the workspace is resolved from the key. version: '1' contact: {} servers: - url: https://api.mailbeast.ai security: [] tags: - name: API Keys description: Create, list and revoke API keys programmatically. - name: Campaigns description: Create, configure, launch and monitor email campaigns. - name: Leads description: Add, read, update and bulk-manage a campaign’s leads. - name: Workspace description: Read usage, subscription and workspace identity. - name: Email Accounts description: >- Connect and manage the sending mailboxes your campaigns send from (SMTP/IMAP or native OAuth). - name: Analytics description: Engagement reporting – per campaign, over time, and across the workspace. - name: Lead Finder description: >- Discover new companies and leads. List past searches and poll a running search’s progress. paths: /v1/campaigns/{cid}/leads/{leadId}: patch: tags: - Leads summary: Update a lead description: >- Update a lead’s fields, tags, custom fields, or status. The email address can only be changed while the lead has not been contacted yet. Reply-based statuses can only be set once the lead has replied. Requires one of the following scopes: `leads:write`, `leads:all`, `all:all`. operationId: campaignLeads_update parameters: - name: cid required: true in: path schema: type: string format: uuid example: a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60 - name: leadId required: true in: path schema: type: string format: uuid example: c9e5b1a3-7f24-4d80-a6b9-2e4f8c0d1a37 - name: Idempotency-Key in: header description: >- Optional. A unique key you generate (max 255 chars, such as a UUID) that makes this request safe to retry. Retrying with the same key replays the original response instead of repeating the operation. Reusing a key with a different body returns `422`. required: false schema: type: string maxLength: 255 example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateLeadApiDto' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/LeadApiDto' '400': description: The request body or parameters failed validation. content: application/json: schema: $ref: '#/components/schemas/ApiErrorDto' example: error: type: invalid_request_error code: validation_failed message: One or more fields are invalid. status: 400 requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f details: - name should not be empty '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ApiErrorDto' example: error: type: authentication_error code: unauthenticated message: Missing or invalid API key. status: 401 requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f '403': description: >- The key lacks a required scope, or the plan does not include API access. content: application/json: schema: $ref: '#/components/schemas/ApiErrorDto' example: error: type: authorization_error code: permission_denied message: This API key is missing the required scope. status: 403 requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f '404': description: The resource does not exist in your workspace. content: application/json: schema: $ref: '#/components/schemas/ApiErrorDto' example: error: type: invalid_request_error code: not_found message: Resource not found. status: 404 requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f '409': description: >- The request conflicts with current state - e.g. a request with the same Idempotency-Key is still being processed, or the operation partially applied. content: application/json: schema: $ref: '#/components/schemas/ApiErrorDto' example: error: type: invalid_request_error code: conflict message: The request conflicts with an existing resource. status: 409 requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f '422': description: >- The Idempotency-Key was already used with a different request body. Use a new key for a new operation. content: application/json: schema: $ref: '#/components/schemas/ApiErrorDto' example: error: type: invalid_request_error code: idempotency_key_reused message: >- The Idempotency-Key was already used with a different request body. Use a new key for a new operation. status: 422 requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f '429': description: >- Rate limit exceeded - retry after the interval in the Retry-After header. content: application/json: schema: $ref: '#/components/schemas/ApiErrorDto' example: error: type: rate_limit_error code: rate_limited message: >- Too many requests. Retry after the interval in the Retry-After header. status: 429 requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f retryAfter: 30 security: - ApiKey: [] components: schemas: UpdateLeadApiDto: type: object properties: email: type: string example: jane.new@acme.com maxLength: 254 description: >- The email can only be changed while the lead has not been contacted yet. firstName: type: string example: Jane maxLength: 128 lastName: type: string example: Doe maxLength: 128 companyName: type: string maxLength: 256 example: Acme Inc. jobTitle: type: string maxLength: 128 example: Head of Growth website: type: string example: https://acme.com maxLength: 512 linkedinProfile: type: string maxLength: 512 example: https://www.linkedin.com/in/janedoe location: type: string maxLength: 128 example: Berlin, Germany tags: example: - vip - q4 type: array items: type: string customFields: type: object additionalProperties: true description: >- Custom fields - each key must be lowercase letters, digits and underscores, starting with a letter, up to 64 characters (e.g. `fund_manager`); a key outside that form is rejected. The number of fields per campaign is capped, and each value is length-limited. customFieldLabels: type: object additionalProperties: type: string description: >- Display labels for custom-field columns (applied on first definition). customFieldTypes: type: object additionalProperties: type: string description: >- Data types for custom-field columns (text | url | number | date | image; applied on first definition). status: type: string enum: - lead_replied_interested - lead_replied_meeting_request - lead_replied_out_of_office - lead_replied_wrong_person - lead_replied_not_interested - lead_replied_unsubscribed - lead_replied_uncategorized - lead_converted - lead_lost - blacklisted description: >- Only user-settable statuses are allowed; platform-managed ones such as `email_sent` or `scheduled` are rejected. Reply-based statuses (`lead_replied_*`, `lead_converted`) require the lead to have already replied. `lead_lost` and `blacklisted` can be set at any time. LeadApiDto: type: object properties: id: type: string format: uuid example: c9e5b1a3-7f24-4d80-a6b9-2e4f8c0d1a37 email: type: string example: jane@acme.com firstName: type: string nullable: true example: Jane lastName: type: string nullable: true example: Doe companyName: type: string nullable: true example: Acme Inc jobTitle: type: string nullable: true example: VP Sales website: type: string nullable: true example: https://acme.com linkedinProfile: type: string nullable: true example: https://www.linkedin.com/in/janedoe location: type: string nullable: true example: New York, US tags: example: - vip - q4 type: array items: type: string customFields: type: object additionalProperties: true example: industry: SaaS status: type: string enum: - not_contacted - scheduled - email_sent - failed - skipped - lead_replied_interested - lead_replied_meeting_request - lead_replied_out_of_office - lead_replied_bounce - lead_replied_wrong_person - lead_replied_not_interested - lead_replied_unsubscribed - lead_replied_uncategorized - lead_converted - lead_lost - blacklisted example: not_contacted verification: $ref: '#/components/schemas/LeadVerificationView' provider: type: string nullable: true example: google metrics: $ref: '#/components/schemas/LeadMetricsView' sequenceProgress: description: Live sequence progress - included on the single-lead detail view. allOf: - $ref: '#/components/schemas/LeadSequenceProgressView' createdAt: type: string format: date-time lastContactedAt: type: string format: date-time nullable: true lastRepliedAt: type: string format: date-time nullable: true required: - id - email - tags - customFields - status - verification - metrics - createdAt ApiErrorDto: type: object properties: error: $ref: '#/components/schemas/ApiErrorBodyDto' required: - error LeadVerificationView: type: object properties: status: type: string nullable: true example: valid subStatus: type: string nullable: true example: email_ok LeadMetricsView: type: object properties: sent: type: number example: 2 opened: type: number example: 1 clicked: type: number example: 0 replied: type: number example: 0 required: - sent - opened - clicked - replied LeadSequenceProgressView: type: object properties: totalSteps: type: number example: 3 sentCount: type: number example: 1 plannedCount: type: number example: 1 failedCount: type: number example: 0 nextPlannedAt: type: string format: date-time nullable: true description: When the next step is scheduled to send; null if none pending. required: - totalSteps - sentCount - plannedCount - failedCount ApiErrorBodyDto: type: object properties: type: type: string example: authorization_error description: Broad error class. code: type: string example: permission_denied description: Stable machine-readable code to switch on. message: type: string example: This API key is missing the required scope. status: type: number example: 403 requestId: type: string example: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f description: Correlation id - quote it in support requests. details: description: Field-level validation messages (present on validation errors). example: - name should not be empty type: array items: type: string retryAfter: type: number description: Seconds to wait before retrying (present on 429 responses). example: 30 required: - type - code - message - status - requestId securitySchemes: ApiKey: scheme: bearer bearerFormat: mb_live_… type: http ```` ## Related topics - [Leads](/leads.md) - [Update a campaign](/api-reference/campaigns/update-a-campaign.md) - [Update a mailbox](/api-reference/email-accounts/update-a-mailbox.md) - [Bulk update mailboxes](/api-reference/email-accounts/bulk-update-mailboxes.md) - [Authentication](/authentication.md)