---
# System prepended metadata

title: Home for Students APIs

---

# Home for Students APIs

## Frontoffice

All the endpoints below are internazionalized and they are scoped by language. Currently, the handled languages are `it` and `en`.

### POST /api/v1/contact-forms

Used to create a new message. 

##### Body

```json 
{
    email: string,
    subject: string,
    body: string,
    name: string,
}
```

### POST api/v1/newsletters

Used to subscribe a user to the Mailchimp newsletter.

#### Body

```json
{
    locationType: 'city' | 'area' | 'interest-point',
    locationUuid: string,
    email: string,
    name: string,
}
```

### GET /api/v1/search/locations

Returns all the locations entities like cities, cities' areas and interest points.

#### Query params


| Name     | Description                       | Type     | Default value  |
| -------- | --------------------------------- | -------- | -------------- |
| page     | Current page of results           | number   | 0              |
| q        | Query term                        | string   | <empty string> |
| results  | Number of results of current page | number   | 5              |
| types    | Types of locations                | string[] | null           |

#### Results

```typescript
{
    type: 'city' | 'area' | 'interest-point' | 'tag'
    name: string,
    uuid: string,
}[]
```


### GET /api/v1/search/rooms

Returns all rooms that respect the requested filter

#### Query params

| Name       | Description                       | Type      | Default value  | Required |
| ---------- | --------------------------------- | --------- | -------------  | -------- |
| entityType | Type of the requested location entity | 'city', 'area', 'interest-point' | city | no |
| entityUuid | UUID of the requested location entity | string | - | no |
| checkIn | Date of check in | isoDate | null | no |
| checkOut | Date of check out| isoDate | null | no |
| roomType | Searched room type | 'single', 'double' | null | no |
| page | Requested page of types | number | 0 | no |
| results | Number of results for the current page | number | 5 | no |

#### Results

```typescript
{
    houseAddress: string,
    houseDescription: string,
    photos: {
        alt?: string,
        src: string,
    }[],
    price: number, // NOTE: It should be sent formatted as an integer
    uuid: string,
}[]
```

# Backoffice

### POST /api/v1/users/auth

Permit to authenticate a user.

#### Body

- email: string
- password: string

#### Response

```json
{
  token: string
}
```

###  GET /api/v1/self/me

Permit to retrieve properties regarding the current user.

#### Headers

- Authentication: bearer <jwt_token>

#### Response

```json
{
  role: 'admin' | 'office' | 'customer'
}
```

## Language

### GET /api/v1/languages

Retrieve all the available languages.

#### Response

```typescript=
{
    code: string
    isDefault: boolean
    name: string
    uuid: string
}[]
```

## Area

### GET /api/v1/area/:areaUuid/translations

Retrieve all the translations of an area.

#### Headers

- Authentication: bearer <jwt_token>

#### Response

```typescript
{
    description: string
    languageUuid: string
    name: string
    status: string[] // e.g. deletable, modifiable
    uuid: string
}[]
```


### PUT /api/v1/area/:areaUuid/translations/:translationUuid

Modify the translation of an area.

#### Headers

- Authentication: bearer <jwt_token>

#### Body

```typescript=
{
    name: string
    description: string
}
```
<!-- ## City

### PUT /api/v1/cities/:cityUuid/translations/:translationUuid

Modify the translation of a city.

#### Headers

- Authentication: bearer <jwt_token>

#### Body

```typescript=
{
   name: string
   description: string
}
``` -->

## House Common Zone

### GET /api/v1/house-common-zones

Get house common zones list.

#### Headers

- Authentication: bearer <jwt_token>

#### Response

```typescript=
{
    createdAt: string
    defaultTranslation: {
        description: string
        name: string
        uuid: string
    }
    icon: string
    updatedAt: string
    uuid: string
}[]
```

### POST /api/v1/house-common-zones

Create new house common zone.

#### Headers

- Authentication: bearer <jwt_token>

#### Body

```typescript=
{
    icon: string
    translation: {
        name: string
        description: string
    }
}
```

#### Response

```typescript=
{
    uuid: string,
    icon: string
    translations: 
    {
        uuid: string,
        houseCommonZoneUuid: string,
        languageUuid: string,
        name: string,
        description: string,
        createdAt: isoDate,
        updatedAt: isoDate
    }[]
}
```
### GET /api/v1/house-common-zones/:houseCommonZoneUuid

Get house common zone data.

#### Headers

- Authentication: bearer <jwt_token>

#### Response

```typescript=
{
    uuid: string,
    icon: string
    createdAt: isoDate,
    updatedAt: isoDate
}[]
```

### GET /api/v1/house-common-zones/:houseCommonZoneUuid/translations

Get house common zone translations.

#### Headers

- Authentication: bearer <jwt_token>

#### Response

```typescript=
{
    uuid: string,
    houseCommonZoneUuid: string,
    languageUuid: string,
    name: string,
    description: string,
    createdAt: isoDate,
    updatedAt: isoDate
}[]
```

### PUT /api/v1/house-common-zones/:houseCommonZoneUuid/translations/:translationUuid

Modify the translation of a house common zone.

#### Headers

- Authentication: bearer <jwt_token>

#### Body

```typescript=
{
   name?: string
   description?: string
}
```

#### Response

```typescript=
{
    description: string
    name: string
    languageUuid: string
    houseCommonZoneUuid: string
    uuid: string,
    createdAt: isoDate,
    updatedAt: isoDate
}[]
```

## House Service

### GET /api/v1/house-services

Get house services list.

#### Headers

- Authentication: bearer <jwt_token>

#### Response

```typescript
{
    createdAt: string
    defaultTranslation: {
        description: string
        name: string
        uuid: string
    }
    icon: string
    updatedAt: string
    uuid: string
}[]
```

### POST /api/v1/house-services

Create new house service.

#### Headers

- Authentication: bearer <jwt_token>

#### Body

```typescript=
{
    icon: string
    translation: {
        name: string
        description: string
    }
}
```

#### Response

```typescript=
{
    uuid: string,
    icon: string
    translations: 
    {
        uuid: string,
        houseServiceUuid: string,
        languageUuid: string,
        name: string,
        description: string,
        createdAt: isoDate,
        updatedAt: isoDate
    }[]
}
```
### GET /api/v1/house-services/:houseServiceUuid

Get house service data.

#### Headers

- Authentication: bearer <jwt_token>

#### Response

```typescript=
{
    uuid: string,
    icon: string
    createdAt: isoDate,
    updatedAt: isoDate
}[]
```

### GET /api/v1/house-services/:houseServiceUuid/translations

Get house service translations.

#### Headers

- Authentication: bearer <jwt_token>

#### Response

```typescript=
{
    uuid: string,
    houseServiceUuid: string,
    languageUuid: string,
    name: string,
    description: string,
    createdAt: isoDate,
    updatedAt: isoDate
}[]
```

### PUT /api/v1/house-services/:houseServiceUuid/translations/:translationUuid

Modify the translation of a house service.

#### Headers

- Authentication: bearer <jwt_token>

#### Body

```typescript=
{
   name?: string
   description?: string
}
```

#### Response

```typescript=
{
    description: string
    name: string
    languageUuid: string
    houseServiceUuid: string
    uuid: string,
    createdAt: isoDate,
    updatedAt: isoDate
}[]
```

## Interest Points

### GET /api/v1/interest-points

Get the list of interest points.

#### Headers

- Authentication: bearer <jwt_token>

#### Response

```typescript
{
    uuid: string,
    areaUuid: string,
    latitude: numeric,
    longitude: numeric,
    address: string,
    createdAt: string,
    updatedAt: string
}[]
```

### POST /api/v1/interest-points

Create a new interest point.

#### Headers

- Authentication: bearer <jwt_token>

#### Body

```typescript=
{
    uuid: string
    areaUuid: string
    latitude: number
    longitude: number
    address: string
    translation: {
        name: string
        description: string
    }
}
```

#### Response

```typescript=
{
    uuid: string,
    areaUuid: string
    latitude: number
    longitude: number
    address: number
    createdAt: isoDate,
    updatedAt: isoDate
    translations: 
    {
        uuid: string,
        tagUuid: string,
        languageUuid: string,
        name: string,
        description: string,
        createdAt: isoDate,
        updatedAt: isoDate
    }[]
}
```
### GET /api/v1/interest-points/:interestPointsUuid

Get interest points data.

#### Headers

- Authentication: bearer <jwt_token>

#### Response

```typescript=
{
    uuid: string,
    areaUuid: string
    latitude: number
    longitude: number
    address: number
    createdAt: isoDate,
    updatedAt: isoDate
}[]
```

### GET /api/v1/interest-points/:interestPointsUuid/translations

Get interest points translations.

#### Headers

- Authentication: bearer <jwt_token>

#### Response

```typescript=
{
    uuid: string,
    interestPointUuid: string,
    languageUuid: string,
    name: string,
    description: string,
    createdAt: isoDate,
    updatedAt: isoDate
}[]
```

### PUT /api/v1/interest-points/:interestPointsUuid/translations/:translationUuid

Modify the translation of a interest point.

#### Headers

- Authentication: bearer <jwt_token>

#### Body

```typescript=
{
   name?: string
   description?: string
}
```

#### Response

```typescript=
{
    description: string
    name: string
    languageUuid: string
    interestPointUuid: string
    uuid: string,
    createdAt: isoDate,
    updatedAt: isoDate
}[]
```

## Photos

### DELETE /api/v1/photos/:uuid

Delete a photo from the DB the the S3 bucket.

#### Headers

- Authentication: bearer <jwt_token>


## Room

### GET /api/v1/aggregate/rooms/:uuid/photos

Get the photos of a room.

#### Headers

- Authentication: bearer <jwt_token>

#### Response

```typescript
{
    alt: string
    createdAt: string
    mimetypes: ('image/jpeg' | 'image/webp')[]
    uuid: string
}[]
```

### POST /api/v1/rooms/:uuid/photos

Create a new photo.

#### Headers

- Authentication: bearer <jwt_token>

#### Body

```
FormData {
    alt: string
    photo: ByteArray
}
```

## Tag

### GET /api/v1/tags

Get tags list.

#### Headers

- Authentication: bearer <jwt_token>

#### Response

```typescript
{
    uuid: string,
    createdAt: isoDate,
    updatedAt: isoDate
}[]
```

### POST /api/v1/tags

Create new Tag.

#### Headers

- Authentication: bearer <jwt_token>

#### Body

```typescript=
{
    translation: 
    {
        name: string
        description: string
    }
}
```

#### Response

```typescript=
{
    uuid: string,
    createdAt: isoDate,
    updatedAt: isoDate
    translations: 
    {
        uuid: string,
        tagUuid: string,
        languageUuid: string,
        name: string,
        description: string,
        createdAt: isoDate,
        updatedAt: isoDate
    }[]
}
```

### GET /api/v1/tags/:tagUuid

Get tag data.

#### Headers

- Authentication: bearer <jwt_token>

#### Response

```typescript=
{
    uuid: string,
    createdAt: isoDate,
    updatedAt: isoDate
}[]
```


### GET /api/v1/tags/:tagUuid/translations

Get tag translations.

#### Headers

- Authentication: bearer <jwt_token>


#### Response

```typescript=
{
    uuid: string,
    tagUuid: string,
    languageUuid: string,
    name: string,
    description: string,
    createdAt: isoDate,
    updatedAt: isoDate
}[]
```

### PUT /api/v1/tags/:tagUuid/translations/:translationUuid

Modify the translation of a tag.

#### Headers

- Authentication: bearer <jwt_token>

#### Body

```typescript=
{
   name?: string
   description?: string
}
```

#### Response

```typescript=
{
    description: string
    name: string
    languageUuid: string
    tagUuid: string
    uuid: string,
    createdAt: isoDate,
    updatedAt: isoDate
}[]
```



## Reservations


```typescript=
ReservationStatus {
  activated = 'activated',
  canceled = 'canceled',
  charging = 'charging',
  checking = 'checking',
  expired = 'expired',
  failed = 'failed',
  pending = 'pending',
  refunded = 'refunded',
}
```


### GET /api/v1/aggregate/reservations

Get aggregate reservations.

#### Headers

- Authentication: bearer <jwt_token>

#### Query params

| Name         | Description                       | Type                | Default value  |
| ------------ | --------------------------------- | ------------------- | -------------- |
| customerUuid | customer that do reservation      | uuid                | null           |
| endDate      | End date filter                   | Date                | null           |
| page         | Current page of results           | number              | 0              |
| paymentType  | Type of payment                   | `internal`\|`stripe` | null           |
| results      | Number of results of current page | number              | 5              |
| roomUuid     | room reserved                     | uuid                | null           |
| startDate    | Start Date filter                 | Date                | null           |
| status       | Reservation status                | ReservationStatus   | null           |

#### Response

```typescript=
{
  customerUuid: string
  deletedAt: Date | undefind
  depositPrice: number
  endDate: Date
  price: number
  roomUuid: string
  startDate: Date
  status: ReservationStatus
  uuid: string
  customer: {
    deletedAt: Date | undefind
    email: string
    firstName: string
    lastName: string
    phone: string
    uuid: string
  }
  room: {
    active: boolean
    creatorUuid: string
    depositPrice: number
    description: string
    electricityBill: boolean
    gasBill: boolean
    house: {
        uuid: string
        areaUuid: string
        creatorUuid: string
        address: string
        area: {
            cityUuid: string
            city: {
                description: string
                name: string
                uuid: string
            }
            description: string
            name: string
            uuid: string
        }
    }
    houseUuid: string
    internetBill: boolean
    monthPrice: number
    name: string
    roomType: 'double' | 'shared' | 'single',
    size: number
    uuid: string
    waterBill: boolean
  }
  payment:{
    deletedAt: Date | undefind
    type: 'internal' | 'stripe'
    paymentId: string
    reservationUuid: string
    uuid: string
  }
}[]
```


### GET /api/v1/aggregate/reservations/:reservationUuid

Get aggregate reservation.

#### Headers

- Authentication: bearer <jwt_token>


#### Response

```typescript=
{
  customerUuid: string
  deletedAt: Date | undefind
  depositPrice: number
  endDate: Date
  price: number
  roomUuid: string
  startDate: Date
  status: ReservationStatus
  uuid: string
  customer: {
    deletedAt: Date | undefind
    email: string
    firstName: string
    lastName: string
    phone: string
    uuid: string
  }
  room: {
    active: boolean
    creatorUuid: string
    depositPrice: number
    description: string
    electricityBill: boolean
    gasBill: boolean
    house: {
        uuid: string
        areaUuid: string
        creatorUuid: string
        address: string
        area: {
            cityUuid: string
            city: {
                description: string
                name: string
                uuid: string
            }
            description: string
            name: string
            uuid: string
        }
    }
    houseUuid: string
    internetBill: boolean
    monthPrice: number
    name: string
    roomType: 'double' | 'shared' | 'single',
    size: number
    uuid: string
    waterBill: boolean
  }
  payment:{
    deletedAt: Date | undefind
    type: 'internal' | 'stripe'
    paymentId: string
    reservationUuid: string
    uuid: string
  }
}
```

### PATCH /api/v1/aggregate/reservations/:reservationUuid/period

Get aggregate reservation.

#### Headers

- Authentication: bearer <jwt_token>

#### Body

```typescript=
{
   endDate: isoDate
   startDate: isoDate
}
```

#### Response

```typescript=
{
  customerUuid: string
  deletedAt: Date | undefind
  depositPrice: number
  endDate: Date
  price: number
  roomUuid: string
  startDate: Date
  status: ReservationStatus
  uuid: string
}
```


## Payments