API Integration Guide

Overview

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

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.

or

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

User Management

Create User

Endpoint: POST /v1/users/create

Authentication: API Key

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

Create Booking

Endpoint: POST /v1/bookings/create

Authentication: API Key

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!"
}

Error Handling

All API endpoints return consistent error responses:

{
    "success": false,
    "error": "Error message describing what went wrong"
}

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

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

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

Support

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.