Create imports

Creates an import into one of the org's lists and answers it.

POST /v1/marketing/imports

Marketing → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/marketing/imports`
Method	`POST`
Operation	`post_marketing_imports`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Creates an import into one of the org's lists and answers it. For a file the import waits in state receiving for its bytes (PUT /v1/marketing/imports/{id}/data); for a source (from: commerce) it is queued at once. A key makes the call idempotent: a second create with it answers the first import. The rows are stamped with the import's id as their source ref, so a filter on ref selects the batch.

Org admin only.

Request

22 fields, body application/json (required).

Field	In	Type	Required	Description
`basis`	body	string	—	Basis is the consent basis recorded for every row: explicit, legitimate_interest or unverified (the default).
`dryRun`	body	boolean	—	DryRun reads and judges every row and writes nothing.
`format`	body	string	—	Format is csv or json; ignored for a source.
`from`	body	string	—	From is a source to read instead of a file, as the host offers them: commerce (the org's commerce form subscribers) or crm (the confirmations the retired newsletter filed in the org's CRM).
`key`	body	string	—	Key makes creating the import idempotent: a second create with the same key answers the first import.
`list`	body	string	—	List is the list to fill, by id or slug.
`map`	body	marketing.Mapping	—
`map.consentAt`	body	string	—	ConsentAt is a column holding when the person subscribed.
`map.email`	body	string	—	Email is the column holding the address.
`map.fields`	body	object	—	Fields maps a custom field key to the column holding it.
`map.fields.*`	body	string	—
`map.first`	body	string	—	First and Last are columns holding the name in two parts.
`map.language`	body	string	—	Language is a column holding a language or locale.
`map.last`	body	string	—	Last is the family name's column.
`map.name`	body	string	—	Name is a column holding the whole name.
`map.status`	body	string	—	Status is a column holding a status from another provider (subscribed, unsubscribed, cleaned, bounced, complained and their usual spellings).
`map.tags`	body	string	—	Tags is a column of tags separated by commas or semicolons.
`name`	body	string	—	Name is the file's name, for the record.
`size`	body	integer (int64)	—	Size is the file's size in bytes, when known; the upload is refused past it.
`status`	body	string	—	Status is what a new row becomes: subscribed (the default), unsubscribed, bounced, complained or cleaned, as an export from another provider records.
`tags`	body	string[]	—	Tags are put on every row the import writes.
`verify`	body	boolean	—	Verify checks each address deliverable before writing it.

Response

Status	Body	Meaning
`200`	marketing.Created	ok
`201`	marketing.Created	created
`default`	problem-details	refused

200 body — 60 fields.

Field	In	Type	Always	Description
`by`	body	string	—	By is who created it.
`createdAt`	body	integer (int64)	—	CreatedAt, UpdatedAt and FinishedAt are unix seconds.
`error`	body	string	—	Error is why a failed import stopped.
`existed`	body	boolean	—	Existed is true when an import with the same key was already there.
`finishedAt`	body	integer (int64)	—	FinishedAt is when it ended; 0 while it runs.
`id`	body	string	—	ID is the import's id ("imp_" and 96 random bits in hex): the batch every subscriber it adds records as its source ref.
`list`	body	string	—	List is the list it fills.
`options`	body	marketing.ImportOptions	—
`options.basis`	body	string	—	Basis is the consent basis recorded for every row: explicit, legitimate_interest or unverified (the default).
`options.dryRun`	body	boolean	—	DryRun reads and judges every row and writes nothing.
`options.format`	body	string	—	Format is csv or json; ignored for a source.
`options.from`	body	string	—	From is a source to read instead of a file, as the host offers them: commerce (the org's commerce form subscribers) or crm (the confirmations the retired newsletter filed in the org's CRM).
`options.key`	body	string	—	Key makes creating the import idempotent: a second create with the same key answers the first import.
`options.map`	body	marketing.Mapping	—
`options.map.consentAt`	body	string	—	ConsentAt is a column holding when the person subscribed.
`options.map.email`	body	string	—	Email is the column holding the address.
`options.map.fields`	body	object	—	Fields maps a custom field key to the column holding it.
`options.map.fields.*`	body	string	—
`options.map.first`	body	string	—	First and Last are columns holding the name in two parts.
`options.map.language`	body	string	—	Language is a column holding a language or locale.
`options.map.last`	body	string	—	Last is the family name's column.
`options.map.name`	body	string	—	Name is a column holding the whole name.
`options.map.status`	body	string	—	Status is a column holding a status from another provider (subscribed, unsubscribed, cleaned, bounced, complained and their usual spellings).
`options.map.tags`	body	string	—	Tags is a column of tags separated by commas or semicolons.
`options.name`	body	string	—	Name is the file's name, for the record.
`options.size`	body	integer (int64)	—	Size is the file's size in bytes, when known; the upload is refused past it.
`options.status`	body	string	—	Status is what a new row becomes: subscribed (the default), unsubscribed, bounced, complained or cleaned, as an export from another provider records.
`options.tags`	body	string[]	—	Tags are put on every row the import writes.
`options.verify`	body	boolean	—	Verify checks each address deliverable before writing it.
`parsed`	body	integer (int64)	—	Parsed is how many bytes of the file the worker has read and judged.
`received`	body	integer (int64)	—	Received is how many bytes of the file have arrived; the next piece starts here.
`report`	body	marketing.Report	—
`report.bases`	body	object	—	Bases count the rows written by the consent basis recorded for them.
`report.bases.*`	body	integer (int64)	—
`report.columns`	body	string[]	—	Columns are the file's columns, as its header named them.
`report.imported`	body	integer (int64)	—	Imported is how many rows became new subscribers.
`report.invalid`	body	integer (int64)	—	Invalid is how many could not be read as an address, for the reasons in Reasons.
`report.map`	body	marketing.Mapping	—
`report.map.consentAt`	body	string	—	ConsentAt is a column holding when the person subscribed.
`report.map.email`	body	string	—	Email is the column holding the address.
`report.map.fields`	body	object	—	Fields maps a custom field key to the column holding it.
`report.map.fields.*`	body	string	—
`report.map.first`	body	string	—	First and Last are columns holding the name in two parts.
`report.map.language`	body	string	—	Language is a column holding a language or locale.
`report.map.last`	body	string	—	Last is the family name's column.
`report.map.name`	body	string	—	Name is a column holding the whole name.
`report.map.status`	body	string	—	Status is a column holding a status from another provider (subscribed, unsubscribed, cleaned, bounced, complained and their usual spellings).
`report.map.tags`	body	string	—	Tags is a column of tags separated by commas or semicolons.
`report.reasons`	body	object	—	Reasons count the skipped and invalid rows by why.
`report.reasons.*`	body	integer (int64)	—
`report.rows`	body	integer (int64)	—	Rows is how many rows were read.
`report.samples`	body	marketing.Sample[]	—	Samples are the first rejected rows: their row number and the reason.
`report.samples[].reason`	body	string	—	Reason is why it was rejected.
`report.samples[].row`	body	integer (int64)	—	Row is the row's number in the file, the header not counted.
`report.skipped`	body	integer (int64)	—	Skipped is how many were left as they were, for the reasons in Reasons.
`report.statuses`	body	object	—	Statuses count the rows written by the status they were written with.
`report.statuses.*`	body	integer (int64)	—
`report.updated`	body	integer (int64)	—	Updated is how many were already on the list and gained a name, tags or fields, or a status that leaves the list.
`state`	body	string	—	State is receiving (waiting for its bytes), queued, processing, done, failed or cancelled.
`updatedAt`	body	integer (int64)	—	UpdatedAt is the last progress.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo marketing imports create

.ts

.py

.go

.rs

.java

import { Configuration, MarketingApi } from 'hanzoai';

const api = new MarketingApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postMarketingImports({ basis: "<basis>", dryRun: false });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import MarketingApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = MarketingApi(client).post_marketing_imports(basis="<basis>", dry_run=False)

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.MarketingAPI.PostMarketingImports(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, marketing_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = marketing_api::post_marketing_imports(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.MarketingApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new MarketingApi(client).postMarketingImports();

The method above is the one at the current release of the document. [email protected] (npm) and [email protected] (PyPI) were generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. SDKs →

curl -X POST https://api.hanzo.ai/v1/marketing/imports \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "basis": "<basis>",
       "dryRun": false
     }'

MCP reaches marketing through the marketing tool, which names its 82 operations with its own verbs — this one among them, under a name only MCP declares. describe explains any of them:

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_marketing_audiences"
         }
       }
     }'

Marketing API · All Hanzo APIs · Interactive reference

Was this page useful?

Broken link or missing step? Drop it in #docs on Discord or open a PR.

PreviousStart imports NextCreate esign