# Create imports URL: https://docs.hanzo.ai/docs/openapi/marketing/post-marketing-imports > Creates an import into one of the org's lists and answers it. `POST /v1/marketing/imports` > [Marketing →](https://docs.hanzo.ai/docs/openapi/marketing) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides) | | | | ------------- | ------------------------------------------- | | **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](https://docs.hanzo.ai/docs/errors). ## Examples **CLI** ```bash hanzo marketing imports create ``` **SDK** **.ts** ```ts import { Configuration, MarketingApi } from 'hanzoai'; const api = new MarketingApi(new Configuration({ accessToken: process.env.HANZO_API_KEY })); const { data } = await api.postMarketingImports({ basis: "", dryRun: false }); ``` **.py** ```python 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="", dry_run=False) ``` **.go** ```go 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 } ``` **.rs** ```rust 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?; ``` **.java** ```java 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. `hanzoai@8.5.914` (npm) and `hanzoai@8.5.914` (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 →](https://docs.hanzo.ai/docs/sdks) **HTTP** ```bash curl -X POST https://api.hanzo.ai/v1/marketing/imports \ -H "Authorization: Bearer $HANZO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "basis": "", "dryRun": false }' ``` **MCP** 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: ```bash 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](https://docs.hanzo.ai/docs/openapi/marketing) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)