---
title: "Upload Import File"
method: POST
path: "/imports"
tags: ["Imports"]
---

# Upload Import File

`POST /imports`

## Request

- Base URL: `https://be.graph8.com/api/v1`
- URL: `https://be.graph8.com/api/v1/imports`
- Auth: HTTP bearer

Upload a CSV or Excel file and get back its id and row count.

Nothing is imported by this call - the file is stored and parsed so it can
be previewed and then imported. The 25 MB ceiling is the app's, enforced by
reading one byte past it so an exact-boundary file is distinguishable from
an oversized one even when `Content-Length` is missing or dishonest.

The `row_count` that comes back is what the import pre-check budgets
against: it is treated as the upper bound on NEW contacts, so an import is
refused if that many would breach the org's limit, even though some rows
will resolve to updates.

## Headers

- `Authorization` string, nullable
- `X-Target-Org-Id` string, nullable

## Response `201`

Successful Response

- ApiResponseDataFileUploadResponse
  - `data` DataFileUploadResponse, required: The stored file, and how many rows it turned out to have. `row_count` is the number a caller should budget against: the import pre-check treats it as the UPPER BOUND on new contacts, so an import is refused if that many would breach the org's contact limit - even though some rows will resolve to updates rather than creates.
    - `datafile_id` string, nullable
    - `row_count` integer, nullable: Rows detected. The import pre-check budgets against this.
    - `columns` string[]: Detected column headers.
  - `pagination` PaginationMeta
    - `page` integer, required: Current page number (1-indexed)
    - `limit` integer, required: Items per page
    - `total` integer, required: Total number of items
    - `has_next` boolean, required: Whether there are more pages
    - `next_cursor` string, nullable: Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers.
    - `total_available` integer, nullable: Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search.
    - `total_is_lower_bound` boolean, nullable: Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search.
    - `notes` string[], nullable: Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/graph8/apis/graph8-developer-api.md) · [All operations](https://skmtc.dev/graph8/apis/graph8-developer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/graph8/apis/graph8-developer-api/revisions/2e7cfa0ca921?raw)