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 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 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 creating the connection, copied when the import was created. Present only when the connection had 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 any item was rejected before an asset was created. 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 an import, the platform recomputes the status of every item from its asset.

Item statuses

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

• processing: The platform is downloading the file from the provider.
• ready: The asset is ready to use.
• failed: The platform could not download 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.