ATBeds Standard JSON API

JSON Connector Token

Issues a bearer token for the Standard JSON connector.

Request Body

• email and password are required.
• connector_uuid narrows token issuing to the active connector.
• abilities may be supplied when a scoped token is needed; omit it for the default token behavior used by this collection.

Success Response Example

{
  "access_token": "1|example-token",
  "token_type": "Bearer"
}

Property List

Returns accessible properties for the authenticated connector user.

Shared endpoint style:

POST {{baseUrl}}{{gatewayPathJson}} with X-Api-Operation: content_property_list.

REST-like style when configured:

GET {{baseUrl}}{{standardJsonContentPropertiesPath}}

For GET requests, query parameters such as page, perPage, propertyId, and filters are merged into data when the key is not already present.

Field Notes

• page defaults to 1.
• perPage defaults to 50 and is capped at 500.
• filters is a flexible filter bag. Current code tolerates filters and filter.
• Response property identifiers are exposed as id, not propertyId.

Success Response Example

{
  "schemaVersion": 2,
  "success": true,
  "operation": "content_property_list",
  "requestId": "rr-docs-request-001",
  "meta": {
    "timestamp": "2026-05-10T12:00:00+00:00"
  },
  "data": {
    "properties": [
      {
        "id": 123,
        "name": "Roomi Demo Hotel",
        "slug": "roomi-demo-hotel",
        "starRating": 5,
        "isActive": true,
        "score": 96,
        "location": {
          "placeId": 1001,
          "placeName": "Istanbul",
          "countryCode": "TR",
          "countryName": "Turkiye",
          "addressLineOne": "Example Street 1",
          "timezone": "Europe/Istanbul",
          "lat": 41.0082,
          "lon": 28.9784
        },
        "type": {
          "id": 1,
          "name": "Hotel",
          "code": "HOTEL",
          "slug": "hotel"
        },
        "chain": null,
        "amenities": [],
        "updatedAt": "2026-05-10T12:00:00+00:00"
      }
    ],
    "nextCursor": null,
    "meta": {
      "count": 1,
      "page": 1,
      "perPage": 50
    }
  }
}

Property Single

Returns one accessible property.

Shared endpoint style:

POST {{baseUrl}}{{gatewayPathJson}} with X-Api-Operation: content_property_single.

REST-like style when configured:

GET {{baseUrl}}{{standardJsonContentPropertiesPath}}/{{propertyId}}

Field Notes

• propertyId is required. Aliases currently accepted by the hydrator include property_id, hotelId, hotel_id, and id.
• For REST-like endpoint templates, a path parameter named propertyId can supply this value when the body omits it.
• Missing or inaccessible properties are returned as partner-safe NOT_FOUND errors.

Success Response Example

{
  "schemaVersion": 2,
  "success": true,
  "operation": "content_property_single",
  "requestId": "rr-docs-request-001",
  "meta": {
    "timestamp": "2026-05-10T12:00:00+00:00"
  },
  "data": {
    "property": {
      "id": 123,
      "name": "Roomi Demo Hotel",
      "slug": "roomi-demo-hotel",
      "starRating": 5,
      "isActive": true,
      "location": {
        "placeId": 1001,
        "placeName": "Istanbul",
        "countryCode": "TR",
        "timezone": "Europe/Istanbul"
      },
      "type": {
        "id": 1,
        "name": "Hotel",
        "code": "HOTEL"
      },
      "chain": null,
      "amenities": [],
      "updatedAt": "2026-05-10T12:00:00+00:00"
    },
    "details": {
      "longDescription": "Client-facing hotel description.",
      "checkinFrom": "14:00:00",
      "checkoutUntil": "12:00:00",
      "totalRooms": 120,
      "currencyCode": "EUR",
      "contact": {
        "website": "https://example.test",
        "email": "[email protected]",
        "phone": "+905551112233"
      }
    }
  }
}

Room Type List

Returns room types for a property.

Shared endpoint style:

POST {{baseUrl}}{{gatewayPathJson}} with X-Api-Operation: content_room_type_list.

REST-like style:

The current default inbound blueprint uses operation detection for room type content. A REST-like path can be configured per connector endpoint, for example /api/content/properties/{propertyId}/room-types.

Field Notes

• propertyId is required.
• page defaults to 1.
• perPage defaults to 500.

Success Response Example

{
  "schemaVersion": 2,
  "success": true,
  "operation": "content_room_type_list",
  "requestId": "rr-docs-request-001",
  "meta": {
    "timestamp": "2026-05-10T12:00:00+00:00"
  },
  "data": {
    "roomTypes": [
      {
        "id": "1001",
        "propertyId": 123,
        "name": "Standard Room",
        "updatedAt": "2026-05-10T12:00:00+00:00",
        "isActive": true,
        "squareMeters": 28,
        "view": "city",
        "class": "standard",
        "category": "double",
        "galleryImages": [],
        "maxOccupancy": {
          "total": 3,
          "adults": 2,
          "children": 1
        }
      }
    ],
    "meta": {
      "propertyId": 123,
      "page": 1,
      "perPage": 500,
      "count": 1
    }
  }
}

Room Type Single

Returns one room type for a property.

Shared endpoint style:

POST {{baseUrl}}{{gatewayPathJson}} with X-Api-Operation: content_room_type_single.

REST-like style:

Custom connector endpoint configuration may route a path such as /api/content/properties/{propertyId}/room-types/{roomTypeId} to this operation.

Field Notes

• propertyId is required.
• roomTypeId is required.
• Identifiers may be numeric or string-like depending on connector identifier mapping.

Success Response Example

{
  "schemaVersion": 2,
  "success": true,
  "operation": "content_room_type_single",
  "requestId": "rr-docs-request-001",
  "meta": {
    "timestamp": "2026-05-10T12:00:00+00:00"
  },
  "data": {
    "roomType": {
      "id": "1001",
      "propertyId": 123,
      "name": "Standard Room",
      "isActive": true,
      "squareMeters": 28,
      "maxOccupancy": {
        "total": 3,
        "adults": 2,
        "children": 1
      },
      "galleryImages": []
    }
  }
}

Rate Plan List

Returns rate plans for a property and, optionally, a room type.

Shared endpoint style:

POST {{baseUrl}}{{gatewayPathJson}} with X-Api-Operation: content_rate_plan_list.

REST-like style:

The current default inbound blueprint uses operation detection for rate plan content. A REST-like path can be configured per connector endpoint, for example /api/content/properties/{propertyId}/rate-plans.

Field Notes

• propertyId is required.
• roomTypeId is optional and may also be sent under filters.roomTypeId.
• currencyCode in each rate plan is the configured selling currency for that plan.

Success Response Example

{
  "schemaVersion": 2,
  "success": true,
  "operation": "content_rate_plan_list",
  "requestId": "rr-docs-request-001",
  "meta": {
    "timestamp": "2026-05-10T12:00:00+00:00"
  },
  "data": {
    "ratePlans": [
      {
        "id": "2001",
        "propertyId": 123,
        "roomTypeId": "1001",
        "name": "Best Available Rate",
        "isActive": true,
        "boardingType": {
          "id": 3001,
          "name": "Room Only",
          "code": "RO"
        },
        "currencyCode": "EUR",
        "payAtHotel": false,
        "packageOnly": false,
        "updatedAt": "2026-05-10T12:00:00+00:00"
      }
    ],
    "meta": {
      "propertyId": 123,
      "roomTypeId": "1001",
      "page": 1,
      "perPage": 500,
      "count": 1
    }
  }
}

Rate Plan Single

Returns one rate plan for a property.

Shared endpoint style:

POST {{baseUrl}}{{gatewayPathJson}} with X-Api-Operation: content_rate_plan_single.

REST-like style:

Custom connector endpoint configuration may route a path such as /api/content/properties/{propertyId}/rate-plans/{ratePlanId} to this operation.

Field Notes

• propertyId is required.
• ratePlanId is required.
• Identifiers may be numeric or string-like depending on connector identifier mapping.

Success Response Example

{
  "schemaVersion": 2,
  "success": true,
  "operation": "content_rate_plan_single",
  "requestId": "rr-docs-request-001",
  "meta": {
    "timestamp": "2026-05-10T12:00:00+00:00"
  },
  "data": {
    "ratePlan": {
      "id": "2001",
      "propertyId": 123,
      "roomTypeId": "1001",
      "name": "Best Available Rate",
      "isActive": true,
      "boardingType": {
        "id": 3001,
        "name": "Room Only",
        "code": "RO"
      },
      "currencyCode": "EUR",
      "payAtHotel": false,
      "packageOnly": false
    }
  }
}

Availability Multi By Location

Searches multiple properties by location.

Shared endpoint style:

POST {{baseUrl}}{{gatewayPathJson}} with X-Api-Operation: availability_multi_by_location.

REST-like style when configured:

POST {{baseUrl}}{{standardJsonAvailabilityLocationPath}}

Field Notes

• stay.checkinDate and stay.checkoutDate use YYYY-MM-DD.
• rooms[].children is a list of child ages, not a child count.
• location may include placeId, countryCode, coordinates, radius, or free-text query.
• Returned offerKey values are opaque and should be stored only for the rate-check and booking flow.

Success Response Example

{
  "schemaVersion": 2,
  "success": true,
  "operation": "availability_multi_by_location",
  "requestId": "rr-docs-request-001",
  "meta": {
    "timestamp": "2026-05-10T12:00:00+00:00"
  },
  "data": {
    "searchId": "SEARCH-123",
    "offers": [
      {
        "offerKey": "ofr_opaque_public_key",
        "propertyId": 123,
        "roomTypeId": 1001,
        "ratePlanId": 2001,
        "board": {
          "code": "RO",
          "name": "Room Only"
        },
        "price": {
          "currencyCode": "EUR",
          "priceKind": "SELLING",
          "total": 240,
          "breakdown": [
            {
              "date": "2026-12-10",
              "amount": 120,
              "currency": "EUR"
            }
          ]
        },
        "cancellation": {
          "refundable": true,
          "deadline": "2026-12-08T23:59:59+03:00"
        },
        "occupancy": {
          "roomIndex": 0,
          "adults": 2,
          "children": [
            8
          ]
        },
        "restrictions": {
          "minLos": 1
        }
      }
    ]
  }
}

Availability Multi

Searches multiple explicitly selected properties.

Shared endpoint style:

POST {{baseUrl}}{{gatewayPathJson}} with X-Api-Operation: availability_multi.

REST-like style when configured:

POST {{baseUrl}}{{standardJsonAvailabilityPath}}

Field Notes

• hotelFilter.propertyIds selects the properties.
• Additional supported filter keys include supplierIds, supplierHotelCodes, ratePlanIds, roomTypeIds, boardCodes, refundableOnly, and nonRefundableOnly.
• Response offer fields are intentionally public; supplier IDs and raw pricing internals are hidden by default.

Availability Single

Searches one explicitly selected property.

Shared endpoint style:

POST {{baseUrl}}{{gatewayPathJson}} with X-Api-Operation: availability_single.

REST-like style when configured:

POST {{baseUrl}}{{standardJsonAvailabilitySinglePath}}

Field Notes

• hotelFilter.propertyIds must contain exactly one property ID for single-property search semantics.
• Availability stores offer snapshots for Standard JSON so later lean rate-check and booking requests can use the public offerKey.
• If no offers are available, the response remains a successful envelope with an empty offers array.

Rate Check

Revalidates a specific offer before booking.

Shared endpoint style:

POST {{baseUrl}}{{gatewayPathJson}} with X-Api-Operation: availability_rate_check.

REST-like style when configured:

POST {{baseUrl}}{{standardJsonRateCheckPath}}

Field Notes

• Preferred request shape is lean: send offerKey and optional searchId from a prior availability response.
• If stay, occupancy, or context is present, the hydrator treats the request as a full canonical rate-check payload.
• Lean rate-check requires a stored offer snapshot. If missing or expired, the API returns 409 with OFFER_SNAPSHOT_NOT_FOUND.

Success Response Example

{
  "schemaVersion": 2,
  "success": true,
  "operation": "availability_rate_check",
  "requestId": "rr-docs-request-001",
  "meta": {
    "timestamp": "2026-05-10T12:00:00+00:00"
  },
  "data": {
    "isAvailable": true,
    "offer": {
      "offerKey": "ofr_opaque_public_key",
      "propertyId": 123,
      "roomTypeId": 1001,
      "ratePlanId": 2001,
      "board": {
        "code": "RO",
        "name": "Room Only"
      },
      "price": {
        "currencyCode": "EUR",
        "priceKind": "SELLING",
        "total": 240
      },
      "cancellation": {
        "refundable": true,
        "deadline": "2026-12-08T23:59:59+03:00"
      },
      "occupancy": {
        "roomIndex": 0,
        "adults": 2,
        "children": []
      }
    },
    "alternatives": []
  }
}

Booking Pre-Reservation

Creates a temporary hold for an offer before final confirmation.

Shared endpoint style:

POST {{baseUrl}}{{gatewayPathJson}} with X-Api-Operation: booking_pre_reservation.

REST-like style when configured:

POST {{baseUrl}}{{standardJsonBookingPreReservationPath}}

Field Notes

• Preferred request shape is lean and depends on an availability snapshot for offerKey.
• pricingExpectation is optional but recommended for client-side price protection. When present, a missing snapshot returns OFFER_SNAPSHOT_NOT_FOUND.
• rooms[].guests should include the lead guest. Public room data is merged onto the stored offer snapshot.
• Idempotency-Key is accepted and echoed in response meta.idempotencyKey.

Success Response Example

{
  "schemaVersion": 2,
  "success": true,
  "operation": "booking_pre_reservation",
  "requestId": "rr-docs-request-001",
  "meta": {
    "idempotencyKey": "booking-pre-rr-docs-request-001",
    "timestamp": "2026-05-10T12:00:00+00:00"
  },
  "data": {
    "preReservationCode": "PRE-123",
    "expiresAt": "2026-05-10T12:15:00+00:00",
    "booking": {
      "reference": "RR-REF-1001",
      "status": "PENDING",
      "price": {
        "total": 240,
        "currencyCode": "EUR"
      },
      "rooms": [
        {
          "roomIndex": 0,
          "propertyId": 123,
          "propertyName": "Roomi Demo Hotel",
          "roomTypeId": 1001,
          "roomTypeName": "Standard Room",
          "ratePlanId": 2001,
          "boardingTypeId": 3001,
          "boardingTypeName": "Room Only",
          "stay": {
            "checkinDate": "2026-12-10",
            "checkoutDate": "2026-12-12"
          },
          "adults": 2,
          "children": [],
          "guests": []
        }
      ]
    }
  }
}

Booking Confirm

Confirms a booking from a pre-reservation or from a still-valid offer snapshot.

Shared endpoint style:

POST {{baseUrl}}{{gatewayPathJson}} with X-Api-Operation: booking_confirm.

REST-like style when configured:

POST {{baseUrl}}{{standardJsonBookingConfirmPath}}

Field Notes

• preReservationCode is optional in the DTO but should be sent when the client performed pre-reservation.
• If preReservationCode maps to a valid hold, the confirm request is merged onto the held request snapshot.
• Without a valid hold, the gateway can still rehydrate from the offer snapshot when available.

Success Response Example

{
  "schemaVersion": 2,
  "success": true,
  "operation": "booking_confirm",
  "requestId": "rr-docs-request-001",
  "meta": {
    "idempotencyKey": "booking-confirm-rr-docs-request-001",
    "timestamp": "2026-05-10T12:00:00+00:00"
  },
  "data": {
    "booking": {
      "reference": "RR-REF-1001",
      "supplierReference": "SUP-REF-1001",
      "agentReference": "AGENT-REF-1001",
      "status": "CONFIRMED",
      "price": {
        "total": 240,
        "currencyCode": "EUR"
      },
      "rooms": [
        {
          "roomIndex": 0,
          "propertyId": 123,
          "propertyName": "Roomi Demo Hotel",
          "roomTypeId": 1001,
          "roomTypeName": "Standard Room",
          "ratePlanId": 2001,
          "stay": {
            "checkinDate": "2026-12-10",
            "checkoutDate": "2026-12-12"
          },
          "adults": 2,
          "children": [],
          "hotelConfirmationNumber": "HOTEL-123"
        }
      ],
      "createdAt": "2026-05-10T12:00:00+00:00"
    }
  }
}

Booking Cancel

Cancels a booking by ATBeds reference, with optional supplier and agent references.

Shared endpoint style:

POST {{baseUrl}}{{gatewayPathJson}} with X-Api-Operation: booking_cancel.

REST-like style when configured:

POST {{baseUrl}}{{standardJsonBookingCancelPath}}

Field Notes

• reference is the ATBeds booking reference and is required.
• supplierReference and agentReference are optional but useful for reconciliation.
• Empty penalties and empty errors are removed from the Standard JSON response.

Success Response Example

{
  "schemaVersion": 2,
  "success": true,
  "operation": "booking_cancel",
  "requestId": "rr-docs-request-001",
  "meta": {
    "idempotencyKey": "booking-cancel-rr-docs-request-001",
    "timestamp": "2026-05-10T12:00:00+00:00"
  },
  "data": {
    "status": "CANCELLED"
  }
}

Booking Modify

Requests a modification to an existing booking.

Shared endpoint style:

POST {{baseUrl}}{{gatewayPathJson}} with X-Api-Operation: booking_modify.

REST-like style when configured:

POST {{baseUrl}}{{standardJsonBookingModifyPath}}

Field Notes

• reference is required.
• Optional modification inputs include newStay, newOccupancy, and roomChanges.
• Current implementation hydrates and dispatches this operation, but the Standard JSON presenter does not have a dedicated lean booking_modify projection. As a result, the data object can include raw modify response keys such as success, booking, priceDiff, errors, and meta.

Current Response Shape Example

{
  "schemaVersion": 2,
  "success": true,
  "operation": "booking_modify",
  "requestId": "rr-docs-request-001",
  "meta": {
    "idempotencyKey": "booking-modify-rr-docs-request-001",
    "timestamp": "2026-05-10T12:00:00+00:00"
  },
  "data": {
    "success": true,
    "booking": {
      "reference": "RR-REF-1001",
      "supplierReference": "SUP-REF-1001",
      "agentReference": "AGENT-REF-1001",
      "status": "CONFIRMED",
      "rooms": [],
      "price": {
        "total": 240,
        "currencyCode": "EUR"
      }
    },
    "priceDiff": {
      "amount": 0,
      "currencyCode": "EUR"
    },
    "errors": null
  }
}

Booking List

Returns bookings visible to the authenticated connector user.

Shared endpoint style:

POST {{baseUrl}}{{gatewayPathJson}} with X-Api-Operation: booking_list.

REST-like style when configured:

POST {{baseUrl}}{{standardJsonBookingListPath}}

Field Notes

• Supported filter keys are fromDate, toDate, status, propertyId, and reference.
• page defaults to 1; perPage defaults to 50.

Success Response Example

{
  "schemaVersion": 2,
  "success": true,
  "operation": "booking_list",
  "requestId": "rr-docs-request-001",
  "meta": {
    "timestamp": "2026-05-10T12:00:00+00:00"
  },
  "data": {
    "items": [
      {
        "reference": "RR-REF-1001",
        "supplierReference": "SUP-REF-1001",
        "agentReference": "AGENT-REF-1001",
        "status": "CONFIRMED",
        "price": {
          "total": 240,
          "currencyCode": "EUR"
        },
        "rooms": [],
        "createdAt": "2026-05-10T12:00:00+00:00",
        "updatedAt": "2026-05-10T12:00:00+00:00"
      }
    ],
    "meta": {
      "page": 1,
      "perPage": 50,
      "count": 1
    }
  }
}

Booking Single

Returns one booking by ATBeds reference.

Shared endpoint style:

POST {{baseUrl}}{{gatewayPathJson}} with X-Api-Operation: booking_single.

REST-like style when configured:

POST {{baseUrl}}{{standardJsonBookingSinglePath}}

Field Notes

• reference is required.
• In a REST-like connector endpoint, reference can be supplied by path parameter when the endpoint template extracts it.

Success Response Example

{
  "schemaVersion": 2,
  "success": true,
  "operation": "booking_single",
  "requestId": "rr-docs-request-001",
  "meta": {
    "timestamp": "2026-05-10T12:00:00+00:00"
  },
  "data": {
    "booking": {
      "reference": "RR-REF-1001",
      "supplierReference": "SUP-REF-1001",
      "agentReference": "AGENT-REF-1001",
      "status": "CONFIRMED",
      "price": {
        "total": 240,
        "currencyCode": "EUR"
      },
      "rooms": [
        {
          "roomIndex": 0,
          "propertyId": 123,
          "propertyName": "Roomi Demo Hotel",
          "roomTypeId": 1001,
          "roomTypeName": "Standard Room",
          "ratePlanId": 2001,
          "stay": {
            "checkinDate": "2026-12-10",
            "checkoutDate": "2026-12-12"
          },
          "adults": 2,
          "children": []
        }
      ],
      "createdAt": "2026-05-10T12:00:00+00:00",
      "updatedAt": "2026-05-10T12:00:00+00:00"
    }
  }
}

Unknown Operation

Returned when a shared endpoint request does not resolve to a supported Standard JSON operation.

Error Response Example

{
  "schemaVersion": 2,
  "success": false,
  "operation": "unknown",
  "requestId": "rr-docs-request-001",
  "meta": {
    "timestamp": "2026-05-10T12:00:00+00:00"
  },
  "error": {
    "code": "UNKNOWN_OPERATION",
    "message": "Unknown or unsupported inbound operation.",
    "details": null,
    "fields": null
  }
}

Missing Operation On Shared Endpoint

Shared endpoint style requires the operation in the header, query string, or top-level body. If all are missing, operation detection resolves to unknown.

REST-like endpoint style does not require a body operation when the configured endpoint supplies the operation.

Error Response Example

{
  "schemaVersion": 2,
  "success": false,
  "operation": "unknown",
  "requestId": "rr-docs-request-001",
  "meta": {
    "timestamp": "2026-05-10T12:00:00+00:00"
  },
  "error": {
    "code": "UNKNOWN_OPERATION",
    "message": "Unknown or unsupported inbound operation."
  }
}

Invalid Schema Version

Standard JSON currently supports only schema version 2.

Error Response Example

{
  "schemaVersion": 2,
  "success": false,
  "operation": "availability_single",
  "requestId": "rr-docs-request-001",
  "meta": {
    "timestamp": "2026-05-10T12:00:00+00:00"
  },
  "error": {
    "code": "UNSUPPORTED_SCHEMA_VERSION",
    "message": "Unsupported schema_version.",
    "details": null,
    "fields": {
      "schema_version": [
        "Only schema_version 2 is supported."
      ]
    }
  }
}

Validation Error

Returned when the operation is known but the normalized canonical request fails validation.

Error Response Example

{
  "schemaVersion": 2,
  "success": false,
  "operation": "availability_single",
  "requestId": "rr-docs-request-001",
  "meta": {
    "timestamp": "2026-05-10T12:00:00+00:00"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request payload is invalid.",
    "details": null,
    "fields": {
      "stay.checkinDate": [
        "The checkin date field is required."
      ],
      "rooms": [
        "At least one room is required."
      ]
    }
  }
}

Authentication Required

Most inbound connector endpoints require authentication. Bearer tokens are preferred.

Token issuing is handled by /api/connectivity/token; it is not a Standard JSON gateway operation.

Error Response Example

{
  "schemaVersion": 2,
  "success": false,
  "operation": "content_property_list",
  "requestId": "rr-docs-request-001",
  "meta": {
    "timestamp": "2026-05-10T12:00:00+00:00"
  },
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "Authentication is required."
  }
}

Unsupported Geography Operation

Geography content operations are not part of the current Standard JSON gateway contract.

Current not-supported Standard JSON operations:

• content_country_list
• content_province_list
• content_city_list

These currently resolve as unknown operations for Standard JSON.

Offer Snapshot Missing

Lean rate-check and strict lean booking requests depend on a stored availability offer snapshot.

Error Response Example

{
  "schemaVersion": 2,
  "success": false,
  "operation": "availability_rate_check",
  "requestId": "rr-docs-request-001",
  "meta": {
    "timestamp": "2026-05-10T12:00:00+00:00"
  },
  "error": {
    "code": "OFFER_SNAPSHOT_NOT_FOUND",
    "message": "Offer snapshot not found or expired. Run availability again.",
    "details": null,
    "fields": {
      "offerKey": [
        "The offer snapshot was not found or has expired. Run availability again."
      ]
    }
  }
}