Connect your systems to SocialRooms

Who can use it

Quick start

1. Sign in to your landlord account and open API keys. Create a key. Choose Read and write if you want to make changes.
2. Send the key in the Authorization header with every request.

curl "https://socialrooms.co.uk/api/v1/listings?city=Leicester&benefit=universal_credit" \
  -H "Authorization: Bearer sr_live_your_key"

{
  "data": [
    {
      "id": 42,
      "title": "Double room in Leicester",
      "kind": "room",
      "location": { "city": "Leicester", "postcode": "LE2" },
      "rent": { "amount": 500, "period": "month", "monthly_equivalent": 500, "bills_included": true },
      "benefits_accepted": ["universal_credit", "housing_benefit"],
      "cover_photo": "https://socialrooms.co.uk/photo?id=101&sig=…",
      "url": "https://socialrooms.co.uk/listing?id=42"
    }
  ],
  "meta": { "page": 1, "per_page": 20, "total": 37, "pages": 2 }
}

Keys and limits

• Base URL: https://socialrooms.co.uk/api/v1. Everything is JSON over HTTPS.
• Send Authorization: Bearer sr_live_… (or X-Api-Key: sr_live_…).
• A key acts as the account that made it.
• Keys are shown once when you create them. We only keep a fingerprint, so a lost key can't be recovered: revoke it and create another.
• Each key can make 120 requests a minute. Check the X-RateLimit-Remaining header. Over the limit you get 429 with Retry-After.
• Never put a key in a public web page or app. To show homes on your website without a key, use the free search box.

Endpoints

The full description, for tools like Postman or code generators, is in the OpenAPI file.

Searching

GET /listings takes the same filters as the website: city (town, city or postcode), q, kind (room or property), property_type, min_beds, max_rent (monthly, weekly charges are compared by their monthly equivalent), benefit, bills, accessible, step_free, ground_floor, pets, plus page and per_page (up to 50).

To keep a copy in sync, poll with approved_since set to the time of your last check. It returns only listings approved after that time.

Keys see other landlords' listings the way visitors do: no street address, postcode district only, and contact details removed from descriptions.

Photo links are signed, so they work in your own system without signing in.

Managing listings

curl -X POST "https://socialrooms.co.uk/api/v1/my/listings" \
  -H "Authorization: Bearer sr_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "property",
    "title": "Two-bed flat near the park",
    "description": "Bright first-floor flat, close to buses and shops.",
    "property_type": "flat",
    "bedrooms": 2,
    "bathrooms": 1,
    "address_line1": "12 Example Road",
    "city": "Leicester",
    "postcode": "LE2 1AA",
    "rent": 750,
    "rent_period": "month",
    "deposit": 750,
    "furnished": "unfurnished",
    "benefits_accepted": ["universal_credit", "housing_benefit"],
    "certificates": { "gas_safety": true, "eicr": true, "damp_mould": true }
  }'

• New listings are checked by our team before they go live, just like on the website. approval_status shows where it is, and missing_required_certificates lists anything stopping approval.
• PATCH /my/listings/{id} changes only the fields you send. Set "status": "let" or "withdrawn" to take a listing down, and "active" to put it back.
• Upload photos with multipart/form-data in a field called photos[] (JPEG, PNG or WebP, up to 8 MB each):

  curl -X POST "https://socialrooms.co.uk/api/v1/my/listings/42/photos" \
    -H "Authorization: Bearer sr_live_your_key" \
    -F "photos[]=@front.jpg" -F "photos[]=@kitchen.jpg"

• Allowed values for every field are at GET /reference.

Enquiries

Keys see enquiries about your listings. Reply with:

curl -X POST "https://socialrooms.co.uk/api/v1/enquiries/310/messages" \
  -H "Authorization: Bearer sr_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"message": "Thanks for your interest. Are you free to view on Thursday?"}'

Replies are sent to the tenant by email as usual, and the same scam checks apply as on the website.

Errors

{ "error": { "code": "validation_failed", "message": "Please complete the title, city and postcode." } }

Rules

• Every listing must welcome tenants on benefits and follow our terms, the same as listings added on the website.
• Only use tenants' details to deal with their enquiry, and keep them secure. You are responsible for how your system stores data from the API under UK GDPR.
• Don't copy listings to other sites without the landlord's permission. Link back to the listing page (url) when you show a listing.
• We may revoke keys that are misused or put tenants at risk.

Questions or ideas? Email support@socialrooms.co.uk.