Easy!Appointments

Lists the services this business offers (length, price) and which providers offer each one. Call this first to get the service_id and provider_id that the other tools need.

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Optional words to filter services by name, for example \"massage\".",
      "type": "string"
    }
  }
}

Finds open start times for one service over a range of days, across every provider who offers it or just one. Times are in the time zone of each provider, given in the result. Use this before booking or rescheduling.

{
  "type": "object",
  "properties": {
    "service_id": {
      "description": "The service, from list_services.",
      "type": "integer"
    },
    "provider_id": {
      "description": "Optional: only this provider.",
      "type": "integer"
    },
    "date_from": {
      "description": "First day to search, YYYY-MM-DD. Defaults to today.",
      "format": "date",
      "type": "string"
    },
    "days": {
      "description": "How many days to search, 1 to 14. Default 7.",
      "default": 7,
      "minimum": 1,
      "maximum": 14,
      "type": "integer"
    },
    "part_of_day": {
      "description": "morning is before 12:00, afternoon 12:00 to 17:00, evening from 17:00.",
      "default": "any",
      "enum": [
        "any",
        "morning",
        "afternoon",
        "evening"
      ],
      "type": "string"
    }
  },
  "required": [
    "service_id"
  ]
}

Searches customers by name, email or phone and returns up to 10 matches with their customer_id. If several people match, ask which one is meant before booking.

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Part of a name, an email address or a phone number.",
      "type": "string"
    }
  },
  "required": [
    "query"
  ]
}

Lists appointments for a customer, a provider and/or a date range, earliest first. Give at least one of customer_id, provider_id or date_from. Without dates it shows the next 30 days.

{
  "type": "object",
  "properties": {
    "customer_id": {
      "description": "From find_customer.",
      "type": "integer"
    },
    "provider_id": {
      "description": "From list_services.",
      "type": "integer"
    },
    "date_from": {
      "description": "YYYY-MM-DD. Defaults to today; give an earlier date to see past visits.",
      "format": "date",
      "type": "string"
    },
    "date_to": {
      "description": "YYYY-MM-DD, inclusive. Defaults to 30 days after date_from.",
      "format": "date",
      "type": "string"
    }
  }
}

Books an appointment for an existing customer (customer_id) or a new one (new_customer). Two steps: first call without confirm to get a preview and show it to the person; only after they agree, call again with the same arguments, confirm: true, the confirmation_token from the preview and an idempotency_key. Easy!Appointments then sends its usual confirmation emails.

{
  "type": "object",
  "properties": {
    "service_id": {
      "description": "From list_services.",
      "type": "integer"
    },
    "provider_id": {
      "description": "From list_services or find_open_slots.",
      "type": "integer"
    },
    "start": {
      "description": "Start time \"YYYY-MM-DD HH:MM\" in the provider's time zone, exactly as find_open_slots returned it.",
      "pattern": "^\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}$",
      "type": "string"
    },
    "customer_id": {
      "description": "An existing customer, from find_customer. Give this or new_customer.",
      "type": "integer"
    },
    "new_customer": {
      "description": "Details for someone not yet in the system. If the email already belongs to a customer, that customer is used. Some businesses also require phone, address, city or zip_code; the preview says which are missing.",
      "properties": {
        "first_name": {
          "type": "string"
        },
        "last_name": {
          "type": "string"
        },
        "email": {
          "format": "email",
          "type": "string"
        },
        "phone": {
          "type": "string"
        },
        "address": {
          "type": "string"
        },
        "city": {
          "type": "string"
        },
        "zip_code": {
          "type": "string"
        }
      },
      "type": "object",
      "required": [
        "first_name",
        "last_name",
        "email"
      ]
    },
    "notes": {
      "description": "Optional note visible to staff.",
      "maxLength": 500,
      "type": "string"
    },
    "confirm": {
      "description": "Leave false (the default) to get a preview without changing anything. Set true only after the person has seen the preview and agreed.",
      "type": "boolean"
    },
    "confirmation_token": {
      "description": "Required when confirm is true: the confirmation_token from the preview of exactly these arguments. It expires after a few minutes; if it has, get a new preview.",
      "type": "string"
    },
    "idempotency_key": {
      "description": "Required when confirm is true. Any unique string, for example a UUID. Reusing it with the same arguments returns the first result instead of acting twice.",
      "type": "string"
    }
  },
  "required": [
    "service_id",
    "provider_id",
    "start"
  ]
}

Moves an appointment to a new start time, optionally with another provider who offers the same service. Two steps: call without confirm for a preview, then, after the person agrees, again with confirm: true, the confirmation_token from the preview and an idempotency_key. Easy!Appointments emails the customer about the change.

{
  "type": "object",
  "properties": {
    "appointment_id": {
      "description": "From list_appointments.",
      "type": "integer"
    },
    "new_start": {
      "description": "New start \"YYYY-MM-DD HH:MM\" in the time zone of the provider it moves to, from find_open_slots.",
      "pattern": "^\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}$",
      "type": "string"
    },
    "provider_id": {
      "description": "Optional: move to this provider. Defaults to the current one.",
      "type": "integer"
    },
    "confirm": {
      "description": "Leave false (the default) to get a preview without changing anything. Set true only after the person has seen the preview and agreed.",
      "type": "boolean"
    },
    "confirmation_token": {
      "description": "Required when confirm is true: the confirmation_token from the preview of exactly these arguments. It expires after a few minutes; if it has, get a new preview.",
      "type": "string"
    },
    "idempotency_key": {
      "description": "Required when confirm is true. Any unique string, for example a UUID. Reusing it with the same arguments returns the first result instead of acting twice.",
      "type": "string"
    }
  },
  "required": [
    "appointment_id",
    "new_start"
  ]
}

Cancels an upcoming appointment. Easy!Appointments deletes it and emails the customer a cancellation notice; this cannot be undone. Two steps: call without confirm for a preview, then, after the person agrees, again with confirm: true, the confirmation_token from the preview and an idempotency_key.

{
  "type": "object",
  "properties": {
    "appointment_id": {
      "description": "From list_appointments.",
      "type": "integer"
    },
    "reason": {
      "description": "Optional reason. It is kept in this server's call log; Easy!Appointments has nowhere to store it.",
      "maxLength": 300,
      "type": "string"
    },
    "confirm": {
      "description": "Leave false (the default) to get a preview without changing anything. Set true only after the person has seen the preview and agreed.",
      "type": "boolean"
    },
    "confirmation_token": {
      "description": "Required when confirm is true: the confirmation_token from the preview of exactly these arguments. It expires after a few minutes; if it has, get a new preview.",
      "type": "string"
    },
    "idempotency_key": {
      "description": "Required when confirm is true. Any unique string, for example a UUID. Reusing it with the same arguments returns the first result instead of acting twice.",
      "type": "string"
    }
  },
  "required": [
    "appointment_id"
  ]
}