Imports

Imports Overview

The Imports API is an adapter API for the batches API and allows you to perform bulk operations on various resources such as contacts, groups, items, assets, and locations via a Semantic upload (a base64-encoded CSV/XLSX/JSON file or a JSON array of objects).

# Imports Resources

The following resources are supported. Note that the actions each resource accepts are different (see below):

• contact: Supports merge, overwrite, and delete.
• group: Supports merge, overwrite, and delete.
• item: Supports merge only.
• asset: Supports merge only.
• location: Supports merge only.

# Imports Actions

• merge: Updates and/or creates the rows in the upload.
• overwrite: Creates and/or updates the rows in the upload, and deletes/detaches all other existing rows of that resource. When a location_id is provided, the deletion is scoped to that location only (see below). Only valid for contact and group.
• delete: Deletes the rows in the upload. A valid id is required for each row. Only valid for contact and group.

If an action is used with a resource that does not support it, the API returns a 400 error, for example: 'delete' cannot be used with Imports API for 'items'.

# location_id and overwrite

location_id is only permitted with action: "overwrite", and it exists solely to scope the overwrite deletion to a single location. It does NOT associate the imported rows to that location - to place an imported row at a location you must set that location in the row's own data. This is a common point of confusion, so it is documented in detail on the Create Import page. Read that section before using overwrite with a location_id.

# Imports Phases

Each import runs its own phases first; the batches phases begin after the imports phases complete.

• prevalidation: Parses and validates the uploaded data against the schema.
• preparsing: Removes duplicates.
• transforming: Transforms the data into a batch-digestible format.

# Imports Modes

• sync: The data field is required, and the import is processed immediately with some restrictions. This is the only mode currently supported.
• async: The data field must be null. This mode is not currently supported by the create endpoint and will return a 400 error.

# Imports Statuses

# Initial/Intermediate Statuses

• queued: Import is valid and is in queue to be processed.
• processing: Writes/deletes/overwrites are being processed.

# Final Statuses

• completed: Processing complete.
• failed: Unable to start or complete processing.
• timed_out: Import took too long to process.

# Stats

• How many resources were created, updated, and/or deleted in this import.
• For the overwrite action, the number of resources removed as overwritten.

# Other Properties

• reason: Reason for a final status other than completed.
• has_upload_file: Indicates if the original payload can be downloaded.
• has_errors_file: Indicates if error rows/items can be downloaded.
• _upload_url: URL for uploading a file/payload via a signed URL.
• _upload_csv_url: URL to download the original payload as a CSV file.
• _upload_json_url: URL to download the original payload as a JSON file.
• _errors_csv_url: URL to download errors as a CSV file.
• _errors_json_url: URL to download errors as a JSON file.