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, choosing Read and write if you want to make changes.
2. Send the key in the Authorization header with every request.

curl "https://www.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://www.socialrooms.co.uk/photo?id=101&sig=…",
      "url": "https://www.socialrooms.co.uk/listing?id=42"
    }
  ],
  "meta": { "page": 1, "per_page": 20, "total": 37, "pages": 2 }
}

Keys and limits

• Base URL: https://www.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 rooms on your website without a key, use the free search box.

Endpoints

All paths are relative to https://www.socialrooms.co.uk/api/v1.

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

Searching

SocialRooms lists rooms only, so every listing is a room. GET /listings takes the same filters as the website:

• city (town, city or postcode) and q (keywords)
• in_hmo (only rooms in an HMO) and max_rent (monthly; weekly charges are compared by their monthly equivalent)
• benefit, bills, accessible, step_free, ground_floor, pets
• support (rooms that come with support or coaching)
• 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 rooms approved after that time.

Keys see other landlords' rooms 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 rooms

Create a room with POST /my/listings:

curl -X POST "https://www.socialrooms.co.uk/api/v1/my/listings" \
  -H "Authorization: Bearer sr_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "room",
    "title": "Double room near the park",
    "description": "Bright double room, close to buses and shops.",
    "in_hmo": true,
    "room_type": "double",
    "rooms_available": 2,
    "bathrooms": 2,
    "address_line1": "12 Example Road",
    "city": "Leicester",
    "postcode": "LE2 1AA",
    "rent": 450,
    "rent_period": "month",
    "deposit": 450,
    "furnished": "furnished",
    "benefits_accepted": ["universal_credit", "housing_benefit"],
    "certificates": { "gas_safety": true, "eicr": true, "damp_mould": true }
  }'

• New rooms 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 room down, and "active" to put it back.
• Set "support" to "support", "coaching" or "both" (or null for neither), and optionally "support_details" to say what's included.
• Allowed values for every field are at GET /reference.

Photos

Upload photos as multipart/form-data in a field called photos[] (JPEG, PNG or WebP, up to 8 MB each):

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

Coaching

curl -X PATCH "https://www.socialrooms.co.uk/api/v1/my/listings/42" \
  -H "Authorization: Bearer sr_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"support": "coaching", "support_details": "Weekly coaching into work and training."}'

Enquiries

Keys see enquiries about your rooms. Reply with:

curl -X POST "https://www.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.

Partnerships: exchanging rooms with other platforms

If you run a housing platform, you can receive our live rooms, send us yours, or both. This is only available under a partnership agreement: there are no open feeds, and personal API keys can't be used for it.

How access works

1. Email hello@sociallets.com with your platform, what you want to exchange, and the IP addresses you'll call us from.
2. Once the agreement is in place, our team sets up your partnership and sends you two credentials, separately and once only: a partner key (sr_partner_…) and a request signing secret (pss_…).
3. Our team also adds your webhook addresses. Each webhook has its own signing secret (whsec_…) so you can check our messages.

Security

• Every request needs the partner key and a signature made with your signing secret. Unsigned or stale requests are refused.
• Requests can be limited to your IP addresses. We recommend it.
• Each partnership can make 120 requests a minute.
• We only keep a fingerprint of your partner key. If a credential may have leaked, email us and we'll replace it straight away; the old one stops working at once.

Signing requests

Send three headers with every request to /api/v1/partner/…:

The signature is the hex HMAC-SHA256 of <t>.<raw body> using your request signing secret. For GET requests the body is empty, so you sign <t>.. The time must be within 5 minutes of ours.

# Shell
BODY='{"rooms":[{"external_id":"ROOM-1001","action":"remove"}]}'
T=$(date +%s)
SIG=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$SIGNING_SECRET" | sed 's/^.* //')
curl -X POST "https://www.socialrooms.co.uk/api/v1/partner/rooms" \
  -H "Authorization: Bearer $PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -H "X-SocialRooms-Signature: t=$T,v1=$SIG" \
  --data "$BODY"

// PHP
$body = json_encode(['rooms' => $rooms]);
$t = time();
$sig = hash_hmac('sha256', $t . '.' . $body, $signingSecret);
// headers: Authorization: Bearer $partnerKey, X-SocialRooms-Signature: "t=$t,v1=$sig"

// Node.js
const body = JSON.stringify({ rooms });
const t = Math.floor(Date.now() / 1000);
const sig = crypto.createHmac('sha256', signingSecret).update(`${t}.${body}`).digest('hex');
// headers: Authorization: `Bearer ${partnerKey}`, 'X-SocialRooms-Signature': `t=${t},v1=${sig}`

Sign the exact bytes you send. Re-encoding the JSON after signing will break the signature.

Partner endpoints

All paths are relative to https://www.socialrooms.co.uk/api/v1. "Receive" and "Send" depend on what your partnership allows. Webhooks are added and changed by our team.

Sending rooms to SocialRooms

Send up to 100 rooms per request to POST /partner/rooms. Give each room your own external_id. Sending the same external_id again updates that room instead of creating a copy, and "action": "remove" takes it down.

{
  "rooms": [
    {
      "external_id": "PARTNER-ROOM-1001",
      "listing_url": "https://partner.example.com/rooms/1001",
      "title": "Double room near the station",
      "description": "Bright double room, close to buses and shops.",
      "room_type": "double",
      "rooms_available": 1,
      "in_hmo": true,
      "address_line1": "12 Example Road",
      "city": "Leicester",
      "postcode": "LE1 1AA",
      "rent": 450,
      "rent_period": "month",
      "furnished": "furnished",
      "bills_included": true,
      "benefits_accepted": ["universal_credit", "housing_benefit"],
      "certificates": { "gas_safety": true, "eicr": true }
    },
    { "external_id": "PARTNER-ROOM-0997", "action": "remove" }
  ]
}

Visitors are sent to your website

Every room needs a listing_url: its page on your website (https, on the website we hold for your partnership). Your rooms show on SocialRooms marked "Listed via" your platform, and the enquire button sends visitors to that page. Enquiries are not taken on SocialRooms for your rooms. Admins can see how many visitors we've sent you.

Rooms already on SocialRooms

New rooms need address_line1 and postcode (the street address is never shown publicly). If that address is already listed on SocialRooms directly, the room is not added: its result is rejected with "reason": "already_listed".

The reply

• The reply has one result per room: created, updated, removed, unchanged, rejected or error, with our room id, its approval_status, any missing_required_certificates and the reasons for any error.
• One bad room never stops the others.
• Rooms are listed under the landlord account linked to your partnership and checked before they go live, unless that account is verified and the room is complete.
• Only rooms are accepted. Whole properties are not listed on SocialRooms.

Receiving rooms from SocialRooms

Load the current rooms once with GET /partner/rooms, then keep them up to date with webhooks. We send a JSON POST to each of your webhook addresses whenever a room goes live, changes, or is let or taken down. Webhooks can be limited to towns or postcode districts.

POST https://partner.example.com/socialrooms
X-SocialRooms-Event: room.published
X-SocialRooms-Delivery: evt_5f2c...
X-SocialRooms-Signature: t=1793185000,v1=6b1d...

{
  "id": "evt_5f2c...",
  "type": "room.published",
  "created_at": "2026-10-28T11:30:00+00:00",
  "api_version": "1.0",
  "data": { "room": { "id": 42, "url": "https://www.socialrooms.co.uk/listing?id=42", "title": "Double room in Leicester", "room_type": "double", "location": { "city": "Leicester", "postcode": "LE1" }, "rent": { "amount": 450, "period": "month" }, "photos": [ ... ] } }
}

Events

• room.published: a room becomes visible.
• room.updated: a live room changes, including photos.
• room.removed: let, withdrawn, under review, deleted or no longer available, with a reason.
• ping: a test event.

Rooms are sent as the public version: no street address, postcode district only, and contact details removed from the description. Link tenants to the room's url to enquire.

Checking our signature

Work out HMAC-SHA256 of <t>.<raw body> with that webhook's secret and compare it with v1. Reject events where t is more than 5 minutes old.

// PHP
[$t, $v1] = [null, null];
foreach (explode(',', $_SERVER['HTTP_X_SOCIALROOMS_SIGNATURE']) as $part) {
    [$k, $v] = explode('=', $part, 2);
    if ($k === 't') { $t = $v; } elseif ($k === 'v1') { $v1 = $v; }
}
$body = file_get_contents('php://input');
$ok = hash_equals(hash_hmac('sha256', $t . '.' . $body, $webhookSecret), $v1) && abs(time() - (int) $t) < 300;

// Node.js
const [t, v1] = req.get('X-SocialRooms-Signature').split(',').map(p => p.split('=')[1]);
const expected = crypto.createHmac('sha256', webhookSecret).update(`${t}.${rawBody}`).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1)) && Math.abs(Date.now() / 1000 - t) < 300;

Delivery

• Reply with any 2xx status within 10 seconds. Anything else is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours and 24 hours.
• A webhook that fails 50 times in a row is switched off. Email us to switch it back on.
• Use the event id to ignore repeats. Events usually arrive within a few minutes and may arrive out of order, so keep the newest version of each room.

Errors

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

Rules

• Every room must welcome tenants on benefits and follow our terms, the same as rooms 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.
• Show rooms from SocialRooms only under a partnership agreement, and link back to the room page (url).
• We may revoke keys or suspend partnerships that are misused or put tenants at risk.

Questions about the API or partnerships? Email hello@sociallets.com.