Sophia PMS – Partner API (v1)

Overview

The Sophia PMS Partner API (v1) is a read-only API that enables authorized partners to retrieve data from hotels using Sophia PMS.

The API provides access to hotel properties, reservations, revenue reports, occupancy metrics, channel mix, and room availability. It allows partners to integrate hotel operational data into their own applications, reporting platforms, and business intelligence solutions.

Key Features

• Hotel Properties: Retrieve the list of hotels accessible to the API key.
• Reservations (Bookings): Retrieve booking lists and details, including guest information, room types, reservation status, rates, and stay dates.
• Revenue and Performance Reports: Access revenue, Occupancy, Average Daily Rate (ADR), and Revenue per Available Room (RevPAR).
• Channel Mix: Analyze revenue and room-night distribution by market segment or booking source.
• Room Availability: Retrieve available room inventory by room type and date, including future dates.

1. Connection Information

The API is read-only and supports GET requests only. All requests must use HTTPS.

Endpoint Reference

2. API Authentication

Sophia issues each partner an API key in the format spk_.... The key must be included in the user-api-key HTTP header of every request.

GET /api/partner/v1/properties
Host: app.sophiapms.com
user-api-key: spk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Security Requirements

• Never pass the API key through a query string.
• Each API key can access only the hotel properties explicitly assigned to it.
• API keys are stored as hashes and cannot be retrieved in their original form.
• If a key is lost, contact Sophia to request a replacement. The previous key will be deactivated immediately.
• When a key is revoked, requests using that key will be rejected within a maximum of one minute.

Partners must keep API keys confidential and must not expose them in public source code or share them with unauthorized systems.

3. Rate Limits

The API enforces rate limits per API key and hotel property.

Limits may be adjusted for individual API keys.

Successful responses include the following headers:

• X-RateLimit-Limit: Maximum number of requests allowed per minute.
• X-RateLimit-Remaining: Number of requests remaining in the current minute.

When the limit is exceeded, the API returns HTTP 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying.

Recommended Practices

• Synchronize data periodically, for example every 5–15 minutes, depending on business requirements.
• Process requests sequentially for each hotel property.
• Avoid concurrent requests for the same property.
• Respect the Retry-After header when receiving a 429 response.
• Use pagination to retrieve all available records.

4. Response Format and Error Codes

4.1. Successful Responses

List endpoints generally return the following structure:

{
  "data": [
    {
      "id": "...",
      "type": "...",
      "attributes": {}
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 120
  }
}

Depending on the endpoint, data may be an array or an object containing data fields and nested collections.

4.2. Error Responses

{
  "errors": {
    "code": "validation_error",
    "title": "property_id is required."
  }
}

4.3. HTTP Error Codes

4.4. Data Conventions

• Dates use the yyyy-MM-dd format.
• Datetimes use the yyyy-MM-ddTHH:mm:ss format and the hotel's local time zone (UTC+7).
• Monetary values are numeric and use the hotel's currency, typically VND.
• Fields without available data are returned as null.

5. Hotel Properties

Endpoint: GET /properties

This endpoint returns the list of hotel properties accessible to the API key. The id field is the property_id required by the other endpoints.

Example request:

curl -H "user-api-key: spk_xxx" \
  "https://app.sophiapms.com/api/partner/v1/properties"

Example response:

{
  "data": [
    {
      "id": 10,
      "type": "property",
      "attributes": {
        "id": 10,
        "title": "Demo Sophia Hotel",
        "code": "DEMO",
        "address": "123 Le Loi",
        "city": "Ho Chi Minh",
        "country": "VN"
      }
    }
  ],
  "meta": {
    "total": 1
  }
}

Partners should call this endpoint before requesting bookings, reports, or room inventory.

6. Booking List

Endpoint: GET /bookings

This endpoint retrieves bookings by hotel property, arrival date range or departure date range, room status, and pagination parameters.

6.1. Request Parameters

At least one date range—arrival or departure—must be provided. If both ranges are supplied, the results must satisfy both conditions.

• The _from and _to parameters must be supplied together.
• The end date cannot be earlier than the start date.
• Each date range is limited to 30 calendar days, inclusive.
• Each returned record represents a booking group with the same arrival and departure dates. Rooms in a group booking with different stay dates are returned as separate records sharing the same booking_id.
• Cancelled rooms are excluded. A booking with all rooms cancelled is not returned.
• When filtering by status, a booking group is returned if at least one room matches the requested status. Its rooms array contains all non-cancelled rooms in that group.
• Pagination and meta.total are based on the number of booking records, not the number of rooms.
• Results are sorted by arrival date in ascending order.

Example request:

curl -H "user-api-key: spk_xxx" \
  "https://app.sophiapms.com/api/partner/v1/bookings?property_id=10&arrival_from=2026-10-01&arrival_to=2026-10-30&status=pending,checked_in&page=1&limit=50"

To retrieve all records, increment page until page * limit >= meta.total.

6.2. Group Booking Example

Suppose booking BK000123 contains four rooms:

The API returns two records because room 103 has different stay dates and room 104 has been cancelled.

7. Booking Details

Endpoint: GET /bookings/{booking_id}?property_id={property_id}

The response follows the same structure as the booking list, with data returned as an array. A group booking may contain multiple groups with different arrival and departure dates.

The API returns 404 not_found if the booking cannot be found or all its rooms have been cancelled.

7.1. Booking Fields

7.2. Room Fields

8. Room Statuses

Room status is defined for each rooms[].status entry, not for the booking as a whole.

The status filter accepts only the values listed above. Passing cancelled or another unsupported value returns 400 validation_error.

Cancelled rooms are not returned. If a room disappears from a synchronization result for the same date range, it may have been cancelled or moved to a different date group. Call the booking details endpoint to verify its current state.

9. Revenue and Performance Reports

The reporting endpoints share the following parameters:

The date range is inclusive and limited to 30 days per request. These endpoints use the same API key and rate limits as booking endpoints.

9.1. Revenue Calculation Rules

Revenue includes amounts already posted to the folio, such as posted room charges and entered services. Therefore, to must not be later than the hotel's current business date, returned in meta.business_date.

• revenue: Revenue including VAT and service charges.
• revenue_ex_vat: Revenue excluding VAT but including service charges.
• total: Total revenue.
• room: Room revenue.
• extra: Service revenue.

Room revenue is calculated by stay night, while service revenue is calculated by posting date.

room_nights_sold counts nights with posted room revenue greater than 10. Complimentary room nights with a rate of zero are excluded. room_nights_available is calculated from rooms in operation, excluding virtual and combined room types and subtracting OOO rooms for each date.

9.2. Revenue, Occupancy, ADR, and RevPAR

Endpoint: GET /reports/summary

Example request:

curl -H "user-api-key: spk_xxx" \
  "https://app.sophiapms.com/api/partner/v1/reports/summary?property_id=10&from=2026-10-01&to=2026-10-27&group_by=week"

The optional group_by parameter supports:

The response includes totals for the entire requested date range and periods[] for individual reporting periods. The first or last period may cover only part of a week or month.

Calculation formulas:

• Occupancy (%) = room_nights_sold / room_nights_available × 100.
• ADR = Room revenue / room_nights_sold.
• RevPAR = Room revenue / room_nights_available.

The corresponding excluding-VAT metrics use room revenue excluding VAT. The data object also includes property_id, from, to, group_by, currency, and sellable_rooms (rooms in operation before subtracting OOO rooms). The API returns null when a denominator is zero.

9.3. Channel Mix

Endpoint: GET /reports/channel-mix

This endpoint provides revenue and distribution by market segment or booking source.

Example request to retrieve data by booking source:

curl -H "user-api-key: spk_xxx" \
  "https://app.sophiapms.com/api/partner/v1/reports/channel-mix?property_id=10&from=2026-10-01&to=2026-10-27&level=source"

The level parameter supports:

• segment (default): Groups data by market segment, such as OTA, Travel Agent, Direct, or Corporate.
• source: Groups data by individual booking source, such as Booking.com, Agoda, or a corporate account, and includes the associated market segment.

Sources without an assigned segment are grouped under Other, with id = 0. The items array is sorted by descending revenue. The totals object contains overall revenue, revenue_ex_vat, room_nights, adr, and adr_ex_vat.

10. Room Availability by Room Type

Endpoint: GET /inventory/vacant

This endpoint returns the number of rooms in operation, sold or reserved rooms, OOO rooms, and vacant rooms by date and room type.

Example request:

curl -H "user-api-key: spk_xxx" \
  "https://app.sophiapms.com/api/partner/v1/inventory/vacant?property_id=10&from=2026-10-28&to=2026-11-05"

Future dates are supported. Availability is calculated based on existing bookings at the time of the request.

Formula:

vacant = max(0, total_rooms - sold - out_of_order)

Virtual and combined room types are excluded. The days[] array contains daily availability data. Each days[].room_types[] array contains room-type details, while days[].totals provides the total for the date.

Note: Room availability changes as bookings are created or updated. Partners should retrieve this endpoint when current availability is required rather than storing results for extended periods.

11. cURL Examples

Retrieve accessible properties:

curl -H "user-api-key: spk_xxx" \
  "https://app.sophiapms.com/api/partner/v1/properties"

Retrieve bookings:

curl -H "user-api-key: spk_xxx" \
  "https://app.sophiapms.com/api/partner/v1/bookings?property_id=10&arrival_from=2026-10-01&arrival_to=2026-10-30"

Retrieve booking details:

curl -H "user-api-key: spk_xxx" \
  "https://app.sophiapms.com/api/partner/v1/bookings/8b7d6e5f-0000-0000-0000-000000000000?property_id=10"

Retrieve weekly revenue, Occupancy, ADR, and RevPAR:

curl -H "user-api-key: spk_xxx" \
  "https://app.sophiapms.com/api/partner/v1/reports/summary?property_id=10&from=2026-10-01&to=2026-10-27&group_by=week"

Retrieve channel mix by source:

curl -H "user-api-key: spk_xxx" \
  "https://app.sophiapms.com/api/partner/v1/reports/channel-mix?property_id=10&from=2026-10-01&to=2026-10-27&level=source"

Retrieve room availability by room type, including future dates:

curl -H "user-api-key: spk_xxx" \
  "https://app.sophiapms.com/api/partner/v1/inventory/vacant?property_id=10&from=2026-10-28&to=2026-11-05"

C# Integration Example

The following example demonstrates how to send a request using HttpClient and wait when the rate limit is reached.

using System;
using System.Net.Http;
using System.Threading.Tasks;

public class SophiaPartnerApi
{
    public static async Task Main()
    {
        using (var http = new HttpClient
        {
            BaseAddress = new Uri(
                "https://app.sophiapms.com/api/partner/v1/")
        })
        {
            http.DefaultRequestHeaders.Add("user-api-key", "spk_xxx");

            var res = await http.GetAsync(
                "bookings?property_id=10&arrival_from=2026-10-01&arrival_to=2026-10-30");

            if ((int)res.StatusCode == 429)
            {
                var wait = res.Headers.RetryAfter?.Delta
                    ?? TimeSpan.FromSeconds(60);

                await Task.Delay(wait);

                res = await http.GetAsync(
                    "bookings?property_id=10&arrival_from=2026-10-01&arrival_to=2026-10-30");
            }

            var json = await res.Content.ReadAsStringAsync();
            Console.WriteLine(json);
        }
    }
}

This example demonstrates basic request handling and rate-limit recovery. Production integrations should also implement HTTP status validation, error handling, pagination, and appropriate retry policies.

12. Data Synchronization Guidelines

12.1. Booking Synchronization

1. Call /properties to retrieve the list of accessible properties.
2. For each property, retrieve upcoming bookings using an arrival date range from today through today + 29 days.
3. Retrieve current stays using status=checked_in with an appropriate departure date range.
4. Process every page until all records have been retrieved.
5. Compare new records with stored data using booking id, rooms[].id, and updated_at to detect changes.

If a room no longer appears in the results for the same date range, call /bookings/{booking_id} to verify its current state. If the details endpoint returns 404, the entire booking has been cancelled or no longer exists under the API's rules.

12.2. Report Synchronization

1. Revenue may change when hotel staff modify folio entries. Retrieve the previous day's data after the hotel completes its night audit, for example, every morning.
2. For more accurate monthly figures, periodically refresh data for the current month.
3. Split date ranges longer than 30 days into multiple requests, each covering no more than 30 days.
4. When consolidating multiple periods, recalculate Occupancy, ADR, and RevPAR from the corresponding totals instead of averaging individual period percentages or rates.
5. Do not set to later than meta.business_date; doing so returns 400 validation_error.

12.3. Rate-Limit Handling

When receiving 429 Too Many Requests, wait for the duration specified by Retry-After before retrying. Requests for the same hotel property should be processed sequentially.

13. Support

For API key replacement, additional property access, or rate-limit adjustments, please contact the Sophia PMS team.

Sophia PMS – Hotel Management System

Website: https://sophiasolution.com/

API Base URL: https://app.sophiapms.com/api/partner/v1

This documentation applies to Sophia PMS Partner API version v1.