Headless Mode with Your Own Front End

PLUS WP-ImmoMakler can not only display your properties itself, it can also hand them over to a separate website. In headless mode, WordPress with WP-ImmoMakler remains the back end: it receives the transfers from your CRM software, manages images and contact persons, and handles contact enquiries. A separate front end, for example a website built with Astro or created with an AI website builder, takes care of the presentation and reads the data through a JSON interface.

What headless mode is for

Fast, search-engine-friendly websites. A statically built or edge-rendered front end delivers finished HTML pages without the detour through PHP and the database.
Create the front end with AI. With AI website builders such as Lovable, Bolt, v0 or Base44, you describe your website in your own words and the builder creates the front end. WP-ImmoMakler provides the technical foundation: the import from your CRM software, the property data through the interface, contact enquiries with spam protection and their forwarding to your CRM software. How to connect an AI website builder to the interface is described in the API reference.
Your own design without theme limits. The front end designs the property list and detail view freely; WP-ImmoMakler supplies the data in the order and with the labels from your settings.
WordPress stays the administration. Your team keeps maintaining texts, pages and posts in the familiar back end; imports, spam protection and the forwarding of enquiries to your CRM software continue to work unchanged.

What the interface delivers

The interface outputs the same properties as your WordPress website. Reference properties, archived properties, properties hidden beyond the licence limit and hidden building projects are left out unless you explicitly request them. Each property comes with:

the data fields, areas, prices and the energy certificate with label, display text and raw value, in the order of your Customizer settings,
the description texts as HTML and as plain text,
images and floor plans in all image sizes, documents, videos and virtual tours,
status, marketing type, property type and all other categories,
address and coordinates, as far as they have been released,
the contact person with the fields from your settings,
SEO title, meta description and the schema.org data of the detail view,
the links to the property on your front end as well as to the PDF print view and the QR code on WordPress.

In addition there are your pages and posts from the block editor as a block structure, three menu locations for the front end and the branding settings.

You will find the complete description of all endpoints in the API reference.

Requirements

WP-ImmoMakler PLUS or higher
A WordPress installation that remains reachable at its own address, even when visitors see the properties on the front end in future
A front end that reads the JSON interface, for example an Astro website or a website created with an AI website builder

Setup

In the back end of your website (wp-admin) under WP-ImmoMakler → Integrations → Headless:

Enable Enable headless interface and save. The endpoints only respond after that.
Note down the base URL of the interface and the API key from the “Access credentials” section. Server applications that call the interface need the key; with the button “Generate new API key” you invalidate the previous key.
Under Address of your front end, enter the public address of the website that displays your properties. All links the interface outputs then point to this front end.
If needed, adjust Path of a property and Path of the property list to the URL structure of your front end. The placeholders {archive_slug}, {slug}, {objektnr_extern}, {post_id} and {locale} are available.
Under Allowed origins, enter the addresses from which forms on your front end may later send contact enquiries. The address of the front end is allowed automatically.

Besides the properties, your front end also needs your pages, menus and your appearance:

Pages and posts continue to be maintained in the block editor. The interface delivers them as a block structure, except for the WP-ImmoMakler template pages.
Menus: In the backend of your website (wp-admin) under Appearance → Menus, assign your menus to the three locations “Headless-Frontend: Hauptnavigation”, “Headless-Frontend: Footer” and “Headless-Frontend: Rechtliches” (German labels, not yet translated). The Navigation section in the headless tab shows which location is already assigned.
Branding: In the Branding section of the headless tab, set the name, tagline, logo, default thumbnail, and primary and accent colour; the interface delivers them to any front end. For the Astro starter, also choose the design preset, font combination and corner rounding in the Astro starter section; another front end only uses them if its developer provides for it. Your front end picks up the values on the next build.

Securing read requests

The read endpoints are public by default, because they only deliver data that your website shows every visitor anyway. As long as your website is not yet public, or if you want to restrict access to your own front end, enable Require an API key for read requests too. Your front end then sends the key in the HTTP header X-ImmoMakler-Key or as a bearer token in the Authorization header.

How a front end uses the interface

A statically built front end first fetches the overview at /properties/manifest during the build. For every visible property it gives the object number, the permalink name and the time of the last change. Comparing it with the previous build shows which detail pages need to be re-rendered and which are dropped. The data of a property is delivered by /properties/{objektnr_extern}; the property list and the category pages are built from /properties and /taxonomies.

Always use the object number (objektnr_extern) as the identifier of a property. The WordPress ID of a property changes with every update from your CRM software, because the import creates the property anew.

For multilingual websites with WPML or Polylang, every property names its language under locale and, under translations, the object number, WordPress ID, permalink name and front-end address of the same property in the other languages, so a front end can build hreflang links and language switchers from them. Under languages, /site lists all languages with code, locale, name and the directory under which the front end serves the language (prefix: / for the default language, /en/ for another one). The directory mirrors the language URLs of WordPress: if the English home page of your WordPress website lives under /en/, the front-end address of every English property, category or page also starts with /en/, and the English property list lives under /en/immobilien/. A language without a directory of its own in WordPress (a separate domain per language, language as a parameter) gets its code as the directory. If the path pattern of a property contains the placeholder {locale}, it is left unchanged, because you then define the language structure yourself.

The locale parameter returns labels, category names and formatting in another language, for example locale=en_GB. This requires the language to be installed in WordPress, selectable in the backend of your website (wp-admin) under Settings → General → Site Language; WordPress only switches to an installed language, otherwise the response stays in the language of the website. WP-ImmoMakler ships its own translations for English, Spanish and French.

The interface describes itself: at /openapi.json it delivers an OpenAPI document for development tools, and at /llms.txt a short description for AI-assisted website builders, see Machine-readable description.

Responses to read requests carry an ETag and cache headers. A front end that sends the ETag back in the If-None-Match header on the next request receives a 304 Not Modified if nothing has changed. A front end running in the browser is best left to the browser cache.