Mapaprop
DEVELOPING

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:

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" }'

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
phone1stringnoThe contact phone number
phone2stringnoA second phone number
mobilestringnoThe mobile (on MercadoLibre it goes as the second phone)
emailstringnoThe email that receives the enquiries
addressstringnoThe address
zipcodestringnoThe postcode
countrynumbernoThe client's country
branchobjectnoThe branch — see below

name is the only required one: without a name, the listing has no owner. Text fields accept up to 256 characters.

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.

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

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",
    "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 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