BETA

Declare a client

POST /property-v1/customers

It is the first step of everything: with no record you cannot upload a property, request a connection link, or publish.

The clientRef says which client the record belongs to, same as everywhere else in the API: it goes in the x-client-ref header (recommended), in the query or in the body.

The minimum that works is the name and the contact details:

curl -X POST https://property-api.mapaprop.com/property-v1/customers \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-client-ref: cliente-42" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Inmobiliaria Modelo",
        "email": "contacto@inmobiliaria-modelo.test",
        "phone1": "2234567890" }'

And the complete record, with everything that gets published on the listing:

{
  "name": "Inmobiliaria Modelo",
  "phone1": "2234567890",
  "mobile": "2235550000",
  "email": "contacto@inmobiliaria-modelo.test",
  "address": "Av. Colón 1234",
  "country": 1,
  "branch": {
    "email": "centro@inmobiliaria-modelo.test",
    "phone1": "2234567891",
    "name": "Sucursal Centro",
    "address": "San Martín 2500"
  }
}

201 response:

{
  "created": true,
  "customer": {
    "customerId": "MAPAPROP-PA-000002",
    "clientRef": "cliente-42",
    "createdAt": "2026-10-01T02:54:30.980Z",
    "updatedAt": "2026-10-01T02:54:30.980Z",
    "name": "Inmobiliaria Modelo",
    "phone1": "2234567890",
    "mobile": "2235550000",
    "email": "contacto@inmobiliaria-modelo.test",
    "address": "Av. Colón 1234",
    "country": 1,
    "branch": {
      "name": "Sucursal Centro",
      "phone1": "2234567891",
      "email": "centro@inmobiliaria-modelo.test",
      "address": "San Martín 2500"
    }
  }
}

The fields

FieldTypeRequired?
namestringyesThe client name, as it appears on the listing
emailstringyes ⁽¹⁾The email that receives the enquiries
phone1stringyes ⁽¹⁾The contact phone number
phone2stringnoA second phone number
mobilestringnoThe mobile (on MercadoLibre it goes as the second phone)
addressstringnoThe address
zipcodestringnoThe postcode
countrynumbernoThe client's country
branchobjectnoThe branch — see below
branchesarraynoSeveral branches, each with its branchRef — see below

⁽¹⁾ email and phone1 count on the client or on its branch — there is no need to repeat them. If you declare only the branch, having them there is enough.

Text fields accept up to 256 characters.

Why email and phone1 are required here and not when publishing. They are the contact details published on every listing: without them, the portal has nowhere to send the client's enquiries.

You are told in this call — the only one where you are looking at the client's details — instead of three steps later, when POST /publication can no longer find them.

The key names are the same ones the property object uses, so the block you were already building works as is. What changed is where you send it: here once, instead of on every upload.

The branch is optional

If you do not send branch, the branch inherits the client's details. It is not a convenience of ours: it is what Mapaprop does when an account is created, and it is why 96 out of every 100 agencies have a single branch with the same details.

The inheritance is field by field, not all or nothing: a branch that declares only its name keeps the client's phone number and email. That is why declaring it does not force you to repeat the rest.

FieldType
name phone1 phone2 mobile email address zipcodestring
zone0 zone1 zone2 zone3number — the zone codes

Several branches: branches

If your client has more than one office and you want each property published with the data of its own, declare them in branches. Each one carries a reference you choose (branchRef), and it is with that reference that the property later says which one it wants:

{
  "name": "Inmobiliaria Lopez",
  "email": "info@lopez.com",
  "phone1": "3414445566",
  "branches": [
    { "branchRef": "centro", "name": "Centro", "email": "centro@lopez.com", "phone1": "3414445566" },
    { "branchRef": "norte",  "name": "Norte",  "email": "norte@lopez.com",  "phone1": "3415556677" }
  ]
}

And when creating the property:

{ "canonical": { }, "portals": ["zonapropapi"], "branchRef": "norte" }
FieldTypeRequiredWhat it is
branchRefstringyesYour reference for that branch. You choose it and it never changes
mapapropBranchIdnumbernoThe branch's id in Mapaprop, if your client has an account — see below

The remaining fields are the same as branch. Up to 50 branches per client.

The reference has to be unique within the client: two branches with the same branchRef are rejected, because then the property could not say which one it wants.

branch and branches coexist. If you were already using branch, you do not have to change anything: it keeps working the same, and a property that sends no branchRef publishes with it.

If you declare branches and do not declare branch, every property has to send its branchRef: with no default branch there is no way to know which one you want, and we do not choose for you.

If your client has a Mapaprop account (or if it is you)

The simplest path: declare nothing. If the branch already exists in Mapaprop, send its branchId as branchRef when you create the property and that is it:

{ "canonical": { }, "branchRef": 777 }

That number is the one you see in your account, and you read it with GET /branches. There is no need to declare it on the record or to give it a name of your own.

Giving it YOUR name is optional, and it helps if your code would rather talk about "centro" than a number:

{ "branches": [ { "branchRef": "centro", "mapapropBranchId": 777 } ] }

Then their branches already exist and they edit them in Mapaprop. In that case do not repeat their data here: declare only the link between your reference and their real id, which you can read with GET /branches:

{ "branches": [ { "branchRef": "centro", "mapapropBranchId": 777 } ] }

The contact data of that branch comes from Mapaprop, not from what you declare here. That is what keeps two versions of the same phone number from existing, with one of them going stale.

And if they do not exist in Mapaprop yet, we create them

This is for a Mapaprop customer automating his own account (the Property API add-on). If you declare a branch with its data and no mapapropBranchId, we create it in your account and give you back its id, already linked to your reference:

{
  "branches": {
    "created": [ { "branchRef": "norte", "mapapropBranchId": 779 } ],
    "failed": []
  },
  "customer": { "…" }
}

From then on that branch is just another one of your account: you see it in Mapaprop, you edit it wherever you like, and your properties pick it with branchRef: "norte".

What you declareWhat happens
branchRef + data, no mapapropBranchIdit is created in your account and we return the id
branchRef + mapapropBranchIdit already exists: only the link is stored, nothing is touched
branchRef alone, no datanothing is created — it would be an empty branch

If one fails, the rest are still created. Each branch is its own operation: failed tells you which ones did not make it and why — your plan's branch limit, a zone that does not exist, an invalid field. You fix those and repeat the PUT: the ones already created are not duplicated.

This does not apply if your clients have no Mapaprop account. There their branches live on the record and there is nothing to create anywhere else — which is the case for most integrators.

Repeating the POST is safe

A POST on a client that already exists does not issue another id nor overwrite the details: it returns the record that is there with created: false and status 200. That makes a retry after a timeout safe.

To change the details there is the PUT, which never touches the id.

And it reactivates a deactivated client

If the client was deactivated, the same POST reactivates it. 200 response with revived: true:

{
  "created": false,
  "revived": true,
  "customer": {
    "customerId": "MAPAPROP-PA-000002",
    "clientRef": "cliente-42",
    "name": "Inmobiliaria Modelo",
    "email": "contacto@inmobiliaria-modelo.test",
    "phone1": "2234567890",
    "revivedAt": "2026-10-02T11:05:41.882Z"
  }
}

It comes back with the same customerId, so their published listings are still theirs. The details you send in that POST are the ones that remain.

Response codes

CodeWhat happenedWhat to do
201The record was created—
200It already existed (created: false) or it was reactivated (revived: true)—
400name, email or phone1 is missing; country is not a positive integer; branch is not an object; or a text exceeds 256 charactersThe field comes in field
400The clientRef is missingSend the x-client-ref header: without it we do not know which client the record belongs to, and we do not guess
401Token missing or invalid—
403Your token does not have the property-api-create scopeWrite to us to enable it