Introduction

Overview

The Mobile Calendar API provides a modern, REST-based interface for integrating external systems such as channel managers, property management systems (PMS), pricing tools, and custom applications. It allows developers to synchronize reservations, availability, pricing, clients, and room data and others between Mobile Calendar and external platforms.

The API supports both data retrieval and data submission — enabling two-way communication for building deep integrations.

Common use cases include:

• Importing or exporting reservations from connected systems

• Managing room availability and restrictions

• Synchronizing pricing rules and occupancy

• Building custom dashboards or automation tools

• Receiving real-time updates through webhooks

Standards and Architecture

The API follows RESTful design principles, using standard HTTP methods and status codes. All requests and responses use JSON format encoded in UTF-8.

• Base URL: https://api.mobile-calendar.com/v1/public

• Content-Type: application/json

• Versioning: Managed via the URL path (e.g., /v1/)

• Rate Limiting: 60 requests per minute per user

• Error handling: compliant with RFC 7807 (application/problem+json)

Authentication and Security

Authentication uses JWT (JSON Web Token) in the Authorization header.

Authorization: Bearer {access_token}

Tokens are obtained through the /auth/login endpoint by providing valid credentials. All communication must occur over HTTPS. Unencrypted HTTP requests are rejected.

You can read more here: Authentiction.

HTTP Status Codes

Code	Meaning	Description
200	OK	Successful request
201	Created	Resource successfully created
204	No Content	Request successful, no response body
300	Multiple Choices	Resource has multiple representations
401	Unauthorized	Invalid or missing authentication
403	Forbidden	Access denied for the resource
404	Not Found	Resource not found
409	Conflict	Resource already exists or invalid state
422	Unprocessable Entity	Validation error in request body
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error
503	Service Unavailable	API temporarily unavailable
504	Gateway Timeout	API did not respond in time

Response Formats

The API primarily returns JSON responses.

Example Success Response (200)

Success (200) example.json

{
  "data": {
    "reservationId": 12345,
    "roomId": 30268,
    "arrival": "2025-10-14",
    "departure": "2025-10-16"
    ...
  },
  "meta": {
    "ruid": "7f80f1b4-a44b-4345-b383-7d0a937b4411"
  }
}

Example Error Response (application/problem+json)

Error (422) example.json

{
  "type": "https://api.mobile-calendar.com...",
  "title": "Invalid request data",
  "status": 422,
  "detail": "The 'arrival' date cannot be in the past.",
  "instance": "/v1/reservations",
  "ruid": "7f80f1b4-a44b-4345-b383-7d0a937b4411"
}

API Versioning and Rate Limits

The current API version is v1. Each major release introduces breaking changes and will be announced in advance.

Rate limits:

• 60 requests per minute per authenticated user

• Exceeding limits returns 429 Too Many Requests

• Response headers include rate limit details:

  • X-RateLimit-Limit

  • X-RateLimit-Remaining

  • X-RateLimit-Reset

Additional Concepts

RUID (Request Unique ID)

Every response includes a ruid value for tracing requests through logs and support tools.

Webhooks

The API supports webhooks for real-time data synchronization. You can register endpoints to receive updates when reservations, availability, or prices change.

Example Webhook events:

• reservation.created

• reservation.updated

• reservation.cancelled

• availability.updated

You can read more here: Webhooks.

Pagination

Endpoints returning lists use pagination parameters:

?page=1&limit=50

Metadata such as total items and next/previous links are included in responses.

Getting Started

1

Request API access

Request API access via your Mobile Calendar account.

2

Generate your API credentials

Generate your API credentials and obtain your JWT token using /auth/login.

3

Make your first request

Example:

curl example

curl -X GET https://api.mobile-calendar.com/v1/reservations \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json"

4

Handle rate limits and errors

Handle rate limits (429) and other errors gracefully in your integration.

5

Subscribe to webhooks (optional)

Subscribe to webhooks for automatic data updates.

6

Explore the OpenAPI documentation

Explore the full OpenAPI documentation to understand all available endpoints and data models.

Support and Best Practices

• Always use HTTPS and short-lived tokens.

• Respect rate limits to ensure stable API access.

• Include your integration name and version in the User-Agent header.

• Log all requests and ruid values for troubleshooting.

• Contact support for partnership integrations or higher rate limits.