Coliving JSON Feed
JSON import field guide
Use /json/import as the example payload and this page as the field-by-field reference for statuses, defaults, and helper endpoints.
Required
Needed to submit a valid request.
Recommended
Strongly recommended for high-quality listing sync, matching, and listing quality.
Optional
Supported, but safe to omit when it does not apply.
Conditional
Only needed when that nested object or workflow is provided.
Fields with documented defaults should not be marked required. If a field is optional here, hosts may omit it and let the importer apply the default where supported.
Practical Notes
- This is the feed shape we ingest from hosts to create and update listings over time.
- Use stable IDs where possible. `original_id` is the strongest sync key, and `original_url` is the preferred fallback when a stable ID is not available.
- 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.
Original Id
| Field | Type | Status | Notes |
|---|---|---|---|
original_id |
string |
Recommended | Stable listing ID in your system. Keep it unchanged across updates because it is the strongest sync key. |
Original Url
| Field | Type | Status | Notes |
|---|---|---|---|
original_url |
string |
Recommended | Public listing URL in your system. Used as the preferred fallback sync key when `original_id` is unavailable. |
Name
| Field | Type | Status | Notes |
|---|---|---|---|
name |
string |
Required | Listing name shown to residents and used in fallback matching. |
Property Size
| Field | Type | Status | Notes |
|---|---|---|---|
property_size |
integer |
Optional | Indoor property size. |
Property Size Unit
| Field | Type | Status | Notes |
|---|---|---|---|
property_size_unit |
string |
Optional | Unit for `property_size`. Use `m2` or `sqft`. |
Parking
| Field | Type | Status | Notes |
|---|---|---|---|
parking |
string |
Optional | Parking value from `/json/import/parking`. |
Internet Download
| Field | Type | Status | Notes |
|---|---|---|---|
internet_download |
integer |
Recommended | Download speed in Mbps. |
Internet Upload
| Field | Type | Status | Notes |
|---|---|---|---|
internet_upload |
integer |
Recommended | Upload speed in Mbps. |
Bedrooms
| Field | Type | Status | Notes |
|---|---|---|---|
bedrooms |
integer |
Optional | Total bedrooms on the property. |
Bathrooms
| Field | Type | Status | Notes |
|---|---|---|---|
bathrooms |
integer |
Optional | Total bathrooms on the property. |
Residents
| Field | Type | Status | Notes |
|---|---|---|---|
residents |
integer |
Optional | Maximum residents on the property. |
Descriptions
| Field | Type | Status | Notes |
|---|---|---|---|
descriptions.property |
text |
Recommended | Property description. Use `\n` for new lines. |
descriptions.neighborhood |
text |
Optional | Neighborhood description. Use `\n` for new lines. |
descriptions.community |
text |
Optional | Community description. Use `\n` for new lines. |
Location
| Field | Type | Status | Notes |
|---|---|---|---|
location.address |
string |
Optional | Street address. |
location.zip |
string |
Optional | Postal code. |
location.neighborhood |
string |
Optional | Neighborhood name. |
location.city |
string |
Optional | City name. |
location.state |
string |
Optional | State, province, or region. |
location.country |
string |
Recommended | Country name. We use this for location defaults, room-size-unit defaults, and matching. |
location.lat |
decimal |
Optional | Latitude. Omit instead of sending placeholders. |
location.lng |
decimal |
Optional | Longitude. Omit instead of sending placeholders. |
Amenities
| Field | Type | Status | Notes |
|---|---|---|---|
amenities[] |
array |
Optional | Array of amenities. |
amenities[].id |
integer |
Conditional | Listing amenity ID from `/json/import/listing-amenities`. |
Prices
| Field | Type | Status | Notes |
|---|---|---|---|
prices.currency |
string |
Optional | Currency code, for example `usd` or `eur`. Default: usd. |
prices.security_deposit_type |
string |
Optional | Use `%` or `fixed`. |
prices.security_deposit |
integer |
Optional | Whole amount in the source currency unless the type is `%`. |
prices.extra_fees[] |
array |
Optional | Array of extra fees. |
prices.extra_fees[].name |
string |
Conditional | Fee name. |
prices.extra_fees[].description |
string |
Optional | Fee description. |
prices.extra_fees[].mandatory |
integer |
Optional | Use `0` or `1`. |
prices.extra_fees[].type |
string |
Optional | Use `fixed` or `percent`. Default: fixed. |
prices.extra_fees[].sum |
integer |
Conditional | Fee amount. |
prices.extra_fees[].frequency |
string |
Conditional | Use `once` or `monthly`. |
Room Types
| Field | Type | Status | Notes |
|---|---|---|---|
room_types[] |
array |
Required | Array of room types. |
room_types[].id |
string |
Optional | Stable room-type ID in your system. Recommended for clean updates across syncs. |
room_types[].name |
string |
Required | Room-type display name. |
room_types[].room_type |
string |
Required | Use `private` or `shared`. |
room_types[].bed_type |
string |
Recommended | Use values like `single`, `full`, `queen`, `king`, `twin`, or `bunk`. |
room_types[].application_url |
string |
Optional | Direct application URL for this room type. |
room_types[].room_size |
integer |
Recommended | Room size. |
room_types[].room_size_unit |
string |
Optional | Unit for `room_size`. If omitted, we derive it from `location.country`. Default: Auto-derived from location country (`sqft` for United States, Liberia, and Myanmar; otherwise `m2`).. |
room_types[].max_occupancy |
integer |
Optional | Maximum residents for this room type. Default: 1. |
room_types[].gender |
string |
Optional | Use for shared rooms when relevant: `mixed`, `male`, or `female`. |
room_types[].bathroom_type |
string |
Optional | Use `private` or `shared`. Default: private. |
room_types[].available_at |
date |
Optional | First available date for the room type. If each room has an `availability.ical` URL, you can omit this field. |
room_types[].rooms[] |
array |
Optional | Array of rooms. |
room_types[].rooms[].id |
string |
Optional | Stable room ID in your system. |
room_types[].rooms[].name |
string |
Conditional | Room name. Required when sending a room object. |
room_types[].rooms[].description |
string |
Optional | Room-level description. |
room_types[].rooms[].availability |
object |
Optional | Availability object. |
room_types[].rooms[].availability.ical |
string |
Recommended | Public iCal URL for room-level availability. |
room_types[].prices |
object |
Required | Room Type Prices object. |
room_types[].prices.base_price |
integer |
Required | Monthly base price. Whole amount in the source currency. |
room_types[].prices.price_jan |
integer |
Optional | January price override. |
room_types[].prices.price_feb |
integer |
Optional | February price override. |
room_types[].prices.price_mar |
integer |
Optional | March price override. |
room_types[].prices.price_apr |
integer |
Optional | April price override. |
room_types[].prices.price_may |
integer |
Optional | May price override. |
room_types[].prices.price_jun |
integer |
Optional | June price override. |
room_types[].prices.price_jul |
integer |
Optional | July price override. |
room_types[].prices.price_aug |
integer |
Optional | August price override. |
room_types[].prices.price_sep |
integer |
Optional | September price override. |
room_types[].prices.price_oct |
integer |
Optional | October price override. |
room_types[].prices.price_nov |
integer |
Optional | November price override. |
room_types[].prices.price_dec |
integer |
Optional | December price override. |
room_types[].prices.discount_90 |
integer |
Optional | Discount percentage for 90+ day stays. |
room_types[].prices.discount_180 |
integer |
Optional | Discount percentage for 180+ day stays. |
room_types[].prices.discount_360 |
integer |
Optional | Discount percentage for 360+ day stays. |
room_types[].amenities[] |
array |
Optional | Array of room amenities. |
room_types[].amenities[].id |
integer |
Recommended | Room amenity ID from `/json/import/room-type-amenities`. |
room_types[].photos[] |
array |
Optional | Array of room photos. |
room_types[].photos[].url |
string |
Conditional | Public photo URL. |
room_types[].photos[].description |
string |
Optional | Short photo caption. |
Bookings
| Field | Type | Status | Notes |
|---|---|---|---|
bookings.stay_min |
integer |
Optional | Minimum stay in months. Default: 1. |
bookings.notice_min_days |
integer |
Optional | Minimum notice before move-in. Default: 2. |
bookings.move_in_max_days |
integer |
Optional | Maximum days before move-in. |
bookings.application_url |
string |
Optional | Property-level application URL. |
bookings.cancellation_policy |
string |
Optional | Cancellation policy from `/json/import/cancellation-policies`. Default: flexible. |
bookings.booking_rules |
string |
Optional | Free-text booking notes or restrictions. |
Community
| Field | Type | Status | Notes |
|---|---|---|---|
community.age_min |
integer |
Optional | Minimum age. Default: 18. |
community.age_max |
integer |
Optional | Maximum age. |
community.age_avg |
integer |
Optional | Average age. |
community.gender |
string |
Optional | Community gender mix, for example `mixed`. |
community.gender_ratio |
integer |
Optional | If mixed, `40` means roughly 40% men and 60% women. |
community.events[] |
array |
Optional | Array of community events. |
community.events[].id |
integer |
Conditional | Community event ID from `/json/import/community-events`. |
community.community_manager |
object |
Optional | Community Manager object. |
community.community_manager.name |
string |
Recommended | First name only. |
community.community_manager.photo |
string |
Recommended | Public headshot URL. |
community.community_manager.onsite |
integer |
Optional | Use `1` for onsite and `0` for not onsite. |
community.types[] |
array |
Optional | Array of community types. |
community.types[].id |
integer |
Conditional | Community type ID from `/json/import/community-types`. |
Media
| Field | Type | Status | Notes |
|---|---|---|---|
media.3d_tour |
string |
Recommended | Direct URL to a 3D tour. |
media.video_tour |
object |
Optional | Video Tour object. |
media.video_tour.type |
string |
Conditional | Use `youtube` or `vimeo`. |
media.video_tour.url |
string |
Recommended | Direct public video URL. |
media.photos |
object |
Optional | Photos object. |
media.photos.property[] |
array |
Optional | Array of property photos. |
media.photos.property[].url |
string |
Conditional | Public property photo URL. |
media.photos.property[].description |
string |
Optional | Photo caption. |
media.photos.community[] |
array |
Optional | Array of community photos. |
media.photos.community[].url |
string |
Conditional | Public community photo URL. |
media.photos.community[].description |
string |
Optional | Photo caption. |
Instructions
| Field | Type | Status | Notes |
|---|---|---|---|
instructions.check_in_earliest |
string |
Optional | Earliest move-in time. Use a time like `14:30` when fixed. Default: flexible. |
instructions.check_in_latest |
string |
Optional | Latest move-in time for backwards compatibility. |
instructions.check_out_latest |
string |
Optional | Latest move-out time. Use a time like `11:00` when fixed. Default: flexible. |
instructions.check_in_contact_person |
string |
Optional | Contact name for arrival questions. |
instructions.check_in_telephone_country |
string |
Optional | Telephone country code such as `+1`. |
instructions.check_in_telephone_number |
string |
Recommended | Arrival support phone number. |
instructions.check_in_instructions |
text |
Recommended | How residents enter the property. Use `\n` for new lines. |
instructions.directions |
text |
Optional | Arrival directions. Use `\n` for new lines. |
instructions.house_manual |
text |
Recommended | House manual content. Hosts can send this through the JSON feed instead of entering it manually in the UI. Use `\n` for new lines. |
Faq
| Field | Type | Status | Notes |
|---|---|---|---|
faq[] |
array |
Optional | Array of faq. |
faq[].question |
string |
Conditional | FAQ question. Required when sending an FAQ item. |
faq[].answer |
text |
Conditional | FAQ answer. Required when sending an FAQ item. Hosts can send FAQs through JSON and do not need to re-enter them manually in the UI. |
Rating
| Field | Type | Status | Notes |
|---|---|---|---|
rating.google_places_id |
string |
Recommended | Google Places ID for review aggregation. |
Helper Endpoints
- /json/import for the full payload example.
- /json/import/listing-amenities — Accepted listing amenities (`id` + `name`), send `id` in payload.
- /json/import/parking — Accepted parking values.
- /json/import/room-type-amenities — Accepted room amenities (`id` + `name`), send `id` in payload.
- /json/import/cancellation-policies — Accepted `bookings.cancellation_policy` values.
- /json/import/community-events — Accepted community event tags (`id` + `name`), send `id` in payload.
- /json/import/community-types — Accepted community type tags (`id` + `name`), send `id` in payload.