ImmobiNet
ImmobiNet API Docs - Auth

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_cursor of a response as the next_cursor query parameter to get the next page; it is null on 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 another sort_field returns 400, 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 returns 400. These lists are ordered by modification date, then by id.
  • 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 id and modification date you have already processed.
  • Resources without updated_since: read the list again from the first page and skip the ids 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_urls of reservations, online_checkin_urls of 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 in updated_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 the language of the contacts): pick the one of the guest's language, or your own default. They are null when 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) or removed (deleted: a reservation cancelled or deleted in the application is usually modified, read its status);
  • 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.

_eventParametersWhat to read
ModAgenzia/Prenotazioneid (reservation id), immobile (property reference), arrivo, partenza, old[arrivo], old[partenza], old[immobile]GET /api/v1/reservations/{id}
ModAgenzia/StatoPrenotazioneprenotazione (reservation id), nuovo_stato (the new status)GET /api/v1/reservations/{prenotazione}
ModAgenziaInquilini/Inquilinoid (guest id), prenotazione (reservation id), arrivo, partenzaGET /api/v1/reservations/{prenotazione}/guests
ImmobiNet/Immobileid (property reference, not the numeric id), old[id]GET /api/v1/properties?codes={id} (exact match), then GET /api/v1/properties/{propertyId}
GruppiImmobili/Gruppoid (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/ListinoRegolelistino (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 datesthe 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/ListinoPulizialistino (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/ServizioRichiestorate plan, property, channel and date parametersno 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: from and to (YYYY-MM-DD, both included, at most 366 days), property_ids and property_codes (comma-separated, at most 50 values in all). Properties are the ones the API user can see and the webservice configuration enables.
  • Amounts: price is in euro (e.g. 120.5) and is a total for the guests of the row, not a supplement. With a per_night rate plan it is the price of one night. With a fixed rate 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, to included) has guest_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 a per_night rate plan consecutive days with the same prices are one period. With a fixed rate plan each period of the rate plan is a period of its own, and its flat price does not depend on the from and to you 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 a fixed rate 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 to from and to. 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_limit from 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 than paging_limit, even none, with a next_cursor that is not null: never stop on an empty items, keep following next_cursor until it is null. total_items counts 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 operationREST 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}
getImmobiliGET /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
getGruppiGET /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)
getAssociazioniproperty_ids of each item of GET /api/v1/residences
getDefinizioneAttributiGET /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 by propertyId, residences by residenceId), not by the SOAP codice. The codes are still there, as code for properties and residences (the SOAP groups; null for a residence without a code, which the SOAP never listed) and as property_code where a resource points to a property, and you can filter by them (property_codes of reservations, codes of 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: codes can return more than one residence, and a residence without a code has code null (an empty codes= is the same as no filter; the PUSH notification of such a residence carries an empty id=).
  • 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_assegnate or prenotazioni_vedi_tutte (and the agency of the user); a user without them gets 403.
  • status instead of confermata and eliminata: a reservation has one status: deleted (it has a deleted_at: deleted or cancelled in the application), awaiting_down_payment, confirmed, checked_in, checked_out, handled and, only for reservations put in that state without going through the application, cancelled, reversed, owner_hold, to_be_handled. The SOAP eliminata is true for deleted and also for cancelled, reversed, owner_hold and to_be_handled (the states flagged as deleted, such as the ones imported from the channels). The SOAP confermata was false for 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, not 12050); 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 answers 400 for more decimals: they are almost always an amount in cents). amounts.stay is the SOAP prezzo and amounts.down_payment the SOAP caparra; amounts.total (the total to be paid, all components included) is new.
  • Dates: arrival and departure are plain dates (2026-07-01), and the date-times (updated_at, deleted_at) are RFC 3339 with the offset of Europe/Rome. The SOAP accepted dates without zero padding (2026-7-1), the filters of the REST API do not: they must be YYYY-MM-DD, and a value that is not a date (such as 2026-02-30), or a _from after its _to, returns 400 with a message. The ends of an interval are always inclusive and are named from and to when the interval is what you are asking for (availability, rates, revenue prices), or <field>_from and <field>_to when it filters a field of the resource (arrival_from, departure_to of the reservations, date_from of the transactions). arrival and departure of /api/v1/search/available-properties are the two ends of a stay, not a filter.
  • Personal data: reservations, quotes, invoices and transactions give the customer only as contact_id (null when there is only a typed name, which the API does not expose). Everything personal is in the contact, /api/v1/contacts/{contact_id}: the addressbook (emails and phone numbers, each with a type), tax_code, vat_number, birth, citizenship, the name and the address. Without anagrafica_personale_tutti a contact is anonymised (last_name is ID#<id>, the other fields are null or empty). guest_area_urls is null without anagrafica_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 getImmobili data are in GET /api/v1/properties/{propertyId} (not in the list, which stays light); they are always present and null when the property has no such data (or the data is not available), points_of_interest is []. SOAP categoria → category (the code of the category; its name and destination, as residential, commercial or holiday, are in GET /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 (code is the code of the point of interest, sorted by code). The coordinates are address.coordinates, the check-in and check-out times are check_in and check_out, the titles are names, the attributes are in GET /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_index is the stored value in kWh/m² per year. The SOAP ace.ipe is that value multiplied by 1000: divide it by 1000 when you compare.
  • Custom fields: like the SOAP, custom_fields has 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 from and to (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}/availability lists one item per property, with a day for each date of the interval, and is paginated (paging_limit from 1 to 50, default 20, next_cursor, _pagination.next_cursor), also the search. Restrict it with property_ids and property_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_plan in the query of the search where it is optional; it must be one of the rate plans enabled for the API user, otherwise 404 in the path and 400 in the query); properties not enabled by the configuration are not shown. Each day has a single available flag: it merges what the SOAP split between getDisponibilita and the rules, and the reason why a day is not available is not returned. The restriction fields are min_stay (1 when not set), max_stay (null when not set), arrival_allowed and departure_allowed (the SOAP arrivo and partenza: whether a stay can start or end that day); all four are null on an installation where the restrictions are not available. Amounts of the search are decimal numbers in euro (the SOAP returns cents), amounts has stay, total, undiscounted_total (the total before the discounts) and the price_items (type and amount, 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 than paging_limit.
  • Rates: GET /api/v1/rate-plans/{ratePlan}/rates replaces getListino and getListinoPersone with one call. Differences from the SOAP: amounts are in euro (the SOAP gives cents), per night or, for a fixed rate plan, one flat amount per period (rate_plan_type; the SOAP gives the tipo of the rate plan); the range is from-to; there is no season number, the rows are periods with their dates; every row of guest_prices is the total for those guests, where getListinoPersone gives the base price and the supplement of each guest beyond the nominal ones. standard rate plans have the markup of the channel of the webservice configuration in the price (the SOAP getListino does not apply it to them). The prices per guest are the price a reservation gets and the one of GET /api/v1/search/available-properties with guests; 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 the min_guests-max_guests ranges 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}/prices stays the revenue prices: it is a separate thing from the rates. A rate plan of SOAP tipo fisso is fixed here: each period of the rate plan has its flat price (the SOAP price of the season, with the markup of the channel if any), the same whatever from and to you 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} replaces getListinoPulizie. Differences from the SOAP: amounts are in euro (the SOAP gives cents); the range is from-to (at most 366 days) and the periods are cut to it; items are identified by property_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 is 404 (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 PUSH ModAgenziaPulizie/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) and ModAgenziaListiniRegole/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). With immobile, read the calendar again with property_codes only for the properties that changed. Without immobile the change is on the whole rate plan (all its properties): read the whole calendar for that rate plan. dal and al of 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 the webservice privilege. An API user with a valid key but without it gets 403; a wrong key is still 401. 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. The description of 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 gets 403, and the message names the scope. GET /api/v1/token and GET /api/v1/users/me need no scope and list the scopes of the key in use. The agency endpoints need no scope either.
Security Schemes
basicAuth
HTTP basic
http