BETA

Look up a client

GET /property-v1/customers

Returns the record of the clientRef you ask for.

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

200 response:

{
  "customer": {
    "customerId": "MAPAPROP-PA-000002",
    "clientRef": "cliente-42",
    "mapapropCustomerId": 11431,
    "createdAt": "2026-10-01T02:54:30.980Z",
    "updatedAt": "2026-10-01T02:54:30.980Z",
    "name": "Inmobiliaria Modelo",
    "phone1": "2234567890",
    "email": "contacto@inmobiliaria-modelo.test",
    "country": 1,
    "branch": { "name": "Sucursal Centro", "phone1": "2234567891" }
  }
}

If you have not declared anything yet, it responds 404 — not a 200 with an empty record, so that you can tell "it does not exist" from "it exists and is incomplete".

The record's three identifiers, and they are not the same thing

FieldWhose it isWho changes it
clientRefyours — how you identify your client. Travels in the x-client-ref headeryou, whenever you want
customerIdPropertyAPI's — issued when the record is created, and the one we always returnnobody
mapapropCustomerIdthe Mapaprop account this record is linked tonobody: it is fixed at creation

mapapropCustomerId only shows up if the record is linked to a Mapaprop account. It is taken from your token when the record is created, so you do not send it in the body and the PUT does not change it. If your token does not represent a Mapaprop account, the field does not come — and that is normal, not a missing value.

Your client's account on each portal, free

If your client has any portal connected, the response also carries a portals block alongsidecustomer, with who they are on each one and the last thing we read from their account:

{
  "customer": { "...": "..." },
  "portals": {
    "zonapropapi": {
      "status": "active",
      "portalAccountId": "MAPAPROP-PA-000002",
      "plans": [
        { "plan": "DESARROLLOS_HOME", "planTotal": 5,  "planAvailable": 1 },
        { "plan": "HOME",             "planTotal": 80, "planAvailable": 31 }
      ],
      "plansReadAt": "2026-10-07T19:32:22.698Z",
      "plansStale": true,
      "quota": { "remaining": 1333, "limit": 1500, "readAt": "2026-10-07T19:33:43.600Z" }
    },
    "argenpropapi": {
      "status": "active",
      "portalAccountId": "310578",
      "plans": null,
      "plansReadAt": null,
      "plansStale": false,
      "quota": null
    }
  }
}

This read costs nothing: it comes from our system, not from the portal.

FieldWhat it is
statusactive if the connection is in force. revoked if it was disconnected
portalAccountIdWho your client is on that portal. It is also emitted when the connection is revoked: it is the piece that lets you reconnect them to the same account
plansThe publication plans and how many are still free. null if we never read them
plansReadAtWhen that list is from
plansStaletrue = there was a publication or a takedown after that read
quotaThe monthly calls your client has left on the portal

portalAccountId means different things depending on the portal, and the portal decides. On Argenprop it is the identifier the portal gave the agency (310578). On Zonaprop it is the code we assign (MAPAPROP-PA-000002), because there the code is set by us when the client is created.

Not every portal reports plans or an allowance, because not all of them work the same way. Argenprop does not work with plans: it works with points from a subscription that your client splits across their listings to position them. That is why plans and quota are always null there — they do not describe what Argenprop has.

🆕 But the points balance CAN be queried, in paying for position: that is where you get how many are left, with the date we read it. You do get portalAccountId and status for all of them. Details: Argenprop.

Look at plansReadAt and plansStale before deciding with plans. They are a copy, not the live state: if your client publishes from the portal's own panel, their allowance drops and we do not find out.

When plansStale is true and you care about the exact number, refresh it against the portal — that does spend a call.

plans: null and plans: [] do not mean the same thing: null is "we never read them"; [] is "we read them and there is none with room".

The block is omitted if your client has no connections, and it only carries the portals your token is enabled for — just like GET /connections.

The two 404s

Your "does it exist?" check does not change: both are 404. What changes is the body, because the fix is different in each case.

You never declared it

{
  "error": "No hay una inmobiliaria declarada para este clientRef",
  "detail": "Creala con POST /property-v1/customers antes de dar de alta propiedades."
}

→ POST, and you get a new customerId.

You deactivated it

{
  "error": "customer_deleted",
  "detail": "Esta inmobiliaria fue dada de baja el 2026-10-01T18:22:04.117Z. Volvé a crearla con POST /property-v1/customers: recupera el mismo customerId (MAPAPROP-PA-000002) y sus propiedades.",
  "deletedAt": "2026-10-01T18:22:04.117Z",
  "customerId": "MAPAPROP-PA-000002"
}

→ the same POST reactivates it, and it recovers the customerId it already had.

If your integration tells the two cases apart, look at the error field: customer_deleted tells you the client existed and that you will recover its id. The other 404 tells you that you will get a new one.

Response codes

CodeWhat happened
200The record
400The x-client-ref header is missing
401Token missing or invalid
403Your token does not have the property-api-read scope
404There is no usable record — the two cases above