Residences
Residences (a hotel, a residence, a building...). A residence collects the properties (units) that belong to
the same structure: property_ids lists them, and each of them gives its residence in residence_id. A property can
belong to no residence. A residence has its own type, address, descriptions, attachments and facilities, those of the
structure as a whole: read them here once instead of repeating them on every property.
Get list of residences
Returns a paginated list of residences, ordered by id ascending (follow _pagination.next_cursor). Requires the API key scope properties:read.
query Parameters
search_nameSearch residences by name
codesOnly the residences with these codes, the ones shown as code (exact match, case-insensitive), comma-separated (codes=A1,B2). At most 50 values, more returns 400. No match gives an empty list; an empty value is the same as no filter. The code is not guaranteed to be unique, so a code can match more than one residence.
paging_limitLimit items returned in response. Must be between 1 and 50
next_cursorGet list of residences › Responses
Get residences list
Get a residence
Requires the API key scope properties:read.
path Parameters
residenceIdGet a residence › Responses
Get a residence
idName of the residence to show. Residences are not translated yet, so it has one entry, in Italian (it); more languages will be added when they are. Always present.
codeCode of the residence, always present. It is not guaranteed to be unique, so use id to refer to a residence. Use the codes query parameter of the list to find the residences with a code.
typeCode of the type of the residence, as listed by GET /api/v1/residence-types (which also gives its name). Omitted when the residence has no type.
Address. Every field can be null when it is not set (or not visible to the API user); depending on the resource a field without a value is null or left out of the response.
property_idsIds of the properties of the residence visible to the API user, in ascending order. Always present, empty when none is visible.
Reserved for custom fields (key → value). Custom fields are not available for residences yet, so it is always an empty object.
Get descriptions of a residence
Requires the API key scope properties:read.
path Parameters
residenceIdGet descriptions of a residence › Responses
Get descriptions of a residence
language^[a-z]{2}$Language, as an ISO 639-1 code of two lowercase letters (it, en). It names the language only, with no region.
textGet all attachments of a residence
Requires the API key scope properties:read.
path Parameters
residenceIdquery Parameters
typeOnly the attachments of this type: images (images that are not panoramic), panoramic_images or file (anything that is not an image). Omit to get all of them. Any other value returns 400.
Get all attachments of a residence › Responses
Get all attachments of a residence
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · attachment_type="file" · requires: id, mime_type, url | |
| type = object · requires: id, mime_type, url +1 more |
idmime_typeurlattachment_typeAdd an attachment to a residence
Needs the privilege to create and edit properties (immobili_crea) as well as the one to read them; without it 403. Requires the API key scope properties:write.
path Parameters
residenceIdAdd an attachment to a residence › Request Body
filetypeAttachment type. Must be the code of an attachment type
visibilitynoteAdd an attachment to a residence › Responses
Upload an attachment of a residence
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · attachment_type="file" · requires: id, mime_type, url | |
| type = object · requires: id, mime_type, url +1 more |
idmime_typeurlattachment_typeGet an attachment of a residence
Requires the API key scope properties:read.
path Parameters
residenceIdattachmentIdGet an attachment of a residence › Responses
Get an attachment of a residence
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · attachment_type="file" · requires: id, mime_type, url | |
| type = object · requires: id, mime_type, url +1 more |
idmime_typeurlattachment_typeDelete an attachment of a residence
Needs the privilege to create and edit properties (immobili_crea) as well as the one to read them; without it 403. Requires the API key scope properties:delete.
path Parameters
residenceIdattachmentIdDelete an attachment of a residence › Responses
Attachment deleted
Get facilities of a residence
Requires the API key scope properties:read.
path Parameters
residenceIdGet facilities of a residence › Responses
Get facilities of a residence
facilityCode of the facility in the catalog GET /api/v1/facilities (e.g. adatto_disabili).
statusWhether the facility is included (included), to be paid for (paid) or not allowed (prohibited).

