Coliving JSON Feed
JSON import example
This is the payload shape we ingest from host feeds. Use stable IDs where possible, omit optional fields instead of placeholders, and use /json/guide for the integration flow and /json/docs for the field-by-field reference.
POST /v1/listings only creates a listing. A matching listing returns 409 and is not updated. Use PATCH with the Coliving listing id to update.
Example Payload
{
"original_id": "property-01",
"original_url": "https://host.example.com/listings/property-01",
"name": "300 Mountain Road",
"property_size": 2500,
"property_size_unit": "m2",
"parking": "Parking on street (free)",
"internet_download": 300,
"internet_upload": 150,
"bedrooms": 10,
"bathrooms": 8,
"residents": 18,
"descriptions": {
"property": "Bright shared home with spacious, work-ready common areas.",
"neighborhood": "Walkable area near transit and cafes.",
"community": "Residents are social, respectful, and internationally minded."
},
"location": {
"address": "300 Mountain Road",
"zip": "90210",
"neighborhood": "Mission District",
"city": "San Francisco",
"state": "California",
"country": "United States",
"lat": 37.8081823,
"lng": -122.4141216
},
"amenities": [
{
"id": 12
}
],
"prices": {
"currency": "usd",
"security_deposit_type": "fixed",
"security_deposit": 1000,
"extra_fees": [
{
"section": "common",
"category": "extra_occupancy",
"name": "Extra guest fee",
"mandatory": 0,
"type": "fixed",
"sum": 50,
"frequency": "monthly"
},
{
"section": "service",
"category": "parking",
"name": "Parking",
"mandatory": 0,
"type": "fixed",
"sum": 100,
"frequency": "monthly"
},
{
"section": "other",
"category": "utilities",
"name": "Utilities fee",
"description": "Electricity, water, and gas",
"mandatory": 1,
"type": "fixed",
"sum": 200,
"frequency": "monthly"
},
{
"section": "other",
"category": "host_service_package",
"name": "Service Package",
"mandatory": 1,
"type": "fixed",
"sum": 250,
"frequency": "once"
},
{
"section": "other",
"name": "City admin levy",
"mandatory": 1,
"type": "fixed",
"sum": 30,
"frequency": "once"
},
{
"section": "tax",
"category": "vat",
"name": "VAT",
"mandatory": 1,
"type": "percent",
"sum": 10,
"frequency": "monthly",
"applies_to": "rent"
}
]
},
"room_types": [
{
"original_id": "private-queen-01",
"name": "Private queen room",
"room_type": "private",
"bed_type": "queen",
"application_url": "https://host.example.com/apply/private-queen-01",
"room_size": 180,
"room_size_unit": "sqft",
"max_occupancy": 2,
"gender": "mixed",
"bathroom_type": "private",
"available_at": "2026-03-16",
"rooms": [
{
"original_id": "room-104",
"name": "Room 104",
"description": "Quiet room with desk and closet.",
"availability": {
"ical": "https://host.example.com/ical/room-104.ics"
}
}
],
"prices": {
"base_price": 1200,
"price_jan": 1200,
"price_feb": 1200,
"price_mar": 1200,
"price_apr": 1250,
"price_may": 1250,
"price_jun": 1300,
"price_jul": 1300,
"price_aug": 1300,
"price_sep": 1250,
"price_oct": 1250,
"price_nov": 1200,
"price_dec": 1200,
"discount_90": 5,
"discount_180": 10,
"discount_360": 15
},
"amenities": [
{
"id": 34
}
],
"photos": [
{
"url": "https://assets.host.example.com/room-104.jpg",
"description": "Desk and window"
}
]
}
],
"bookings": {
"stay_min": 3,
"notice_min_days": 14,
"move_in_max_days": 90,
"application_url": "https://host.example.com/apply/property-01",
"cancellation_policy": "flexible",
"booking_rules": "No overnight guests without approval."
},
"community": {
"age_min": 25,
"age_max": 45,
"age_avg": 31,
"gender": "mixed",
"gender_ratio": 50,
"events": [
{
"id": 1061
}
],
"community_manager": {
"name": "Jeff",
"photo": "https://assets.host.example.com/community-manager.jpg",
"onsite": 1
},
"types": [
{
"id": 8
}
]
},
"media": {
"3d_tour": "https://my.matterport.com/show/?m=123456789",
"video_tour": {
"type": "youtube",
"url": "https://www.youtube.com/watch?v=fYfFgcBlxrQ"
},
"photos": {
"property": [
{
"url": "https://assets.host.example.com/property-01.jpg",
"description": "Coworking lounge"
}
],
"community": [
{
"url": "https://assets.host.example.com/community-01.jpg",
"description": "Community dinner"
}
]
}
},
"instructions": {
"check_in_earliest": "14:30",
"check_in_latest": "20:00",
"check_out_latest": "11:00",
"check_in_contact_person": "Sandra",
"check_in_telephone_country": "+1",
"check_in_telephone_number": "5551234567",
"check_in_instructions": "Use the keypad at the main entrance.",
"directions": "From the airport, take the express train to Downtown Station.",
"house_manual": "Quiet hours start at 10pm. Clean shared areas after use."
},
"faq": [
{
"question": "Is cleaning included?",
"answer": "Yes, common areas are cleaned weekly."
}
],
"rating": {
"google_places_id": "ChIJN1t_tDeuEmsRUsoyG83frY4"
}
}
Practical Notes
- This is the feed shape we ingest from hosts to create and update listings over time.
- POST /v1/listings only creates a listing. If this host already has a listing with the same original_id, original_url, address, or name, the API returns 409 and does not update it. Update an existing listing with PATCH /v1/listings/{id} and the Coliving listing id.
- On PATCH, include the Coliving `id` to update an existing room type or room. Omit `id` to create a new one; new room types require `name`, `room_type`, and `prices.base_price`, and new rooms require `name`. The PATCH response includes the listing room types and room IDs so you can store and use those IDs on later updates. When sending `room_types`, include every existing room type you want to keep active; omitted room types remain stored but are deferred for one year.
- Omit optional fields instead of sending placeholders like `N/A`, empty strings, or fake coordinates.
- Enum values must match the helper endpoints exactly.
- Photo URLs and iCal URLs must be public and reachable without authentication.
- Use `\n` for new lines inside text fields.
- `faq` accepts question-and-answer objects, so hosts can send FAQ content through the JSON feed without re-entering it manually in the UI.
- Do not send `status`. POST stores `pending_api`. PATCH does not change listing status. Only Coliving admin can publish a listing or take it offline.
- `prices.extra_fees` covers common fees, optional services, mandatory other fees, and taxes. Send `section` and `category` for a catalog fee. Omit `category` only for a custom Other fee. Send `applies_to` for a percent tax. Catalog fees are stored with the catalog name, the locked mandatory flag, and `once` where frequency is locked. A fee left out of a later PATCH is kept.