---
title: Map API Fields to Posts
slug: map-api-fields-to-posts
type: how-to
plugin: huxx-connect-pro
summary: Route API data into post fields, taxonomy terms, custom fields (including ACF and Meta Box repeaters), and featured images with token templates.
keywords: [post creator, field mapping, tokens, ACF, Meta Box, taxonomies, featured image]
version_added: 1.3.5
version_updated: 1.3.5
level: intermediate
pro: true
related: [sync-api-data-to-posts, choose-sync-mode-and-matching, keys-syntax]
---

Post Creator (Pro) writes each API item into a post through *mappings*: a target (where the value goes) plus a format template (what the value is). This page covers every mapping group and the template syntax they all share.

> **Quick version:**
> 1. Post Creator editor → **Field Mapping** tab. Three groups: **Post Data**, **Taxonomies**, **Custom Fields**.
> 2. Templates use `{dot.path}` tokens resolved against each item: `{title}`, `{meta.createdAt}`, `{title} — {brand}`.
> 3. **Post Data** targets: Title, Content, Excerpt, Slug, Date, Date (GMT), Featured Image.
> 4. **Taxonomies**: pick a taxonomy, map `{tags}` — arrays become one term per element; scalars are comma-split.
> 5. **Custom Fields**: type a meta key (autocomplete lists ACF, MetaBox, Etch, and WP fields, including repeater sub-fields as `parent.sub`).
> 6. Keep the API's HTML intact via Configuration → Advanced → **Preserve original HTML content**.

## Mapping groups

The **Field Mapping** tab has three collapsible groups, and every row is target + format:

| Group | Target | Add button |
|---|---|---|
| Post Data | Title, Content, Excerpt, Slug, Date, Date (GMT), Featured Image | **+ Add Field** |
| Taxonomies | Any taxonomy with admin UI enabled | **+ Add Taxonomy** |
| Custom Fields | Any post meta key | **+ Add Custom Field** |

Post Data targets are single-use — once a mapping claims Title, the option is disabled in other rows. A live preview under each row shows the value resolved against the current sample item, and clicking a value in the **API Response** tree inserts its token into the focused input.

:::novice
The API Response panel shows one real item from your endpoint as a folder-like tree. Every mapping is just "take this piece of the tree, put it in that WordPress slot." See [what is an API](/docs/connect/explanation/what-is-an-api/) for the bigger picture.
:::

## Token templates

Format values are templates. `{dot.path}` tokens are replaced with data from the current item; anything outside braces is kept as literal text.

```
{title} — {brand}
```

Output for DummyJSON product #1:

```
Essence Mascara Lash Princess — Essence
```

Rules worth knowing:

- Paths use dot notation into nested data: `{meta.createdAt}`, `{dimensions.width}`. See [key extraction syntax](/docs/connect/reference/keys-syntax/) for the full path grammar.
- A token whose path doesn't exist resolves to an empty string. The editor flags this with a warning icon: "Some fields were not found in sample data."
- In a mixed template, an array or object value is JSON-encoded into the string. A Custom Fields mapping whose format is a *single* token keeps the raw value (arrays stay arrays).
- Slug mappings are passed through WordPress slug sanitization automatically.

## Map taxonomy terms

Add a row in **Taxonomies**, pick the taxonomy, and set the format. The dropdown lists every taxonomy with an admin UI site-wide, not just those registered for your post type — terms only attach meaningfully when the taxonomy is registered for the target post type, so pick one that is. If the token resolves to an array, each element becomes a term; if it resolves to a string, the string is split on commas.

```
Taxonomy: Tags    Format: {tags}
```

Output for a DummyJSON product with `"tags": ["beauty", "mascara"]`:

```
Terms assigned: beauty, mascara
```

Each taxonomy row has a **Match by** option — **Name** (default), **Slug**, **ID**, or **Custom Meta Field** — controlling how resolved values are matched to existing terms. The **Auto-create terms** toggle (on by default) creates terms that don't exist yet; with Slug or Custom Meta Field matching you can also set **Term name (optional)**, a template like `{name} ({species})`, so auto-created terms get readable names instead of the raw lookup value.

## Map custom fields

In **Custom Fields**, the target is a meta key. Start typing and an autocomplete lists every field discovered for the chosen post type, each tagged with its source: **ACF**, **MetaBox**, **Etch**, or **WP** (existing plain meta keys).

- **ACF**: registered fields are listed by name. Repeater, group, and flexible content fields also expose their sub-fields in `parent.sub` dot notation (labeled `Parent → Sub`). Writes go through ACF's own API, so relationship, gallery, image, and date fields receive correctly coerced values.
- **Meta Box**: registered fields are listed, with group sub-fields flattened to `group.sub` dot notation the same way.

To fill a repeater from an API array, target the sub-field and use a wildcard token. When your format contains an array index like `{reviews.0.comment}`, a bracket button appears next to the input — click it to switch to multiple value mode ("for repeaters, relationships, etc."), which rewrites the token to a wildcard:

```
Target: reviews.comment    Format: {reviews.[].comment}
```

Output: one repeater row per array element, each with its `comment` sub-field set. In single value mode the same mapping would store just one value.

## Set a featured image

Choose **Featured Image** as a Post Data target and map it to an image URL, for example `{thumbnail}` on DummyJSON. Three options appear under the row:

- **Download to media library** (on by default) — sideloads the image as an attachment. Turn it off to hot-link the external URL instead.
- **URL prefix** — prepended when the API returns relative paths (e.g. `https://cdn.example.com/`). A warning icon appears if the resolved value doesn't start with `http://` or `https://` and no prefix is set.
- **Filename** (download mode only) — a template for the saved file's name, like `{title}-featured`. Filename tokens resolve against the API item like every other template, so use item fields (for DummyJSON, `{title}`), not post fields. Don't include a file extension.

Custom Fields mappings that point at ACF/Meta Box image or file fields show the same **Download to media library** toggle.

## Preserve original HTML

If your API returns HTML content, WordPress's save-time sanitizer can strip tags during scheduled runs — cron has no logged-in user, so the `unfiltered_html` capability check fails and styles, template scripts, and email markup (e.g. Mailchimp campaigns) get mangled. Manual runs by an administrator don't hit this, which makes the two run types produce different content.

The fix is in the Configuration card under **Advanced**: turn on **Preserve original HTML content** to store the API's HTML exactly as received and make scheduled runs match manual runs. Leave it off (the default) if your API returns content from untrusted users — comments, forum posts, user-submitted forms — so WordPress keeps stripping risky tags before saving.

## If it didn't work

**The preview shows an empty value.** The token path doesn't match the sample item. Click the exact value in the API Response tree instead of typing the path — the inserted token is always correct. Remember paths are relative to each item, not the response root.

**A repeater or relationship field saved only one value.** The mapping is in single value mode. Click the bracket toggle next to the format input to switch to multiple value mode, which converts the token to the `{path.[].field}` wildcard form.

**Terms came in as one long term.** The token resolved to a single string without commas, or to a JSON-encoded blob from a mixed template. Use a single `{token}` that points directly at the array so each element becomes its own term.