> ## 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. # Add Leads > Import 1–1,000 profiles into an existing campaign, with duplicate and validation results. Requires `leads:write`, plus `inbox:send` when importing into a running campaign. The REST limit is **1–1,000 leads per request**. MCP `add_leads` has separate 500-lead draft and 50-lead approval limits; those are not the REST limit. Only `linkedinUrl` is required on each lead. Existing campaign duplicates are skipped; inspect `leadsAdded`, `duplicatesSkipped`, `invalidEntries` and any per-entry errors in the response. ## Dynamic/custom fields REST accepts custom fields as **flat properties** beside `linkedinUrl`, such as `industry` or `icebreaker`. MCP instead uses the nested `custom_fields` argument. Keep the interfaces distinct. ```json theme={null} { "campaignId": "CAMPAIGN_ID", "leads": [{ "linkedinUrl": "https://www.linkedin.com/in/PROFILE_ID", "firstName": "Alex", "company": "Example company", "icebreaker": "We met at the conference" }] } ``` This REST request imports immediately when accepted. Campaign state determines subsequent outreach; use the dashboard to review the sequence. Send an [Idempotency-Key](https://docs.sendler.ai/api-reference/behavior.md#idempotent-writes) when retrying an import. ## OpenAPI ````yaml POST /v1/leads 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: post: tags: - External API - Leads summary: Add leads to campaign description: >- Adds multiple leads to an existing campaign. Duplicates are automatically skipped. operationId: leads.add parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AddLeadsToCampaignDto' responses: '201': description: Leads added successfully content: application/json: schema: $ref: '#/components/schemas/AddLeadsResponseDto' '400': description: Invalid request data '404': description: Campaign not found security: - api-key: [] components: schemas: AddLeadsToCampaignDto: type: object properties: campaignId: type: string description: Campaign ID to add leads to example: cmobr5lei0000u1h02ezf5itt leads: type: array description: >- Array of leads (1 to 1000 per request) - only linkedinUrl required, all other fields are dynamic minItems: 1 maxItems: 1000 items: type: object properties: linkedinUrl: type: string example: https://www.linkedin.com/in/johndoe/ firstName: type: string example: John lastName: type: string example: Doe company: type: string example: Acme Corp title: type: string example: VP of Engineering email: type: string example: john@example.com additionalProperties: true required: - linkedinUrl example: - linkedinUrl: https://www.linkedin.com/in/johndoe/ firstName: John lastName: Doe company: Acme Corp title: VP of Engineering industry: SaaS region: EMEA required: - campaignId - leads AddLeadsResponseDto: type: object properties: success: type: boolean description: Success status example: true leadsAdded: type: number description: Number of leads added example: 10 duplicatesSkipped: type: number description: Number of duplicates skipped example: 2 invalidEntries: type: number description: Number of invalid entries example: 0 errors: description: Details of any errors type: array items: type: object required: - success - leadsAdded - duplicatesSkipped - invalidEntries 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.