IRironcladapp
Records

Run a Records Metadata Import

Changed on

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

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

Path parameters

importIdstring uuid required

The import ID. This is used to identify a specific staged import.

Headers

x-as-user-emailstring
Example:jane.doe@test.com

Denotes the actor of the request. When used, the API will take into account this user's permissions and access. This or x-as-user-id is required when the associated token was produced from the Client Credentials grant or with legacy bearer tokens on select endpoints. A token produced from the Authorization Code grant (which is already scoped to a user) may also use this header to act as a different user in the same company, provided the token carries the identity.users.impersonate scope and the token's own user has been granted the API User Impersonation permission. A request that sends this header without both never acts as the named user; depending on the company's configuration it either proceeds as the token's own user or is rejected with a 403. More information about permissions.

x-as-user-idstring
Example:5f0375c4cdc1927a3c5edcd3

Denotes the actor of the request. When used, the API will take into account this user's permissions and access. This or x-as-user-email is required when the associated token was produced from the Client Credentials grant or with legacy bearer tokens on select endpoints. A token produced from the Authorization Code grant (which is already scoped to a user) may also use this header to act as a different user in the same company, provided the token carries the identity.users.impersonate scope and the token's own user has been granted the API User Impersonation permission. A request that sends this header without both never acts as the named user; depending on the company's configuration it either proceeds as the token's own user or is rejected with a 403. More information about permissions.

Request body

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

importIdstring uuid required
status'NEW' | 'STAGING' | 'STAGED' | 'IMPORTING' | 'INDEXING' | 'IMPORTED' | 'ERROR' required

Example response

{
  "importId": "55ef635d-f2a9-5419-cd34-8b1ca4f733e9"
}

Changes