BETA

List a client's properties

GET /property-v1/properties

Returns the properties you loaded for the clientRef you ask for, 50 at a time, with the publication status of each portal and that of its images. This is the read you use to reconcile your database with ours: what got loaded, how it arrived and where it is published.

curl https://property-api.mapaprop.com/property-v1/properties \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-client-ref: cliente-42"

200 response:

{
  "clientRef": "cliente-42",
  "total": 50,
  "nextToken": "eyJzayI6IlBST1AjMDFNNzVERUhES1FLVzFOSkc0MUZQTkFSM0cjQ0FOT05JQ0FMIiwiaCI6ImE5ZjMxYzAwOGIyZSJ9",
  "items": [
    {
      "paId": "01M75DEHDKQKW1NJG41FPNAR3G",
      "code": "DEV-909181",
      "title": "4-bedroom house in San Lorenzo Chico",
      "status": "active",
      "createdAt": "2026-11-11T13:41:08.147Z",
      "updatedAt": "2026-11-11T14:56:07.327Z",
      "images": { "total": 29, "ready": 29, "status": "ready" },
      "mapaprop": { "propertyId": 2619616, "state": "synced", "images": { "saved": 29, "failed": 0 } },
      "verdictAt": "2026-11-11T14:56:04.956Z",
      "portals": {
        "zonaprop": {
          "verdict": "fields_complete",
          "remoteStatus": "published",
          "itemId": "01M73AB0SYGTFWFB8W2Z19SYP7",
          "portalItemId": 60676441,
          "url": "https://www.zonaprop.com.ar/propiedades/-60676441.html",
          "publishedAt": "2026-11-11T14:56:12.185Z"
        },
        "argenprop": { "verdict": "fields_complete", "remoteStatus": null },
        "mercadolibre": { "verdict": "fields_complete", "remoteStatus": null },
        "cabaprop": { "verdict": "out_of_coverage", "remoteStatus": null }
      }
    }
  ]
}

The fields

FieldWhat it is
clientRefWhose listing this is. It comes back in the response so you don't have to remember which header you asked with
totalHow many came in THIS page, not how many the client has
nextTokenWhat you ask the next page with. If it doesn't come, you are done — see the note below
items[].paIdThe id you use to fetch it, edit it and publish it
items[].codeYour code, the one you sent in the object. It is the key you match against your own database
items[].titleThe title, so the listing reads on its own without cross-referencing anything
items[].statusactive, or deleted if you removed it (only shows up with includeDeleted=true)
items[].deletedAtWhen you removed it. It only comes on removed properties — an active one does not carry the field
items[].imagesHow the images arrived: total the ones you sent, ready the ones that ended up publishable, and the status of the ingest. A ready lower than total is a property that will publish with fewer photos than you expect
items[].mapapropOnly if your account publishes on Mapaprop. How the property ended up in your Mapaprop account: propertyId the id you see it with in the app, state how the creation turned out, and images how many photos were saved and how many were rejected. ⚠️ It is another step than images: that one is our ingest, this one is what Mapaprop accepted
items[].verdictAtWhen the verdict each portal carries was taken. ⚠️ It is from that day: if we fix a mapping afterwards, this does not know about it. For today's verdict use the GET by paId
items[].portalsOne entry per portal this property was mapped against. They are the same ones you see in the GET by paId

portals[].* — the per-portal status

FieldWhat it is
verdictWhether the object is enough for that portal: ok, fields_complete, out_of_coverage…
blockersThe fields that are missing or unusable. It only comes if there are any; the detail of each one is given by the GET by paId
remoteStatusWhat the portal says about the listing. It always comes: null means it was never published
itemIdThe id of the publication on our side
portalItemIdThe id of the listing in the portal, where the portal returns it on publishing
urlThe published listing
publishedAt · unpublishedAtWhen it was published and when it was taken down
lastErrorThe portal's last rejection of this listing, if there was one

The fields in this block —except verdict and remoteStatus— are omitted when they do not exist. A url set to null would claim the listing has no URL; the truth is that it has not been published yet.

The parameters

ParameterDefaultWhat it does
limit50How many per page. The maximum is 50: a higher value is trimmed to 50, and one that cannot be understood is ignored (it does not raise an error)
nextToken—The nextToken from the previous page, as is. It is opaque: do not build it or edit it
includeDeletedfalseIncludes the ones you removed
include—include=canonical adds items[].canonical, the object exactly as you sent it. ⚠️ Until 2026-12-19 it also comes without asking; after that you have to ask for it (API changes)
# the first page
curl "https://property-api.mapaprop.com/property-v1/properties" …

# the next one
curl "https://property-api.mapaprop.com/property-v1/properties?nextToken=eyJzayI6…" …

# 10 at a time, including the removed ones
curl "https://property-api.mapaprop.com/property-v1/properties?limit=10&includeDeleted=true" …

The walk ends when NO nextToken comes. A total lower than your limit does NOT mean you are done.

A page can come short —even empty— and still carry a nextToken: that happens when there are many removed properties in a row and the page is spent skipping them. If you stop the walk on total < limit, you are left without part of the inventory and nothing warns you.

The correct loop is always the same:

let token;
do {
  const r = await get(`/property-v1/properties${token ? `?nextToken=${token}` : ''}`);
  process(r.items);
  token = r.nextToken;      // ← THIS is the condition, not r.total
} while (token);

It is a read of our system: it costs no call from your client's quota in the portal, neither the first page nor the last one. What the portal says about each listing is brought by the status query, which does cost 1 per property.

What it returns beyond the GET by paId

Nothing: the listing brings less. It is a projection meant for walking, not for inspecting.

ListingGET /properties/{paId}
The code, the title and the dates✅✅
The per-portal status (remoteStatus, url, portalItemId)✅✅
The summary of the images✅ {total, ready, status}✅ with the detail of each one
How it ended up in your Mapaprop account✅ mapaprop✅
The object you postedwith ?include=canonical✅
TODAY's verdict, recalculated❌ — the one from the day it was created✅
The detail of each blocker❌ — only the name of the field✅
The detail of the last publication (lastPublish)❌✅

For reconciling, the listing is enough. To understand one property, ask for the property.

Response codes

CodeWhat happened
200The page. If the client has none, total: 0, items: [] and no nextToken
400The x-client-ref header is missing, or the nextToken is not valid ("error": "invalid_next_token")
401Token absent or invalid
403Your token does not have the property-api-read scope

An invalid nextToken —badly copied, cut off, or from another account— is a 400 and not a 200 with the first page: silently serving you the first one would make you walk the same properties forever. If you lost the token, start over without it.

A client with no properties returns 200 with items: [], not a 404. The 404 would mean the client does not exist, and that is answered by the GET of the client.