File Import Action

Learn about Middle's "Import File into Hubspot Action"

Action purpose

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

Supports CSV and BZ2-compressed CSV files, fetched from an S3 presigned URL, with robust options for field mapping, transformations, and optional formatting prior to upload.

Workflow steps | docs.middledocs.middle.app

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.

You can review the internal names of fields by either reviewing the record type in the Apps section (limited to ENTERPRISE customers), by reviewing your stored records and clicking to view a record in JSON, or exporting a file of stored records and reviewing the column headers.

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: [phone]	primary_phone:phone:&&phone_number

Object identity reconciliation

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

External ID properties | docs.middledocs.middle.app

The format is:

csv_column_name:hubspot_property_name:PRIMARY|SECONDARY

Examples

id:hs_object_id:PRIMARY
email:email:SECONDARY

• PRIMARY — HubSpot internal ID field

• SECONDARY — Unique field such as Email, Domain, or External ID

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.