BETA

The property JSON object

This is the reference for what you send: what fields the property object has, which are required, what values each one accepts, and how to say "I don't have this piece of data."

This is a reference for the object, not for an endpoint. To understand how a property is identified —why type and operation are stable keys and where their values come from— read The property model first.

The object you send

This is the complete object. Below is what's required, what's optional, and what values each field accepts.

{
  "code": "DEV-V3-909181",
  "type": 1,
  "operation": 2,
  "title": "Hermoso departamento luminoso con excelente ubicación y amenities completos",
  "address": "Av. Santa Fe 4271",
  "mapLatitude": -34.5828,
  "mapLongitude": -58.4206,
  "zone0": 1,
  "zone1": 1,
  "zone2": 46,
  "description": "Excelente propiedad ubicada en zona premium con fácil acceso a transporte público, comercios y servicios. Ideal para vivir o invertir.\n\nCuenta con todos los servicios y amenities modernos. Perfecta para familias o inversión.\n\nUbicación estratégica con fácil acceso a centros comerciales, escuelas y transporte público.",
  "descriptionFormatted": "Excelente propiedad ubicada en zona premium con fácil acceso a transporte público, comercios y servicios. Ideal para vivir o invertir.\n\nCuenta con todos los servicios y amenities modernos. Perfecta para familias o inversión.\n\nUbicación estratégica con fácil acceso a centros comerciales, escuelas y transporte público.",
  "zipcode": "1425",
  "betweenStreets": "Entre Av. Pueyrredón y Av. Coronel Díaz",
  "urlWebExternal": "https://ejemplo-inmobiliaria.com/propiedad-dev",
  "conditions": "Contado",
  "yearsOld": 16,
  "totalFloors": 16,
  "apartmentsPerFloor": 3,
  "floors": 2,
  "buildingArea": 126,
  "landArea": 189,
  "ambiences": 2,
  "rooms": 3,
  "dependencies": 1,
  "bathrooms": 1,
  "toilettes": 2,
  "garage": 2,
  "currency": "USD",
  "price": 142410,
  "zone3": 0,
  "rented": false,
  "sold": false,
  "reserved": false,
  "suspended": false,
  "occupancy": null,
  "images": [
    {
      "url": "https://cdn.ejemplo.com/propiedades/909181/foto-1.jpg",
      "description": "Imagen principal",
      "main": true
    },
    {
      "url": "https://cdn.ejemplo.com/propiedades/909181/foto-2.jpg",
      "description": "Imagen 2",
      "main": false
    },
    {
      "url": "https://cdn.ejemplo.com/propiedades/909181/foto-3.jpg",
      "description": "Imagen 3",
      "main": false
    }
  ],
  "blueprint": {
    "url": "https://cdn.ejemplo.com/propiedades/909181/plano.jpg"
  },
  "videos": [
    {
      "source": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "description": "Recorrido"
    }
  ],
  "prices": {
    "expensesCurrency": "ARS",
    "expensesPrice": 500,
    "taxCurrency": "ARS",
    "taxPrice": 200,
    "paymentPeriod": 1
  },
  "altPrices": [
    {
      "description": "Alquiler por semana",
      "currency": "ARS",
      "price": 100000
    }
  ],
  "attributes": [
    {
      "locale": "es_AR",
      "country": "ar",
      "id": "accessible",
      "label": "Accesible",
      "group": "propertyAttribute",
      "group_sub": "label",
      "group_subtype": "ammenities",
      "type": "bool",
      "key_legacy": "accessible",
      "selected": true,
      "status": true
    },
    {
      "locale": "es_AR",
      "country": "ar",
      "id": "statusAverage",
      "label": "Estado Regular",
      "group": "propertyStatus",
      "group_sub": "status",
      "type": "list",
      "key_legacy": "8",
      "value": 8
    },
    // … and 42 more entries, one per property attribute
  ],
  "publication": { … }  // per-portal publishing configuration — see its own page
}

Photos, floor plan, videos, and accessory prices

They go in the same JSON: you send a single object.

BlockShapeNote
imageslist of {url, description, main}the URL, not the file: the binary doesn't travel in a JSON
blueprint{url}only one per property
videoslist of {source, description}source is the YouTube or Matterport URL
prices{expensesCurrency, expensesPrice, taxCurrency, taxPrice, paymentPeriod}expenses and taxes, amounts as numbers
altPriceslist of {description, currency, price}alternative prices

⚠️ The property's price and currency don't go here: they're fields of the property itself and are already above.

All five blocks are registered in the same call. You send the object once and the photos, the blueprint, the videos, the expenses and the alternative prices are saved with the property — there is no second call per accessory.

And here the rule above has a useful consequence: since price does not go inside prices, registering the expenses cannot change the property's price.

The attributes array

Each entry describes one piece of data. There are two families: the property's status (propertyStatus) and its attributes — amenities, orientation, heating type, and so on (propertyAttribute).

[
  {
    "locale": "es_AR",
    "country": "ar",
    "id": "accessible",
    "label": "Accesible",
    "group": "propertyAttribute",
    "group_sub": "label",
    "group_subtype": "ammenities",
    "type": "bool",
    "key_legacy": "accessible",
    "selected": true,
    "status": true
  },
  {
    "locale": "es_AR",
    "country": "ar",
    "id": "statusAverage",
    "label": "Estado Regular",
    "group": "propertyStatus",
    "group_sub": "status",
    "type": "list",
    "key_legacy": "8",
    "value": 8
  }
]

The value you send is key_legacy: it's the same across every country. The id, the label, and the value come from your country's catalog — where to get them is further below.

attributes is required, and an empty list is valid. If the property has no attributes, send "attributes": []; what you can't do is omit the key.

The bag is checked against the catalogue

Every entry is looked up in the catalogue of the property's country, and whatever does not add up comes out in object.contract of the checker:

WhatWhat we tell youDoes it invalidate the object?
the id does not exist in that countryrule: unknown — it is ignored, the property is still savedno
the key_legacy is not the catalogue'srule: attribute_value, with the right oneyes
a bool attribute with a selected that is not a booleanrule: attribute_valueyes

The catalogue is not the same across the 15 countries. The key sets are subsets of one another: what exists in Argentina may not exist in Paraguay or Brazil. Request the catalogue with the property's country, not with any country — it is the most common cause of an attribute that does not get published.

An invented id does not break the creation: it is ignored. But that feature travels to no portal, and that is not something you notice by looking at the property — which is why it is reported.

customerSource — where the customer came from

Every response that includes the customer block also includes, at the root, where it came from:

ValueWhat it means
accountThis is your record, read with your clientRef. The normal case
placeholderYou didn't declare a record and this is filler. This only happens on /verify — creating without a record responds 400, it doesn't fill in. It's fixed with POST /customers
frozenThe snapshot that property was created with (returned by GET and PUT). It's not your record as of today, and that's deliberate: this way GET tells you with what data that property was published

It's at the root and not inside customer on purpose: inside it would mix with the fields you declared.

The customer is NOT part of this object

The customer is declared once, separately, and its properties inherit it.

👉 Customers — the POST /property-v1/customers, its fields, the customerId we return to you, and the branch.

⚠️ If you send customer inside this object, it's ignored — same as propertyId, customerId, and branchId. And without a declared customer, the creation call responds 400 with rule: account_required.

publication — how it gets published

Inside the same object travels a publication key with what each portal needs from your account and your publishing choices. It's not a field of the property: it's how you publish it.

{
  "publication": {
    "api": {
      "argenprop": {
        "visible": true,
        "token": "<tu-token-de-argenprop>"
      },
      "zonaprop": {
        "plan": {
          "plan": "SUPERDESTACADO"
        },
        "token": "<tu-token-de-zonaprop>"
      },
      "cabaprop": {
        "token": "<tu-token-de-cabaprop>"
      },
      "mercadolibre": {
        "listingTypeId": "gold_special",
        "condition": "used",
        "token": "<tu-token-de-mercadolibre>"
      }
    }
  }
}

The full reference is at The publication key.

Required fields

There are 26, plus the attributes array. Everything else is optional.

Most are standalone fields:

FieldTypeRule
codestring^[A-Za-z0-9._-]{1,30}$
titlestring1–150 characters
descriptionstringat least 1 character
priceinteger1 or more
currencystringUSD or ARS
typeinteger—the type id — pa_key_legacy of the type group in the catalog
operationinteger—the operation id — pa_key_legacy of the operation group
zone0integerone of the 15 countriescountry. The list comes from the catalogue: if yours is not there, we cannot resolve the type or the operation
zone1integer—province
zone2integer—county or department
addressstringat least 1 character
zipcodestring^[A-Za-z0-9-]{1,10}$
mapLatitudenumber-90 – 90see the warning below
mapLongitudenumber-180 – 180see the warning below
buildingAreainteger0 – 100,000built area, in m²
landAreainteger1 – 10,000,000the TOTAL area of the property, in m² — even for an apartment
ambiencesinteger0 – 50the rooms (living/dining areas)
roomsinteger0 – 50⚠️ these are bedrooms, not rooms
bathroomsinteger0 – 50
toilettesinteger0 – 10
garageinteger0 – 100
floorsinteger0 – 10floors of the unit
totalFloorsinteger0 – 200floors of the building
apartmentsPerFloorinteger0 – 50
dependenciesinteger0 – 10
yearsOldinteger0 – 300age, in years

The type and operation numbers are the same across every country — what changes from one country to another is the label. You'll find them listed in Constants.

zone3 doesn't always exist, and that's why it's optional. Capital Federal zones —Recoleta, Caballito, Palermo— have three levels: the neighborhood is the last one. In those cases send zone0, zone1, and zone2, and leave zone3 out. You'll notice it in the zone catalog: the code comes with three segments instead of four.

The two areas have different floors, and it's on purpose. landArea starts at 1 because every property occupies land; buildingArea accepts 0, because a lot has no construction and declaring it as zero is correct.

Optional fields

FieldTypeRule
zone3integer—locality or neighborhood
betweenStreetsstring—
occupancyinteger1 – 50
soldboolean—closed as a sale — see the note below
rentedboolean—closed as a rental — see the note below
reservedboolean—reserved
suspendedboolean—publication suspended
descriptionFormattedstring—the description with its line breaks; if you don't send it, description is used
conditionsstring—operation conditions — "Cash", "Mortgage-eligible"…
urlWebExternalstring—the property's URL on your own site

🔴 sold · rented · reserved · suspended: ONE status or none, never two — and sold/rented have to be consistent with operation (a sale doesn't close a rental listing).

Both rules are rejected by the verifier, with details on what to fix: the statuses a property travels with.

mapLatitude and mapLongitude are required, and they go as a number, not as text. They're in the table above: if you omit them or send them as null, the property doesn't pass validation. Geocode the address before posting.

And 0 is not "no coordinate": it's a real point in the Gulf of Guinea, so a property with 0, 0 gets published there. Validation accepts it —it's a valid number— but the listing comes out wrong.

How to say "I don't have this piece of data"

An optional field you don't have is sent as null or not sent at all: for us it's the same.

What's not the same is sending 0. A 0 in an area, in the age, in the number of occupants, or in a coordinate is stored as the number zero — that is, as a piece of data.

If a field does not exist, we tell you

If you send a key that is not in this contract, it does not go anywhere — and from now on we report it in object.contract, in the response of both the POST and the verify:

{
  "object": {
    "contract": [
      { "field": "metrosCuadrados", "rule": "unknown", "value": 55,
        "detail": "no existe en el contrato del objeto: se ignora y no se guarda" },
      { "field": "prices.abl", "rule": "unknown", "value": 300,
        "detail": "no existe en el contrato: prices acepta expensesPrice, expensesCurrency, taxPrice, taxCurrency, paymentPeriod" }
    ]
  }
}

It also applies inside the blocks (prices, altPrices, images, blueprint, videos), and in a list we tell you which item: images[1].rotacion.

It is a report, not a rejection: valid does not change and the property is stored anyway. It is there so you do not send a field for months believing it arrives.

⚠️ A key existing in the Mapaprop object does not make it part of this contract. If you send accessible, we will report it: the PropertyAPI contract is the one that rules.

The blocks have rules of their own

The subfields of each block are validated just like the fields above: type, allowed values, minimums.

blocksubfieldrule
pricesexpensesPrice · taxPriceinteger, minimum 0
pricesexpensesCurrency · taxCurrencyUSD or ARS — independent of the price currency
pricespaymentPeriod1 = day · 2 = month · 3 = year
altPrices[]priceinteger, minimum 1
altPrices[]currencyUSD or ARS
images[] · blueprinturlrequired
videos[]sourcerequired

The zone has to exist

zone1, zone2 and zone3 are validated against the catalogue, and so is their hierarchy: a zone2 that exists but hangs from another zone1 is rejected just like an invented one. A zone that does not exist leaves the property out of every search by location, so we do not let it in.

To leave a level undeclared, send 0 — it is the same convention as the 4-segment code, where the last segment is 0 when there is no third level. -1 and omitting the key mean the same thing.

You do not need to post to find out. The checker looks the zone up in the catalogue and tells you beforehand, for free: you will see it in object.contract as zone2 with rule: not_found, and the value carries the 4-segment code to look it up with.

Where the values come from

The enumerated fields —type, operation, status, orientations, amenities— don't have a fixed list on this page, on purpose: they depend on the country and change when a new one is added.

You request them here:

GET /property-attributes?country=AR

See the full endpoint reference

It returns, for that country, everything it accepts: the text key (pa_key), the value you send (pa_key_legacy), the translated label (pa_label), and the family (pa_group_subtype).

Request the catalog for the property's country, not just any one: a type can be enabled in Argentina and not in Peru.

And keep this in mind: we don't validate values against the catalog. A value that country doesn't use isn't rejected: it's stored, and the property ends up published with the wrong data. The catalog isn't a suggestion — it's the only way to know what to send.

Verify before publishing

You can send your object and see what it produces, without creating anything:

POST /property-v1/properties/verify

It tells you whether the object is valid, which rules it breaks field by field, and what would happen on each portal. It's the same body as the creation call, without the write.

Your token needs the property-api-verify scope. Without it, the response is 403. Request it along with your access credentials.

See also