Field Mapping for Imports

Understanding Field Mapping for Imports

When you import data from an API, the importer needs to know which API fields contain the information for each WordPress post field. For example:

• Which API field contains the post title?
• Which field contains the main content?
• Which field has the featured image URL?
• Which field contains the excerpt?

Field mapping connects your API response to WordPress post structure.

Available WordPress Post Fields

The importer supports mapping to these core WordPress post fields:

Title (Required)

The main heading/name of the post. Every post must have a title.

WordPress field: Post title

Example API fields: title, name, headline, subject

Content

The main body text of the post. This is what readers see as the post content.

WordPress field: Post content

Example API fields: content, body, article_text, description

Excerpt

A short summary or preview of the post. Used in post listings and archives.

WordPress field: Post excerpt

Example API fields: excerpt, summary, preview, teaser

Featured Image URL

The main image for the post. This should be a complete URL to an image file.

WordPress field: Featured image (sets it as attachment)

Example API fields: image_url, featured_image, thumbnail, photo

How to Map Fields

Step 1: Preview API Data

First, fetch a sample of your API response to see the available fields:

1. In API Press admin, go to your import API
2. Click “Test Request” to fetch sample data
3. Review the response to see exactly what field names are available

Step 2: Map Each Field

For each WordPress post field, you will see:

• API key/path – Where to find data in the API response
• Fallback value – Default text to use if API field is empty
• Required – Whether this field must have data for import

Step 3: Use Correct Field Paths

Field paths can be simple (single level) or nested (multiple levels):

• title – Simple field at root level
• data.title – Nested field (inside “data” object)
• article.meta.summary – Deeply nested field

Pro Tip: Check the API response carefully. Field names are case-sensitive. Title and title are different.

Detailed Field Mapping Guide

Title Field (Required)

The title is required. Every imported post needs a title.

How to map: Enter the API field that contains the post’s main title.

Example: If your API has a field called headline, enter headline

Fallback value: If this field is required but has no value, import will fail. You can set a fallback to use instead (e.g., “Untitled”)

Content Field

The main body of the post. This is optional but recommended.

How to map: Enter the API field containing the post body text.

Example: If your API has body or description, use that

If API returns HTML: API Press will preserve HTML markup in the post content

Fallback value: If empty, use this default text

Excerpt Field

A short summary. This is optional.

How to map: Enter the API field with summary text.

Example: summary, preview, or teaser

Length: WordPress excerpts typically show in post listings. Keep them relatively short (under 300 characters).

Fallback value: If no excerpt in API, automatically use first portion of content

Featured Image URL Field

URL of the image to use as featured image. This is optional.

How to map: Enter the API field with a complete image URL.

Example: image_url, featured_image, or thumbnail

Important: Must be a complete URL starting with http:// or https://

If partial URL: Use nested paths. For example:

Using Fallback Values

Fallback values provide defaults when API data is missing or empty.

When to Use Fallback Values

Use fallback values when:

• An API field might be empty for some items
• You want to ensure every post has some content in a field
• You want to categorize or tag posts based on source

Examples

Required Field Toggle

Check the “Required for import” box for fields that must have data for the post to be created.

When to Mark as Required

By default, only Title is required. Mark other fields as required if:

• The field is essential for the post (e.g., Content must exist)
• You want to skip items that lack this data
• You never want empty values, even with fallback

What Happens

If a required field has no data and no fallback value:

• That item is skipped (not imported)
• Log shows why it was skipped
• Import continues with other items

Note: Title is always required. You cannot uncheck it.

Mapping Examples

Example 1: Blog Posts from WordPress API

API Response Sample:

Field Mapping:

Example 2: Products with Nested Data

API Response Sample:

Field Mapping:

Example 3: With Fallback Values

Scenario: Some products might not have descriptions

Field Mapping:

Troubleshooting Field Mapping

Data not importing correctly

Solution:

• Double-check field names are spelled exactly as they appear in API response
• Verify nested paths use correct dot notation (e.g., data.items.title)
• Test the API response to see exact field names and structure

Some posts missing data

Solution:

• Check if required field toggle is preventing import for items with empty fields
• Set appropriate fallback values
• Uncheck “Required for import” if field should not block entire post

Featured images not appearing

Solution:

• Verify image URLs are complete (include https://)
• Check that images are publicly accessible
• Use correct field path for image URL

Special characters appearing incorrectly

Solution:

• Ensure API is returning UTF-8 encoded data
• Check that API response content includes proper encoding headers