> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zixflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Import People

> Queue a people CSV import from a publicly reachable HTTPS URL

#### Description

Queues a people CSV import from a public HTTPS CSV URL.

Build `mapping` in the dashboard Import wizard (Users), then copy the JSON from Review. Attribute keys include system and custom fields for your workspace — do not invent them by hand. See [Get mapping from the dashboard](/api-reference/zixflow-ai/import/introduction#get-mapping-from-the-dashboard-recommended).

Also see [CSV Import Introduction](/api-reference/zixflow-ai/import/introduction) for auth, limits, and statuses.

#### Headers

<ParamField header="x-api-key" type="string" required placeholder="Enter your API key">
  Your API key for authentication. Must have **Dashboard** permission.
</ParamField>

<ParamField header="x-workspace-id" type="string" required placeholder="Enter your workspace ID">
  Your workspace ID for authentication. Must own the API key.
</ParamField>

<ParamField header="Content-Type" type="string" required default="application/json">
  Must be `application/json`.
</ParamField>

#### Body

<ParamField body="file_url" type="string" required placeholder="https://files.example.com/people.csv">
  Public HTTPS URL of the CSV. Must return raw CSV bytes (not an HTML share/preview page).
</ParamField>

<ParamField body="mapping" type="array" required>
  Column → attribute map copied from the dashboard. Each item needs `csv_column` and `attribute`. CSV column names and attribute keys must be unique (case-insensitive).

  <Expandable title="mapping[]" defaultOpen="true">
    <ParamField body="csv_column" type="string" required placeholder="Email">
      CSV header name. Must match the CSV header exactly.
    </ParamField>

    <ParamField body="attribute" type="string" required placeholder="email">
      Required attribute key for this column. Best obtained from the dashboard mapping JSON (system or custom).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="on_duplicate" type="string" default="update" placeholder="update">
  How to handle duplicates: `update` (default) or `skip`.
</ParamField>

<ParamField body="segment_id" type="string" placeholder="65f1a2b3c4d5e6f7a8b9c0d1">
  Optional 24-char ObjectId of a `manual_list_upload` segment. Imported people are added to that list.
</ParamField>

#### Request Example

```json theme={null}
{
  "file_url": "https://files.example.com/people.csv",
  "on_duplicate": "update",
  "segment_id": "65f1a2b3c4d5e6f7a8b9c0d1",
  "mapping": [
    { "csv_column": "user_id", "attribute": "user_id" },
    { "csv_column": "email", "attribute": "email" },
    { "csv_column": "phone", "attribute": "phone" }
  ]
}
```

Use the `mapping` array exported from the dashboard Review step for your file — do not rely on the sample keys above.

#### Response

<ResponseField name="success" type="boolean">
  Indicates whether the API call was successful.
</ResponseField>

<ResponseField name="message" type="string">
  Success or error message from the API.
</ResponseField>

<ResponseField name="data" type="object">
  Queued import details.
</ResponseField>

<ResponseField name="data.import_id" type="string">
  Unique import job ID. Use this to [poll status](/api-reference/zixflow-ai/import/people/get-status) or [cancel](/api-reference/zixflow-ai/import/people/cancel).
</ResponseField>

<ResponseField name="data.status" type="string">
  Initial job status. Typically `in-queue`.
</ResponseField>

<ResponseField name="data.segment_id" type="string">
  Present only when you sent `segment_id` in the request.
</ResponseField>

<ResponseExample>
  ```json 200-Success theme={null}
  {
    "success": true,
    "message": "Import queued. Processing will begin shortly.",
    "data": {
      "import_id": "68f0c1a2b3c4d5e6f7a8b9c0",
      "status": "in-queue",
      "segment_id": "65f1a2b3c4d5e6f7a8b9c0d1"
    }
  }
  ```

  ```json 400-Bad Request theme={null}
  {
    "success": false,
    "message": "mapping is required"
  }
  ```

  ```json 401-Unauthorized theme={null}
  {
    "error": true,
    "message": "Unauthorized"
  }
  ```

  ```json 403-Forbidden theme={null}
  {
    "error": true,
    "message": "Unauthorized"
  }
  ```

  ```json 404-Not Found theme={null}
  {
    "success": false,
    "message": "segment not found"
  }
  ```

  ```json 429-Too Many Requests theme={null}
  {
    "success": false,
    "message": "daily public API import limit reached (10 per day)"
  }
  ```

  ```json 503-Service Unavailable theme={null}
  {
    "success": false,
    "message": "message broker unavailable"
  }
  ```
</ResponseExample>

#### Typical 400 messages

`file_url is required` / `file_url must be a valid https url` / `mapping is required` / `mapping entries require csv_column and attribute` / `duplicate csv_column in mapping: …` / `duplicate attribute in mapping: …` / `unsupported mapping attribute for people: …` / `on_duplicate must be update or skip` / `invalid segment_id` / `segment must be of type manual_list_upload`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.