Getting started with Express API

Build your own website or app —running on your own server, with your web and your design— using the Mapaprop Express API to serve your account's inventory (properties, developments, branches, zones). It is a developer API: the site or system is yours and you consume it from the outside; Mapaprop does not host it. All methods operate on the account that owns the token —your inventory and your configuration—: the scope comes from the access token, it is not sent as a parameter. Queries submitted by your visitors enter your Mapaprop Inbox.

1. Obtain your access token

The Express API works with your Mapaprop API Token (not with third-party OAuth2 app registration). If you're already a Mapaprop Pro+ customer (or higher), you activate your token with one click from your account —Settings > API Token— and use it as Authorization: Bearer {token}. The token does not expire (unless you regenerate or deactivate it). Step-by-step guide: Express API Token.

There's no need to register any application or request authorization: the token is self-service for customers with a Pro+ plan or higher. The OAuth2 flow from Getting Started is for portals and third parties, not for this API. If your integration runs in the browser, activate the CORS scope from the same screen.

2. How your site is resolved

Which ones need a site and which ones don't

Only ten services need a site: those that return site content —settings, settings-v2, design, features, menus, pages, pages/{url}, pages/static/{pageId}, posts, posts/{url}—. They are meant to build your site with content you manage from Mapaprop.

All inventory services work without a site: they are resolved solely with the account that owns the token. These are properties, properties/{propertyHash}, developments, development/properties, branches, types, operations, zones, zones/suggestions and messages (inquiry submission).

If your integration only consumes inventory —the typical case of your own site on WordPress or another CMS, where you manage the content there— you don't need any site in Mapaprop and you will never see the CUSTOMER_WITHOUT_WEBSITE error.

The exception is seller-submissions: it does require a site in your account, because the submission is associated with it. If your token has no bound site and you don't send websiteId in the body either, the response is NOT_FOUND.

How the site is chosen

For the ten content services you don't need to send which one: your site is bound to your API Token from your Mapaprop account, and all of them use it automatically. You bind it —or create one— from Settings > API Token, in the Website Function card.

The site is resolved as follows:

Your token already has a bound site → that one is used. This is the normal case and you don't have to do anything.
Your token has no bound site and you have a single active site → that one is used.
Your token has no bound site and you have more than one active site → you must indicate which one with the websiteId parameter. Example: GET /api/action/express-v1/settings-v2?websiteId=1234. Only a websiteId that is one of your own active sites is accepted (it is validated against your token's account); any other is rejected.

A site counts as active from the moment you create it in your account. It does not need to have a domain pointed at it or any content loaded.

Previously, when the site could not be resolved, these services returned 200 with empty content, without warning. They now return a clear error (see below).

Errors when resolving the site

On error, the response is a JSON with the fields error (a stable code, ideal for your integration) and description (human-readable text), with status HTTP 400:

{
  "error": "AMBIGUOUS_WEBSITE",
  "description": "El cliente tiene mas de un sitio activo. Especifique el parametro websiteId."
}

`error`	When it occurs	`description`
`CUSTOMER_WITHOUT_WEBSITE`	Your account has no active site in Mapaprop.	`El cliente no tiene un sitio web activo en Mapaprop.`
`AMBIGUOUS_WEBSITE`	You have more than one active site and did not provide a valid `websiteId`.	`El cliente tiene mas de un sitio activo. Especifique el parametro websiteId.`

For your error-handling logic, match against the error field (the code), which is stable. The description is text meant to be read.

3. Basic flow

What you build with this API is your site with your inventory. Everything resolves from the token: there is no need to send which account it is about.

1 · Fetch the catalogs, once

types and operations return the types and operations you have in use, not the full country catalog. That lets you build the search filters without offering options that would return nothing. zones does the same with the zones where you have properties, and zones/suggestions resolves the autocomplete as the visitor types.

They rarely change: fetch them at start-up and cache them.

2 · List and search

properties is the listing, with from and size for pagination.

The maximum is 20 per call, and the defaults are not the same everywhere: properties returns 10 when you omit size, while developments and development/properties return 7. Asking for more than 20 is not silently trimmed: it returns an error that says so.

3 · Render the listing page

properties/{propertyHash} returns the full property.

4 · Developments

developments lists your projects. Each one carries the ids of its units in developmentProperties, and with those ids you request the units from development/properties.

The parameter is propertyIds, plural, and it is required: without it the call fails. And the endpoint filters by the ids you send — it does not resolve "the units of development X". If you pass the development id instead of the ones in developmentProperties, it returns the development itself and nothing in the response tells you.

For the development fields — the 10 the agency declares and the developmentStats block with the figures derived from the units — see the developments page.

5 · Receive enquiries

messages sends your visitor's enquiry, and it lands in your Mapaprop Inbox like any other. If your site also receives properties from prospective sellers, that goes through seller-submissions — the only inventory service that does require a site (see above).

6 · Site content, if you manage it from Mapaprop

Only if you use Mapaprop for the content as well as the inventory: settings-v2 (the configuration), design (colors and typography), features, menus, pages and posts.

These are the ones that need a resolved site — which is what the previous section explains. If your content lives in your own CMS, you will never use them.

4. Browse services

GET /api/action/express-v1/settings-v2

GET /api/action/express-v1/design

GET /api/action/express-v1/branches

GET /api/action/express-v1/menus

GET /api/action/express-v1/types

GET /api/action/express-v1/operations

GET /api/action/express-v1/pages

GET /api/action/express-v1/pages/{url}

GET /api/action/express-v1/pages/static/{pageId}

GET /api/action/express-v1/posts

GET /api/action/express-v1/posts/{url}

GET /api/action/express-v1/zones

GET /api/action/express-v1/zones/suggestions

GET /api/action/express-v1/properties

GET /api/action/express-v1/development/properties

GET /api/action/express-v1/developments

GET /api/action/express-v1/properties/{propertyHash}

POST /api/action/express-v1/messages

POST /api/action/express-v1/seller-submissions

GET /api/action/express-v1/features

GET /api/action/express-v1/settings deprecated