Introduction
The Roomies API is provided for authorized users to integrate with our platform programatically. It allows access to public available listings, as well as controls to manage existing listings. You will need API access which is not available for all accounts, only on request.
This documentation aims to provide all the information you need to work with our API.
Authenticating requests
To authenticate requests, include an Authorization header with the value "Bearer {API_TOKEN}".
All authenticated endpoints are marked with a requires authentication badge in the documentation below.
You can retrieve your token by visiting your dashboard and clicking Generate API token.
Feeds
Endpoints that return currently available listings that can be listed on other sites with permission.
Available rooms
requires authentication
This endpoint will return currently available rooms.
Example request:
curl --request GET \
--get "https://www.roomies.com/api/v1/feeds/rooms" \
--header "Authorization: Bearer {API_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"const url = new URL(
"https://www.roomies.com/api/v1/feeds/rooms"
);
const headers = {
"Authorization": "Bearer {API_TOKEN}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());Example response (200):
{
"data": [
{
"id": 1,
"url": "https://www.roomies.com/rooms/1",
"user": {
"id": 1,
"first_name": "Camylle",
"photo_url": null,
"large_photo_url": null,
"leads_enabled": false,
"last_active_at": null,
"preferred_locale": "en_US",
"banned": false,
"deleted": false
},
"subtitle": "Furnished room in an apartment",
"route": "Angelina Overpass",
"postcode": "53446",
"location": {
"id": 1,
"place_name": "Lake Gunner, KY",
"neighborhood": null,
"locality": null,
"place": "Lake Gunner",
"district": null,
"region": "KY",
"country": "United States",
"latitude": 58.516672,
"longitude": -136.552423
},
"photos": [
{
"id": 1,
"url": "https://res.cloudinary.com/test/image/upload/c_fill,dpr_1.0,f_jpg,fl_lossy,g_auto,h_512,q_auto:good,w_896/0868d42e08afc44e27fd719358ef1a5b",
"order": 1
}
],
"rent": 2774,
"bills_included": true,
"security_deposit": 1975,
"available_on": "2004-12-12",
"preferred_gender": "Males",
"property_type": "apartment",
"bathroom_type": "Shared bathroom",
"stay_length": null,
"bedrooms": null,
"bathrooms": null,
"roomies": null,
"parking": true,
"internet_access": true,
"private_room": true,
"furnished": true,
"accessible": true,
"description": "Extra Spacious Master bed and bath tes with King bed, attached ensuite bathroom with double vanity, and walk-in closet near Red Rock.",
"roomies_description": "We are animal-friendly vegans looking for other like-minded folks who are veg-friendly.",
"lgbt_friendly": true,
"cannabis_friendly": true,
"cat_friendly": true,
"dog_friendly": true,
"children_friendly": true,
"student_friendly": true,
"senior_friendly": true,
"requires_background_check": true,
"latitude": -60.12459,
"longitude": 168.25346,
"activated": false
},
{
"id": 2,
"url": "https://www.roomies.com/rooms/2",
"user": {
"id": 2,
"first_name": "Jackeline",
"photo_url": null,
"large_photo_url": null,
"leads_enabled": false,
"last_active_at": null,
"preferred_locale": "en_US",
"banned": false,
"deleted": false
},
"subtitle": "Furnished room with ensuite in a house",
"route": "Caroline Mount",
"postcode": "79752",
"location": {
"id": 2,
"place_name": "Teresaborough, HI",
"neighborhood": null,
"locality": null,
"place": "Teresaborough",
"district": null,
"region": "HI",
"country": "United States",
"latitude": -31.972498,
"longitude": -55.011469
},
"photos": [
{
"id": 2,
"url": "https://res.cloudinary.com/test/image/upload/c_fill,dpr_1.0,f_jpg,fl_lossy,g_auto,h_512,q_auto:good,w_896/100df5aec4398bc40a32470d0df517e8",
"order": 1
}
],
"rent": 2055,
"bills_included": true,
"security_deposit": 2049,
"available_on": "1991-12-29",
"preferred_gender": "Anyone welcome",
"property_type": "house",
"bathroom_type": "Ensuite",
"stay_length": null,
"bedrooms": null,
"bathrooms": null,
"roomies": null,
"parking": true,
"internet_access": true,
"private_room": true,
"furnished": true,
"accessible": true,
"description": "Extra Spacious Master bed and bath tes with King bed, attached ensuite bathroom with double vanity, and walk-in closet near Red Rock.",
"roomies_description": "We are animal-friendly vegans looking for other like-minded folks who are veg-friendly.",
"lgbt_friendly": true,
"cannabis_friendly": true,
"cat_friendly": true,
"dog_friendly": true,
"children_friendly": true,
"student_friendly": true,
"senior_friendly": true,
"requires_background_check": true,
"latitude": -82.46995,
"longitude": -37.29038,
"activated": false
}
],
"links": {
"first": "/?page=1",
"last": "/?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"links": [
{
"url": null,
"label": "« Previous",
"active": false
},
{
"url": "/?page=1",
"label": "1",
"active": true
},
{
"url": null,
"label": "Next »",
"active": false
}
],
"path": "/",
"per_page": 500,
"to": 2,
"total": 2
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.Leads
Endpoints for managing received leads.
List leads
requires authentication
This endpoint will return all your leads, sorted by their age.
Example request:
curl --request GET \
--get "https://www.roomies.com/api/v1/leads" \
--header "Authorization: Bearer {API_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"const url = new URL(
"https://www.roomies.com/api/v1/leads"
);
const headers = {
"Authorization": "Bearer {API_TOKEN}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());Example response (200):
{
"data": [
{
"leadable_id": 3,
"leadable_type": "App\\Models\\Room",
"name": "Vivianne",
"email": "kuhn.jaclyn@roomies.com",
"phone_number": null,
"content": "Quam sed quasi commodi tempore in qui hic.",
"created_at": "2025-02-10T04:31:44+00:00"
},
{
"leadable_id": 4,
"leadable_type": "App\\Models\\Room",
"name": "Jerrold",
"email": "rosendo.stracke@roomies.com",
"phone_number": null,
"content": "Aliquam recusandae sit nihil.",
"created_at": "2025-02-10T04:31:44+00:00"
}
],
"links": {
"first": "/?page=1",
"last": "/?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"links": [
{
"url": null,
"label": "« Previous",
"active": false
},
{
"url": "/?page=1",
"label": "1",
"active": true
},
{
"url": null,
"label": "Next »",
"active": false
}
],
"path": "/",
"per_page": 25,
"to": 2,
"total": 2
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.