IntentRank Docs

WordPress Integration Guide

The IntentRank WordPress plugin provides seamless integration that allows IntentRank to send articles directly to your WordPress site via REST API endpoints. This guide will help you install, configure, and use the plugin to automatically receive and publish articles from IntentRank.

Features

The WordPress plugin includes the following features:

  • Integration Key Authentication: Secure API authentication using integration keys with multiple authentication methods
  • Flexible Post Modes: Choose whether posts are published immediately or saved as drafts for review
  • Dual REST API Endpoints:
    • Modern /articles endpoint for bulk article processing (recommended)
    • Legacy /post endpoint for backward compatibility
  • Test Endpoint: Verify your integration configuration with the /test endpoint
  • Full Post Support: Supports title, content (HTML/Markdown), excerpt, categories, tags, featured images, and custom slugs
  • SEO Integration: Automatic focus keyword support for popular SEO plugins (Yoast SEO, Rank Math, SEOPress, The SEO Framework)
  • Automatic Category/Tag Creation: Automatically creates categories and tags if they don't exist
  • Smart Image Handling:
    • Downloads featured images from external URLs (including S3)
    • Automatically inserts images into post content
    • Saves images to WordPress media library
  • Admin Interface:
    • Articles management page with unpublished article count
    • Manual publish functionality for draft articles
    • Bulk publish capability
    • Settings page with API endpoint information
  • Content Processing: Automatically cleans HTML content (removes code block markers)
  • Custom Post Type: Uses a dedicated post type to track IntentRank articles separately from regular posts

Installation

Step 1: Download and Install the Plugin

Download the IntentRank plugin ZIP file:

Download Plugin ZIP

Follow these steps to install the plugin:

  1. Log in to your WordPress admin dashboard
  2. Navigate to Plugins → Add New
  3. Click "Upload Plugin" at the top of the page
  4. Click "Choose File" and select the downloaded intentrank.zip file
  5. Click "Install Now" and wait for the installation to complete
  6. Click "Activate Plugin" to activate it

Step 2: Configure the Plugin

After activation, go to Settings → IntentRank in your WordPress admin. You'll need to paste your Integration Token in the "Integration Token" field.

To get your Integration Token:

  1. Log in to your IntentRank account
  2. Navigate to WordPress integration settings
  3. Generate your Integration Token
  4. Copy the token

Then in WordPress:

  1. Go to Settings → IntentRank in your WordPress admin panel
  2. Paste your Integration Token in the "Integration Token" field
  3. Select your Post Mode:
    • Save as Draft: Posts will be saved as drafts in the IntentRank Articles section for review and manual publishing
    • Post Directly: Posts will be published immediately to your WordPress blog
  4. Click "Save Changes" to establish the connection

Next Steps

After completing the setup above, test the connection and then create the integration in your IntentRank account.

3. Managing Articles

After configuration, you can manage incoming articles:

  • View Articles: Go to IntentRank > Articles to see all received articles
  • Unpublished Count: The menu shows a badge with the count of unpublished articles
  • Publish Articles: Click "Publish" on individual articles or use "Bulk Publish" for multiple articles
  • Edit Articles: Click on any article to edit it before publishing

4. API Endpoints Display

The settings page displays your API endpoints:

  • Articles Endpoint: /wp-json/intentrank/v1/articles (recommended for new integrations)
  • Legacy Post Endpoint: /wp-json/intentrank/v1/post (for backward compatibility)

Copy these URLs to configure in your IntentRank account.

API Usage

The plugin provides three REST API endpoints:

1. Articles Endpoint (Recommended)

POST /wp-json/intentrank/v1/articles

This is the main endpoint for receiving articles from IntentRank. It supports bulk article processing with the new payload format.

Request Body

Articles Endpoint Payload
{
  "data": {
    "articles": [
      {
        "id": "article-123",
        "title": "Your Article Title",
        "content_html": "<p>Your article content in HTML format.</p>",
        "content_markdown": "Your article content in Markdown format.",
        "meta_description": "SEO meta description",
        "slug": "your-article-slug",
        "tags": ["tag1", "tag2"],
        "image_url": "https://example.com/image.jpg",
        "keyword": "focus keyword for SEO"
      }
    ]
  }
}

Response

{
  "success": true,
  "results": [
    {
      "success": true,
      "article_id": "article-123",
      "post_id": 456,
      "post_status": "draft"
    }
  ]
}

2. Legacy Post Endpoint

POST /wp-json/intentrank/v1/post

Legacy endpoint for backward compatibility. Supports single post creation.

Authentication

You can authenticate using one of the following methods:

  1. Authorization Header (Recommended):
    Authorization: Bearer YOUR_INTEGRATION_KEY
  2. X-API-Key Header:
    X-API-Key: YOUR_INTEGRATION_KEY
  3. Query Parameter:
    ?api_key=YOUR_INTEGRATION_KEY

Request Body

Legacy Post Endpoint Payload
{
  "title": "Your Post Title",
  "content": "<p>Your post content in HTML format.</p>",
  "excerpt": "Optional post excerpt",
  "categories": ["Category Name", "Another Category"],
  "tags": ["tag1", "tag2", "tag3"],
  "featured_image": "https://example.com/image.jpg"
}

Parameters

Legacy Post Endpoint Parameters
ParameterTypeRequiredDescription
titlestringYesThe post title
contentstringYesThe post content (HTML supported, code block markers are automatically removed)
excerptstringNoPost excerpt/summary
categoriesarrayNoArray of category names or IDs
tagsarrayNoArray of tag names or IDs
featured_imagestringNoURL to the featured image (will be downloaded and saved to media library)

3. Test Endpoint

GET /wp-json/intentrank/v1/test

Use this endpoint to verify your integration configuration and API key.

Response

{
  "success": true,
  "plugin_version": "1.0.0",
  "post_mode": "draft",
  "key_configured": true,
  "message": "Integration key is valid and plugin is ready to receive articles."
}

Response Format

The plugin returns appropriate HTTP status codes and JSON responses. Here are the expected response formats:

Success Response (200 OK)

{
  "success": true,
  "post_id": 123,
  "post_status": "draft",
  "message": "Post created successfully as draft.",
  "edit_link": "https://yoursite.com/wp-admin/post.php?action=edit&post=123"
}

Error Response (401 Unauthorized)

{
  "code": "invalid_api_key",
  "message": "Invalid integration key.",
  "data": {
    "status": 401
  }
}

Example Requests

Articles Endpoint (Recommended)

curl -X POST https://yoursite.com/wp-json/intentrank/v1/articles \
  -H "Authorization: Bearer YOUR_INTEGRATION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "articles": [
        {
          "id": "article-123",
          "title": "My New Blog Post",
          "content_html": "<p>This is the content of my blog post.</p>",
          "content_markdown": "This is the content of my blog post.",
          "meta_description": "A brief summary of the post",
          "slug": "my-new-blog-post",
          "tags": ["plugin", "api"],
          "image_url": "https://example.com/image.jpg",
          "keyword": "wordpress plugin"
        }
      ]
    }
  }'

Legacy Post Endpoint

curl -X POST https://yoursite.com/wp-json/intentrank/v1/post \
  -H "Authorization: Bearer YOUR_INTEGRATION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My New Blog Post",
    "content": "<p>This is the content of my blog post.</p>",
    "excerpt": "A brief summary of the post",
    "categories": ["Technology", "WordPress"],
    "tags": ["plugin", "api"],
    "featured_image": "https://example.com/image.jpg"
  }'

Test Endpoint

curl -X GET https://yoursite.com/wp-json/intentrank/v1/test \
  -H "Authorization: Bearer YOUR_INTEGRATION_KEY"

Example PHP Requests

Articles Endpoint (Recommended)

$response = wp_remote_post('https://yoursite.com/wp-json/intentrank/v1/articles', array(
    'headers' => array(
        'Authorization' => 'Bearer YOUR_INTEGRATION_KEY',
        'Content-Type' => 'application/json',
    ),
    'body' => json_encode(array(
        'data' => array(
            'articles' => array(
                array(
                    'id' => 'article-123',
                    'title' => 'My New Blog Post',
                    'content_html' => '<p>This is the content of my blog post.</p>',
                    'content_markdown' => 'This is the content of my blog post.',
                    'meta_description' => 'A brief summary of the post',
                    'slug' => 'my-new-blog-post',
                    'tags' => array('plugin', 'api'),
                    'image_url' => 'https://example.com/image.jpg',
                    'keyword' => 'wordpress plugin'
                )
            )
        )
    )),
));

Legacy Post Endpoint

$response = wp_remote_post('https://yoursite.com/wp-json/intentrank/v1/post', array(
    'headers' => array(
        'Authorization' => 'Bearer YOUR_INTEGRATION_KEY',
        'Content-Type' => 'application/json',
    ),
    'body' => json_encode(array(
        'title' => 'My New Blog Post',
        'content' => '<p>This is the content of my blog post.</p>',
        'excerpt' => 'A brief summary of the post',
        'categories' => array('Technology', 'WordPress'),
        'tags' => array('plugin', 'api'),
        'featured_image' => 'https://example.com/image.jpg'
    )),
));

Advanced Features

SEO Keyword Support

The plugin automatically saves focus keywords for popular SEO plugins:

  • Yoast SEO: Saves to _yoast_wpseo_focuskw
  • Rank Math: Saves to rank_math_focus_keyword
  • SEOPress: Saves to _seopress_analysis_target_kw
  • The SEO Framework: Saves to _tsf_focus

Keywords are sent in the keyword field of the articles endpoint payload.

Image Handling

  • Automatic Download: Featured images are automatically downloaded from external URLs (including S3)
  • Media Library: Images are saved to the WordPress media library
  • Content Insertion: Images are automatically inserted at the beginning of post content
  • Thumbnail Generation: WordPress automatically generates thumbnails and attachment metadata

Content Processing

  • HTML Cleaning: Automatically removes code block markers (markdown code fences) from content
  • Sanitization: All content is sanitized using WordPress's built-in functions
  • HTML Filtering: HTML content is filtered using wp_kses_post() to prevent XSS attacks

Security

  • All API requests are validated using the Integration Key
  • Multiple authentication methods supported (Authorization header, X-API-Key header, or query parameter)
  • Post content is sanitized using WordPress's built-in sanitization functions
  • HTML content is filtered using wp_kses_post() to prevent XSS attacks
  • The plugin follows WordPress coding standards and security best practices
  • Only users with manage_options capability can access admin pages

Requirements

  • WordPress 5.0 or higher
  • PHP 7.2 or higher

Support

For support, please contact IntentRank support or visit the plugin documentation.

Next Steps

Now that you understand how to set up the WordPress integration, you can:

  • Install and activate the IntentRank WordPress plugin
  • Configure your integration key in the plugin settings
  • Test your integration using the test endpoint
  • Configure the WordPress API endpoint in your IntentRank account
  • Start receiving articles automatically

If you need help or have questions, please reach out to our support team or check our API reference documentation.