Data model

The shape of it

Entity (organization)
├── Property                     the rental unit
│   ├── Inventory item           what is inside it
│   └── Booking                  a stay, or a blocked range
│       ├── Guest                who is staying
│       ├── Payment              what they owe and paid
│       ├── Note / Reminder      internal context
│       └── Lease document       generated from a Template
├── Lead                         an inbound enquiry, before it becomes a booking
│   └── Pipeline stage           where it sits in the funnel
├── Conversation                 messages with a guest or a lead
├── Task                         work on a property, assigned to a Vendor
└── Vendor                       cleaner, handyman, contractor

Entity

The organization. Every other record belongs to exactly one entity, and your API key is bound to one entity, so you never need to pass an entity id to scope a request — it is implied.

Some endpoints do take an entityId in the path (/tasks/get/entity/:entityId). Those are for reading a specific entity you already have access to; they do not let you reach across organizations.

Property

A rental unit: address, bedrooms, bathrooms, rates, amenities, images, availability. Rates are a list, not a single number, because pricing varies by length of stay.

Properties carry a timezone, and it matters: booking dates are millisecond timestamps, and check-in and check-out are interpreted in the property's local time.

Lead — and where to find it

A lead is an inbound enquiry: someone asking about a property before any booking exists. Leads carry the enquirer's name, contact details, desired dates, destination, party size, and the pipeline stage they are in.

Leads live under /webhooks/, not /leads/. This is the single most confusing thing about this API, so it is worth stating early:

What you want	Endpoint
List leads	GET /webhooks/get/all
Create a lead	POST /webhooks/create-lead
Update a lead	POST /webhooks/update-lead
Move a lead to another stage	POST /webhooks/update-stage
Delete a lead	POST /webhooks/delete-lead

The path is historical: leads first arrived as inbound webhooks from listing sites, and the collection kept the name. The same /webhooks/ prefix also holds genuine provider callbacks (/webhooks/resend, /webhooks/twilio/sms) which are not part of this API — they are called by third parties, not by you.

Pipeline stage

The configurable funnel a lead moves through. Stages are per-entity and ordered, so read them from GET /pipeline-stages/get/entity/:entityId before moving a lead — the stage ids are not fixed constants.

Booking

A booking is a stay on a property between two timestamps. It is also the record that carries the lease: guest signatures, lease documents generated from a template, background check state, and the payment schedule.

Two things to know:

• A blocked date range is also a booking. POST /bookings/block-dates creates one. When you read bookings you will see these alongside real stays, so check status before treating one as a guest stay.
• A booking can be reversed back into a lead with POST /bookings/reverse-to-lead/:bookingId. A lead and a booking are separate records, not one record in two states.

Guest

The person staying. A booking has one primary guest (guestId) plus additionalGuests for everyone else on the lease. Guests are people with their own login to the guest app, so a guest record can exist without any booking.

Conversation

The message thread with a guest or lead, across SMS, email, and in-app. Messages are appended to a conversation, and a conversation is attached to a booking or a lead.

When you send a message through the API it really goes out — to a phone, to an inbox. There is no dry-run mode. Test on https://dev.core.mtro.app.

Task and Vendor

A task is work on a property — cleaning, repair, turnover — on a date, usually assigned to a vendor. Vendors are the entity's service providers.

Payment

What a booking owes and what has been paid, including Stripe checkout links and recurring schedules. Payment endpoints move real money. Treat every write here as requiring explicit human confirmation in your integration.

Identifiers

Ids are MongoDB ObjectIds: 24 hexadecimal characters. Dates and times are millisecond timestamps (1790000000000), not seconds and not ISO strings. Getting this wrong by a factor of 1000 puts a booking in 1970.