Fresha API and MCP server

• POST

  list_appointments

  Appointments in a date range, with client, services, team member and status.

  read

  Lists appointments for the dates you give, ordered by start time. Each one has its client, services, team member and status. Statuses are Booked, Confirmed, Completed, Cancelled and No-show, plus any custom statuses your business created in Settings; custom ones come back under their own name. Pass appointment_id from an item to reschedule_appointment or cancel_appointment. Pass next_cursor back as cursor for the next page.

  POST /api/v1/fresha/list_appointments

  Input

  Input: list_appointments

  Parameter	Type	Description
  from required	date	First day.
  to	date	Last day. Default: same as from.
  status	string	booked, confirmed, completed, cancelled or no_show, or the name of a custom status. Default: all.
  team_member_id	string	Only this team member.
  client_id	string	Only this client.
  location_id	string	Only this location. Default: all locations.
  cursor	string	Next page cursor from the previous call.

  Example response

  {
    "appointments": [
      {
        "appointment_id": "ap_90311301",
        "client": {
          "client_id": "cl_48213977",
          "name": "Anna Smith"
        },
        "start_at": "2026-10-15T10:00:00+01:00",
        "end_at": "2026-10-15T10:45:00+01:00",
        "services": [
          "Haircut"
        ],
        "team_member": {
          "team_member_id": "tm_5521",
          "name": "Sam"
        },
        "status": "Booked",
        "location_id": "loc_201"
      }
    ],
    "next_cursor": null
  }

• POST

  find_available_slots

  Free start times on one day for one or more services, for anyone or one team member.

  read

  Returns the free start times on one day for the services you list, booked back to back in that order. Each slot names the team member who is free. Pass start_at from a slot to create_appointment or reschedule_appointment. The search covers one day per call.

  POST /api/v1/fresha/find_available_slots

  Input

  Input: find_available_slots

  Parameter	Type	Description
  service_ids required	string[]	Services from list_services, booked in this order.
  date required	date	Day to search.
  team_member_id	string	Only this team member. Default: anyone.
  location_id	string	Only this location. Default: all locations.

  Example response

  {
    "date": "2026-10-16",
    "slots": [
      {
        "start_at": "2026-10-16T14:30:00+01:00",
        "end_at": "2026-10-16T15:15:00+01:00",
        "team_member_id": "tm_5521",
        "team_member": "Sam"
      },
      {
        "start_at": "2026-10-16T16:00:00+01:00",
        "end_at": "2026-10-16T16:45:00+01:00",
        "team_member_id": "tm_5521",
        "team_member": "Sam"
      }
    ]
  }

• POST

  list_clients

  Your client list with contact details, last appointment and marketing consent.

  read

  Lists clients, A to Z, with contact details, their last appointment date and marketing consent. The last appointment ignores cancelled and no-show bookings, the same as Fresha's Client insights report. Use last_appointment_before to find clients who have not been in since a date. Card details are never returned. Pages hold up to 500 clients; pass next_cursor back as cursor.

  POST /api/v1/fresha/list_clients

  Input

  Input: list_clients

  Parameter	Type	Description
  search	string	Name, email or phone.
  last_appointment_before	date	Only clients whose last appointment was before this date.
  location_id	string	Only this location. Default: all locations.
  limit	integer	1 to 500. Default: 100.
  cursor	string	Next page cursor from the previous call.

  Example response

  {
    "clients": [
      {
        "client_id": "cl_48213977",
        "name": "Anna Smith",
        "email": "anna@example.com",
        "phone": "+44 7700 900123",
        "last_appointment": "2026-06-20",
        "accepts_marketing": true,
        "accepts_sms_marketing": false
      }
    ],
    "next_cursor": "eyJvZmZzZXQiOjEwMH0"
  }

• POST

  get_client

  Client profile: details, notes, allergies, and upcoming and past appointments.

  read

  Returns one client's profile: contact details, the notes your team saved, allergies, and upcoming and past appointments, newest first. Notes are visible only to your team. Use it before booking or writing to a client.

  POST /api/v1/fresha/get_client

  Input

  Input: get_client

  Parameter	Type	Description
  client_id required	string	Client ID from list_clients.

  Example response

  {
    "client_id": "cl_48213977",
    "name": "Anna Smith",
    "phone": "+44 7700 900123",
    "notes": [
      {
        "text": "Prefers a warm toner, no fragrance.",
        "created_at": "2026-05-14T11:02:00+01:00"
      }
    ],
    "allergies": [],
    "upcoming_appointments": [
      {
        "appointment_id": "ap_90311245",
        "start_at": "2026-10-16T14:30:00+01:00",
        "services": [
          "Haircut"
        ]
      }
    ],
    "past_appointments": [
      {
        "appointment_id": "ap_88120411",
        "start_at": "2026-06-20T11:00:00+01:00",
        "services": [
          "Colour"
        ],
        "status": "Completed"
      }
    ]
  }

• POST

  list_services

  Your service menu with categories, durations and prices.

  read

  Returns your service menu grouped by category, with duration and price for each service. Prices are in your business currency. Use service_id from an item in find_available_slots and create_appointment.

  POST /api/v1/fresha/list_services

  Input

  Input: list_services

  Parameter	Type	Description
  location_id	string	Only this location. Default: all locations.

  Example response

  {
    "services": [
      {
        "service_id": "sv_1203",
        "name": "Haircut",
        "category": "Hair",
        "duration_minutes": 45,
        "price": "45.00",
        "currency": "GBP"
      },
      {
        "service_id": "sv_1288",
        "name": "Colour",
        "category": "Hair",
        "duration_minutes": 90,
        "price": "85.00",
        "currency": "GBP"
      }
    ]
  }

• POST

  list_team_members

  Bookable team members with their locations and services.

  read

  Lists the team members who can be booked, with their locations and the services each one offers. Use team_member_id from an item to filter list_appointments or to book with a specific person.

  POST /api/v1/fresha/list_team_members

  Input

  Input: list_team_members

  Parameter	Type	Description
  location_id	string	Only this location. Default: all locations.

  Example response

  {
    "team_members": [
      {
        "team_member_id": "tm_5521",
        "name": "Sam",
        "locations": [
          "loc_201"
        ],
        "service_ids": [
          "sv_1203",
          "sv_1288"
        ]
      }
    ]
  }

• POST

  get_sales_summary

  Sales, discounts and refunds from the Sales summary report, for a date range.

  read

  Returns the Sales summary report for the dates you give: items sold, sales, discounts and refunds. Set group_by to split the totals by payment method, discount name or discount type. Tips and service charges are not in this report, because it is built from sale items. Amounts are in your business currency.

  POST /api/v1/fresha/get_sales_summary

  Input

  Input: get_sales_summary

  Parameter	Type	Description
  from required	date	First day.
  to	date	Last day. Default: same as from.
  group_by	enum	payment_method, discount_name or discount_type. Default: no grouping.
  location_id	string	Only this location. Default: all locations.

  Example response

  {
    "from": "2026-10-10",
    "to": "2026-10-10",
    "currency": "GBP",
    "groups": [
      {
        "payment_method": "Card",
        "items_sold": 18,
        "sales": "742.00",
        "discounts": "30.00",
        "refunds": "0.00"
      },
      {
        "payment_method": "Cash",
        "items_sold": 7,
        "sales": "266.00",
        "discounts": "10.00",
        "refunds": "45.00"
      }
    ],
    "total": {
      "items_sold": 25,
      "sales": "1008.00",
      "discounts": "40.00",
      "refunds": "45.00"
    }
  }

• POST

  list_payouts

  Payouts from your business wallet to your bank, with dates, amounts and fees.

  read

  Lists transfers from your business wallet to your bank, newest first. Each has its date, amount, the fees Fresha deducted and the net amount. Scheduled and manual payouts are both included. It works only when Fresha Payments is on, and the account needs the Wallet and card processing permission.

  POST /api/v1/fresha/list_payouts

  Input

  Input: list_payouts

  Parameter	Type	Description
  from	date	Start of the period. Default: 30 days ago.
  to	date	End of the period. Default: today.
  cursor	string	Next page cursor from the previous call.

  Example response

  {
    "payouts": [
      {
        "payout_id": "po_77120",
        "type": "scheduled",
        "date": "2026-09-29",
        "amount": "840.00",
        "fees": "12.60",
        "net": "827.40",
        "currency": "GBP"
      },
      {
        "payout_id": "po_76988",
        "type": "manual",
        "date": "2026-09-22",
        "amount": "300.00",
        "fees": "0.50",
        "net": "299.50",
        "currency": "GBP"
      }
    ],
    "next_cursor": null
  }

• POST

  create_appointment

  Book one or more services for a client at a given time.

  asks first write

  Books the services you list for a client, back to back, from start_at. The appointment starts as Booked. Without team_member_id it goes to the first team member who is free. Check the time with find_available_slots first; a time that is taken fails. The booking can reach the client. By default you confirm each call; you can switch that off for this tool.

  POST /api/v1/fresha/create_appointment

  Input

  Input: create_appointment

  Parameter	Type	Description
  client_id required	string	Client ID from list_clients.
  start_at required	datetime	ISO 8601 with time zone.
  service_ids required	string[]	Services from list_services, in order.
  team_member_id	string	Team member. Default: first available.
  location_id	string	Only this location. Default: all locations.
  note	string	Appointment note for your team.

  Example response

  {
    "appointment_id": "ap_90311245",
    "status": "Booked",
    "start_at": "2026-10-16T14:30:00+01:00",
    "end_at": "2026-10-16T15:15:00+01:00",
    "services": [
      {
        "service_id": "sv_1203",
        "name": "Haircut",
        "price": "45.00",
        "currency": "GBP"
      }
    ],
    "team_member": "Sam"
  }

• POST

  reschedule_appointment

  Move an appointment to a new time, and optionally to another team member.

  asks first write

  Moves one appointment to a new start time, keeping its services. Set team_member_id to hand it to someone else. Check the new time with find_available_slots first. The move can reach the client. By default you confirm each call; you can switch that off for this tool.

  POST /api/v1/fresha/reschedule_appointment

  Input

  Input: reschedule_appointment

  Parameter	Type	Description
  appointment_id required	string	Appointment ID from list_appointments.
  start_at required	datetime	New start, ISO 8601 with time zone.
  team_member_id	string	New team member. Default: unchanged.

  Example response

  {
    "appointment_id": "ap_90311301",
    "status": "Booked",
    "start_at": "2026-10-16T10:00:00+01:00",
    "end_at": "2026-10-16T10:45:00+01:00",
    "team_member": "Sam"
  }

• POST

  cancel_appointment

  Cancel a current or future appointment with one of your cancellation reasons.

  asks first write

  Cancels one appointment. Fresha only cancels appointments that start in the future, so a past one fails; mark it as a no-show in the app instead. The reason must be one of the cancellation reasons you manage in Fresha. Your payment policy for the appointment applies as it does in the app. For a repeating series, scope picks this appointment or the whole series. By default you confirm each call; you can switch that off for this tool.

  POST /api/v1/fresha/cancel_appointment

  Input

  Input: cancel_appointment

  Parameter	Type	Description
  appointment_id required	string	Appointment ID from list_appointments.
  reason required	string	Name of one of your cancellation reasons.
  notify_client	boolean	Send the client a cancellation message. Default: true.
  scope	enum	this_appointment or whole_series, for repeating appointments. Default: this_appointment.

  Example response

  {
    "appointment_id": "ap_90311245",
    "status": "Cancelled",
    "reason": "Team member unwell",
    "scope": "this_appointment",
    "client_notified": true
  }

• POST

  add_client

  Create a client profile. Nothing is sent to the client.

  write

  Creates a client profile and returns its client_id, which you pass to create_appointment. It sends nothing to the client and reaches no one, so it runs without asking first. Search with list_clients first to avoid a duplicate profile.

  POST /api/v1/fresha/add_client

  Input

  Input: add_client

  Parameter	Type	Description
  first_name required	string	First name.
  last_name	string	Last name.
  email	string	Email.
  phone	string	Mobile number with country code.

  Example response

  {
    "client_id": "cl_48213990",
    "name": "Maya Patel",
    "phone": "+44 7700 900456"
  }

• POST

  add_client_note

  Save a note on a client profile, such as a color formula or preference.

  write

  Adds a simple note to a client profile. Notes are private: only your team sees them, never the client. Fresha cannot recover a deleted note, so the agent adds notes and never deletes them. It reaches no one, so it runs without asking first.

  POST /api/v1/fresha/add_client_note

  Input

  Input: add_client_note

  Parameter	Type	Description
  client_id required	string	Client ID from list_clients.
  text required	string	Note text.

  Example response

  {
    "client_id": "cl_48213977",
    "note_id": "nt_5521",
    "created_at": "2026-10-11T09:12:00+01:00"
  }

• POST

  add_blocked_time

  Block time in a team member's calendar for a break, training or admin.

  write

  Blocks a time range in one team member's calendar, so no one can book it. Use title for a reason such as one of your blocked time types, and description for a note your team sees. It reaches no client and is removed in Fresha in one step, so it runs without asking first.

  POST /api/v1/fresha/add_blocked_time

  Input

  Input: add_blocked_time

  Parameter	Type	Description
  team_member_id required	string	Team member from list_team_members.
  start_at required	datetime	ISO 8601 with time zone.
  end_at required	datetime	ISO 8601 with time zone.
  title	string	Reason, e.g. one of your blocked time types.
  description	string	Note your team sees on the block.

  Example response

  {
    "blocked_time_id": "bt_3302",
    "team_member": "Sam",
    "start_at": "2026-10-14T13:00:00+01:00",
    "end_at": "2026-10-14T14:00:00+01:00",
    "title": "Training"
  }

Each successful call uses credits for the work it takes; failed calls and timeouts cost nothing. A hard spend cap is on by default. Authenticate with the Authorization: Bearer header.