> ## Documentation Index > Fetch the complete documentation index at: https://developer.instantly.ai/llms.txt > Use this file to discover all available pages before exploring further. # Add leads in bulk to a campaign or list > Adds up to 1000 leads to either a campaign or a list. You must provide a `campaign_id` or a `list_id`, but not both. The endpoint validates emails, checks against blocklists and existing leads. Requires one of the following scopes: `leads:create`, `leads:all`, `all:create`, `all:all` ## OpenAPI ````yaml https://api.instantly.ai/openapi/api_v2.json post /api/v2/leads/add openapi: 3.1.0 info: title: API Explorer description: >- The entire API V2 documentation is interactive and can be tested here. To the right side of every endpoint you will see a box with an example request. You can click on the "Try it" button to send a request to the server right from the docs. You will need to provide an API key by clicking the `ApiKeyAuth_token` blue text. version: 2.0.0 servers: - url: https://api.instantly.ai description: Instantly API Server security: - ApiKeyAuth: [] tags: - name: Analytics description: Endpoints related to analytics x-displayName: Analytics - name: OAuth description: >- OAuth authentication endpoints for connecting Google and Microsoft email accounts x-displayName: OAuth - name: Account description: An email account that can be used to send campaigns x-displayName: Account - name: Campaign description: A campaign that can be sent to a list of recipients x-displayName: Campaign - name: Email description: >- A campaign email, a reply, a manually sent email, or any other email that's visible in the Unibox x-displayName: Email - name: EmailVerification description: A single email verification x-displayName: Email Verification - name: LeadList description: A list used to store leads x-displayName: Lead List - name: InboxPlacementTest description: An inbox placement test x-displayName: Inbox Placement Test - name: InboxPlacementAnalytics description: Analytics data for individual emails in inbox placement tests x-displayName: Inbox Placement Analytics - name: InboxPlacementBlacklist&SpamAssassinReport description: Report data for an inbox placement test x-displayName: Inbox Placement Blacklist & SpamAssassin Report - name: APIKey description: API Key x-displayName: API Key - name: AccountCampaignMapping description: Account Campaign Mapping x-displayName: Account Campaign Mapping - name: Lead description: A lead entity representing an individual lead x-displayName: Lead - name: BackgroundJob description: A background job that can be used to perform long-running tasks x-displayName: Background Job - name: CustomTag description: >- A custom tag for organizing and categorizing accounts and campaigns. You can use them as filters in apis that list accounts and campaigns. x-displayName: Custom Tag - name: CustomTagMapping description: >- This entity represents a tag being assigned to a specific campaign or email account. When an email account is assigned a tag, a new custom tag mapping entry is created, which connects the tag (`tag_id` field) with the email account (`resource_id` field). You can use it to see which tag si connected to which resource. x-displayName: Custom Tag Mapping - name: BlockListEntry description: A blocked email or domain x-displayName: Block List Entry - name: LeadLabel description: A custom label for categorizing and managing leads x-displayName: Lead Label - name: Workspace description: A workspace entity representing a workspace x-displayName: Workspace - name: SuperSearchEnrichment description: >- An enrichment can take different forms, such as email enrichment or LinkedIn enrichment. Leads may be imported from SuperSearch using the dedicated endpoint, or enriched directly within a list or campaign by attaching an enrichment to it. x-displayName: SuperSearch Enrichment - name: WorkspaceGroupMember description: >- A member of a workspace group. You can use the endpoints within this entity to manage the members of a workspace group. x-displayName: Workspace Group Member - name: WorkspaceMember description: A member of a workspace with associated user details x-displayName: Workspace Member - name: CampaignSubsequence description: A subsequence entity representing a follow-up sequence x-displayName: Campaign Subsequence - name: AuditLog description: Audit log records for tracking system activities x-displayName: Audit Log - name: Webhook description: A webhook subscription for receiving event notifications x-displayName: Webhook - name: WebhookEvent description: A webhook event that was sent or attempted to be sent x-displayName: Webhook Event - name: DFYEmailAccountOrder description: A Done-For-You email account order x-displayName: DFY Email Account Order - name: CustomPromptTemplate description: Custom prompt templates for creating custom prompts x-displayName: Custom Prompt Template - name: SalesFlow description: >- Manages how sales users view and interact with campaign and lead lists within the sales flow. x-displayName: Sales Flow - name: EmailTemplate description: A campaign email template x-displayName: Email Template - name: WorkspaceBilling description: Workspace Billing x-displayName: Workspace Billing - name: CRMActions description: CRM related actions x-displayName: CRM Actions paths: /api/v2/leads/add: post: tags: - Lead summary: Add leads in bulk to a campaign or list description: >- Adds up to 1000 leads to either a campaign or a list. You must provide a `campaign_id` or a `list_id`, but not both. The endpoint validates emails, checks against blocklists and existing leads. Requires one of the following scopes: `leads:create`, `leads:all`, `all:create`, `all:all` operationId: bulkAddLeads requestBody: content: application/json: schema: type: object properties: campaign_id: type: string format: uuid description: >- The unique identifier for the campaign to add leads to. Use this field OR `list_id`, but not both. example: 019e0e3e-b690-71a9-b399-fbf49894dded list_id: type: string format: uuid description: >- The unique identifier for the list to add leads to. Use this field OR `campaign_id`, but not both. example: 019e0e3e-b690-71a9-b399-fbf55d2134c0 leads: type: array minItems: 1 maxItems: 1000 description: >- An array of lead objects to create. When using `campaign_id`: Each lead object must contain an `email`. When using `list_id` Each lead object must contain at least one of the following: `email`, `first_name`, or `last_name`. items: type: object properties: email: type: - string - 'null' description: Email address of the lead example: example@example.com personalization: type: - string - 'null' description: Personalization of the lead example: Hello, how are you? website: type: - string - 'null' description: Website of the lead example: https://example.com last_name: type: - string - 'null' description: Last name of the lead example: Doe first_name: type: - string - 'null' description: First name of the lead example: John company_name: type: - string - 'null' description: Company name of the lead example: Example Inc. job_title: type: - string - 'null' description: Job title of the lead example: Head of Growth phone: type: - string - 'null' description: Phone number of the lead example: '+1234567890' lt_interest_status: type: number description: >- Lead interest status. It can be either a static value (check below), or a custom status interest value enum: - 1 - 2 - 3 - 4 - 0 - -1 - -2 - -3 - -4 x-enumDescriptions: '0': Out of Office '1': Interested '2': Meeting Booked '3': Meeting Completed '4': Won '-1': Not Interested '-2': Wrong Person '-3': Lost '-4': No Show example: 1 pl_value_lead: type: - string - 'null' description: Potential value of the lead example: High assigned_to: type: - string - 'null' description: ID of the user assigned to the lead format: uuid example: 019e0e3e-599d-7e0a-961f-546be24be171 custom_variables: type: object additionalProperties: type: - string - number - boolean - 'null' description: >- Custom variables can include any metadata about the lead that is relevant to the campaign, the campaign will be updated to allow all the other leads in the campaign to have the same custom variables. The custom variables will be added to the lead payload field example: past_customer: true has_tried_competitors: false required: [] additionalProperties: false blocklist_id: type: - string - 'null' format: uuid description: >- Optional blocklist ID to check leads against. If omitted, the workspace default blocklist is used. example: 019e0e3e-b690-71a9-b399-fbf6624eaaad assigned_to: type: string format: uuid description: >- Optional user ID to assign all imported leads to. If omitted, leads are assigned to the campaign owner when `campaign_id` is defined, or the user making the request. example: 019e0e3e-b690-71a9-b399-fbf7e91525db verify_leads_on_import: type: boolean description: >- If true, a background job will be created to verify the email addresses of the imported leads. example: false skip_if_in_workspace: type: boolean description: >- If true, any lead that already exists anywhere in your workspace (in any campaign or list) will be skipped. This option overrides the other "skip_if" flags. example: true skip_if_in_campaign: type: boolean description: >- If true, any lead that already exists in ANY campaign in your workspace will be skipped. example: false skip_if_in_list: type: boolean description: >- If true, any lead that already exists in ANY list in your workspace will be skipped. example: false required: - leads required: true responses: '200': description: A summary of the bulk import operation. content: application/json: schema: description: A summary of the bulk import operation. type: object properties: status: type: string description: Indicates the request was processed. example: success total_sent: type: integer description: The total number of leads included in the request payload. example: 10 leads_uploaded: type: integer description: The number of leads that were successfully created. example: 7 in_blocklist: type: integer description: >- The number of leads that were skipped because their email was found on the blocklist. example: 1 blocklist_used: type: - 'null' - string description: The ID of the blocklist that was used for the check. example: 019e0e3e-b690-71a9-b399-fbf87a5a78ed duplicated_leads: type: integer description: >- The number of leads that were already in this specific campaign or list and were not re-added. example: 0 skipped_count: type: integer description: >- The number of leads skipped due to the `skip_if_in_...` flags being enabled. example: 1 invalid_email_count: type: integer description: >- The number of leads skipped due to an invalid email format or a missing email address. example: 1 incomplete_count: type: integer description: >- The number of leads skipped due to missing email and names. Only calculated for lists. example: 1 duplicate_email_count: type: integer description: >- The number of leads skipped because their email was duplicated within the request payload itself. example: 0 remaining_in_plan: type: - 'null' - integer description: >- The remaining lead uploads in the current billing plan. This value is only present in the response when a `campaign_id` is provided. example: 9993 created_leads: type: array description: >- A list of created leads with their summary information. You can use this to map your input to the created leads. items: type: object properties: index: type: integer description: >- The index of the lead in the input array. For leads that have no email address you can use this field as the key to your input leads. example: 0 id: type: string format: uuid description: >- The ID of the lead. Use it for GET, DELETE or PATCH operations. example: 019e0e3e-b690-71a9-b399-fbf98bda4f7c email: type: - 'null' - string example: test@example.com first_name: type: - 'null' - string example: John last_name: type: - 'null' - string example: Doe phone: type: - 'null' - string example: '+1234567890' required: - id - index example: id: 019e0e3e-b690-71a9-b399-fbfa05ff37fb email: test@example.com index: 0 example: - id: 019e0e3e-b690-71a9-b399-fbfbc546f941 email: test@example.com index: 0 required: - status - total_sent - leads_uploaded - in_blocklist - blocklist_used - duplicated_leads - skipped_count - invalid_email_count - incomplete_count - duplicate_email_count - remaining_in_plan - created_leads '401': description: >- This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked) content: application/json: schema: type: object properties: statusCode: type: number enum: - 401 example: 401 error: type: string enum: - Unauthorized example: Unauthorized message: type: string example: Missing Authorization header required: - statusCode - error - message '402': description: >- This request cannot be fulfilled because the workspace does not have an active paid plan content: application/json: schema: type: object properties: statusCode: type: number enum: - 402 example: 402 error: type: string enum: - Payment Required example: Payment Required message: type: string example: Workspace does not have an active paid plan required: - statusCode - error - message '404': description: The requested resource was not found content: application/json: schema: type: object properties: statusCode: type: number enum: - 404 example: 404 error: type: string enum: - Not Found example: Not Found message: type: string example: Resource not found required: - statusCode - error - message '429': description: >- You have exceeded the rate limit. Please check the rate limit docs for more information. content: application/json: schema: type: object properties: statusCode: type: number enum: - 429 example: 429 error: type: string enum: - Too Many Requests example: Too Many Requests message: type: string example: Rate limit exceeded required: - statusCode - error - message components: securitySchemes: ApiKeyAuth: type: http scheme: bearer ````