Integrations API Setup

Connect your PMS, Channel Manager, or Internal Booking System directly to the Coliving platform. Our API is designed to be developer-friendly, stateless, and highly performant.

Base API URL

https://api.coliving.com/v2 V2 STABLE

Authentication

All API requests require a valid API key. You can pass the key in two ways:

X-API-Key Header: Send your key in a custom header.
Bearer Token: Use the standard Authorization header.

Need a key?

Contact our partnership team at partners@coliving.com to request your unique production API key.

Auth Examples

Option 1: Custom Header

X-API-Key: sk_live_xxxxxxxxxxxxxxxx

Option 2: Bearer Token

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx

GET

Verify Credentials

Test your connection and verify that your API key is correctly configured. Returns host profile information.

/v2/me

Headers

X-API-Key * Header

Your secret API key

Authorization Header

Bearer {api_key}

Responses

200

Key is valid. Returns user info.

401

Unauthorized. Key is missing or invalid.

429

Rate limit exceeded (60 req/min).

Response Samples

Success (200)

{
  "success": true,
  "data": {
    "name": "Jane Cooper",
    "email": "jane@example.com",
    "created_at": "2024-01-01T08:00:00Z"
  }
}

Unauthorized (401)

{
  "success": false,
  "error": "Invalid API Key"
}

Rate Limit (429)

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

GET

List Room Types

Fetch all room types and their configurations for a specific property. This is the source of truth for room_type_id and base pricing.

/v2/integrations/{provider}/listings/{listing_id}/room-types

Headers

X-API-Key * Header

Required

Path Parameters

provider

e.g. mangobeds

listing_id

Property ID

Responses

200

Success. Returns array of room types.

404 Not Found: The listing doesn't exist or isn't assigned to your API key.

Response Samples

Success (200)

{
  "success": true,
  "data": {
    "room_types": [
      {
        "room_type_id": 38753,
        "name": "Standard Room",
        "room_type": "private",
        "amount": 5,
        "prices": {
          "currency": "USD",
          "base_price": 750,
          "price_jan": 800
        }
      }
    ]
  }
}

Not Found (404)

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

POST

Update Availability

Synchronize room counts for specific date ranges. Updates take effect immediately on the live platform.

/v2/integrations/{provider}/availability

Headers

Content-Type

application/json

X-API-Key *

Required

Path Parameters

provider

e.g. mangobeds

Body Parameters

listing_id * In data array

Target Listing ID

room_type_id * In data array

Target Room Type ID

available * In data array

Integer: 0 to N

start_date / end_date In data array

YYYY-MM-DD

Responses

200

Success. Returns confirmed ranges.

Errors: 400 (Invalid IDs), 403 (Permission), 422 (Validation)

Update Examples

Request Body

{
  "data": [
    {
      "listing_id": "5325",
      "room_type_id": "38753",
      "available": 3,
      "start_date": "2024-05-01",
      "end_date": "2024-05-31"
    }
  ]
}

Success (200)

{
  "success": true,
  "message": "Availability updated successfully"
}

Ownership Error (403)

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

Invalid Room Type (400)

{
  "success": false,
  "error": "Invalid room types for listings",
  "details": {
    "invalid_room_types": [{"listing_id": 5325, "room_type_id": 999}]
  }
}

POST

Update Rates

Batch update pricing. You can set a global base_price and override specific months if needed.

/v2/integrations/{provider}/rates

Headers

Content-Type application/json

X-API-Key * Required

Path Parameters

provider

e.g. mangobeds

Body Parameters

listing_id * In data array

Target Listing ID

room_type_id * In data array

Target Room Type ID

base_price * In data array

Default rate

currency

ISO (e.g. EUR)

price_jan...dec Optional

Monthly Overrides

Responses

200

Success. Rates updated.

Errors: 400 (Invalid IDs), 403 (Permission), 422 (Validation / Currency)

Rate Update Samples

Request Body

{
  "data": [
    {
      "listing_id": "5325",
      "room_type_id": "38753",
      "base_price": 800,
      "currency": "EUR"
    }
  ]
}

Success (200)

{
  "success": true,
  "message": "Rates updated successfully"
}

Validation Logic Error (400/403)

{
  "success": false,
  "error": "Unauthorized access to listings"
}

Payload Error (422)

{
  "success": false,
  "error": "Validation Error",
  "details": {
    "data.0.base_price": ["The base_price must be at least 0."]
  }
}

GET

List Bookings

Polled updates for new or modified bookings. Always returns a version timestamp to track changes.

/v2/integrations/{provider}/bookings

Headers

X-API-Key *

Required

Path Parameters

provider

e.g. mangobeds

Query Parameters

updated_after Optional

Y-m-d H:i:s

listing_id Optional

ID Filter

Responses

200

Success. Returns array of summaries.

Errors: 404 (Listing ID not found), 422 (Date format error)

Booking Feed Samples

Success (200)

{
  "success": true,
  "data": {
    "Bookings": [
      {
        "booking_id": 8821,
        "listing_id": 5325,
        "status": "confirmed",
        "version": "2024-05-20 14:30:00"
      }
    ]
  }
}

Filter Error (404/422)

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

GET

Get Booking Details

Retrieve full details for a specific reservation, including guest contact info and payment breakdown.

/v2/integrations/{provider}/bookings/{id}

Headers

X-API-Key * Required

Path Parameters

provider

e.g. mangobeds

Booking ID

Responses

200

Success. Returns full JSON.

Errors: 401 (Auth), 404 (Not Found / Ownership)

Detailed Samples

Success (200)

{
  "success": true,
  "data": {
    "Booking": {
      "booking_id": 8821,
      "reference": "CO-1002",
       "guest": {
        "name": "Alex Rivera",
        "email": "alex@example.com"
      },
      "pricing": {
        "total": 1250.00,
        "currency": "EUR"
      }
    }
  }
}

Error (401/404)

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

Live Test Data

demo_context_v1.php

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

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,
                'max_occupancy' => 1,
                'room_size' => '15',
                'room_size_unit' => 'm2',
                'available_at' => '2026-02-20',
                '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,
                ],
            ],
        ],
    ],
];