{"openapi":"3.1.0","info":{"title":"SocialRooms API","version":"1.0","description":"Search rooms and homes for people on benefits, manage your listings and handle enquiries. Guide: https://socialrooms.co.uk/developers"},"servers":[{"url":"https://socialrooms.co.uk/api/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Your sr_live_... API key"}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}},"schemas":{"Listing":{"type":"object","properties":{"id":{"type":"integer"},"url":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string"},"property_type":{"type":"string"},"bedrooms":{"type":"integer"},"bathrooms":{"type":"integer"},"location":{"type":"object"},"rent":{"type":"object"},"available_from":{"type":["string","null"]},"benefits_accepted":{"type":"array","items":{"type":"string"}},"features":{"type":"object"},"supported_housing":{"type":"boolean"},"cover_photo":{"type":["string","null"]},"description":{"type":"string"},"photos":{"type":"array","items":{"type":"object"}},"status":{"type":"string","description":"Your own listings only"},"approval_status":{"type":"string"}}},"ListingInput":{"type":"object","properties":{"kind":{"type":"string","enum":["room","property"]},"title":{"type":"string"},"description":{"type":"string"},"property_type":{"type":"string","enum":["house","flat","bungalow","hmo","studio","other"]},"dwelling":{"type":"string","enum":["house","flat"],"description":"Whole properties of type hmo, studio or other: is it a house or a flat?"},"room_type":{"type":"string","enum":["single","double","twin","ensuite","studio_room"]},"rooms_available":{"type":"integer"},"bedrooms":{"type":"integer"},"bathrooms":{"type":"integer"},"address_line1":{"type":"string"},"city":{"type":"string"},"county":{"type":"string"},"postcode":{"type":"string"},"rent":{"type":"number","description":"Amount per rent_period"},"rent_period":{"type":"string","enum":["month","week"],"description":"\"week\" = weekly service charge"},"deposit":{"type":"number"},"available_from":{"type":"string","format":"date"},"furnished":{"type":"string","enum":["furnished","part_furnished","unfurnished"]},"suitable_for":{"type":"string","enum":["individual","couple","family","sharers"]},"status":{"type":"string","enum":["active","draft","let","withdrawn"]},"benefits_accepted":{"type":"array","items":{"type":"string","enum":["universal_credit","universal_credit_no_housing","housing_benefit","pension_credit","esa","jsa","pip","dla","attendance_allowance","carers_allowance","child_benefit","other"]}},"bills_included":{"type":"boolean"},"wheelchair_accessible":{"type":"boolean"},"pets_allowed":{"type":"boolean"},"step_free":{"type":"boolean"},"ground_floor":{"type":"boolean"},"certificates":{"type":"object","additionalProperties":{"type":"boolean"},"description":"e.g. {\"gas_safety\": true, \"eicr\": true}"}}},"Enquiry":{"type":"object","properties":{"id":{"type":"integer"},"listing":{"type":"object"},"status":{"type":"string"},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"from_me":{"type":"boolean"},"sender_name":{"type":"string"},"body":{"type":"string"},"created_at":{"type":"string"}}}}}}}},"paths":{"/me":{"get":{"summary":"The account and key making the request","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/reference":{"get":{"summary":"Allowed values: kinds, property types, benefits, certificates","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/listings":{"get":{"summary":"Search live listings","parameters":[{"name":"city","in":"query","required":false,"schema":{"type":"string"},"description":"Town, city or postcode"},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Keywords"},{"name":"kind","in":"query","required":false,"schema":{"type":"string"},"description":"room or property"},{"name":"property_type","in":"query","required":false,"schema":{"type":"string"},"description":""},{"name":"min_beds","in":"query","required":false,"schema":{"type":"integer"},"description":""},{"name":"max_rent","in":"query","required":false,"schema":{"type":"integer"},"description":"Monthly, £"},{"name":"benefit","in":"query","required":false,"schema":{"type":"string"},"description":"Benefit key, see /reference"},{"name":"bills","in":"query","required":false,"schema":{"type":"boolean"},"description":""},{"name":"accessible","in":"query","required":false,"schema":{"type":"boolean"},"description":""},{"name":"pets","in":"query","required":false,"schema":{"type":"boolean"},"description":""},{"name":"step_free","in":"query","required":false,"schema":{"type":"boolean"},"description":""},{"name":"ground_floor","in":"query","required":false,"schema":{"type":"boolean"},"description":""},{"name":"approved_since","in":"query","required":false,"schema":{"type":"string"},"description":"Only listings approved after this time"},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":""},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer"},"description":"Up to 50"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Listing"}},"meta":{"type":"object"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/listings/{id}":{"get":{"summary":"One live listing","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Listing"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/my/listings":{"get":{"summary":"Your listings (landlord keys)","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string"},"description":""}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Listing"}}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"summary":"Create a listing (write keys). New listings are checked by our team before going live.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Listing"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/my/listings/{id}":{"get":{"summary":"One of your listings, with certificates","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Listing"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"patch":{"summary":"Update fields (only the fields you send change). Set status to let or withdrawn to take it down.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingInput"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Listing"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/my/listings/{id}/photos":{"post":{"summary":"Upload photos (multipart/form-data, field photos[], JPEG/PNG/WebP up to 8 MB each)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Listing"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/my/listings/{id}/photos/{photoId}":{"delete":{"summary":"Remove a photo","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"photoId","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Listing"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/enquiries":{"get":{"summary":"Your enquiries","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string"},"description":"open or closed"},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":""},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer"},"description":"Up to 100"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Enquiry"}},"meta":{"type":"object"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/enquiries/{id}":{"get":{"summary":"An enquiry with its messages","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Enquiry"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/enquiries/{id}/messages":{"post":{"summary":"Reply (write keys)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Enquiry"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/enquiries/{id}/close":{"post":{"summary":"Close an enquiry (write keys)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Enquiry"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}}}}