Skip to content

Headless Mode and REST API for Your Own Front End and AI-Built Websites

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 REST API in JSON format.

  • 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.
  • Connect or create an AI website. If you have already created your website with an AI website builder such as Lovable, Bolt, v0 or Base44, a prompt connects it to your properties without rebuilding it. Likewise, you describe a new 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 under Connecting an AI website to your CRM software, with guides for Lovable, Bolt, v0, Base44 and Replit. If you maintain your website in the EmDash CMS, the properties appear there on server-rendered pages. With ChatGPT, Claude, Gemini or Cursor, you have the website programmed as a project of its own, with a framework of your choice, optionally starting from our Astro starter.
  • 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.
  • Enquiries land in your CRM software automatically. Contact enquiries from the front end go through the same processing as the contact form of your WordPress website. The e-mail to your CRM software carries an OpenImmo feedback XML attachment, from which the CRM software creates the prospect as a contact and assigns the enquiry to the property. Nobody has to transfer enquiries by hand, and the front end does not need to know the interface of your CRM software.
  • 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.
Diagram: CRM software, WordPress with WP-ImmoMakler and Astro front end, connected by import and REST API

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 REST API reference.

  • 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

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

  1. Enable the interface

    Enable Enable headless interface and save. The endpoints only respond after that.

  2. Note down the access credentials

    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.

  3. Enter the address of your front end

    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.

  4. Adjust the paths

    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}, {object_number}, {object_number_normalized}, {post_id} and {locale} are available.

  5. Enter the allowed origins

    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.

Headless tab with the interface enabled, credentials and front end address

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

  • Pages and posts: You continue to maintain them 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.
Branding and Astro starter sections in the headless tab with logo, colours and design preset

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.

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/{object_number}; the property list and the category pages are built from /properties and /taxonomies.

Always use the object number (object_number) 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 addresses on the front end, every property also states object_number_normalized: the object number in lower case, with every character other than letters and digits replaced by hyphens, so A/1 2 becomes a-1-2. This form needs no encoding in a URL, and /properties/{object_number} finds the property by it as well.

All keys of the interface are in English and the same on every website, regardless of the language of the website and of the CRM software the properties come from: purchase_price instead of kaufpreis, living_area instead of wohnflaeche, rooms instead of anzahl_zimmer. Each data field also states under source_key the name that WordPress and the OpenImmo format use and that you know from the settings and the Customizer. The search parameters are English as well (type, location, price_min); the search still accepts the parameters of your WordPress website’s search form (typ, ort, von-kaufpreis) as aliases, so a filtered address of the property list keeps working unchanged.

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.