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
| Field | Type | Required? | |
|---|---|---|---|
name | string | yes | The client name, as it appears on the listing |
email | string | yes ⁽¹⁾ | The email that receives the enquiries |
phone1 | string | yes ⁽¹⁾ | The contact phone number |
phone2 | string | no | A second phone number |
mobile | string | no | The mobile (on MercadoLibre it goes as the second phone) |
address | string | no | The address |
zipcode | string | no | The postcode |
country | number | no | The client's country |
branch | object | no | The branch — see below |
branches | array | no | Several 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.
| Field | Type |
|---|---|
name phone1 phone2 mobile email address zipcode | string |
zone0 zone1 zone2 zone3 | number — 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" }
| Field | Type | Required | What it is |
|---|---|---|---|
branchRef | string | yes | Your reference for that branch. You choose it and it never changes |
mapapropBranchId | number | no | The 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 declare | What happens |
|---|---|
branchRef + data, no mapapropBranchId | it is created in your account and we return the id |
branchRef + mapapropBranchId | it already exists: only the link is stored, nothing is touched |
branchRef alone, no data | nothing 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
| Code | What happened | What to do |
|---|---|---|
201 | The record was created | — |
200 | It already existed (created: false) or it was reactivated (revived: true) | — |
400 | name, email or phone1 is missing; country is not a positive integer; branch is not an object; or a text exceeds 256 characters | The field comes in field |
400 | The clientRef is missing | Send the x-client-ref header: without it we do not know which client the record belongs to, and we do not guess |
401 | Token missing or invalid | — |
403 | Your token does not have the property-api-create scope | Write to us to enable it |
Related
- Clients — what the record is and all the methods
GET·PUT·DELETE- Uploading properties — the next step