Format ACF Field Values in REST API Responses

Control how ACF fields are serialised in REST API responses — return full objects instead of IDs for images, posts, and other relational fields.

By default, ACF returns raw database values in REST responses (e.g. image attachment IDs instead of URLs). Use the acf_format query parameter to get formatted values:

GET /wp-json/wp/v2/posts/123?acf_format=standard

This returns rich data — image fields include URLs and sizes, post object fields include full post data, etc.

To always return formatted values without requiring the query parameter, use the acf/rest/format_value_for_rest filter:

<?php
// Always return formatted values for all fields.
add_filter( 'acf/rest/format_value_for_rest', '__return_true' );

To format only specific field types:

<?php
add_filter( 'acf/rest/format_value_for_rest/type=image', '__return_true' );
add_filter( 'acf/rest/format_value_for_rest/type=post_object', '__return_true' );
add_filter( 'acf/rest/format_value_for_rest/type=relationship', '__return_true' );

Example response difference for an image field:

// Without formatting (raw):
{ "hero_image": 456 }

// With acf_format=standard:
{
    "hero_image": {
        "ID": 456,
        "url": "https://example.com/wp-content/uploads/hero.jpg",
        "width": 1200,
        "height": 800,
        "alt": "Hero image",
        "sizes": {
            "thumbnail": "https://example.com/wp-content/uploads/hero-150x150.jpg",
            "medium": "https://example.com/wp-content/uploads/hero-300x200.jpg"
        }
    }
}

Note: Formatted responses are larger and may include nested data. For performance-sensitive endpoints, consider using raw values and resolving references client-side.