ImmobiNet API Docs - Auth
PMS ImmobiNet - Token info & User
Timezone: All date-time values in this API are in the Europe/Rome timezone
(UTC+1 in winter, UTC+2 in summer). Dates follow RFC 3339 format with explicit offset,
e.g. 2026-06-26T14:30:00+02:00.
Polling
The APIs are mostly read only (writing is limited to revenue prices, message replies and the attachments of messages and residences). To keep a copy of the data in sync, read the lists again periodically (polling), or let ImmobiNet call you when something changes (see "Change notifications (PUSH)" below) and then read the changed items.
- Pages: lists are paginated with a cursor. Pass
_pagination.next_cursorof a response as thenext_cursorquery parameter to get the next page; it isnullon the last page. A cursor only moves through the pages of one read: it cannot be kept to resume later. Keep the same filters and sort on every page: a cursor is valid for the same filters it was issued with, and a cursor used with anothersort_fieldreturns400, like any other invalid cursor. updated_since: available only where the modification date is reliable (e.g. reservations and contacts: the page of each resource says whether it supports it). It returns the items modified at or after the given instant (ISO 8601 with an explicit offset, e.g.2026-01-31T10:00:00+01:00; URL-encode the+as%2B); a date in the future or not valid returns400. These lists are ordered by modification date, then byid.- Late items: the modification date is set when a change is saved, slightly before it becomes visible, so an
item saved while you are reading can appear later with a modification date older than the newest one you have
seen. Start each poll from the highest modification date you have seen minus a margin (e.g. a few minutes) and
skip the items whose
idand modification date you have already processed. - Resources without
updated_since: read the list again from the first page and skip theids you have already processed; the page of each resource says what can and cannot be seen this way (e.g. changes to existing items or deletions). - Links: links to pages for the guests (e.g.
guest_area_urlsof reservations,online_checkin_urlsof guests) depend on the current time too, not only on the data (the agency can block access after arrival or departure). Links can stop working without the reservation appearing again inupdated_since: don't store them, read them when needed. These fields are objects with one link for each language of the installation, keyed by language code ({"it": "https://...", "en": "https://..."}, the codes of thelanguageof the contacts): pick the one of the guest's language, or your own default. They arenullwhen no link is available.
Change notifications (PUSH)
ImmobiNet can call a URL of yours when some data changes. The notification only says what changed (event, type and a few identifiers): read the data from the API afterwards. These are the same notifications as the SOAP web service.
Setup: the agency sets the URL in the contact of the API user, tab "Notifiche PUSH" (one URL per user; it
must start with http). In the same tab it can choose the events to send; choosing none sends all of them,
including the events that cannot be chosen there. Notifications are sent only while the user is active.
The call: an HTTP GET to your URL, with the parameters added to its query string (any query string you put
in the URL is kept, so you can add a secret token of yours to recognise the calls):
_event: what changed (see the table below);_type:inserted(created),modified(changed or, for several events, created) orremoved(deleted: a reservation cancelled or deleted in the application is usuallymodified, read itsstatus);- the parameters of the event (table below), and
old[...]with the previous values when they changed; ref: the code of the ImmobiNet installation.
Timing and delivery: a notification usually arrives within a minute of the change. Identical notifications (same event, type and parameters) close in time are sent once. Notifications are sent one at a time: answer quickly (e.g. store the parameters and process them separately). The response is only logged: there are no retries, a failed or timed-out call is lost, and the calls are not signed. Use polling as well to recover from missed notifications.
Visibility: notifications are not filtered by what the API user can read: you can receive events about
items that the API does not return to you (404, or missing from the lists). Ignore them.
_event | Parameters | What to read |
|---|---|---|
ModAgenzia/Prenotazione | id (reservation id), immobile (property reference), arrivo, partenza, old[arrivo], old[partenza], old[immobile] | GET /api/v1/reservations/{id} |
ModAgenzia/StatoPrenotazione | prenotazione (reservation id), nuovo_stato (the new status) | GET /api/v1/reservations/{prenotazione} |
ModAgenziaInquilini/Inquilino | id (guest id), prenotazione (reservation id), arrivo, partenza | GET /api/v1/reservations/{prenotazione}/guests |
ImmobiNet/Immobile | id (property reference, not the numeric id), old[id] | GET /api/v1/properties?codes={id} (exact match), then GET /api/v1/properties/{propertyId} |
GruppiImmobili/Gruppo | id (residence code, not the numeric id; empty for a residence without a code), old[id] | GET /api/v1/residences?codes={id} (the codes filter matches the residence code) |
ModAgenziaListiniRegole/ListinoAperture, ModAgenziaListiniRegole/ListinoRegole | listino (rate plan name), immobile (property reference, absent when the change is on the whole rate plan), dal, al (date-times with offset) | GET /api/v1/rate-plans/{listino}/availability?property_codes={immobile}&from=...&to=... (opening and stay restrictions of the days: see "Migrating from the SOAP web service") |
ModAgenzia/Listino, ModAgenzia/ListinoStagione, ModAgenzia/ListinoPeriodo, ModAgenziaListiniPersona/* | parameters vary by event: some carry only the rate plan, others only the property and the dates | the rates changed: read GET /api/v1/rate-plans/{ratePlan}/rates again for the rate plan and the properties concerned (see "Rates and rate plans") |
ModAgenziaPulizie/ListinoPulizia | listino (rate plan name), immobile (property reference), dal, al (date-times with offset) | GET /api/v1/cleaning-fees/{listino}?property_codes={immobile}&from=...&to=... (the cleaning fees changed: see "Cleaning fees") |
ModAgenzia/Disponibilita, ModAgenzia/Incarico, the other ModAgenziaListiniRegole/*, ModAgenziaOfferte/Offerta (special offers of a rate plan), ModAgenziaPulizie/ServizioRichiesto | rate plan, property, channel and date parameters | no REST equivalent yet (the other rules are only in the SOAP web service) |
arrivo and partenza are date-times with offset (e.g. 2026-07-01T00:00:00+02:00) in the reservation events
and plain dates (2026-07-01) in the guest events. ModAgenzia/Prenotazione is sent only for reservations with
a property; ModAgenzia/StatoPrenotazione only when the status is changed from the status form of the
application, and a reservation saved with a new status also sends ModAgenzia/Prenotazione. Quotes, contacts, invoices and transactions have no notifications: use polling. The events
available depend on the features enabled for the agency.
Rates and rate plans
GET /api/v1/rate-plans lists the rate plans enabled for the API user: the one of its webservice configuration
first, then those of the enabled channels (empty without a webservice configuration). Their code is the value of
the {ratePlan} of /api/v1/rate-plans/{ratePlan}/availability and /api/v1/rate-plans/{ratePlan}/rates and the rate_plan parameter of /api/v1/search/available-properties. Their
type says what the prices of /api/v1/rate-plans/{ratePlan}/rates mean: per_night (a price for each night) or fixed (one flat
amount for a stay inside a period, whatever the number of nights).
GET /api/v1/rate-plans/{ratePlan}/rates gives the prices of a rate plan, one item per property (with rate_plan and
rate_plan_type, the type above), as periods:
- Parameters:
fromandto(YYYY-MM-DD, both included, at most 366 days),property_idsandproperty_codes(comma-separated, at most 50 values in all). Properties are the ones the API user can see and the webservice configuration enables. - Amounts:
priceis in euro (e.g.120.5) and is a total for the guests of the row, not a supplement. With aper_nightrate plan it is the price of one night. With afixedrate plan it is one flat amount for a stay inside the period, whatever the number of nights (rules on the length of stay and on the arrival day are not part of this API). It is what a stay of the whole period pays: when the channel markup is rounded (e.g. up to the euro), the rounding applies to each night, so a shorter stay inside the period can pay a slightly different total. The markup of the channel of the webservice configuration, if the rate plan has one, is already in the price: it is neither a parameter nor a field of the response, and you cannot see it separately. - Periods: each period (
from,toincluded) hasguest_prices(min_guests,max_guests,price): a price for the guests from the minimum of the rate plan up to the capacity of the property (limited by the maximum of the rate plan). A period is split on the dates of the supplements per guest. With aper_nightrate plan consecutive days with the same prices are one period. With afixedrate plan each period of the rate plan is a period of its own, and its flatpricedoes not depend on thefromandtoyou ask for; only percentage supplements per guest are given (the flat amount increased by the percentage, the same for any length of stay), while supplements in euro, which are charged per night, are not represented: those numbers of guests show the flat amount. When periods of afixedrate plan overlap, the days they share go to the period that starts later (on the same start, to the one that ends first), so the periods you receive never overlap. Periods are cut tofromandto. Days without a price are not covered by any period, and a property without any price in the range is not returned. - Pages: the list is paginated like the others (
paging_limitfrom 1 to 50,next_cursor,_pagination.next_cursor), but a property is skipped when it has no price, and a request reads at most 100 properties. A page can therefore hold fewer items thanpaging_limit, even none, with anext_cursorthat is notnull: never stop on an emptyitems, keep followingnext_cursoruntil it isnull.total_itemscounts the visible properties that match the filters, including the ones without prices, so it is not the number of items you will receive. - Staying in sync: read the rates once, completely, then use the PUSH notifications of the rates (see the table in "Change notifications (PUSH)") and read again only the properties concerned. The notifications can be lost: repeat the complete read from time to time.
Migrating from the SOAP web service
The REST API reads the same data as the SOAP web service, with the same API user and the same webservice configuration. These are the SOAP read operations that have a REST equivalent:
| SOAP operation | REST call |
|---|---|
getPrenotazioni (periodo arrivo/partenza with dal/al) | GET /api/v1/reservations with arrival_from and arrival_to (or departure_from and departure_to), all in YYYY-MM-DD format and inclusive |
getPrenotazioni (immobili: property codes) | GET /api/v1/reservations?property_codes=... (a list of codes) or property_ids=... |
getPrenotazioni (ultimaModifica) | GET /api/v1/reservations?updated_since=... (see "Polling") |
getPrenotazioni (prenotazioni: ids) | GET /api/v1/reservations/{reservationId} |
getImmobili | GET /api/v1/properties and GET /api/v1/properties/{propertyId} (the SOAP property code is code; filter with codes). The structured data of the SOAP property are in the detail only: see "Property detail fields" below |
getGruppi | GET /api/v1/residences (GET /api/v1/residences?codes=... to filter by code) and GET /api/v1/residences/{residenceId} (type, address with coordinates; descriptions, attachments and facilities in its sub-resources) |
getAssociazioni | property_ids of each item of GET /api/v1/residences |
getDefinizioneAttributi | GET /api/v1/facilities (the catalog) and GET /api/v1/properties/{propertyId}/facilities |
getDisponibilita and getListinoAperture (openings of a rate plan by property and year) | GET /api/v1/rate-plans/{ratePlan}/availability (the days of the interval from-to, one item per property) |
getListinoRegole (stay restrictions: minimum and maximum stay, arrival and departure days) | the fields min_stay, max_stay, arrival_allowed and departure_allowed of each day of GET /api/v1/rate-plans/{ratePlan}/availability |
ricercaDisponibilita (free properties with their price) | GET /api/v1/search/available-properties (arrival, departure, guests, rate_plan, channel) |
getListino, getListinoPersone (prices of a rate plan) | GET /api/v1/rate-plans/{ratePlan}/rates (from, to, property_ids, property_codes); see "Rates and rate plans" |
getListinoPulizie (cleaning fees of a rate plan) | GET /api/v1/cleaning-fees/{ratePlan} (from, to, property_ids, property_codes); see "Cleaning fees" |
getDefinizioneListini (the rate plans) | GET /api/v1/rate-plans (code, name, min_guests, max_guests of the rate plans enabled for the API user) |
Writing (setPrenotazione, editPrenotazione, delPrenotazione) is not available in the REST API, which is read
only.
Differences to know when you move a client:
- Numeric ids, codes as filters: resources are identified by their numeric
id(properties bypropertyId, residences byresidenceId), not by the SOAPcodice. The codes are still there, ascodefor properties and residences (the SOAP groups;nullfor a residence without a code, which the SOAP never listed) and asproperty_codewhere a resource points to a property, and you can filter by them (property_codesof reservations,codesof residences and of properties): all ignore case and are an exact match. A code is a filter, never part of a path. A code with no match gives an empty list (200), not an error; the SOAP answered "property not found". A residence code is not guaranteed to be unique:codescan return more than one residence, and a residence without a code hascodenull(an emptycodes=is the same as no filter; the PUSH notification of such a residence carries an emptyid=). - Fewer rows are possible: the REST API is fail-closed. If the API user has a webservice configuration, only
the properties enabled for it are visible, and a reservation of any other property is not returned, even with
the filters above. If the configuration enables no property, the lists are empty. The SOAP web service could also
return reservations or properties that the configuration does not enable: expect fewer rows than before in
these cases. A second cause: the SOAP filtered reservations only by
operator, while the REST API applies the full visibility of the application to the API user, with the
privileges
prenotazioni_vedi_agenzia,prenotazioni_vedi_assegnateorprenotazioni_vedi_tutte(and the agency of the user); a user without them gets403. statusinstead ofconfermataandeliminata: a reservation has onestatus:deleted(it has adeleted_at: deleted or cancelled in the application),awaiting_down_payment,confirmed,checked_in,checked_out,handledand, only for reservations put in that state without going through the application,cancelled,reversed,owner_hold,to_be_handled. The SOAPeliminatais true fordeletedand also forcancelled,reversed,owner_holdandto_be_handled(the states flagged as deleted, such as the ones imported from the channels). The SOAPconfermatawasfalsefor a reservation awaiting a down payment (awaiting_down_payment) and for a deleted one. A status defined by the agency is returned with its own name: treat unknown values as valid. Deleted reservations stay in the list.- Amounts: unlike the SOAP web service, which returns amounts as integers in cents, every amount of the REST
API is a decimal number in euro (
120.5, not12050); divide the SOAP values by 100 when you compare the two. The amounts the API returns are rounded to two decimals (reservations, quotes, availability, rates, invoices, transactions, revenue prices). The amounts you send (PUT /api/v1/revenue/price-lists/{priceList}/prices) are in euro too, with at most two decimals (the server answers400for more decimals: they are almost always an amount in cents).amounts.stayis the SOAPprezzoandamounts.down_paymentthe SOAPcaparra;amounts.total(the total to be paid, all components included) is new. - Dates:
arrivalanddepartureare plain dates (2026-07-01), and the date-times (updated_at,deleted_at) are RFC 3339 with the offset ofEurope/Rome. The SOAP accepted dates without zero padding (2026-7-1), the filters of the REST API do not: they must beYYYY-MM-DD, and a value that is not a date (such as2026-02-30), or a_fromafter its_to, returns400with amessage. The ends of an interval are always inclusive and are namedfromandtowhen the interval is what you are asking for (availability, rates, revenue prices), or<field>_fromand<field>_towhen it filters a field of the resource (arrival_from,departure_toof the reservations,date_fromof the transactions).arrivalanddepartureof/api/v1/search/available-propertiesare the two ends of a stay, not a filter. - Personal data: reservations, quotes, invoices and transactions give the customer only as
contact_id(nullwhen there is only a typed name, which the API does not expose). Everything personal is in the contact,/api/v1/contacts/{contact_id}: theaddressbook(emails and phone numbers, each with atype),tax_code,vat_number,birth,citizenship, the name and the address. Withoutanagrafica_personale_tuttia contact is anonymised (last_nameisID#<id>, the other fields arenullor empty).guest_area_urlsisnullwithoutanagrafica_personale_tutti. - Not in the REST reservation (yet): the notes for the customer, the extra price components, the beds, the
rate plan name, the expiry date and the creation time of the SOAP
getPrenotazioni. - Filters and cursor: filters combine (all must match), also with
updated_since. A cursor is valid for the same combination of filters with which it was issued: do not change the filters between the pages of a read. With different filters a cursor is not rejected when it is well formed, but the result is the one of the new query from that position, which is not what you want; start again from the first page instead. - Property detail fields: the SOAP
getImmobilidata are inGET /api/v1/properties/{propertyId}(not in the list, which stays light); they are always present andnullwhen the property has no such data (or the data is not available),points_of_interestis[]. SOAPcategoria→category(the code of the category; its name anddestination, asresidential,commercialorholiday, are inGET /api/v1/property-categories),idAgenzia→agency_id,composizione→composition(bathrooms,bedrooms,rooms,balconies,terraces),appartamento→apartment(floor,elevators,total_floors,unit_number),superficie→surface(value,unit),ace→energy_certificate(class,performance_index; only for an issued certificate),immobileTuristico→capacity(type,max_guests,double_beds,single_beds,sofa_beds,bunk_beds),distanze→points_of_interest(codeis the code of the point of interest, sorted by code). The coordinates areaddress.coordinates, the check-in and check-out times arecheck_inandcheck_out, the titles arenames, the attributes are inGET /api/v1/properties/{propertyId}/facilities. Not ported: the extra information of the notice boards (tabelloni), the land, house, villa and warehouse data and the kitchen, garden and similar fields of the SOAP type (the SOAP never filled them), and the geographic id of the city. - Energy index:
energy_certificate.performance_indexis the stored value in kWh/m² per year. The SOAPace.ipeis that value multiplied by 1000: divide it by 1000 when you compare. - Custom fields: like the SOAP,
custom_fieldshas only the custom fields marked "Web" in the application (and, unlike the SOAP, never the ones marked for internal use), and only the ones with a value. The same rule applies to contacts and quotes. - Availability and search: the interval is
fromandto(YYYY-MM-DD, inclusive, at most 366 days for the calendar and 60 nights for the search), not the year of the SOAP;GET /api/v1/rate-plans/{ratePlan}/availabilitylists one item per property, with a day for each date of the interval, and is paginated (paging_limitfrom 1 to 50, default 20,next_cursor,_pagination.next_cursor), also the search. Restrict it withproperty_idsandproperty_codes(comma-separated lists, at most 50 values in all). Properties are identified by their numeric id and the rate plan by its name ({ratePlan}in the path of the calendar and of the rates,rate_planin the query of the search where it is optional; it must be one of the rate plans enabled for the API user, otherwise404in the path and400in the query); properties not enabled by the configuration are not shown. Each day has a singleavailableflag: it merges what the SOAP split betweengetDisponibilitaand the rules, and the reason why a day is not available is not returned. The restriction fields aremin_stay(1 when not set),max_stay(nullwhen not set),arrival_allowedanddeparture_allowed(the SOAParrivoandpartenza: whether a stay can start or end that day); all four arenullon an installation where the restrictions are not available. Amounts of the search are decimal numbers in euro (the SOAP returns cents),amountshasstay,total,undiscounted_total(the total before the discounts) and theprice_items(typeandamount, negative for a discount) that make it up; the search does not return the down payment and the security deposit. Differences from the SOAP search: with the same price in more than one rate plan the first enabled one wins (the SOAP kept the last), and a free property for which no price can be computed is left out, so a page can hold fewer items thanpaging_limit. - Rates:
GET /api/v1/rate-plans/{ratePlan}/ratesreplacesgetListinoandgetListinoPersonewith one call. Differences from the SOAP: amounts are in euro (the SOAP gives cents), per night or, for afixedrate plan, one flat amount per period (rate_plan_type; the SOAP gives thetipoof the rate plan); the range isfrom-to; there is no season number, the rows are periods with their dates; every row ofguest_pricesis the total for those guests, wheregetListinoPersonegives the base price and the supplement of each guest beyond the nominal ones.standardrate plans have the markup of the channel of the webservice configuration in the price (the SOAPgetListinodoes not apply it to them). The prices per guest are the price a reservation gets and the one ofGET /api/v1/search/available-propertieswithguests; where the SOAP rows, added up, give something else, the rates are the ones to trust. The total is rounded to the cent once (the SOAP rounds up each supplement row, so its sums can be a cent higher). A row with no price is dropped, so themin_guests-max_guestsranges of a period may not be contiguous. A property whose capacity is below the minimum number of guests of the rate plan has no rows./api/v1/revenue/price-lists/{priceList}/pricesstays the revenue prices: it is a separate thing from the rates. A rate plan of SOAPtipofissoisfixedhere: each period of the rate plan has its flatprice(the SOAP price of the season, with the markup of the channel if any), the same whateverfromandtoyou ask for; of the supplements per guest only the percentage ones are given (those in euro are charged per night, so the total would depend on the length of the stay). - Cleaning fees:
GET /api/v1/cleaning-fees/{ratePlan}replacesgetListinoPulizie. Differences from the SOAP: amounts are in euro (the SOAP gives cents); the range isfrom-to(at most 366 days) and the periods are cut to it; items are identified byproperty_id(the SOAP gives the property code); a property with no fee in the range is not listed and the pages are full; a rate plan with no cleaning price list is an empty list (200), a rate plan that does not exist or is not enabled is404(the SOAP gives a fault). The fee is set by year, so periods follow the years and consecutive years with the same fee are one period. Like the SOAP, the fee has no channel markup. To stay in sync use the PUSHModAgenziaPulizie/ListinoPulizia: read again the property it names (immobile) for the rate plan (listino) and the interval (dal,al; split it into windows of at most 366 days). - Staying in sync without reading everything: read the calendar once, completely, when you start. Then use the
PUSH notifications
ModAgenziaListiniRegole/ListinoAperture(openings) andModAgenziaListiniRegole/ListinoRegole(stay restrictions): each carries the rate plan (listino, pass it as{ratePlan}: a change on a rate plan that others derive from is sent once for each of them), the interval (dal,al) and, when the change is on one property, its reference (immobile). Withimmobile, read the calendar again withproperty_codesonly for the properties that changed. Withoutimmobilethe change is on the whole rate plan (all its properties): read the whole calendar for that rate plan.dalandalof such notifications run from today to two years ahead, more than the 366 days a calendar request accepts: split the read into windows of at most 366 days. The notifications can be lost (see "Change notifications (PUSH)"): repeat the complete read from time to time. - Notifications: the PUSH notifications are the same as the SOAP ones (see "Change notifications (PUSH)").
- Privilege
webservice: like the SOAP web service, the REST API requires thewebserviceprivilege. An API user with a valid key but without it gets403; a wrong key is still401. If you used the REST API before this requirement, ask the agency administrator to grant the privilege to the role of your API user. - API key scopes: every API key has a list of scopes
<resource>:<action>(e.g.reservations:read), chosen by the agency administrator in the API Keys tab of the user. Thedescriptionof each operation says which scope it requires. A key can only call the operations covered by its scopes, in addition to the privileges of its user: with a missing scope the call gets403, and the message names the scope.GET /api/v1/tokenandGET /api/v1/users/meneed no scope and list the scopes of the key in use. The agency endpoints need no scope either.

