Bookings

Reservations and date blocks, from availability checks to lease signing.

15 endpoints. Every request needs an Authorization: Bearer mtro_... header, and responses follow the envelope described in Errors and conventions.

POST /bookings/block-dates

Block dates on a property (e.g. for maintenance or owner use). Creates a blocked-dates booking.

Required scope: bookings.write
MCP tool: bookings_block_dates

Request body

Field	Type	Required	Description
propertyId	string	yes	Property ID to block dates on
startDate	number	yes	Block start date (timestamp ms)
endDate	number	yes	Block end date (timestamp ms)
notes	string	no	Reason for blocking dates

Example

curl -X POST 'https://core.mtro.app/bookings/block-dates' \
  -H 'Authorization: Bearer mtro_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{"propertyId":"<propertyId>","startDate":0,"endDate":0}'

POST /bookings/block-dates/delete/{bookingId}

Delete an owner block/blocked-dates booking. This is destructive and should require owner confirmation when used by an agent.

Required scope: bookings.write
MCP tool: bookings_delete_block_dates

Path parameters

Name	Type	Required	Description
bookingId	string	yes

Example

curl -X POST 'https://core.mtro.app/bookings/block-dates/delete/<bookingId>' \
  -H 'Authorization: Bearer mtro_your_api_key'

POST /bookings/block-dates/update/{bookingId}

Update an owner block/blocked-dates booking. This writes calendar state and should require owner confirmation when used by an agent.

Required scope: bookings.write
MCP tool: bookings_update_block_dates

Path parameters

Name	Type	Required	Description
bookingId	string	yes

Request body

note

Field names are taken from the Core handler, which reads exactly these. Types and which of them are required are not yet documented.

Field	Type	Required	Description
endDate	any	no
notes	any	no
startDate	any	no

Example

curl -X POST 'https://core.mtro.app/bookings/block-dates/update/<bookingId>' \
  -H 'Authorization: Bearer mtro_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST /bookings/create

Create a new booking. Required: propertyId, startDate (timestamp ms), endDate (timestamp ms). The primary guest is identified by guestEmail: Core finds the matching guest or creates one from guestName, guestSurname and guestMobile.

Required scope: bookings.write
MCP tool: bookings_create

Request body

Field	Type	Required	Description
propertyId	string	yes	Property ID for the booking
startDate	number	yes	Start date as millisecond timestamp
endDate	number	yes	End date as millisecond timestamp
guestEmail	string	no	Primary guest email. Core matches an existing guest on this address or creates one.
guestName	string	no	Primary guest first name, used when the guest has to be created
guestSurname	string	no	Primary guest surname, used when the guest has to be created
guestMobile	string	no	Primary guest mobile number in E.164 format
rate	number	no	Rate per day
source	string	no	Booking source
status	string	no	Booking status: confirmed, pending, cancelled
notes	string	no	Booking notes
leadId	string	no	Lead this booking was converted from
templateId	string	no	Lease template ID
customFields	object[]	no	Custom field values for the booking

Example

curl -X POST 'https://core.mtro.app/bookings/create' \
  -H 'Authorization: Bearer mtro_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{"propertyId":"<propertyId>","startDate":0,"endDate":0}'

POST /bookings/delete/{bookingId}

Delete a booking by bookingRef. This action cannot be undone.

Required scope: bookings.write
MCP tool: bookings_delete

Path parameters

Name	Type	Required	Description
bookingId	string	yes

Example

curl -X POST 'https://core.mtro.app/bookings/delete/<bookingId>' \
  -H 'Authorization: Bearer mtro_your_api_key'

GET /bookings/get/{bookingId}

Get detailed information about a specific booking by bookingRef or raw booking ID.

Required scope: bookings.read
MCP tool: bookings_get

Path parameters

Name	Type	Required	Description
bookingId	any	yes	Raw booking ObjectId.

Example

curl -X GET 'https://core.mtro.app/bookings/get/<bookingId>' \
  -H 'Authorization: Bearer mtro_your_api_key'

Response

Field	Type
message	string
error	boolean
booking	object

Fields of booking

Field	Type
id	string
createdAt	integer
propertyId	string
guestId	string
additionalGuests	any[]
startDate	integer
endDate	integer
startDateOnly	string
endDateOnly	string
dateSemantics	object
rate	integer
source	string
status	string
guests	object
pets	object
customFields	any[]
mergeFieldValues	object
leaseDocuments	any[]
leasePackage	any
lastUpdated	integer
guestSign	any[]
ownerSign	any[]
backgroundCheckProvider	any
backgroundCheckCreditCheckRequested	boolean
backgroundCheckCreditCheckLocked	boolean
backgroundCheckStatus	any
backgroundCheckProviderStatus	any
backgroundCheckProviderRequestId	any
backgroundCheckProviderReservationId	any
backgroundCheckGuestPortalUrl	any
backgroundCheckReportUrl	any
backgroundCheckGuestPortalStatus	any
backgroundCheckGuestPortalLastScreen	any
backgroundCheckRiskColor	any
backgroundCheckTopRisks	any[]
backgroundCheckRequestedAt	any
backgroundCheckCompletedAt	any
backgroundCheckLastSyncedAt	any
backgroundCheckError	any
backgroundCheckReviewReason	any
backgroundCheckActionRequired	any
backgroundCheckCanResumeIdentityVerification	boolean
backgroundCheckPackage	any
backgroundCheckPackageLabel	any
backgroundCheckPackagePriceCents	any
backgroundCheckSelectedGuests	any[]
backgroundCheckPayer	any
backgroundCheckPaymentStatus	any
backgroundCheckPaymentCheckoutUrl	any
backgroundCheckPaymentIntentId	any
backgroundCheckPaymentChargedAt	any
backgroundCheckPaymentError	any
backgroundCheckBillingAcceptedAt	any
backgroundCheckBillingAcceptedBy	any
backgroundCheckRequestedBy	any
backgroundCheckOwnerPaymentMethodAvailable	boolean
surveyStatus	any
guest	object
property	object
platformFeePayer	string
initialPaymentId	any
leaseReadiness	object
progress	object

GET /bookings/get/all

List all bookings you have access to. Returns compact live booking rows with simple bookingRef values like B001. Prefer bookingRef over raw ObjectIds in later tool calls.

Required scope: bookings.read
MCP tool: bookings_list

Example

curl -X GET 'https://core.mtro.app/bookings/get/all' \
  -H 'Authorization: Bearer mtro_your_api_key'

Response

Field	Type
message	string
error	boolean
bookings	object[]

Fields of bookings[]

Field	Type
id	string
createdAt	integer
propertyId	string
guestId	string
additionalGuests	any[]
startDate	integer
endDate	integer
startDateOnly	string
endDateOnly	string
dateSemantics	object
rate	integer
source	string
status	string
calendarBlockedAt	any
surveyStatus	any
hasSurvey	boolean
guests	object
pets	object
customFields	any[]
mergeFieldValues	object
leaseDocuments	any[]
leasePackage	any
lastUpdated	integer
guestSign	any[]
ownerSign	any[]
backgroundCheckProvider	string
backgroundCheckCreditCheckRequested	boolean
backgroundCheckCreditCheckLocked	boolean
backgroundCheckStatus	any
backgroundCheckProviderStatus	any
backgroundCheckProviderRequestId	any
backgroundCheckProviderReservationId	any
backgroundCheckGuestPortalUrl	any
backgroundCheckReportUrl	any
backgroundCheckGuestPortalStatus	any
backgroundCheckGuestPortalLastScreen	any
backgroundCheckRiskColor	any
backgroundCheckTopRisks	any[]
backgroundCheckRequestedAt	any
backgroundCheckCompletedAt	any
backgroundCheckLastSyncedAt	any
backgroundCheckError	any
backgroundCheckReviewReason	any
backgroundCheckActionRequired	any
backgroundCheckCanResumeIdentityVerification	boolean
backgroundCheckPackage	any
backgroundCheckPackageLabel	any
backgroundCheckPackagePriceCents	any
backgroundCheckSelectedGuests	any[]
backgroundCheckPayer	any
backgroundCheckPaymentStatus	any
backgroundCheckPaymentCheckoutUrl	any
backgroundCheckPaymentIntentId	any
backgroundCheckPaymentChargedAt	any
backgroundCheckPaymentError	any
backgroundCheckBillingAcceptedAt	any
backgroundCheckBillingAcceptedBy	any
backgroundCheckRequestedBy	any
backgroundCheckOwnerPaymentMethodAvailable	boolean
backgroundCheckRequestedByUser	any
platformFeePayer	string
initialPaymentId	any
guest	object
property	object
progress	object

POST /bookings/public/check-availability

Check if a property is available for specific dates.

Required scope: any valid API key for the entity.
MCP tool: bookings_check_availability

Request body

Field	Type	Required	Description
propertyId	string	yes	Property ID to check
startDate	number	yes	Start date as millisecond timestamp
endDate	number	yes	End date as millisecond timestamp

Example

curl -X POST 'https://core.mtro.app/bookings/public/check-availability' \
  -H 'Authorization: Bearer mtro_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{"propertyId":"<propertyId>","startDate":0,"endDate":0}'

POST /bookings/request-background-check/{bookingId}

Request a background check for a booking. This can trigger external workflow and should require owner confirmation when used by an agent.

Required scope: bookings.write
MCP tool: bookings_request_background_check

Path parameters

Name	Type	Required	Description
bookingId	string	yes

Request body

note

Field names are taken from the Core handler, which reads exactly these. Types and which of them are required are not yet documented.

Field	Type	Required	Description
applicationType	any	no
creditCheckRequested	any	no
packageType	any	no
payer	any	no
savePaymentMethodForFuture	any	no
selectedGuests	any	no

Example

curl -X POST 'https://core.mtro.app/bookings/request-background-check/<bookingId>' \
  -H 'Authorization: Bearer mtro_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST /bookings/reverse-to-lead/{bookingId}

Reverse a booking back to a lead. This changes workflow state and should require owner confirmation when used by an agent.

Required scope: bookings.write
MCP tool: bookings_reverse_to_lead

Path parameters

Name	Type	Required	Description
bookingId	string	yes

Example

curl -X POST 'https://core.mtro.app/bookings/reverse-to-lead/<bookingId>' \
  -H 'Authorization: Bearer mtro_your_api_key'

POST /bookings/set-background-check-approval/{bookingId}

Approve or reject a booking background check. This changes booking state and should require owner confirmation when used by an agent.

Required scope: bookings.write
MCP tool: bookings_set_background_check_approval

Path parameters

Name	Type	Required	Description
bookingId	string	yes

Request body

Field	Type	Required	Description
approval	boolean	yes	Set true to approve the background check, false to reject it.

Example

curl -X POST 'https://core.mtro.app/bookings/set-background-check-approval/<bookingId>' \
  -H 'Authorization: Bearer mtro_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{"approval":true}'

POST /bookings/set-lease-prepared/{bookingId}

Mark lease preparation state for a booking. This writes account data and should require owner confirmation when used by an agent.

Required scope: bookings.write, leases.sign
MCP tool: bookings_set_lease_prepared

Path parameters

Name	Type	Required	Description
bookingId	string	yes

Request body

note

Field names are taken from the Core handler, which reads exactly these. Types and which of them are required are not yet documented.

Field	Type	Required	Description
feePayer	any	no
initialPaymentAmount	any	no
ownerName	any	no
platformFeePayer	any	no
signature	any	no

Example

curl -X POST 'https://core.mtro.app/bookings/set-lease-prepared/<bookingId>' \
  -H 'Authorization: Bearer mtro_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST /bookings/set-primary-guest/{bookingId}

Set the primary guest for a booking that does not have one yet. This writes account data and should require owner confirmation when used by an agent.

Required scope: bookings.write
MCP tool: bookings_set_primary_guest

Path parameters

Name	Type	Required	Description
bookingId	string	yes

Request body

Field	Type	Required	Description
guestEmail	string	yes	Email of the guest to set as primary. Core matches an existing guest on this address or creates one.
guestName	string	no	Guest first name, used when the guest has to be created
guestSurname	string	no	Guest surname, used when the guest has to be created

Example

curl -X POST 'https://core.mtro.app/bookings/set-primary-guest/<bookingId>' \
  -H 'Authorization: Bearer mtro_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{"guestEmail":"<guestEmail>"}'

POST /bookings/sign/{bookingId}

Sign a booking/lease as owner. This is legally significant and should require owner confirmation when used by an agent.

Required scope: leases.sign
MCP tool: bookings_sign

Path parameters

Name	Type	Required	Description
bookingId	string	yes

Request body

note

Field names are taken from the Core handler, which reads exactly these. Types and which of them are required are not yet documented.

Field	Type	Required	Description
ownerName	any	no
signature	any	yes

Example

curl -X POST 'https://core.mtro.app/bookings/sign/<bookingId>' \
  -H 'Authorization: Bearer mtro_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{"signature":"<signature>"}'

POST /bookings/update/{bookingId}

Update an existing booking. Use bookingRef from bookings_list, plus any fields to update.

Required scope: bookings.write
MCP tool: bookings_update

Path parameters

Name	Type	Required	Description
bookingId	string	yes

Example

curl -X POST 'https://core.mtro.app/bookings/update/<bookingId>' \
  -H 'Authorization: Bearer mtro_your_api_key'