Halls API (1.0.0)

Download OpenAPI specification:

Please contact your account manager with any queries, or if in doubt email support@studentcrowd.com.

Request Rate Limiting

To ensure the stability and performance of our API for all users, we have implemented a request rate limit. This rate limit is designed to prevent excessive usage that could impact the service quality for other users.

Rate Limit Details:

Request Limit: 60 requests
Time Window: 60 seconds (1 minute)

This means that within any given 60-second window, a maximum of 60 requests can be made to the API from a single client (identified by an API key or IP address). If the number of requests exceeds this limit, additional requests will be temporarily blocked until the start of the next time window.

Halls

List

query Parameters

size	integer <int32> <= 500 Default: 100 Number of results to return
updated_since	string <date-time> Example: updated_since=2026-02-01T00:00:00Z Optional. Return only halls updated after this timestamp (delta sync). Format: ISO 8601 in UTC, e.g. `2026-02-11T14:30:00Z`. Invalid or malformed values return 400 Bad Request.

Responses

Response samples

200
429

Content type

application/json

{"data": [{"type": "hall",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"attributes": {"name": "Kingsley Lodge",
"type": "private",
"landlord": "string",
"postcode": "string",
"catering": "catered",
"available": true,
"availability": "available",
"minimumPrice": 134.5,
"pricePersonWeek": 67.25,
"currency": "gbp",
"billingCycle": "weekly",
"beds": 30,
"city": "Chester",
"country": "United Kingdom",
"features": ["Bike Storage",
"CCTV / Surveillance Cameras",
"Contents Insurance",
"Onsite Cafeteria",
"WiFi In Room (All Free)"
],
"rating": 4.14,
"criteriaRatings": {"value": 5,
"management": 5,
"socialSpaces": 1,
"internetWifi": 4,
"location": 4,
"cleaning": 5,
"socialExperience": 4
},
"openingDate": "2020/8",
"latitude": 53.19,
"longitude": -2.891,
"accommodationType": "PBSA",
"propSet": {"quality": "B",
"price": "2",
"location": [{"tag": "Near-Campus",
"reference": "Nottingham Trent University (NTU)",
"ukprn": "10004797"
}
],
"label": "B 2 Near-Campus, City"
},
"createdAt": "2017-11-29T10:54:06+00:00",
"updatedAt": "2017-11-29T10:54:06+00:00"
},
"relationships": {"roomTypes": {"links": {"related": "/halls/{hallId}/room-types"
}
},
"reviews": {"links": {"related": "/halls/{hallId}/reviews"
}
}
},
"links": {"self": "/halls/{hallId}"
}
}
],
"links": {"self": "/{path}?page=1",
"first": "/{path}?page=1",
"prev": "/{path}?page=2",
"next": "/{path}?page=4",
"last": "/{path}?page=10"
}
}

Hall

path Parameters

hallId

required

string

Hall ID

Responses

Response samples

200
429

Content type

application/json

{"type": "hall",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"attributes": {"name": "Kingsley Lodge",
"type": "private",
"landlord": "string",
"postcode": "string",
"catering": "catered",
"available": true,
"availability": "available",
"minimumPrice": 134.5,
"pricePersonWeek": 67.25,
"currency": "gbp",
"billingCycle": "weekly",
"beds": 30,
"city": "Chester",
"country": "United Kingdom",
"features": ["Bike Storage",
"CCTV / Surveillance Cameras",
"Contents Insurance",
"Onsite Cafeteria",
"WiFi In Room (All Free)"
],
"rating": 4.14,
"criteriaRatings": {"value": 5,
"management": 5,
"socialSpaces": 1,
"internetWifi": 4,
"location": 4,
"cleaning": 5,
"socialExperience": 4
},
"openingDate": "2020/8",
"latitude": 53.19,
"longitude": -2.891,
"accommodationType": "PBSA",
"propSet": {"quality": "B",
"price": "2",
"location": [{"tag": "Near-Campus",
"reference": "Nottingham Trent University (NTU)",
"ukprn": "10004797"
}
],
"label": "B 2 Near-Campus, City"
},
"createdAt": "2017-11-29T10:54:06+00:00",
"updatedAt": "2017-11-29T10:54:06+00:00"
},
"relationships": {"roomTypes": {"links": {"related": "/halls/{hallId}/room-types"
}
},
"reviews": {"links": {"related": "/halls/{hallId}/reviews"
}
}
},
"links": {"self": "/halls/{hallId}"
}
}

Reviews

path Parameters

hallId

required

string

Hall ID

query Parameters

size	integer <int32> <= 500 Default: 100 Number of results to return

Responses

Response samples

200
429

Content type

application/json

{"data": [{"type": "review",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"attributes": {"text": "I have loved my time at this University",
"ratings": {"value": 5,
"management": 5,
"socialSpaces": 1,
"internetWifi": 4,
"location": 4,
"cleaning": 5,
"socialExperience": 4
},
"userType": "CURRENT",
"studentType": "UK",
"averageRating": 4.14,
"createdAt": "2017-11-29T10:54:06+00:00",
"updatedAt": "2017-11-29T10:54:06+00:00"
},
"relationships": {"hall": {"links": {"related": "/halls/{hallId}"
}
}
},
"links": {"self": "/reviews/{hallId}"
}
}
],
"links": {"self": "/{path}?page=1",
"first": "/{path}?page=1",
"prev": "/{path}?page=2",
"next": "/{path}?page=4",
"last": "/{path}?page=10"
}
}

Room Types

path Parameters

hallId

required

string

Hall ID

query Parameters

size	integer <int32> <= 500 Default: 100 Number of results to return

Responses

Response samples

200
429

Content type

application/json

{"data": [{"type": "roomType",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"attributes": {"name": "Deluxe suite",
"arrangement": "apartment",
"bedroomOccupancy": 1,
"priceArrangement": "per_room",
"price": 134.5,
"pricePersonWeek": 67.25,
"squareMeters": {"min": 23,
"max": 27
},
"available": true,
"createdAt": "2017-11-29T10:54:06+00:00",
"updatedAt": "2017-11-29T10:54:06+00:00"
},
"relationships": {"hall": {"links": {"related": "/halls/{hallId}"
}
},
"roomTenancies": {"links": {"related": "/room-types/{roomTypeId}/room-tenancies"
}
}
},
"links": {"self": "/room-types/{roomTypeId}"
}
}
],
"links": {"self": "/{path}?page=1",
"first": "/{path}?page=1",
"prev": "/{path}?page=2",
"next": "/{path}?page=4",
"last": "/{path}?page=10"
}
}

Room Types

List

query Parameters

size	integer <int32> <= 500 Default: 100 Number of results to return
updated_since	string <date-time> Example: updated_since=2026-02-01T00:00:00Z Optional. Return only room types updated after this timestamp (delta sync). Format: ISO 8601 in UTC, e.g. `2026-02-11T14:30:00Z`. Invalid or malformed values return 400 Bad Request.

Responses

Response samples

200
429

Content type

application/json

{"data": [{"type": "roomType",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"attributes": {"name": "Deluxe suite",
"arrangement": "apartment",
"bedroomOccupancy": 1,
"priceArrangement": "per_room",
"price": 134.5,
"pricePersonWeek": 67.25,
"squareMeters": {"min": 23,
"max": 27
},
"available": true,
"createdAt": "2017-11-29T10:54:06+00:00",
"updatedAt": "2017-11-29T10:54:06+00:00"
},
"relationships": {"hall": {"links": {"related": "/halls/{hallId}"
}
},
"roomTenancies": {"links": {"related": "/room-types/{roomTypeId}/room-tenancies"
}
}
},
"links": {"self": "/room-types/{roomTypeId}"
}
}
],
"links": {"self": "/{path}?page=1",
"first": "/{path}?page=1",
"prev": "/{path}?page=2",
"next": "/{path}?page=4",
"last": "/{path}?page=10"
}
}

RoomType

path Parameters

roomTypeId

required

string

RoomType ID

Responses

Response samples

200
429

Content type

application/json

{"type": "roomType",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"attributes": {"name": "Deluxe suite",
"arrangement": "apartment",
"bedroomOccupancy": 1,
"priceArrangement": "per_room",
"price": 134.5,
"pricePersonWeek": 67.25,
"squareMeters": {"min": 23,
"max": 27
},
"available": true,
"createdAt": "2017-11-29T10:54:06+00:00",
"updatedAt": "2017-11-29T10:54:06+00:00"
},
"relationships": {"hall": {"links": {"related": "/halls/{hallId}"
}
},
"roomTenancies": {"links": {"related": "/room-types/{roomTypeId}/room-tenancies"
}
}
},
"links": {"self": "/room-types/{roomTypeId}"
}
}

Room Tenancies

List

query Parameters

size	integer <int32> <= 500 Default: 100 Number of results to return
updated_since	string <date-time> Example: updated_since=2026-02-01T00:00:00Z Optional. Return only room tenancies updated after this timestamp (delta sync). Format: ISO 8601 in UTC, e.g. `2026-02-11T14:30:00Z`. Invalid or malformed values return 400 Bad Request.

Responses

Response samples

200
429

Content type

application/json

{"data": [{"type": "roomTenancy",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"attributes": {"type": "flexible",
"price": 174.08,
"pricePersonWeek": 87.04,
"available": true,
"startDate": "2021-09-22",
"academicYear": "21/22",
"minimumStay": 180,
"incentiveText": "£150 cashback for 22/23 bookings",
"incentiveValue": 150,
"createdAt": "2021-11-29T10:54:06+00:00",
"updatedAt": "2021-11-29T10:54:06+00:00"
},
"relationships": {"roomType": {"links": {"related": "/room-types/{roomTypeId}"
}
}
},
"links": {"self": "/room-tenancies/{roomTenancyId}"
}
}
],
"links": {"self": "/{path}?page=1",
"first": "/{path}?page=1",
"prev": "/{path}?page=2",
"next": "/{path}?page=4",
"last": "/{path}?page=10"
}
}

RoomTenancy

path Parameters

roomTenancyId

required

string

Room Tenancy ID

Responses

Response samples

200
429

Content type

application/json

{"type": "roomTenancy",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"attributes": {"type": "flexible",
"price": 174.08,
"pricePersonWeek": 87.04,
"available": true,
"startDate": "2021-09-22",
"academicYear": "21/22",
"minimumStay": 180,
"incentiveText": "£150 cashback for 22/23 bookings",
"incentiveValue": 150,
"createdAt": "2021-11-29T10:54:06+00:00",
"updatedAt": "2021-11-29T10:54:06+00:00"
},
"relationships": {"roomType": {"links": {"related": "/room-types/{roomTypeId}"
}
}
},
"links": {"self": "/room-tenancies/{roomTenancyId}"
}
}

Reviews

List

query Parameters

size	integer <int32> <= 500 Default: 100 Number of results to return
updated_since	string <date-time> Example: updated_since=2026-02-01T00:00:00Z Optional. Return only reviews updated after this timestamp (delta sync). Format: ISO 8601 in UTC, e.g. `2026-02-11T14:30:00Z`. Invalid or malformed values return 400 Bad Request.

Responses

Response samples

200
429

Content type

application/json

{"data": [{"type": "review",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"attributes": {"text": "I have loved my time at this University",
"ratings": {"value": 5,
"management": 5,
"socialSpaces": 1,
"internetWifi": 4,
"location": 4,
"cleaning": 5,
"socialExperience": 4
},
"userType": "CURRENT",
"studentType": "UK",
"averageRating": 4.14,
"createdAt": "2017-11-29T10:54:06+00:00",
"updatedAt": "2017-11-29T10:54:06+00:00"
},
"relationships": {"hall": {"links": {"related": "/halls/{hallId}"
}
}
},
"links": {"self": "/reviews/{hallId}"
}
}
],
"links": {"self": "/{path}?page=1",
"first": "/{path}?page=1",
"prev": "/{path}?page=2",
"next": "/{path}?page=4",
"last": "/{path}?page=10"
}
}

Review

path Parameters

reviewId

required

string

Review ID

Responses

Response samples

200
429

Content type

application/json

{"type": "review",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"attributes": {"text": "I have loved my time at this University",
"ratings": {"value": 5,
"management": 5,
"socialSpaces": 1,
"internetWifi": 4,
"location": 4,
"cleaning": 5,
"socialExperience": 4
},
"userType": "CURRENT",
"studentType": "UK",
"averageRating": 4.14,
"createdAt": "2017-11-29T10:54:06+00:00",
"updatedAt": "2017-11-29T10:54:06+00:00"
},
"relationships": {"hall": {"links": {"related": "/halls/{hallId}"
}
}
},
"links": {"self": "/reviews/{hallId}"
}
}