MyMaison API docs

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
  }  
}```

Hai ancora bisogno di aiuto? Contattaci Contattaci