Skip to main content
Talk to salesStart

Import leads from CSV

Import organization-scoped leads from CSV with reviewed field mappings.

POST/api/leads/import
HTTP referenceScope leads:writeUpdated September 27, 2026

This page documents the canonical HTTP contract for this endpoint.

The HTTP request is multipart form data. JSON-valued form parts must parse as an array/object as indicated. Headers must be unique and nonblank. Explicit mappings must reference actual CSV headers and supported standard lead fields; multiple sources may target email_addresses or phone_numbers, but other targets must be unique. Invalid or unusable mappings fail instead of silently importing unmapped rows.

Files with fewer than 100 rows are processed inline and return summary, crm_source, leads_created, and csv_nulls. Larger files return an asynchronous admission receipt, shown in the response example. Only poll when a task identifier is returned; admission is not proof of completed import. Poll the returned task identifier with Get lead import status.

Body parameters

  • filerequired

    file (multipart/form-data)

  • check_company_blacklist · optional

    boolean

    Defaults true.

  • check_email_blacklist · optional

    boolean

    Defaults true.

  • mappings · optional

    string (JSON array)

    Entries use csv_column (an existing header) and standard_field (a supported lead target, such as email_addresses). Omit to infer mappings; explicit mappings bypass inference.

  • default_values · optional

    string (JSON object)

  • custom_field_static_values · optional

    string (JSON object)

  • null_policy · optional

    string

    common or preserve; defaults to common.

Errors

StatusMeaning
400Invalid form JSON, duplicate/blank CSV headers, invalid or conflicting mappings, no usable mappings, or mapping application failure.
401Missing authentication or organization/user context.
403Missing leads:write scope.
422Invalid multipart form field.
503Asynchronous upload storage or import admission unavailable.

Docs