An import represents a single call to import files from a connected account. Each import attempts to create one asset per requested file and tracks the outcome of the import operation for each file.

Three endpoints return an import, with different fields in each response:

• Import files returns a confirmation of what was accepted: the _id and has_failures fields, and one item per requested file.
• List imports returns each import as a summary, without the items array.
• Retrieve an import returns the full import, including the items array with the current status of each file.

Source file, item, and asset

Each file in an import moves through three stages, with a different name at each:

• Source file: What you select. In the Import files request, the source_id field of each entry contains the unique identifier of a file in the connected account.
• Item: How the import tracks the file. The items array has one entry per requested file, with a field named action for the outcome of the import operation, and a status field for its asset, or an error object if the file was rejected.
• Asset: What you use. Each accepted file becomes an asset with its own identifier in the asset_id field. Once the item reaches the ready status, use that value with the rest of the API.

Import fields

An import object can include the following fields:

• _id: The unique identifier of the import.
• connection_id: The unique identifier of the connection the files were imported through.
• provider: The data connector provider (google_drive).
• custom_id: The label you supplied when you authorized the connection, copied when the import was created. Present only when you supplied one.
• item_count: The number of files requested in the import.
• created_at: The date and time, in the RFC 3339 format, when the import was created.
• has_failures: Whether at least one item was rejected before an asset was created. A skipped item is not a failure. Returned by Import files.
• items: One entry per requested file, in request order. Returned by Import files and Retrieve an import.

An import is immutable. Each time you retrieve it, the status field of each item reflects the current status of its asset.

Item actions

The action field indicates the outcome of the import operation for each file. Import files always returns it. Retrieve an import omits it for imports from before this field existed, so treat an absent value as unknown. It has one of the following values:

Summarize a request

To count how many files were imported, skipped, or rejected, use the action field, not the status field.

The status field alone cannot indicate the outcome of the import operation. A newly imported file and a skipped duplicate can both show the processing status: the new file because its import just started, the duplicate because an earlier import of the same file is still running. Only the action field distinguishes them, because it is set once and never changes, while the status field keeps updating as the asset is processed.

Item statuses

The status field of an item has one of the following values:

• processing: The platform is fetching the file from the provider.
• ready: The asset is ready to use.
• failed: The platform could not fetch the file.

An item that was rejected before an asset was created has no value in its status field. Instead, it includes an error object with code and message fields. For the possible codes, see the Error codes page.