# File Import Action

## Action purpose

Imports a file into HubSpot using the `/crm/v3/imports` API.

Supports [**CSV and BZ2-compressed CSV** files](https://docs.middle.app/middle-docs/building-workflows/workflow-steps#file-export), fetched from an **S3 presigned URL**, with robust options for **field mapping**, **transformations**, and **optional formatting** prior to upload.

{% embed url="<https://docs.middle.app/middle-docs/building-workflows/workflow-steps#file-export>" %}

## Overview

This action allows you to import any supported HubSpot object type — such as **Contacts**, **Companies**, **Deals**, **Tickets**, or **Notes** — using a CSV file.

You can define mappings between CSV columns and HubSpot property names either by:

1. Providing a **structured array** of field definitions, or
2. Using a **special “Field Definitions String”** input (recommended for a more streamlines implementation).

The action handles:

* Field transformations
* Static values
* Row filtering
* CSV reformatting for Hubspot
* Optional date/datetime normalization
* Upsert / Create / Update import modes

## Field Definitions String

Defines field mappings, transformations, and filters in **text format**, one mapping per line.

Example:

```
source_field:destination_field
```

In cases where the file is sourced from a Middle file export, the source\_field will be the internal name of the Middle field.

{% hint style="info" %}
You can review the internal names of fields by either reviewing the record type in the [Apps](https://docs.middle.app/middle-docs/app-development/sync-records) section (limited to ENTERPRISE customers), by [reviewing your stored records](https://docs.middle.app/middle-docs/building-workflows/sync/stored-records) and clicking to view a record in JSON, or [exporting a file of stored records](https://docs.middle.app/middle-docs/faqs/can-i-manually-export-data) and reviewing the column headers.
{% endhint %}

### Transformations

| Transformation             | Description                                                                                                                                                                               | Example                                              |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `&&remove_whitespace`      | Removes all spaces and tabs.                                                                                                                                                              | `first_name:first_name:&&remove_whitespace`          |
| `&&uppercase`              | Converts the string to uppercase.                                                                                                                                                         | `name:name:&&uppercase`                              |
| `&&lowercase`              | Converts the string to lowercase.                                                                                                                                                         | `email:email:&&lowercase`                            |
| `&&titlecase`              | Capitalizes each word.                                                                                                                                                                    | `full_name:name:&&titlecase`                         |
| `&&static_value;VALUE`     | Sets this field to a static value for all rows.                                                                                                                                           | `status:status:&&static_value;Active`                |
| `&&filter_row;VALUE`       | Keeps only rows where this field equals VALUE; discards all others.                                                                                                                       | `region:region:&&filter_row;CA`                      |
| `&&disallowed_value;VALUE` | Discards the row if the disallowed value exists for this column.                                                                                                                          | `joinStatus:join_status:&&disallowed_value;Prospect` |
| `&&disallow_null`          | Discards rows with blank values or "null" values                                                                                                                                          | `email:email:&&disallow_null`                        |
| `&&phone_number`           | Applies transformation to the cell to attempt to match E164 format.  If the phone number lacks a country code, a US country code will be used.  Example post-transformation: +16054443333 | `primary_phone:phone:&&phone_number`                 |

## Object identity reconciliation

Defines which field pair is the **unique identifier** for record reconciliation.

{% embed url="<https://docs.middle.app/middle-docs/guides/app-reference/hubspot/external-id-properties>" %}

The format is:

```
csv_column_name:hubspot_property_name:PRIMARY|SECONDARY
```

Examples

```
id:hs_object_id:PRIMARY
email:email:SECONDARY
```

{% hint style="info" %}

* **PRIMARY** — HubSpot internal ID field
* **SECONDARY** — Unique field such as Email, Domain, or External ID
  {% endhint %}

## Error handling

* **403 File Access Error:** File in S3 could not be retrieved — check presigned URL expiration.
* **Reconciliation Missing:** If no primary or secondary key is identified, import will abort.
* **Transformation Error:** Misspelled or unknown transformation names trigger a runtime error.
* **Column Mismatch:** If a specified CSV column is not found, an exception is raised.

## Best practices

* Always include a **reconciliation key** (`PRIMARY` or `SECONDARY`).
* Use **optional\_formatting = true** if the column order in your CSV is unpredictable.
* Limit transformations to supported types — unrecognized transformations will cause failure.
* Test transformations with a small dataset first.
* Use **static\_value** for flags or constant properties to simplify source CSVs.