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/v1
V1 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: your_api_key_hereOption 2: Bearer Token
Authorization: Bearer your_api_key_here
POST
Provider Key
Receive and save the provider API key for the authenticated integration host. The owner is resolved from the API key that calls this endpoint.
/v1/integrations/{provider}/provider-key
Headers
Content-Type
application/json
X-API-Key *
Required
Authorization
Bearer {api_key} (optional alternative)
Path Parameters
provider
Supported: mangobeds
Body Parameters
provider_api_key *
string
Provider API key to store
Responses
200
Success. Returns
data.status as created, updated, or unchanged.
401
Unauthorized. API key is missing, invalid, inactive, or expired.
409
Conflict. Provider API key already used by another account.
422
Validation error.
provider_api_key is missing or invalid.
404
Unsupported provider.
500
Internal server error.
Provider Key Samples
Request Body
{
"provider_api_key": "mb_provider_key_123456789"
}Success (200) - Created
{
"data": {
"status": "created",
"message": "Provider API key saved successfully"
},
"meta": {
"request_id": "req_integrations_001"
}
}Success (200) - Updated
{
"data": {
"status": "updated",
"message": "Provider API key saved successfully"
},
"meta": {
"request_id": "req_integrations_001"
}
}Success (200) - Unchanged
{
"data": {
"status": "unchanged",
"message": "Provider API key saved successfully"
},
"meta": {
"request_id": "req_integrations_001"
}
}Conflict (409)
{
"error": {
"type": "conflict",
"message": "This provider API key is already used by another account.",
"request_id": "req_integrations_001",
"errors": []
}
}Validation Error (422)
{
"error": {
"type": "validation_error",
"message": "Validation failed",
"request_id": "req_integrations_001",
"errors": [
{
"path": "provider_api_key",
"code": "required",
"message": "The provider_api_key field is required."
}
]
}
}Unauthorized (401)
{
"error": {
"type": "auth_error",
"message": "Invalid API key",
"request_id": "req_integrations_001",
"errors": []
}
}Unsupported Provider (404)
{
"error": {
"type": "unsupported_provider",
"message": "Unsupported integration provider.",
"request_id": "req_integrations_001",
"errors": []
}
}Internal Error (500)
{
"error": {
"type": "internal_error",
"message": "An unexpected error occurred.",
"request_id": "req_integrations_001",
"errors": []
}
}
GET
Verify Credentials
Test your connection and verify that your API key is correctly configured. Returns host profile information.
/v1/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)
{
"data": {
"name": "Jane Cooper",
"email": "jane@example.com",
"created_at": "2024-01-01T08:00:00Z",
"last_login_at": "2024-01-15T12:00:00Z"
},
"meta": {
"request_id": "req_integrations_001"
}
}Unauthorized (401)
{
"error": {
"type": "auth_error",
"message": "Invalid API key",
"request_id": "req_integrations_001",
"errors": []
}
}Rate Limit (429)
{
"error": {
"type": "rate_limit_error",
"message": "Rate limit exceeded.",
"request_id": "req_integrations_001",
"errors": [
{
"path": "retry_after",
"code": "rate_limited",
"message": "30"
}
]
}
}
POST
Update Availability
/v1/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)
{
"data": {
"message": "Availability updated successfully"
},
"meta": {
"request_id": "req_integrations_001"
}
}Ownership Error (403)
{
"error": {
"type": "forbidden",
"message": "Unauthorized access to listings",
"request_id": "req_integrations_001",
"errors": [
{
"path": "unauthorized_listing_ids.0",
"code": "forbidden",
"message": "5325"
}
]
}
}Invalid Room Type (400)
{
"error": {
"type": "validation_error",
"message": "Invalid room types for listings.",
"request_id": "req_integrations_001",
"errors": [
{
"path": "invalid_room_types",
"code": "invalid",
"message": "[{\"listing_id\":\"1\",\"room_type_id\":\"999\",\"reason\":\"Room type not found or does not belong to listing\"}]"
}
]
}
}
POST
Update Rates
/v1/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)
{
"data": {
"message": "Rates update accepted for background processing"
},
"meta": {
"request_id": "req_integrations_001"
}
}Validation Logic Error (400/403)
{
"error": {
"type": "forbidden",
"message": "Unauthorized access to listings",
"request_id": "req_integrations_001",
"errors": []
}
}Payload Error (422)
{
"error": {
"type": "validation_error",
"message": "Validation failed",
"request_id": "req_integrations_001",
"errors": [
{
"path": "data.0.base_price",
"code": "invalid",
"message": "The base_price must be at least 0."
}
]
}
}
GET
List Bookings
Polled updates for new or modified bookings. Each booking summary includes a version timestamp for incremental sync. Use updated_after with the latest version you have already processed; use page / per_page to walk large result sets in batches within the same filter.
Response keys (V1): The feed uses data.Bookings (array, PascalCase). Booking detail uses data.Booking (object). Clients must use these exact key names.
/v1/integrations/{provider}/bookings
Headers
X-API-Key *
Required
Path Parameters
provider
e.g. mangobeds
Query Parameters
checkout_after
Optional • Y-m-d
Purpose: Used to filter for current and future bookings. Usually set to "today" to fetch only stays that haven't ended yet, avoiding the need to process historical data.
Example: 2026-02-16
updated_after
Optional • Date or Date-time
Purpose: Core for incremental synchronization (polling). Supports Y-m-d or Y-m-d H:i:s. Provide the version timestamp from your last sync to receive ONLY bookings that have been created or modified since then.
Example: 2026-02-16 or 2026-02-16 10:00:00
listing_id
Optional • ID Filter
Purpose: Filter bookings for a specific property. Useful if you want to sync data property-by-property instead of account-wide.
Example: 5325
page
Optional • integer ≥ 1
Purpose: Page index for data.Bookings (default 1).
per_page
Optional • 1–100
Purpose: Bookings per page (default 50, maximum 100). Request additional page values until meta.pagination.current_page reaches meta.pagination.last_page.
Responses
200
Success. Returns
data.Bookings for the current page and meta.pagination (current_page, per_page, total, last_page, from, to). If nothing matches, Bookings is [] and total is 0.
401
Unauthorized. API Key is missing, invalid, or expired.
404
Not Found. The
listing_id provided does not exist or does not belong to your account.
422
Unprocessable Content. Validation error, e.g.,
updated_after is not in Y-m-d H:i:s format.
429
Too Many Requests. Rate limit exceeded (60 requests per minute). Please implement exponential backoff.
Response Body Fields
booking_id
The unique identifier for the reservation.
listing_id
ID of the property being booked.
room_type_id
ID of the specific room type or configuration.
checkin_at / checkout_at
Planned arrival and departure dates (YYYY-MM-DD).
status
Current state:
confirmed, cancelled, pending.
version
Core for Polling: This is the
updated_at timestamp. Pass this into your next updated_after request to fetch subsequent changes.
Booking Feed Samples
Success (200)
{
"data": {
"Bookings": [
{
"booking_id": 8821,
"listing_id": 5325,
"room_type_id": 38753,
"status": "confirmed",
"checkin_at": "2024-06-01",
"checkout_at": "2024-06-15",
"version": "2024-05-20 14:30:00"
}
]
},
"meta": {
"request_id": "req_integrations_001",
"pagination": {
"current_page": 1,
"per_page": 50,
"total": 1,
"last_page": 1,
"from": 1,
"to": 1
}
}
}Filter Error (404/422)
{
"error": {
"type": "not_found",
"message": "Listing not found or unauthorized.",
"request_id": "req_integrations_001",
"errors": []
}
}
GET
Get Booking Details
Retrieve full details for a specific reservation, including guest contact info and payment breakdown.
/v1/integrations/{provider}/bookings/{id}
Headers
X-API-Key *
Required
Path Parameters
provider
e.g. mangobeds
id
Booking ID
Responses
200
Success.
data.Booking is the full booking object for provider mangobeds (nullable fields may be null).
Errors: 401 (Auth), 404 (Not Found / Ownership)
Detailed Samples
Success (200)
{
"data": {
"Booking": {
"booking_id": 8821,
"booking_reference": "CO-1002",
"listing_id": 441,
"room_type_id": 902,
"room_type_name": "Studio",
"room_id": null,
"status": "confirmed",
"checkin_at": "2026-05-01",
"checkout_at": "2026-05-31",
"nights": 30,
"guests": {
"total": 1,
"rooms": 1
},
"guest": {
"name": "Alex Rivera",
"email": "alex@example.com",
"phone": "+34600000000",
"country": "ES"
},
"pricing": {
"currency": "EUR",
"total": 1250.0,
"total_local": null,
"security_deposit": 250.0
},
"notes": "Late arrival after 22:00",
"meta": {
"version": "2026-04-12 15:30:00",
"created_at": "2026-04-01T10:00:00+00:00",
"updated_at": "2026-04-12T14:30:00+00:00"
}
}
},
"meta": {
"request_id": "req_integrations_001"
}
}Error (401/404)
{
"error": {
"type": "not_found",
"message": "Booking not found or unauthorized",
"request_id": "req_integrations_001",
"errors": []
}
}
GET
List Messages
Retrieve the conversation history for a specific booking.
/v1/bookings/{booking_id}/messages
Headers
X-API-Key *
Required
Path Parameters
booking_id
Booking ID
Query Parameters
page
Optional, integer ≥ 1
Page index for data.messages (default 1).
per_page
Optional, integer 1–100
Messages per page (default 50, max 100).
Ordering: created_at, then id. Use meta.pagination to fetch additional pages.
Responses
200
Success. Returns
data.messages for the requested page and meta.pagination (current_page, per_page, total, last_page, from, to).
Errors: 401 (Auth), 403 (Forbidden), 404 (Not Found)
Response Samples
Success (200)
{
"data": {
"messages": [
{
"id": 1059,
"sender": "guest",
"sender_name": "Ana Smith",
"text": "Hi! What time is check-in?",
"is_seen": true
}
]
},
"meta": {
"request_id": "req_integrations_001",
"pagination": {
"current_page": 1,
"per_page": 50,
"total": 24,
"last_page": 1,
"from": 1,
"to": 1
}
}
}Error (404)
{
"error": {
"type": "not_found",
"message": "Booking or conversation not found.",
"request_id": "req_integrations_001",
"errors": []
}
}
POST
Create Message
Send a new message to the guest for a specific booking.
/v1/bookings/{booking_id}/messages
Headers
Content-Type
application/json
X-API-Key *
Required
Path Parameters
booking_id
Booking ID
Body Parameters
message.text *
String
The content of the message
Responses
201
Created. Returns the saved message.
Errors: 403 (Forbidden), 404 (Not Found), 409 (Conflict - Closed conversation), 422 (Validation)
Message Create Samples
Request Body
{
"message": {
"text": "Hi Alex, check-in is possible after 3 PM."
}
}Success (201)
{
"data": {
"message": {
"id": 1060,
"sender": "host",
"sender_name": "Sunny Villa",
"text": "Hi Alex, check-in is possible after 3 PM.",
"is_seen": false
}
},
"meta": {
"request_id": "req_integrations_001"
}
}Payload Error (422)
{
"error": {
"type": "validation_error",
"message": "Validation failed",
"request_id": "req_integrations_001",
"errors": [
{
"path": "message.text",
"code": "required",
"message": "The message.text field is required."
}
]
}
}Live Test Data
demo_context_v1.php