---
title: "Run a Records Metadata Import"
method: POST
path: "/records/metadata-import/{importId}/run"
tags: ["Records"]
---

# Run a Records Metadata Import

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

## Request

- Base URL: `https://ironcladapp.com/public/api/v1`
- URL: `https://ironcladapp.com/public/api/v1/records/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.records.runMetadataImports`

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

**OAuth Scope required:** `public.records.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
  - `matchMethod` 'UPSERT' | 'INSERT_OR_ERROR' | 'INSERT_ONLY' | 'UPDATE_OR_ERROR' | 'UPDATE_ONLY': How should we match your data to Ironclad records? * `UPSERT` (recommended): For rows without a matching record create a new record, and for rows with a matching record update that record. * `INSERT_OR_ERROR`: For rows without a matching record create a new record, but prevent import if there are any matching records. * `INSERT_ONLY`: For rows without a matching record create a new record, but ignore rows with a matching record. * `UPDATE_OR_ERROR`: Update rows with a matching record, but prevent the import if there are any rows that don't have a matching record. * `UPDATE_ONLY`: Update rows with a matching record, but ignore rows with no matching record.
  - `errorHandling` 'ERROR' | 'IGNORE': How should we handle rows with errors? * `ERROR` (Don't allow errors, recommended): Prevent import if there are any rows with errors in the file. * `IGNORE`: Ignore rows with errors, and import all other rows.

## 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/records/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)