Run the Importer

Once your API is configured and field mapping is set up, you are ready to import data and create posts. This article explains how to run the importer, configure import behaviors, and monitor the process.

Import Settings Overview

Before running an import, you need to configure three key settings:

  • Target Post Type – What type of posts to create (Posts, Pages, or custom post types)
  • Import Behavior – Create new posts or update existing ones
  • Post Status – Draft, Published, Pending, or Private

Choosing Target Post Type

The target post type determines where imported items are created in WordPress.

Available Options

Post Type Use For Availability
Posts Blog articles, news items, general content Free
Pages Static pages, company info, documentation Free
Custom Post Types Products, portfolios, events, testimonials, etc. PRO

Difference Between Posts and Pages

  • Posts: Have publication date, appear in reverse chronological order, included in feeds and archives
  • Pages: No publication date, not automatically archived, good for static content

For blog-like content, use Posts. For standalone content, use Pages.

Import Behavior

The import behavior determines how the importer handles items from the API.

Create New Posts

Creates a new post for every item in the API response. This is the most common behavior.

When to use:

  • Initial import of new data
  • You want every API item as a separate post
  • You do not need to update existing posts

Result: Every run creates new posts, even if they have duplicate titles or content.

Update Existing by Title (or Create) PRO

Matches items by title. If a post with that exact title exists, it updates it. If not, creates a new post.

When to use:

  • Running periodic imports to keep content fresh
  • You want to update posts instead of creating duplicates
  • API data may change between imports

How it works:

  1. For each API item, checks if a post with that title already exists
  2. If found: updates content, excerpt, featured image, etc.
  3. If not found: creates new post

Important: Title matching is exact. “My Article” and “My article” are different.

Post Status

The post status determines whether imported posts are immediately visible or require review.

Available Status Options

Status Visibility Use When
Draft Only visible to editors/admins Want to review before publishing
Publish Immediately visible to all visitors Content is verified and ready for public
Pending Review Only visible to editors/admins, flagged for review Content needs editorial approval
Private Only visible if logged in Member-only or restricted content

Recommended Status by Use Case

  • First import from new source: Draft (review before publishing)
  • Trusted automated source: Publish
  • Content needs editing: Pending Review
  • Member-only content: Private

Collection Path

The collection path tells the importer where to find the array of items in your API response.

When to Use Collection Path

Use collection path when the items are nested inside the API response:

Scenario Collection Path
Items at root level: [{ … }, { … }] (leave blank)
Items under “items” key: { “items”: [{ … }] } items
Items nested deeper: { “data”: { “articles”: [{ … }] } } data.articles

Important: Collection path uses dot notation to navigate nested structures. Get this wrong and the importer will not find any items.

Before Running Your First Import

Checklist

  1. API endpoint is configured and tested
  2. Field mapping is complete for all required fields
  3. Collection path is correct
  4. Target post type is selected
  5. Post status is set appropriately
  6. You have backed up your database (just in case)

Test with Limited Data

Before importing thousands of items:

  1. Add a limit parameter to your API URL to fetch just a few items (e.g., &limit=5)
  2. Run the import with this limited data
  3. Review the created posts
  4. Check that titles, content, images, etc. look correct
  5. If satisfied, remove the limit and run a full import

Running the Import

Manual Import

To manually run an import:

  1. Go to WordPress admin > API Press
  2. Click on your import API
  3. Click the “Run Importer” button
  4. Wait for the process to complete
  5. Review the import summary and any error messages

Import Process

During import, API Press:

  1. Fetches data from the API endpoint
  2. Finds the items using your collection path
  3. For each item, maps API fields to WordPress post fields
  4. Creates (or updates) posts with the mapped data
  5. Downloads and sets featured images
  6. Logs results and any errors

Import Summary

After import completes, you will see:

  • Number of items processed
  • Number of posts created
  • Number of posts updated (if using update mode)
  • Any errors or skipped items
  • Total time to complete

Automated Import PRO

With the Pro version, you can schedule the importer to run automatically on a regular schedule (daily, weekly, hourly, etc.).

Monitoring Import Results

Check Created Posts

After import:

  1. Go to WordPress admin > Posts (or your post type)
  2. Look for newly created posts
  3. Click on a post to review the content
  4. Check that title, content, featured image look correct
  5. Make any necessary edits

Review Import Logs

Check detailed import history:

  1. Go to API Press admin
  2. Click your import API
  3. Scroll to import history section
  4. See list of all previous imports with timestamps and results

Check for Errors

If posts were not created as expected:

  • Review error messages in the import summary
  • Check API Press logs for detailed error information
  • Verify field mapping is correct
  • Confirm collection path correctly finds items

Common Import Scenarios

Scenario 1: One-Time Import of Blog Posts

Setup:

  • Target post type: Posts
  • Import behavior: Create new
  • Post status: Draft (to review first)

Process:

  1. Configure API to fetch from external blog
  2. Map title, content, featured image fields
  3. Test with 5 items
  4. Run full import when satisfied
  5. Review and publish posts in WordPress

Scenario 2: Periodic Product Catalog Sync

Setup:

  • Target post type: Products (Custom post type, Pro only)
  • Import behavior: Update by title (or create)
  • Post status: Publish

Process:

  1. Configure API to fetch from product database
  2. Map title, description, price, image
  3. Set up scheduled import (daily or weekly)
  4. Existing products update with new data, new products get created

Scenario 3: Content Feed Import

Setup:

  • Target post type: Pages
  • Import behavior: Create new
  • Post status: Pending Review (for editorial approval)

Process:

  1. API fetches content from external service
  2. All items created as pending pages
  3. Editors review and publish pages

Troubleshooting Import Issues

No items imported / All items skipped

Causes:

  • Collection path is incorrect
  • Required fields have no data and no fallback
  • API returned no data or error

Solution:

  • Test API endpoint to verify it returns data
  • Check collection path matches API response structure
  • Verify field mapping is correct
  • Check error messages in import log

Partial Data (missing content, images, etc.)

Causes:

  • Field mapping path is incorrect
  • API field is named differently than expected
  • Data in API is empty

Solution:

  • Verify field paths are spelled exactly as in API response
  • Use fallback values for missing data
  • Check if featured images need full URL prefix

Import is very slow or times out

Causes:

  • Importing too many items at once
  • Large images taking time to download
  • API is responding slowly

Solution:

  • Break import into smaller batches (import 100 at a time)
  • Increase API timeout setting
  • Skip featured images initially, add them later
  • Try importing during off-peak hours

Duplicate posts created

Causes:

  • Import ran twice by mistake
  • Using “Create new” behavior instead of “Update by title”

Solution:

  • Switch to “Update by title” behavior for subsequent imports
  • Delete duplicate posts manually or in bulk

Featured images not importing

Causes:

  • Image URLs are incomplete (missing https://)
  • Images are not publicly accessible
  • Image URL field path is incorrect

Solution:

  • Ensure image URLs are complete with protocol
  • Test image URLs directly in browser
  • Verify correct field path in mapping
  • Use fallback to placeholder image if available

Best Practices for Importing

Always Test First

  • Test with a small sample (5-10 items) before full import
  • Review created posts carefully
  • Delete test posts and re-import if needed

Use Appropriate Post Status

  • Draft for new sources (review first)
  • Publish for trusted, verified sources
  • Pending for content needing approval

Set Fallback Values

  • Always provide fallbacks for non-required fields
  • Prevents incomplete posts
  • Better user experience

Monitor and Log

  • Check import history regularly
  • Watch for errors or warnings
  • Review created posts for quality

Backup Before Major Imports

  • Backup database before importing large datasets
  • Have recovery plan if something goes wrong

Document Your Setup

  • Keep notes on which APIs are used for which content
  • Document field mappings and special configurations
  • Record any issues encountered and solutions

After Importing

Immediate Steps

  1. Review created posts for accuracy
  2. Check post details: title, content, image, date
  3. Publish posts (if imported as draft)
  4. Check that posts appear on site correctly

Ongoing Maintenance

  • Schedule future imports if content changes regularly
  • Monitor for API changes that might break import
  • Keep field mappings updated
  • Archive old imported content if appropriate