---
title: "Run an Entities Metadata Import"
method: POST
path: "/entities/metadata-import/{importId}/run"
tags: ["Entities"]
---

# Run an Entities Metadata Import

`POST /entities/metadata-import/{importId}/run`

## Request

- Base URL: `https://ironcladapp.com/public/api/v1`
- URL: `https://ironcladapp.com/public/api/v1/entities/metadata-import/{importId}/run`
- Auth: API key in header `Authorization` and OAuth 2
  - Authorization code: `https://ironcladapp.com/oauth/authorize`
  - Client credentials
  - Token URL: `https://ironcladapp.com/oauth/token` scopes: `public.entities.runMetadataImports`

Run a staged entities metadata import by ID. Each column in the import file must correspond exactly (case-sensitive) to either an entity property ID or one of the following system column names: `system_id`, `system_name`, `system_status`, `system_parentId`, `system_relationshipTypeName`. Columns that do not match a known property or system column will cause a 400 error.

The following entity properties will use default values when not provided in the import file:
* `system_status`: defaults to `ACTIVE`
* `entity_category`: defaults to `external`
* `entity_businessType`: defaults to `company`

**OAuth Scope required:** `public.entities.runMetadataImports`

## Path parameters

- `importId` string, uuid, required

## Headers

- `x-as-user-email` string
- `x-as-user-id` string

## Request body

- object
  - `matchRecordsOn` 'id' | 'name' | 'originalFilename' | 'CREATE_ALL_NEW', required: The property to match records on. * `id`: match on record ID * `name`: match on record name * `originalFilename`: match on the original filename * `CREATE_ALL_NEW`: create a new record for every row

## Response `200`

200

- object
  - `importId` string, uuid, required
  - `status` 'NEW' | 'STAGING' | 'STAGED' | 'IMPORTING' | 'INDEXING' | 'IMPORTED' | 'ERROR', required

## Other responses

- `400`: 400
- `404`: 404
- `409`: 409

## Changes

- **2026-11-03** `435da5a4396e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ironcladapp/apis/ironclad-public-api/changes/entities/metadata-import/:importId/run/post.md)

---

[API](https://skmtc.dev/ironcladapp/apis/ironclad-public-api.md) - [All operations](https://skmtc.dev/ironcladapp/apis/ironclad-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ironcladapp/apis/ironclad-public-api/revisions/435da5a4396e?raw)