> ## Documentation Index > Fetch the complete documentation index at: https://docs.sendler.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update Lead Status > Set a lead outcome and/or CRM categorization. Requires `leads:write`. Supply at least one of `status` or `customLeadStatus`. * Settable `status`: `OPPORTUNITY`, `MEETING_BOOKED`, `DONE`, `UNSUBSCRIBED`, `IRRELEVANT`. * `customLeadStatus`: `LEAD`, `INTERESTED`, `MEETING_BOOKED`, `MEETING_COMPLETE_NOT_CLOSED`, `CLOSED`, `WRONG_PERSON`, `NOT_INTERESTED`, `NO_RESPONSE`. Sequence-managed statuses such as `MESSAGE_SENT` cannot be set through this endpoint. `DONE`, `UNSUBSCRIBED`, and `IRRELEVANT` stop further campaign outreach and remain permitted by the REST lapsed-subscription policy. `note` **replaces** existing notes; omit it to preserve them. Its maximum length is 1,000 characters. Use an [Idempotency-Key](https://docs.sendler.ai/api-reference/behavior.md#idempotent-writes) for retries. MCP uses `custom_status`, while this REST endpoint uses `customLeadStatus`. ## OpenAPI ````yaml PATCH /v1/leads/{id}/status openapi: 3.0.0 info: title: SendPilot External API description: > # SendPilot External API v1 Public API for integrating with SendPilot programmatically. ## Authentication Requests authenticate with a workspace API key in the `X-API-Key` header: ``` X-API-Key: sp_live_your_api_key_here ``` `Authorization: Bearer sp_live_...` (or `sp_test_...`) is also accepted. Prefer one header; `X-API-Key` takes precedence. Clerk OAuth tokens for MCP connection URLs are not public REST API keys. A key only reaches what its scopes and creator's current workspace permissions allow. Each operation lists the scopes it needs in `x-sp-scopes`. Use `GET /v1/me` to inspect the effective permissions and subscription state. ## Rate Limits - **Per API Key**: 300 requests/minute - **Per Workspace**: 50,000 requests/day Responses that reach the rate limiter include these headers; early authentication failures may not: - `X-RateLimit-Limit`: Max requests per minute - `X-RateLimit-Remaining`: Remaining requests in current window - `X-RateLimit-Reset`: Epoch timestamp when limit resets ## LinkedIn Sender Limits When using messaging endpoints, these headers show account limits: - `X-LinkedIn-Messages-Remaining`: Messages left today - `X-LinkedIn-Connections-Remaining`: Connection requests left today - `X-LinkedIn-Quota-Reset-At`: When daily limits reset ## Retries Send an `Idempotency-Key` header on POST and PATCH requests. A retry with the same key within 24 hours returns the first result (with `Idempotent-Replayed: true`) instead of acting twice. The same key with a different request answers 422 `IDEMPOTENCY_KEY_REUSED`; a retry while the first request still runs answers 409 `IDEMPOTENCY_IN_PROGRESS`. Once execution is attempted, its response (including errors) is retained. If a process stops or result storage fails after the attempt, the durable record blocks another execution for the replay window and returns 409 `IDEMPOTENCY_IN_PROGRESS` or `IDEMPOTENCY_REPLAY_UNAVAILABLE`. Check the operation's status before using a new key: an uncertain outcome may already have acted. Requests refused before execution is claimed, such as authentication or rate-limit refusals, can be retried with the same key. ## Webhooks Configure webhooks in the SendPilot app to receive real-time events: - `lead.tag.updated` - `lead.updated` - `message.sent` - `reply.received` - `connection_request.sent` - `connection_request.accepted` - `campaign.started` - `campaign.paused` - `campaign.resumed` - `campaign.finished` ## Error Codes Errors return a JSON body. Use the machine-readable `code` when supplied; validation messages can be arrays, and some legacy errors omit `code`. A typical error is: ```json { "statusCode": 400, "error": "Bad Request", "code": "SPECIFIC_ERROR_CODE", "message": "Human-readable description" } ``` version: '1.0' contact: name: SendPilot Support url: https://sendpilot.ai email: support@sendpilot.ai servers: - url: https://api.sendpilot.ai security: [] tags: [] paths: /v1/leads/{id}/status: patch: tags: - External API - Leads summary: Update lead status description: >- Update the status (OPPORTUNITY, MEETING_BOOKED, DONE, UNSUBSCRIBED, IRRELEVANT) and/or custom status of a lead operationId: leads.updateStatus parameters: - name: id required: true in: path description: Lead ID schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateLeadStatusDto' responses: '200': description: Lead status updated content: application/json: schema: $ref: '#/components/schemas/UpdateLeadResponseDto' '400': description: At least one of status or customLeadStatus is required '404': description: Lead not found security: - api-key: [] components: schemas: UpdateLeadStatusDto: type: object properties: status: type: string description: >- New status for the lead. Only outcome statuses can be set; statuses managed by the sequence engine are rejected. example: MEETING_BOOKED enum: - OPPORTUNITY - MEETING_BOOKED - DONE - UNSUBSCRIBED - IRRELEVANT customLeadStatus: type: string description: New custom lead status for CRM categorization example: INTERESTED enum: - LEAD - INTERESTED - MEETING_BOOKED - MEETING_COMPLETE_NOT_CLOSED - CLOSED - WRONG_PERSON - NOT_INTERESTED - NO_RESPONSE note: type: string description: Optional note/reason for status change example: Customer showed interest in demo maxLength: 1000 UpdateLeadResponseDto: type: object properties: success: type: boolean description: Success status example: true leadId: type: string description: Lead ID example: lead_123 status: type: string description: New status example: MEETING_BOOKED message: type: string description: Message required: - success - leadId - status - message securitySchemes: api-key: type: apiKey in: header name: X-API-Key description: 'API key for authentication (prefix: sp_live_ or sp_test_)' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.