---
title: "Import items in bulk"
method: POST
path: "/v1/imports"
tags: ["Imports"]
---

# Import items in bulk

`POST /v1/imports`

This endpoint lets you upload a CSV file containing people, events, objects, or relationships. It provides a handy way of adding and updating them in bulk. Uploading people, objects, or relationships is like performing an [`identify` call](/integrations/api/track/tag/track_v2/entity/) for each row in your CSV; uploading events is like performing a [`track` call](/integrations/api/track/tag/track-events/track/).

You'll need to provide us the public URL of your CSV as a part of this operation. We recommend that you host your CSVs from short-lived URLs. Ideally, your URLs will expire 2 hours after you initiate an import so that your customers' information doesn't remain publicly available after you've uploaded it to us.

Check out the CSV requirements based on what you're importing: [people](/journeys/people/uploading-people/#csv-requirements), [events](/journeys/people/uploading-people/#event-csv-requirements), and [objects or relationships](/journeys/objects-data/objects/import-objects/#csv-requirements).

This endpoint performs some basic validation on the request and then queues the import for processing. The import happens in multiple stages after your request, and may even fail. You'll need to [lookup the status of the import](/integrations/api/app/tag/imports/getImport/) to check on its progress.

Records in your CSV might result in errors or warnings during the import. We make the errors and warnings available in CSV files that you can download via our export endpoints. [Lookup your import](/integrations/api/app/tag/imports/getImport/) to get download URLs for error and warning reports.

## Request body

- object
  - `import` union, required
    - object — Contains your import parameters.
      - `name` string, required — A friendly name for your import. This helps you identify your import.
      - `data_file_url` string, required — The URL or path to the CSV file you want to import.
      - `type` 'people', required — The type of import.
      - `identifier` 'id' | 'email', required — The type of identifier you want to use to identify people in your sheet—`id` or `email`. At least one column in the CSV must contain an identifier.
      - `data_to_process` 'all' | 'only_new' | 'only_existing' — Controls whether your import adds and updates all rows, adds only new rows, or updates only existing rows. Defaults to `all`. Event imports support only `all` and `only_existing`. Formerly called `people_to_process`.
      - `description` string — A helpful description that can help you find and recognize your import operation.
    - object — Contains your import parameters.
      - `name` string, required — A friendly name for your import. This helps you identify your import.
      - `data_file_url` string, required — The URL or path to the CSV file you want to import.
      - `type` 'event', required — The type of import.
      - `identifier` 'id' | 'email', required — The type of identifier you want to use to identify people in your sheet—`id` or `email`. At least one column in the CSV must contain an identifier.
      - `data_to_process` 'all' | 'only_new' | 'only_existing' — Controls whether your import adds and updates all rows, adds only new rows, or updates only existing rows. Defaults to `all`. Event imports support only `all` and `only_existing`. Formerly called `people_to_process`.
      - `description` string — A helpful description that can help you find and recognize your import operation.
    - object — Contains your import parameters.
      - `name` string, required — A friendly name for your import. This helps you identify your import.
      - `data_file_url` string, required — The URL or path to the CSV file you want to import.
      - `type` 'relationship', required — The type of import.
      - `identifier` 'id' | 'email' | 'cio_id', required — The type of identifier used to identify the person in each relationship—`id`, `email`, or `cio_id`.
      - `data_to_process` 'all' | 'only_new' | 'only_existing' — Controls whether your import adds and updates all rows, adds only new rows, or updates only existing rows. Defaults to `all`. Event imports support only `all` and `only_existing`. Formerly called `people_to_process`.
      - `description` string — A helpful description that can help you find and recognize your import operation.
    - object — Contains your import parameters.
      - `name` string, required — A friendly name for your import. This helps you identify your import.
      - `data_file_url` string, required — The URL or path to the CSV file you want to import.
      - `object_type_id` string, required — The object type an object belongs to—like "Companies" or "Accounts". Object type IDs are string-formatted integers that begin at `1` and increment for each new type.
      - `type` 'object', required — The type of import.
      - `data_to_process` 'all' | 'only_new' | 'only_existing' — Controls whether your import adds and updates all rows, adds only new rows, or updates only existing rows. Defaults to `all`. Event imports support only `all` and `only_existing`. Formerly called `people_to_process`.
      - `description` string — A helpful description that can help you find and recognize your import operation.

## Response `200`

Returns an import payload.

- object
  - `import` ImportObject, required — Represents an import operation.
    - `id` integer — This is the `import_id` you'll use if you want to [lookup your import operation](/integrations/api/app/tag/imports/getImport/).
    - `created_at` integer — The date time when the referenced ID was created.
    - `updated_at` integer — The date time when the referenced ID was last updated.
    - `name` string — A friendly name for your import. This helps you identify your import.
    - `description` string — A helpful description that can help you find and recognize your import operation.
    - `rows_to_import` integer — The total number of importable rows we found in the CSV.
    - `rows_imported` integer — The number of rows we imported from the CSV.
    - `state` 'preprocessing' | 'preprocessed' | 'validating' | 'validated' | 'importing' | 'imported' | 'failed' | 'canceled' — The state of the import—whether your import is being processed, fully completed (`imported`), or if it failed.
    - `type` 'people' | 'event' | 'object' | 'relationship' — The type of import.
    - `identifier` 'id' | 'email' — The type of identifier you used to identify people in your CSV. Not applicable for object imports.
    - `data_to_process` 'all' | 'only_new' | 'only_existing' — Controls whether your import adds and updates all rows, adds only new rows, or updates only existing rows. Defaults to `all`. Event imports support only `all` and `only_existing`. Formerly called `people_to_process`.
    - `people_to_process` 'all' | 'only_new' | 'only_existing' — Returned for people and event imports, even if you imported using the field `data_to_process`. This field will be deprecated soon.
    - `object_type_id` string — The object type an object belongs to—like "Companies" or "Accounts". Only applies to object imports.
    - `error` string — If your import fails, this helps you understand why.

## Other responses

- `429` — Your request is over the 10-per-second limit.

---

[API](https://skmtc.dev/customer/apis/customer-io-journeys-api-reference.md) · [All operations](https://skmtc.dev/customer/apis/customer-io-journeys-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/customer/customer-io-journeys-api-reference/revisions/4b391af7cb06/schema)