---
title: "Import entity records from CSV"
method: POST
path: "/api/apps/{app_id}/entities/{entity_name}/import"
---

# Import entity records from CSV

`POST /api/apps/{app_id}/entities/{entity_name}/import`

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Creates records in one of the app's entities from a CSV file, and returns the records it created.

Send the file as `multipart/form-data` in a field named `file`. The first row has to be a header row with no blank or repeated column names. Commas, semicolons, and tabs all work as the delimiter, and the file can be up to 10 MB.

Base44 pairs each of the entity's fields with the column of the same name, ignoring case, spaces, and punctuation. For any field it can't pair by name, an AI model picks a matching column or leaves the field out. Columns that match no field are ignored, and every required field needs a column.

The import is all or nothing. Every row is checked against the entity's schema before anything is written, and if one row fails, no records are created. A file Base44 can't import still returns a successful response, with `status` set to `error` and the reason in `details`, so read `status` before `output`.

Each row becomes a new record, so importing the same file twice creates every record twice. Row-level security applies, so the whole call is rejected when the entity's `rls` create rule doesn't cover one of the rows. Imported records don't trigger the app's webhooks, automations, or workflows.

<Note>This endpoint accepts a personal API key belonging to a user with access to the app. A read-only key is refused, and workspace API keys are not accepted.</Note>

## Path parameters

- `app_id` string, required — ID of the app that owns the entity.
- `entity_name` string, required — Name of the entity, exactly as [List entity schemas](/api-reference/list-entity-schemas) reports it. Don't pass `User` here. It doesn't fail, but it reads and writes a separate, disconnected set of records stored under that name, not the app's real user accounts, which are managed through their own endpoints.

## Response `200`

The import's outcome, including when the file couldn't be imported.

- object — The outcome of a CSV import.
  - `status` 'success' | 'error', required — Whether the import went through. Either `"success"` or `"error"`. On `error` no records were created.
  - `details` string, nullable, required — What happened, in plain language. On `error` it says why the file couldn't be imported, for example a required field no column matched.
  - `output` object[], nullable, required — The records the import created, in the same shape as [List entity records](/api-reference/list-entity-records) returns them, or `null` when `status` is `error`.
    - `id` string, nullable — ID of the record. Pass it as `entity_id` to [Get entity record](/api-reference/get-entity-record), [Update entity record](/api-reference/update-entity-record) or [Delete entity record](/api-reference/delete-entity-record).
    - `created_date` string, nullable — When the record was created, as a UTC timestamp in ISO 8601 format. A record Base44 has just created carries a `Z` suffix, and a record read back from storage does not.
    - `updated_date` string, nullable — When the record last changed, as a UTC timestamp in ISO 8601 format. A record Base44 has just created carries a `Z` suffix, and a record read back from storage does not.
    - `created_by` string, nullable — Email of the app user who created the record, or `anonymous` when a visitor created it on an app that needs no login. Apps that hide record authorship leave this field out of the response.
    - `created_by_id` string, nullable — ID of the app user who created the record, or `anonymous` when a visitor created it on an app that needs no login.
    - `is_sample` boolean, nullable — Whether Base44 stored the record as sample data while the app was being built. A record you create reports `false`.

## Other responses

- `400` — The file is over 10 MB, or on some apps a value is over 20,000 characters.
- `401` — Missing or invalid credentials.
- `403` — You don't have access to this app, the entity's `rls` create rule doesn't cover one of the rows, or your API key is read-only.
- `404` — App not found, or the app has no entity with this name.
- `405` — The entity is `User`, whose records can't be imported.
- `422` — The request has no `file` field.
- `429` — Rate limit exceeded. The base limit is 20 requests per minute. See [Rate limits](/developers/references/apps-api/get-started/rate-limits) for the multiplier your plan gets.

## Changes

- **2026-09-29** `347e2afcf94a` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/idealspot/apis/base44-app-management-api/changes/api/apps/:app_id/entities/:entity_name/import/post.md)

---

[API](https://skmtc.dev/idealspot/apis/base44-app-management-api.md) · [All operations](https://skmtc.dev/idealspot/apis/base44-app-management-api/llms.txt) · [OpenAPI document](https://skmtc.dev/idealspot/apis/base44-app-management-api/revisions/e2a6a9f1fe4c?raw)