BookMyColiving API v1

Authentication

All requests require an x-api-key header. Keys are scoped to a single operator account.

curl -H "x-api-key: bmc_your_api_key_here" \
  https://bookmycoliving.com/api/v1/leads

Base URL

https://bookmycoliving.com/api/v1

Response Shape

List endpoints return a { data, pagination } envelope. Single-resource endpoints return the resource directly.

{
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "totalPages": 3
  }
}

Every authenticated response carries:

• X-RateLimit-Limit, your hourly budget for this endpoint
• X-RateLimit-Remaining, calls left in the current window
• X-RateLimit-Reset, epoch seconds when the window resets

Idempotency

Pass Idempotency-Key on writes. We cache the first response for 24h and replay it on retries, even after a 5xx or timeout you can safely retry without creating duplicates. Replayed responses include Idempotent-Replayed: true.

curl -X POST https://bookmycoliving.com/api/v1/properties \
  -H "x-api-key: bmc_..." \
  -H "Idempotency-Key: 8b1f...-uuid-..." \
  -H "Content-Type: application/json" \
  -d '{ ... }'

External IDs

Pass an externalId in the property body and we'll record it alongside our own id. On POST /properties, if the same externalId already exists for your operator account, we return the existing record (HTTP 200 + { reused: true }) instead of creating a duplicate. Filter list endpoints with ?externalId=.

Properties

curl -X POST https://bookmycoliving.com/api/v1/properties \
  -H "x-api-key: bmc_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sunny Coliving",
    "description": "...",
    "cityId": "<from /api/v1/cities>",
    "address": "123 Main St",
    "amenities": ["wifi", "gym"],
    "contactEmail": "host@example.com",
    "colivingTypeIds": ["<from /api/v1/coliving-types>"],
    "roomOptions": [
      { "type": "PRIVATE", "priceMonthly": 80000 }
    ]
  }'

{ "photos": [{ "url": "https://..." }, { "url": "https://..." }] }

Leads

curl -H "x-api-key: bmc_..." \
  "https://bookmycoliving.com/api/v1/leads?since=2026-04-01T00:00:00Z"

Messages

{ "content": "Thanks for your interest!", "propertyId": "..." }

Reference Data

These endpoints return canonical IDs and slugs. Cache responses for at least 1 hour.

Webhooks

Set a webhook URL in Dashboard Settings to receive real-time events. Events are POSTed as JSON.

Events

• lead.created, new tenant enquiry on one of your properties
• message.received, a tenant or admin sent you a message
• property.created, property created (typically by your own integration)
• property.updated, property details changed
• property.approved, admin approved your listing, it's now live
• property.rejected, admin rejected your listing (check adminNotes)
• property.deleted, property removed

Payload Format

POST <your-webhook-url>
Content-Type: application/json
X-BMC-Event: lead.created
X-BMC-Timestamp: 2026-04-25T10:00:00.000Z
X-BMC-Signature: <hmac-sha256(`${timestamp}.${body}`, your-webhook-secret)>
User-Agent: BookMyColiving-Webhook/1.0

{
  "event": "lead.created",
  "timestamp": "2026-04-25T10:00:00.000Z",
  "data": {
    "id": "lead_abc",
    "propertyId": "prop_xyz",
    "guestName": "Jane Smith",
    "guestEmail": "jane@example.com",
    ...
  }
}

Verifying Signatures

Each delivery is signed with HMAC-SHA256 over `${timestamp}.${rawBody}` using your webhook secret (separate from your API key, generate it in dashboard settings). Including the timestamp in the signed material defeats replay attacks. Verify on your end:

// Node.js example
const crypto = require("crypto");

function verifyWebhook(rawBody, headers, webhookSecret) {
  const sig = headers["x-bmc-signature"];
  const ts  = headers["x-bmc-timestamp"];
  // Reject events older than 5 minutes, protects against replay
  if (Math.abs(Date.now() - Date.parse(ts)) > 5 * 60_000) return false;
  const expected = crypto
    .createHmac("sha256", webhookSecret)
    .update(`${ts}.${rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(sig),
  );
}

We deliver fire-and-forget, failed deliveries are not retried. Use POST /webhooks/test below to validate your receiver before going live.

Test endpoint

curl -X POST https://bookmycoliving.com/api/v1/webhooks/test \
  -H "x-api-key: bmc_..." \
  -H "Content-Type: application/json" \
  -d '{ "event": "lead.created" }'

Errors

Errors return a JSON body: { "error": "Human-readable message" }

Rate Limits

• Default endpoints, 1,000 requests per hour per API key
• Reference data (/cities, /coliving-types, /amenities), 5,000 per hour
• Outbound messages (POST /messages/:threadId), 60 per hour per API key

Read your remaining budget from the X-RateLimit-* response headers. Exceeded limits return 429. Cache reference data to avoid unnecessary calls.

Versioning

The API is versioned via the URL path (/api/v1/). We commit to at least 6 months notice before deprecating any endpoint, and breaking changes only happen in new major versions.