Skip to main content
Talk to salesStart

Import companies from CSV

Upload a CSV and map its columns to company fields.

POST/api/companies/import
HTTP referenceScope companies:write (organization admin)Updated September 27, 2026

This page documents the canonical HTTP contract for this endpoint.

The route requires an authenticated user with user-admin permission and companies:write. Mapping values are multipart form fields containing JSON objects; core mappings map Company target fields to a CSV header alias or list of aliases. use_async defaults true; when false, the request is processed inline and returns a completion object instead of a queued task receipt. Poll the returned task ID only for asynchronous admission.

Body parameters

  • filerequired

    file

    CSV file uploaded as multipart/form-data.

  • source_label · optional

    string

    Optional source label.

  • core_field_mappings · optional

    JSON object

    Multipart form field containing JSON: target core field -> source CSV header alias or alias list, e.g. {"name":["Company Name"],"domain":"Website"}.

  • custom_field_mappings · optional

    JSON object

    Multipart form field containing JSON: custom-field key -> source CSV header alias or alias list.

  • custom_field_static_values · optional

    JSON object

    Optional fixed custom-field values applied to imported records.

  • use_async · optional

    boolean

    Use background processing; default true.

  • null_policy · optional

    string

    CSV null handling: common (default; blanks and common null tokens become empty) or preserve (literal tokens are retained).

Errors

StatusMeaning
400Malformed JSON mapping form field or invalid null_policy.
401Authentication and organization/user context required.
403Missing companies:write scope or user-admin permission.
503CSV storage or background-job admission failed.

Docs