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, your configuration, your leads—: 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 workflow

TBD

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