MyMaison API docs
It’s the best possible solution to operate within your account using a RESTful API. We provide a few key endpoints:
/bookings, create, edit, delete bookings/bookings/:id/guests, create, update and delete guests/rentals, read your properties/rentals/guest_countries, read countries/guest_cities, read cities for a given country
Plus, we provide webhooks for a few key events. Read more below.
Authentication and endpoint
We require that you add authentication details to each API request.
First, you have to find your api_token. Visit this section of your MyMaison account and copy the API key you find there.
Now, you have 2 options:
- URL parameter:
?secret=API_TOKEN - Header parameter:
x-mymaison-secret:API_TOKEN
Please note that this is the first version of our authentication system and will be upgraded in the future for better security and improved API granular controls.
The main endpoint for all the methods of this API is: https://host.mymaisonapp.com/api/v1/
Required headers
Please don’t forget to add Content-Type: application/json to all your POST and PATCH/PUT requests.
Upload to Police Website and other portals
As of now, the API is not designed to allow you to request an upload of your data to the police website (AlloggiatiWeb) or to other institutions’ websites.
All these operations will be performed automatically by our application and you will get notified once something changes in the status of the bookings or the guests.
The webhooks system is not yet perfect. Please keep this in mind and let us know if you need to monitor specific events that are not yet covered by the system.
Bookings Endpoint
To create a booking
POST /bookings
{
"booking": {
"check_in": "2018-08-01", // required
"check_out": "2018-08-10", // required
"rental_id": 123 // required. <Rental :id>
"client_full_name": "Mario Rossi" // required
}
}
Successful response:
{
"id": 123
"check_in": "2018-08-01", // required
"check_out": "2018-08-10", // required
"rental": 123
}
To read a single booking
GET /bookings/:id
{
"id": 123
"check_in": "2018-08-01", // required
"check_out": "2018-08-10", // required
"rental": 123
}
To cancel a booking
DELETE /bookings/:id
{
"id": 123
"check_in": "2018-08-01", // required
"check_out": "2018-08-10", // required
"rental": 123,
"canceled_at": "2019-01-01T08:15:00"
}
Guests Endpoint
To add a guest to a booking
POST /bookings/:id/guests
{
"guest": {
"name": "Mario", // required
"surname": "Rossi", // required
"gender": 1, // required
"date_of_birth": "1990-01-01", // required
"country_of_nationality_id": 123, // required. <GuestCountry :id>
"country_of_birth_id": 123, // required. <GuestCountry :id>
"city_of_birth_id": 123, // required if country_of_birth requires to specify city. <GuestCity :id>
"document": { // required for first guest in array
"country_of_issue_id": 123, // GuestCountry id
"city_of_issue_id": 123, // GuestCountry id
"type": 1, // 1: ID card, 2: Passport, 3: Driver's License
"number": "12345678" // required
}
}
}
Successful response:
{
"id": 33,
"guest_type": null,
"name": "Mario",
"surname": "Rossi",
"check_in_date": "2019-04-25",
"check_out_date": "2019-04-28",
"gender": 1,
"date_of_birth": "1990-01-01",
"nationality": "444111",
"place_of_birth": "444111 | 444111",
"document_type": null,
"document_number": null,
"document_place_of_issue": null,
"created_at": "2019-04-26T14:01:54.495Z",
"updated_at": "2019-04-26T14:01:54.495Z",
"user_id": 372611,
"status": "pending",
"parent_guest_id": 28,
"listing_id": 72,
"successfully_sent_at": null,
"anonymized_at": null,
"confirmation_code": null,
"amount": null,
"billing_address": null,
"booking_id": 411,
"country_of_birth_id": 2,
"city_of_birth_id": null,
"country_of_issue_document_id": null,
"city_of_issue_document_id": null,
"country_of_nationality_id": 2
}
To retrieve a single guest
GET /bookings/:id/guests/:id
{
"id": 33,
"guest_type": null,
"name": "Mario",
"surname": "Rossi",
"check_in_date": "2019-04-25",
"check_out_date": "2019-04-28",
"gender": 1,
"date_of_birth": "1990-01-01",
"nationality": "444111",
"place_of_birth": "444111 | 444111",
"document_type": null,
"document_number": null,
"document_place_of_issue": null,
"created_at": "2019-04-26T14:01:54.495Z",
"updated_at": "2019-04-26T14:01:54.495Z",
"user_id": 372611,
"status": "pending",
"parent_guest_id": 28,
"listing_id": 72,
"successfully_sent_at": null,
"anonymized_at": null,
"confirmation_code": null,
"amount": null,
"billing_address": null,
"booking_id": 411,
"country_of_birth_id": 2,
"city_of_birth_id": null,
"country_of_issue_document_id": null,
"city_of_issue_document_id": null,
"country_of_nationality_id": 2
}
To update a guest
PATCH /bookings/:id/guests/:id
{
"guest": {
"name": "Mario", // required
"surname": "Rossi", // required
"gender": 1, // required
"date_of_birth": "1990-01-01", // required
"country_of_nationality_id": 123, // required. <GuestCountry :id>
"country_of_birth_id": 123, // required. <GuestCountry :id>
"city_of_birth_id": 123, // required if country_of_birth requires to specify city. <GuestCity :id>
"document": { // required for first guest in array
"country_of_issue_id": 123, // GuestCountry id
"city_of_issue_id": 123, // GuestCountry id
"type": 1, // 1: ID card, 2: Passport, 3: Driver's License
"number": "12345678" // required
}
}
}
To delete a guest
DELETE /bookings/:id/guests/:id
Rentals
GET /rentals
Response:
[
{
"id": 39,
"name": "DE AMICIS 1",
"created_at": "2018-09-10T05:56:04.340Z",
"disabled": false,
"access_token": "xxxxxxxxx"
},
{
"id": 40,
"name": "DE AMICIS 2",
"created_at": "2018-09-10T05:56:04.351Z",
"disabled": false,
"access_token": "xxxxxxxxx"
}
]
GuestCountries
GET /guest_countries
This endpoint supports a q params to filter countries by name:
/guest_countries?q[name_it_cont]=ita will return all countries with the word ‘ita’ in their italian name.
Response:
[
{
"id": 1,
"name_it": "Italia",
"name_en": "Italy",
"aw_code": "1234"
},
{
"id": 2,
"name_it": "Germania",
"name_en": "Germany",
"aw_code": "444111"
}
]
GuestCities
GET /guest_countries/:id/guest_cities
This endpoint supports a q params to filter cities by name:
/guest_cities?q[name_it_cont]=mila will return all cities with the word ‘mila’ in their italian name.
Response:
[
{
"id": 1,
"name_it": "Milano",
"name_en": "Milan",
"aw_code": "123456MI"
},
{
"id": 2,
"name_it": "Civitavecchia",
"name_en": null,
"aw_code": "123433556RM"
},
{
"id": 3,
"name_it": "Lecco",
"name_en": null,
"aw_code": "12356LC"
},
{
"id": 4,
"name_it": "Roma",
"name_en": null,
"aw_code": "223454RM"
},
{
"id": 5,
"name_it": "Assago",
"name_en": null,
"aw_code": "2969654MI"
}
]
Webhooks
Before you can receive any events you must register your endpoint url. To do so, visit the Account > Integrations page of your MyMaison account.
Here’s a list of events triggered by our webhooks system:
booking.create: A new booking has been created booking.update: A new booking has been updated
Example of body sent after online check-in has been completed:
{
"event": "booking.update",
"changes": {
"online_check_in_completed_at": {
"from": null,
"to": "2018-01-01 21:00:00 UTC+2"
}
},
"booking": {
"uid": 1234,
"check_in": "2018-08-01",
"check_out": "2018-08-10",
"rental_id": 123
}
}```