# Tafaddal

> Tafaddal (تفضّل, said ta-FAD-dal, Arabic for "please, come in") is the booking layer for AI agents. A business connects once, and Claude, ChatGPT, Gemini or any AI agent can check live availability, hold a slot, take payment and confirm a booking over MCP or a REST API, without a browser.

Tafaddal launches in Doha, Qatar, in winter 2026–27, starting with tours and experiences (desert safaris, dhow cruises, kayaking, city tours), then salons and spas. Businesses are "hosts", the people booked for are "guests", and AI assistants are "agents".

Status: private beta. Public bookings are not open yet. To request API access, email hello@tafaddal.ai with the subject "API access".

## Connect

- MCP endpoint: https://mcp.tafaddal.ai/mcp (streamable HTTP, OAuth sign-in for consumer agents)
- REST base: https://api.tafaddal.ai/v1 (API keys for platforms)

## Tools

Each MCP tool has a matching REST endpoint.

- search_offers (GET /v1/offers): find bookable experiences and services by category, party size and price; pass a date (and earliest/latest times of day) to get each offer's free times, with the full-refund deadline for each [read]
- get_offer (GET /v1/offers/{id}): details, media, location and policies for one offer [read]
- check_availability (GET /v1/offers/{id}/availability): live slots with remaining capacity and price [read]
- book (POST /v1/bookings): book a start time in one step: confirmed at once when the host takes payment at the venue, otherwise held for 10 minutes with a payment link for the guest [sensitive write]
- get_booking (GET /v1/bookings/{id}): status and details; over MCP it adds the refund deadlines, what cancelling now would refund and the host's WhatsApp, and with no reference it lists the signed-in guest's upcoming bookings [read]
- change_booking (POST /v1/bookings/{id}/change): move to another start time on the same offer, same party and price, free of charge, within the host's minimum notice; refund deadlines keep counting from the earlier time (refunds_count_from), so a move can't reopen a free cancellation [sensitive write]
- cancel_booking (POST /v1/bookings/{id}/cancel): cancel, with the refund the policy allows [sensitive write]

## For businesses

A business on Tafaddal can connect its own agent to manage its bookings and availability: MCP at https://host.tafaddal.ai/mcp, with OAuth sign-in by someone on the business (scopes: manage, read). Look-ups: get_overview, list_bookings, find_booking, get_day, list_offers, list_closures [read]. Changes take two steps: a propose_ tool (propose_cancel_booking, propose_close_departure, propose_reopen_departure, propose_set_places, propose_close_dates, propose_remove_closure) returns a summary and a confirmation_id, and confirm_change makes the change [sensitive write]. Times are Doha local time.

## Conventions

- Send an Idempotency-Key header with every write; retries are safe.
- REST holds need the guest's name and an email or phone (guest_name, guest_email, guest_phone). Bookings are addressed by their reference, e.g. TF-8Q2KXM.
- Bodies can be JSON or form-encoded; responses are JSON. Errors look like {"error": {"code": "slot_unavailable", "message": "…"}}.
- Amounts are integers in minor units with an ISO 4217 currency, e.g. {"amount": 50000, "currency": "QAR"} is QAR 500.00.
- Times are ISO 8601 with an offset. Doha is UTC+3.
- Policies (cancellation windows, deposit, age or health requirements) come back with every offer and hold.
- A person approves every payment. Agents can only book what a host has published.
- Access: [read] tools change nothing; [write] tools create something reversible (a hold lapses, a payment link does nothing until paid); [sensitive write] tools commit, move or cancel a booking, so confirm with the guest first. Guests can connect with search only, which leaves out every write tool.
- Emails: guests who sign in over MCP get a confirmation, any change or cancellation, and a reminder the day before (not for bookings made less than 30 hours ahead), from bookings@tafaddal.ai. REST bookings don't email the guest; platforms keep their own customer messages. The host is emailed about every booking either way.

## Booking lifecycle

- A hold starts as held, then becomes expired, released, or confirmed (after payment or a direct confirm).
- A confirmed booking can be changed (it stays confirmed), or ends as cancelled, completed or no_show.

## Errors

slot_unavailable, hold_expired, policy_violation, payment_required, rate_limited, not_found

## Webhooks

booking.confirmed, booking.changed, booking.cancelled, booking.completed, hold.expired

## Pages

- [Home](https://tafaddal.ai/): what Tafaddal is, for hosts and developers
- [Developers](https://tafaddal.ai/developers): quickstart, tools, lifecycle, errors and webhooks
- [Privacy policy (draft)](https://tafaddal.ai/privacy)
- [Terms of service (draft)](https://tafaddal.ai/terms)

## Contact

hello@tafaddal.ai