API Integration Guide

Integrate with the Coliving API to create users and bookings on your platform.

Important: API keys are provided by the admin team. Partners do not create their own API keys.

The API uses API key authentication and is designed for external partners to create users and bookings on the platform.

Base API URL
https://api.coliving.com/v2 V2 STABLE

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.

Getting Your API Key

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

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

API Key Features

Each API key includes:

  • Name: Human-readable identifier for the key
  • Permissions: Specific permissions (e.g., users.create, bookings.create)
  • Expiration: Optional expiration date for security
  • Status: Active or inactive state
  • Usage tracking: Automatic tracking of usage and IP addresses

Auth Examples

Option 1: Custom Header
X-API-Key: sk_your_api_key_here
Option 2: Bearer Token
Authorization: Bearer sk_your_api_key_here

User Management

POST

Create User

Create a new user in the system. Users created via API are automatically marked as active.

POST /v2/users

Authentication: API Key

Note: User creation follows the same flow as web registration, including proper name formatting, meta attributes storage, event firing (UserCreated), and Google Tag Manager tracking.

Testing: Use the provided request examples to test the endpoints. The actual response structure will be returned when you make real API calls.

Request Example

Request Body
{
    "email": "user@example.com",
    "password": "securepassword123",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+1234567890",
    "date_of_birth": "1990-01-01",
    "gender": "male",
    "country": "United States",
    "city": "New York",
    "timezone": "America/New_York",
    "language": "en"
}

Booking Management

POST

Create Booking

Create a new booking and reservation in the system.

POST /v2/bookings

Authentication: API Key

Request Example

Request Body
{
    "user_id": 123,
    "listing_id": 456,
    "room_type_id": 789,
    "checkin_at": "2024-02-01",
    "checkout_at": "2024-02-15",
    "guests": 2,
    "message": "Looking forward to my stay!"
}

Listing Management

GET

List Listings

Retrieve a list of all listings associated with your account.

GET /v2/listings

Authentication: API Key

Response Example

Success (200)
[
    {
        "id": 101,
        "name": "Sunny Apartment",
        "room_types": [
            {
                "id": 501,
                "name": "Standard Room"
            },
            {
                "id": 502,
                "name": "Deluxe Suite"
            }
        ]
    },
    {
        "id": 102,
        "name": "City Center Loft",
        "room_types": [
            {
                "id": 503,
                "name": "Entire Loft"
            }
        ]
    }
]

Error Handling

All API endpoints return consistent error responses:

Common HTTP status codes:

  • 200 - Success
  • 201 - Created
  • 400 - Bad Request (validation errors)
  • 401 - Unauthorized (invalid or missing API key)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Not Found
  • 500 - Internal Server Error
Error Response Format
{
    "success": false,
    "error": "Error message describing what went wrong"
}

Rate Limiting

API requests are rate limited to 60 requests per minute per API key.

Best Practices

  1. Store API keys securely - Never expose API keys in client-side code
  2. Use HTTPS - Always make requests over HTTPS
  3. Handle errors gracefully - Implement proper error handling in your integration
  4. Validate responses - Always check the success field in responses
  5. Monitor usage - Keep track of your API usage and rate limits
  6. Contact admin for key management - API keys are managed by the admin team
  7. Use descriptive names - Admin will name your API keys clearly for better management
  8. Follow Laravel conventions - Use API Resources for consistent response formatting
  9. Include required fields - Ensure all required fields are provided for user and booking creation
  10. Handle meta data properly - Use meta attributes for additional user/booking information

Testing the API

To test the API endpoints and see the actual response structure:

  1. Set up your testing environment:
    • base_url: Your API base URL
    • api_key: Your API key (provided by admin)
  2. Test the endpoints:
    • Use the request examples above to create test data
    • Make actual API calls to see real responses
    • Test both User and Booking creation endpoints

Pro Tip: The best way to understand the API responses is to test them yourself. Use tools like Postman, curl, or your preferred API testing tool with the examples provided above.

Support & Sandbox

For API support, please contact the development team with:

  • Your API key (masked)
  • Request details
  • Error messages
  • Expected vs actual behavior

For API key requests or management, contact the admin team directly.

Ready to integrate?

Contact the admin team to get your API key and start building amazing integrations with the Coliving platform!

Want to test the API first?

Try our API Sandbox to test the endpoints with mock data before integrating with the production API.