Enquiries

In the context of the Housemates API, "Enquiries" represent instances of communication initiated by students on the API partner's platform, pertaining to queries or requests about the accommodation services. These Enquiries are then sent to Housemates through the API for further processing and response.

An Enquiry can primarily involve questions about room availability, specific features of properties or rooms, booking procedures, or any other inquiries that a student may have regarding the accommodation services.

We support two main types of enquiry in our systems, these are:

General enquiries

A general enquiry should be used when your student simply has a question about the process or needs some support to find a room. It does not require specific operator, property or room information to be created.

Specific enquiries

A specific enquiry should be related to an individual room type and may relate to availability, specific features or more generally booking procedures. These do require a bit more information to be created, we require room, property and operator IDs.

Each Enquiry is treated as a unique entity with its own identifier, often referred to as an Enquiry ID. This identifier can be used to track the specific Enquiry, including its status, content, and any responses provided.

The enquiry model

The enquiry model informs you about all of the information an enquiry in Housemates systems possesses.

Attributes

  • Name
    id
    Type
    string
    Description

    This is the unique identifier that is used to identify the enquiry in our system. It is also used to retrieve detailed information about an enquiry.

  • Name
    operator_id
    Type
    string
    Description

    Unique identifier used to identify the accommodation provider in our system.

  • Name
    property_id
    Type
    string
    Description

    Unique identifier of the property in question.

  • Name
    room_id
    Type
    string
    Description

    Unique identifier of the room in question.

  • Name
    property_name
    Type
    text
    Description

    Name of the property in question. e.g. "Vega".

  • Name
    room_name
    Type
    text
    Description

    Name of the room in question. e.g. "Studio".

  • Name
    first_name
    Type
    string
    Description

    First name of the student who made the enquiry.

  • Name
    last_name
    Type
    string
    Description

    Last name of the student who made the enquiry.

  • Name
    email
    Type
    string
    Description

    Email address of the student who made the enquiry.

  • Name
    contact_number
    Type
    string
    Description

    Phone number of the student who made the enquiry.

  • Name
    message
    Type
    string
    Description

    The message that the student sent to the accommodation provider.

  • Name
    status
    Type
    string
    Description

    The status of the enquiry. Possible values are "pending", "in_progress", "resolved", "closed".

Enquiry model

{
    "id":"01H5FS1N0KYJFJN3ET78PD9EKT",
    "operator_id":"03d7438a-309f-446e-96be-7b123180e155",
    "property_id":"01H14V1E5EVWGANKXQG7TVYGQ1",
    "room_id":"01H14V1E98A2A046WFDJZTEJER",
    "property_name":"Vega",
    "room_name":"Standard Ensuite",
    "first_name":"John",
    "last_name":"Doe",
    "email":"john@gmail.com",
    "message":"This is the enquiry message about property",
    "contact_number":"+447898897654",
    "status":"in_progress"
}
GET/api/enquiries

List all enquiries

This endpoint provides you the ability to access a paginated catalogue of all student-originated enquiries, generated on your platform and subsequently submitted to Housemates. For ease of navigation and optimal user experience, the system is configured to display a maximum of ten enquiries per page by default.

Required attributes

  • Name
    X-API-PARTNER-ID
    Type
    string
    Description

    Your API partner ID provided by Housemates. It should be provided in the header.

Optional attributes

    • Name
      per_page
      Type
      integer
      Description

      Limit the number of properties returned.

    • Name
      page
      Type
      integer
      Description

      The page number to be returned. e.g. page=2. By default, the first page is returned. It is usually used for pagination.

Filters

You can filter the enquiries by its status. Possible values are "pending", "in_progress", "resolved", "closed":

  • Name
    filter[status]
    Type
    string
    Description

    Filter enquiries by status. e.g. filter[status]=resolved

Request

GET
/api/enquiries

curl --request GET \
--url "https://api.housemates.io/api/enquiries" \
--header 'X-API-PARTNER-ID: {API_PARTNER_ID}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access_token}'

# Filter by status

curl --globoff --request GET \
--url "https://api.housemates.io/enquiries?filter[status]=pending" \
--header 'X-API-PARTNER-ID: {API_PARTNER_ID}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access_token}'

Response

{
  "success":true,
  "code":0,
  "locale":"en",
  "message":"OK",
  "data":{
    "items":[
      {
        "id":"01H4Y4ZQCR24X9J6Y19M3B950X",
        "operator_id":"03d7438a-309f-446e-96be-7b123180e155",
        "property_id":"01H14V1E5EVWGANKXQG7TVYGQ1",
        "room_id":"01H14V1E98A2A046WFDJZTEJER",
        "property_name":"Vega",
        "room_name":"Standard Ensuite",
        "first_name":"John",
        "last_name":"Doe",
        "email":"john.doe@email.com",
        "message":"Need more information about the room",
        "contact_number":null,
        "status":"pending"
      }
    ],
    "meta":{
      "total":2,
      "count":2,
      "per_page":10,
      "current_page":1,
      "total_pages":1,
      "path":"https://api.housemates.io/enquiries",
      "links":[
        {
          "url":null,
          "label":"« Previous",
          "active":false
        },
        {
          "url":"https://api.housemates.io/enquiries?page=1",
          "label":"1",
          "active":true
        },
        {
          "url":null,
          "label":"Next »",
          "active":false
        }
      ]
    },
    "links":{
      "first":"https://api.housemates.io/enquiries?page=1",
      "last":"https://api.housemates.io/enquiries?page=1",
      "next":null,
      "prev":null
    }
  }
}
GET/api/enquiries/:id

Retrieve an enquiry

This endpoint allows you to retrieve an individual enquiry - this may be used to check the status of a specific users enquiry or to populate your own CRM system.

Required attributes

  • Name
    X-API-PARTNER-ID
    Type
    string
    Description

    Your API partner ID provided by Housemates. It should be provided in the header.

  • Name
    enquiry_id
    Type
    string
    Description

    Unique identifier for the enquiry to be provided in the path.

Request

GET
/api/enquiries/01H4Y4ZQCR24X9J6Y19M3B950X
curl --request GET \
--url 'https://api.housemates.io/api/enquiries/{enquiry_id}' \
--header 'X-API-PARTNER-ID: {API_PARTNER_ID}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access_token}'

Response

{
  "success":true,
  "code":0,
  "locale":"en",
  "message":"OK",
  "data":{
    "item":{
      "id":"01H6BEBV7PTP8ZJP5SZY377R0X",
      "operator_id":"03d7438a-309f-446e-96be-7b123180e155",
      "property_id":"01H14V1E5EVWGANKXQG7TVYGQ1",
      "room_id":"01H14V1E98A2A046WFDJZTEJER",
      "property_name":"Vega",
      "room_name":"Standard Ensuite",
      "first_name":"John",
      "last_name":"Smith",
      "email":"john@gmail.com",
      "message":"This is the enquiry message",
      "contact_number":"+447904413565",
      "status":"pending"
    }
  }
}
POST/api/enquiries

Create a specific enquiry

This endpoint allows you to create a new enquiry about a specific room type and property.

Required attributes

  • Name
    X-API-PARTNER-ID
    Type
    string
    Description

    Your API partner ID provided by Housemates. You can find it in your partner dashboard. It should be provided in header.

  • Name
    operator_id
    Type
    string
    Description

    The unique identifier of the operator received as part of the room object.

  • Name
    property_id
    Type
    string
    Description

    The unique identifier of the property received as part of the room object.

  • Name
    room_id
    Type
    string
    Description

    The unique identifier of the room.

  • Name
    first_name
    Type
    string
    Description

    The first name of the student.

  • Name
    last_name
    Type
    string
    Description

    The last name of the student.

  • Name
    email
    Type
    string
    Description

    The email address of the student.

  • Name
    contact_number
    Type
    string
    Description

    The contact number of the student. It should be in international format.
    e.g. +447898893412

  • Name
    message
    Type
    string
    Description

    The message of the student.

  • Name
    additional_fields
    Type
    object
    Description

    This object represents additional information with an enquiry, stored as key-value pairs in a valid JSON format. It allows you to include custom data alongside predefined fields for better organization and retrieval of infromation.

    Predefined Keys:

    Custom Keys: You can also include custom keys to capture bespoke information relevant to their requirements.

Request

POST
/api/enquiries

curl --request POST \
--url 'https://api.housemates.io/api/enquiries' \
--header 'X-API-PARTNER-ID: 01H0N04529EXND84J5AN2ZH7CX' \
--header 'Content-Type: application/vnd.api+json' \
--header 'Accept: application/vnd.api+json' \
--header 'Authorization: Bearer b2fcrSRUV8OsN6Yn79UKGIiGDCLUJtGqEL3m2aO4' \
--data '{
"operator_id": "03d7438a-309f-446e-96be-7b123180e155",
"property_id": "01H14V1E5EVWGANKXQG7TVYGQ1",
"room_id": "01H14V1E98A2A046WFDJZTEJER",
"first_name": "John",
"last_name": "Doe",
"email": "john@gmail.com",
"message": "This is the enquiry message about property",
"contact_number": "+447898897654",
"additional_fields": "{
    "move-in": "January 2024",
    "move-out": "July 2024",
    "university": "The University of Manchester"
}"
}'

Response

{
    "success":true,
    "code":201,
    "locale":"en",
    "message":"OK",
    "data": {
       "enquiry_id" : "01H14V1E5EVWGANKXQG7TVYGQ1"
    }
}
POST/api/enquiries/general

Create a general enquiry

This endpoint allows you to create a new general enquiry.

Required attributes

  • Name
    X-API-PARTNER-ID
    Type
    string
    Description

    Your API partner ID provided by Housemates. You can find it in your partner dashboard. It should be provided in header.

  • Name
    first_name
    Type
    string
    Description

    The first name of the student.

  • Name
    last_name
    Type
    string
    Description

    The last name of the student.

  • Name
    email
    Type
    string
    Description

    The email address of the student.

  • Name
    contact_number
    Type
    string
    Description

    The contact number of the student. It should be in international format.
    e.g. +447898893412

  • Name
    message
    Type
    string
    Description

    The message of the student.

  • Name
    metadata
    Type
    object
    Description

    A string which contains a valid JSON object as key value pair containing any metadata that you wish to store against the enquiry. This can be used to store any information that you wish to be returned when retrieving the enquiry.

  • Name
    additional_fields
    Type
    object
    Description

    This object represents additional information with an enquiry, stored as key-value pairs in a valid JSON format. It allows you to include custom data alongside predefined fields for better organization and retrieval of infromation.

    Predefined Keys:

    Custom Keys: You can also include custom keys to capture bespoke information relevant to their requirements.

Request

POST
/api/enquiries

curl --request POST \
--url 'https://api.housemates.io/api/enquiries/general' \
--header 'X-API-PARTNER-ID: 01H0N04529EXND84J5AN2ZH7CX' \
--header 'Content-Type: application/vnd.api+json' \
--header 'Accept: application/vnd.api+json' \
--header 'Authorization: Bearer b2fcrSRUV8OsN6Yn79UKGIiGDCLUJtGqEL3m2aO4' \
--data '{
"first_name": "John",
"last_name": "Doe",
"email": "john@gmail.com",
"message": "This is the enquiry message about property",
"contact_number": "+447898897654"
"metadata": "{
    "key1": "value1",
    "key2": "value2"
}",
"additional_fields": "{
    "move-in": "January 2024",
    "move-out": "July 2024",
    "university": "The University of Manchester"
}"
}'

Response

{
    "success":true,
    "code":201,
    "locale":"en",
    "message":"OK",
    "data": {
       "enquiry_id" : "01H14V1E5EVWGANKXQG7TVYGS3"
    }
}