Integrations API

Endpoints for Channel Managers / PMS (e.g., Mangobeds). All endpoints are versioned under /v1 and have sandbox variants under /v1/sandbox.

Base URLs

Sandbox: https://api.coliving.com

Authentication

All API requests require an API key to be included in the request headers. API keys are provided by the admin team and should be kept secure.

X-API-Key: sk_your_api_key_here

Authorization: Bearer sk_your_api_key_here

Getting Your API Key

API keys are created and managed by the admin team through the admin panel. To get an API key:

Contact the admin team with your integration requirements
Provide details about your use case and required permissions
Receive your API key via secure communication
Store the key securely in your application

API Key Verification

GET /v1/me

Verify a Coliving-issued API key and retrieve user information. This endpoint is called by external providers to validate API keys and get host account details.

Flow: 1. Host generates API key on Coliving → 2. Host adds key on provider platform → 3. Provider calls this endpoint to verify and get user details → 4. If valid, provider saves key and establishes connection.

Request

Include your Coliving-issued API key in the Authorization header.

Authorization: Bearer sk_your_coliving_api_key_here

Response

On success, returns HTTP 200 with user details and verification status.

{
  "success": true,
  "api_key_verified_at": "2024-01-15T10:30:00.000Z",
  "name": "John Doe",
  "email": "john@example.com",
  
  
  "created_at": "2023-06-15T08:20:00.000Z",
  "last_login_at": "2024-01-14T16:45:00.000Z"
}

Error Responses

401 - Unauthorized

{
  "success": false,
  "error": "API key missing"
}

429 - Rate Limit Exceeded

{
  "success": false,
  "error": "Rate limit exceeded",
  "retry_after": 45
}

Rate Limiting: 60 requests per minute per IP address.

Room Types - List

GET /v1/integrations/{provider}/listings/{listing_id}/room-types

Retrieve all room types for a specific listing owned by the authenticated user. The response is provider-aware via the internal dispatcher.

Note: Replace {provider} with your identifier, e.g., mangobeds, siteminder, beds24.

Authorization: You can only fetch room types for listings that belong to your account. The API validates listing ownership using your API key.

Path Parameters

{provider}: Provider identifier (e.g., mangobeds).
{listing_id}: The ID of the listing you own.

Response

On success, returns HTTP 200 with an array of room types.

{
  "success": true,
  "data": {
    "room_types": [
      {
        "room_type_id": 38753,
        "listing_id": 5325,
        "name": "Full Bedroom",
        "room_type": "private",
        "bed_type": "king",
        "bathroom_type": "private",
        "gender": "Separated",
        "amount": 6,
        "max_occupancy": 1,
        "room_size": 15,
        "room_size_unit": "m2",
        "available_at": "2025-10-26",
        "prices": {
          "currency": "USD",
          "base_price": 500.0,
          "price_jan": 500.0,
          "price_feb": 500.0,
          "price_mar": 520.0,
          "price_apr": 520.0,
          "price_may": 550.0,
          "price_jun": 560.0,
          "price_jul": 580.0,
          "price_aug": 580.0,
          "price_sep": 540.0,
          "price_oct": 520.0,
          "price_nov": 500.0,
          "price_dec": 600.0
        }
      }
    ]
  }
}

Error Responses

401 - Unauthorized

{
  "success": false,
  "error": "API key missing"
}

404 - Not Found / Unauthorized Listing

{
  "success": false,
  "error": "Listing not found or unauthorized"
}

Availability Update

POST /v1/integrations/{provider}/availability

Update room availability for specific listings and room types. Supports both single-day and date-range updates.

Note: Replace {provider} with your identifier, e.g., mangobeds, siteminder, beds24.

Authorization: You can only update availability for listings that belong to your account. The API will validate ownership of both listings and room types.

Request

Send availability data in JSON format. Body supports single-day or inclusive date-range updates.

{
  "data": [
    {
      "listing_id": "5325",
      "room_type_id": "38753",
      "available": 2,
      "start_date": "2025-12-01",
      "end_date": "2025-12-20"
    }
  ]
}

Request Parameters

listing_id *

The ID of the listing

room_type_id *

The ID of the room type

available *

Number of available rooms (integer)

start_date *

Start date (YYYY-MM-DD format)

end_date *

End date (YYYY-MM-DD format)

Response

On success, returns HTTP 200 with a confirmation payload showing updated availability.

{
  "success": true,
  "availability": {
    "room_type_id_38753 (6 rooms)": [
      "2025-12-01 -> 2025-12-20 : 2"
    ]
  }
}

Error Responses

400 - Bad Request

{
  "success": false,
  "error": "Invalid room types for listings",
  "details": {
    "invalid_room_types": [
      {
        "listing_id": "1",
        "room_type_id": "999",
        "reason": "Room type not found or does not belong to listing"
      }
    ]
  }
}

401 - Unauthorized

{
  "success": false,
  "error": "API key missing"
}

403 - Forbidden

{
  "success": false,
  "error": "Unauthorized access to listings",
  "details": {
    "unauthorized_listing_ids": ["999", "1000"]
  }
}

422 - Validation Error

{
  "success": false,
  "error": "validation_error",
  "message": "The given data was invalid.",
  "errors": {
    "data.0.listing_id": ["The listing id field is required."]
  }
}

Rate Limiting: 100 requests per minute per API key.

Test Data

host = [
  'id' => 6368,
  'name' => 'Demo Host',
  'email' => 'demohost@palmesus.no',
  'apiKey' => 'sk_zSygBSklJsc8nsZdIS1xi8amfZz1oklt',
];

listings = [
  [
    'id' => 5325,
    'user_id' => 6368,
    'name' => 'Demo listing',
    'stay_min' => 30,
    'room_types' => [
      [
        'id' => 38753,
        'listing_id' => 5325,
        'name' => 'Full Bedroom',
        'room_type' => 'private',
        'bed_type' => 'king',
        'bathroom_type' => 'private',
        'gender' => 'Separated',
        'amount' => 6 (number of rooms),
        'max_occupancy' => 1,
        'room_size' => 15,
        'room_size_unit' => 'm2',
        'prices' => [
          'currency' => 'USD',
          'base_price' => 1000,
          'price_jan' => null,
          'price_feb' => null,
          'price_mar' => null,
          'price_apr' => null,
          'price_may' => null,
          'price_jun' => null,
          'price_jul' => null,
          'price_aug' => null,
          'price_sep' => null,
          'price_oct' => null,
          'price_nov' => null,
          'price_dec' => null,
        ],
      ],
    ],
  ],
];

Sandbox vs Production

All endpoints are available in both sandbox and production environments:

Sandbox Environment

Use for testing and development:

• Base URL: https://api.coliving.com/v1/sandbox
• Test data available
• No real bookings created
• Safe for experimentation

Production Environment

Use for live integrations:

• Base URL: https://api.coliving.com/v1
• Real data and bookings
• Production rate limits
• Requires approval

Important: Always test with sandbox endpoints first before switching to production. Production endpoints require separate API keys and approval from the admin team.