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
| Field | What it is |
|---|---|
clientRef | Whose listing this is. It comes back in the response so you don't have to remember which header you asked with |
total | How many came in THIS page, not how many the client has |
nextToken | What you ask the next page with. If it doesn't come, you are done — see the note below |
items[].paId | The id you use to fetch it, edit it and publish it |
items[].code | Your code, the one you sent in the object. It is the key you match against your own database |
items[].title | The title, so the listing reads on its own without cross-referencing anything |
items[].status | active, or deleted if you removed it (only shows up with includeDeleted=true) |
items[].deletedAt | When you removed it. It only comes on removed properties — an active one does not carry the field |
items[].images | How 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[].mapaprop | Only 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[].verdictAt | When 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[].portals | One 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
| Field | What it is |
|---|---|
verdict | Whether the object is enough for that portal: ok, fields_complete, out_of_coverage… |
blockers | The 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 |
remoteStatus | What the portal says about the listing. It always comes: null means it was never published |
itemId | The id of the publication on our side |
portalItemId | The id of the listing in the portal, where the portal returns it on publishing |
url | The published listing |
publishedAt · unpublishedAt | When it was published and when it was taken down |
lastError | The 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
| Parameter | Default | What it does |
|---|---|---|
limit | 50 | How 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 |
includeDeleted | false | Includes 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.
| Listing | GET /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 posted | with ?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
| Code | What happened |
|---|---|
200 | The page. If the client has none, total: 0, items: [] and no nextToken |
400 | The x-client-ref header is missing, or the nextToken is not valid ("error": "invalid_next_token") |
401 | Token absent or invalid |
403 | Your 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.
Related
- Query a property — with today's verdict and the images
- Creating properties · Modify · Remove
- Publish — and that is where this listing's
portalscomes from