Booking management

confirm_booking

Confirms a hold with the customer's contact details. Depending on the business's policies this sends a 6-digit verification code to the customer by WhatsApp, SMS or email, returns a payment link for a deposit, asks the business for approval, or confirms immediately.

View as Markdown

Scope & access

Directory + businessWrites data

Follow the credential fields below. Public discovery does not require a login; private booking operations require the indicated token.

This tool advertises idempotent behavior. If an idempotencyKey is specified, reuse it with identical arguments only when retrying that same intended action.

Parameters

These are the directory endpoint parameters. Business endpoints scope public discovery to the published business; owner calls still require businessId. Inspect tools/list on your endpoint for the exact schema.

holdIdRequired

string

holdId: the holdId returned by create_hold, e.g. "bkg_01j…"

customerRequired

object

customer: contact details; a phone (E.164) or email is required to send the verification code

idempotencyKeyRequired

string

idempotencyKey: a unique string you generate per intended action (e.g. a UUID); retries with the same key return the same result

Example call

Pass this object to the MCP client's callTool method. Replace placeholders with returned IDs, saved credentials and the customer's details; use future dates appropriate to their request.

confirm_booking · MCP client arguments

json

{
  "name": "confirm_booking",
  "arguments": {
    "holdId": "<holdId>",
    "customer": {
      "name": "Asha Perera",
      "email": "asha@example.com"
    },
    "idempotencyKey": "<new-UUID-for-this-action>"
  }
}

JSON schemas

Nested fields, formats, enums and constraints are included in the complete schemas. Successful data is returned in structuredContent. SDK input validation and domain errors use different error shapes.

Input schemaJSON Schema

Input JSON Schema

json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "holdId": {
      "type": "string",
      "minLength": 1,
      "description": "holdId: the holdId returned by create_hold, e.g. \"bkg_01j…\""
    },
    "customer": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120,
          "description": "name: customer full name, e.g. \"Asha Perera\""
        },
        "phone": {
          "type": "string",
          "pattern": "^\\+[1-9]\\d{6,14}$",
          "description": "phone: customer mobile number in E.164 format, e.g. \"+94771234567\""
        },
        "email": {
          "type": "string",
          "format": "email",
          "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
          "description": "email: customer email address, e.g. \"asha@example.com\""
        },
        "marketingConsent": {
          "description": "marketingConsent: true only if the customer explicitly agreed to receive offers from this business",
          "type": "boolean"
        }
      },
      "required": [
        "name"
      ],
      "description": "customer: contact details; a phone (E.164) or email is required to send the verification code"
    },
    "idempotencyKey": {
      "type": "string",
      "minLength": 8,
      "maxLength": 200,
      "description": "idempotencyKey: a unique string you generate per intended action (e.g. a UUID); retries with the same key return the same result"
    }
  },
  "required": [
    "holdId",
    "customer",
    "idempotencyKey"
  ]
}

Output schemaJSON Schema

Output JSON Schema

json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "bookingId": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "held",
        "pending_verification",
        "pending_payment",
        "pending_approval",
        "confirmed",
        "cancelled",
        "expired",
        "no_show",
        "completed"
      ]
    },
    "nextStep": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "accessToken": {
      "description": "Returned once after verification or when verification is not required. Store securely for booking management.",
      "type": "string"
    },
    "total": {
      "type": "object",
      "properties": {
        "amountMinor": {
          "type": "number"
        },
        "currency": {
          "type": "string"
        },
        "formatted": {
          "type": "string"
        }
      },
      "required": [
        "amountMinor",
        "currency",
        "formatted"
      ],
      "additionalProperties": false
    },
    "depositDue": {
      "type": "object",
      "properties": {
        "amountMinor": {
          "type": "number"
        },
        "currency": {
          "type": "string"
        },
        "formatted": {
          "type": "string"
        }
      },
      "required": [
        "amountMinor",
        "currency",
        "formatted"
      ],
      "additionalProperties": false
    },
    "paymentUrl": {
      "description": "Customer must open this URL to pay; do not collect payment credentials in chat.",
      "type": "string"
    },
    "expiresAt": {
      "type": "string"
    },
    "verification": {
      "type": "object",
      "properties": {
        "channel": {
          "type": "string"
        },
        "destination": {
          "type": "string"
        },
        "expiresAt": {
          "type": "string"
        }
      },
      "required": [
        "channel",
        "destination",
        "expiresAt"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "bookingId",
    "status",
    "nextStep",
    "message",
    "total",
    "depositDue"
  ],
  "additionalProperties": {}
}

Behavior annotationsMCP

Tool annotations

json

{
  "readOnlyHint": false,
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": true
}

Errors & next steps

Check isError before reading a success response. Follow nextStep where supplied, and never treat a pending booking as confirmed. See Errors and retries and the booking lifecycle for recovery paths.

Back to all tools