> ## Documentation Index > Fetch the complete documentation index at: https://docs.manypi.com/llms.txt > Use this file to discover all available pages before exploring further. # Import leads > Write a batch of leads. **Up to 100 rows per request** — chunk larger files client-side so a big import cannot outlive the request timeout and so progress is real. `declare_fields` lets the same request that carries the first chunk also declare the custom columns those rows write into. It is idempotent, so resending the declarations with every chunk is harmless. A full workspace still returns `200` — the rows that fitted were written — with `code: "lead_limit"` in the body. Requires the `write` permission. ## OpenAPI ````yaml POST /api/leads/import openapi: 3.1.0 info: title: ManyPI API description: >- The REST API behind ManyPI — AI lead generation, email validation, cold-email outreach, agent runs and web scraping. Every endpoint is authenticated with a ManyPI API key (`mpi_...`) or an OAuth 2.1 access token, and honours the permissions granted to that credential. version: 2.0.0 contact: name: ManyPI Support email: support@manypi.com url: https://manypi.com servers: - url: https://app.manypi.com description: Production security: - bearerAuth: [] tags: - name: Leads description: Find, store, enrich and manage leads. - name: Email validation description: Verify that lead addresses can receive mail. - name: Outreach description: Inboxes, sequences, campaigns, sending and replies. - name: Agent description: Agent runs, replies and skills. - name: Scraping description: Scrapers, runs and extracted data. - name: Endpoints description: Publish scrapers as typed REST endpoints. - name: Account description: Key validation and account information. paths: /api/leads/import: post: tags: - Leads summary: Import leads description: >- Write a batch of leads. **Up to 100 rows per request** — chunk larger files client-side so a big import cannot outlive the request timeout and so progress is real. `declare_fields` lets the same request that carries the first chunk also declare the custom columns those rows write into. It is idempotent, so resending the declarations with every chunk is harmless. A full workspace still returns `200` — the rows that fitted were written — with `code: "lead_limit"` in the body. Requires the `write` permission. operationId: importLeads requestBody: required: true content: application/json: schema: type: object required: - rows properties: rows: type: array minItems: 1 maxItems: 100 items: $ref: '#/components/schemas/ImportRow' duplicates: type: string enum: - merge - overwrite - skip default: merge description: >- `merge` fills blanks on the existing lead; `overwrite` lets incoming values win; `skip` leaves it untouched. declare_fields: type: array maxItems: 60 items: $ref: '#/components/schemas/LeadFieldInput' example: duplicates: merge declare_fields: - label: Ecommerce platform type: text rows: - company: Acme GmbH full_name: Lena Roth title: Head of Growth email: lena@acme.de domain: acme.de custom: ecommerce_platform: Shopify responses: '200': description: Per-row outcome for the chunk. content: application/json: schema: type: object properties: created: type: integer updated: type: integer skippedDuplicate: type: integer skippedNoIdentity: type: integer description: >- No email and no domain-plus-name, so there is nothing to file the row under. skippedOverLimit: type: integer skippedOtherWorkspace: type: integer failed: type: array items: type: object properties: index: type: integer error: type: string remaining: type: integer nullable: true description: Lead slots left after this batch. declared: type: array items: type: string code: type: string description: '`lead_limit` when the plan filled up mid-import.' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' components: schemas: ImportRow: type: object description: >- A lead needs an email, or a domain plus a name, or it cannot be filed and is skipped. properties: company: type: string maxLength: 300 full_name: type: string maxLength: 200 title: type: string maxLength: 200 email: type: string maxLength: 320 phone: type: string maxLength: 60 domain: type: string maxLength: 300 linkedin_url: type: string maxLength: 500 location: type: string maxLength: 200 source_url: type: string maxLength: 1000 score: type: integer minimum: 0 maximum: 100 nullable: true status: type: string enum: - new - qualified - contacted - disqualified nullable: true custom: type: object description: Keys must match declared columns, or the values are dropped. LeadFieldInput: type: object required: - label properties: label: type: string maxLength: 60 key: type: string maxLength: 40 description: Derived from the label when absent. type: type: string default: text options: type: array maxItems: 50 items: type: string description: type: string maxLength: 500 nullable: true auto_research: type: boolean default: false Error: type: object properties: error: type: string description: Human-readable message. code: type: string description: >- A machine-readable code on gated failures: `lead_limit`, `outreach_locked`, `validation_credits_exhausted`. responses: BadRequest: description: The request body or parameters failed validation. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: >- Missing, invalid or expired credential — or a key that lacks the permission this route requires. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer description: >- A ManyPI API key (`mpi_...`) from Settings → API keys, or an OAuth 2.1 access token obtained through the MCP consent flow. ````