Exposing ACF Fields to the WordPress REST API
By default, Advanced Custom Fields (ACF) data is stored in the database but remains invisible to the standard WordPress REST API endpoints. When you query a post via /wp-json/wp/v2/posts, the response includes standard meta fields but excludes custom ACF groups unless explicitly registered. This separation exists because ACF treats its fields as internal configuration rather than native post metadata, yet modern front-end applications often require direct access to this data without parsing HTML or relying on AJAX calls to fetch a separate JSON payload.
To bridge this gap and ensure all ACF fields appear within an ACF object in your API responses, you must register the field groups using WordPress filters that modify the output of the REST API. The primary mechanism for this is the rest_response filter applied specifically to ACF data structures or by registering custom meta fields directly on the post schema.
The most straightforward approach involves utilizing the acf/register_rest_api_fields logic, which allows you to map specific field groups to the REST API response. However, since ACF does not provide a single built-in hook that automatically dumps every active group into an ACF key, you typically need to iterate through the registered field groups and manually register each one as a meta field. This ensures that the data is treated as standard post metadata by the WP REST API server.
You can achieve this programmatically by accessing the ACF field group object and registering it within the acf/register_rest_api_fields action or similar hooks depending on your ACF Pro version. The core logic involves looping through $groups = acf_get_field_groups() and calling acf_register_meta_group for each one, effectively exposing their values.
Here is a conceptual implementation pattern using a custom filter hook often used in conjunction with ACF:
add_filter('rest_response', function($response) {
// Check if the request is for posts or pages
if ($response->data['type'] == 'post' || $response->data['type'] == 'page') {
$post = $response->data;
// Access the ACF field groups registered in your theme/plugins
$field_groups = acf_get_field_groups();
$acf_data = [];
foreach ($field_groups as $group) {
// Only register if the group is active and has fields
if (!empty($group['fields'])) {
$key = 'acf_' . preg_replace('/[^a-zA-Z0-9]/', '_', $group['name']);
// Retrieve the values for this specific field group
$values = get_post_meta($post->id, $key, true);
// If values exist, add them to the ACF object in the response
if (!empty($values)) {
$acf_data[$key] = $values;
}
}
}
if (!empty($acf_data)) {
$response->data['ACF'] = $acf_data;
}
}
return $response;
}, 10, 1);
This approach manually constructs the ACF object by iterating over available field groups and checking for existing meta keys. It respects the version-specific behavior of ACF Pro where acf_get_field_groups() returns the full list of registered groups. The trade-off here is that you are responsible for mapping internal field names to clean, REST-friendly keys if your field group names contain spaces or special characters.
A more robust alternative involves registering the fields dynamically using register_post_meta within the acf/register_rest_api_fields hook context, ensuring the data is cached efficiently and accessible without runtime database overhead for every request. This method integrates seamlessly with how WordPress handles meta queries, allowing you to filter posts by ACF values directly in GraphQL or REST queries.
When implementing this solution, be mindful of performance implications. Fetching all field groups for every post response can introduce latency if the list is massive. In high-traffic scenarios, consider caching the ACF object generation or limiting the exposure to specific post types rather than global defaults. Additionally, ensure that sensitive fields within these groups are excluded from the public API response using conditional logic within your filter to prevent data leakage.
For developers looking to streamline this process in a Laravel ecosystem or headless WordPress setup, integrating these hooks into a dedicated plugin or theme snippet is recommended. This keeps your core application clean while maintaining full control over what data is exposed via the API.