> ## 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. # Add leads > Add 1-100 leads to a campaign. Each is deduplicated by email within the campaign, provider-detected, and counts toward the monthly-imports quota. The response summarizes the outcome and returns the created leads. Requires one of the following scopes: `leads:write`, `leads:all`, `all:all`. ## OpenAPI ````yaml /openapi.json post /v1/campaigns/{cid}/leads 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: post: tags: - Leads summary: Add leads description: >- Add 1-100 leads to a campaign. Each is deduplicated by email within the campaign, provider-detected, and counts toward the monthly-imports quota. The response summarizes the outcome and returns the created leads. Requires one of the following scopes: `leads:write`, `leads:all`, `all:all`. operationId: campaignLeads_add parameters: - name: cid required: true in: path schema: type: string format: uuid example: a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60 - 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/AddLeadsApiDto' responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/AddLeadsApiResponseDto' '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 '402': description: A plan limit was reached - top up or upgrade. content: application/json: schema: $ref: '#/components/schemas/ApiErrorDto' example: error: type: invalid_request_error code: plan_limit_exceeded message: A plan limit was reached. status: 402 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: AddLeadsApiDto: type: object properties: leads: minItems: 1 maxItems: 100 description: >- Leads to add (1-100). Each is deduplicated by email within the campaign, provider-detected, and counts toward the monthly-imports quota. Send one element to add a single lead. type: array items: $ref: '#/components/schemas/LeadInputApiDto' required: - leads AddLeadsApiResponseDto: type: object properties: summary: $ref: '#/components/schemas/AddLeadsSummaryDto' leads: description: The leads that were created. type: array items: $ref: '#/components/schemas/LeadApiDto' required: - summary - leads ApiErrorDto: type: object properties: error: $ref: '#/components/schemas/ApiErrorBodyDto' required: - error LeadInputApiDto: type: object properties: email: type: string example: jane@acme.com maxLength: 254 description: >- Lead email. Only structural validation here (a non-empty string within the length cap) - a malformed address is NOT a request-level 400 but a non-fatal row counted in `summary.invalid`, so one bad address never rejects the whole batch. firstName: type: string example: Jane maxLength: 128 lastName: type: string example: Doe maxLength: 128 companyName: type: string example: Acme Inc maxLength: 256 jobTitle: type: string example: VP Sales maxLength: 128 website: type: string example: https://acme.com maxLength: 512 linkedinProfile: type: string example: https://linkedin.com/in/jane maxLength: 512 location: type: string example: New York, US maxLength: 128 tags: example: - vip - q4 type: array items: type: string customFields: type: object additionalProperties: true description: >- Custom fields - a flat map of string/number/boolean values. 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. example: industry: SaaS employees: 120 customFieldLabels: type: object additionalProperties: type: string description: >- Display labels for custom-field columns (canonical slug → label). Applied only when a field is first defined on the campaign. example: fund_manager: Fund Manager customFieldTypes: type: object additionalProperties: type: string description: >- Data types for custom-field columns (canonical slug → text | url | number | date | image). Applied only when first defined. example: logo_url: image required: - email AddLeadsSummaryDto: type: object properties: submitted: type: number example: 3 description: Leads submitted in the request. created: type: number example: 2 description: New leads created. duplicates: type: number example: 1 description: Skipped as duplicates (already in the campaign). invalid: type: number example: 0 description: Rejected (invalid or unprocessable). required: - submitted - created - duplicates - invalid 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 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 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 securitySchemes: ApiKey: scheme: bearer bearerFormat: mb_live_… type: http ```` ## Related topics - [Leads](/leads.md) - [Bulk mutate leads](/api-reference/leads/bulk-mutate-leads.md) - [Workspace & Usage](/workspace.md) - [Subscription](/api-reference/workspace/subscription.md) - [Emails](/emails.md)