# 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](/middle-docs/app-development/sync-records.md) section (limited to ENTERPRISE customers), by [reviewing your stored records](/middle-docs/building-workflows/sync/stored-records.md) and clicking to view a record in JSON, or [exporting a file of stored records](/middle-docs/faqs/can-i-manually-export-data.md) 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.middle.app/middle-docs/guides/app-reference/hubspot/file-import-action.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.