Kickserv API and MCP server

• POST

  list_customers

  Customers and contacts, searchable by name, email, phone or address.

  read

  Returns customers with their number, contact details and service address. Search matches name, email, phone and street address. Pass the customer_number to get_customer, create_job and the other tools.

  POST /api/v1/kickserv/list_customers

  Input

  Input: list_customers

  Parameter	Type	Description
  query	string	Name, email, phone or street address.
  page	integer	Page number. Default: 1.

  Example response

  {
    "customers": [
      {
        "customer_number": "2218",
        "name": "Lee Residence",
        "email": "lee@example.com",
        "phone": "555-0142",
        "service_address": "41 Maple St, Austin, TX 78701"
      }
    ],
    "page": 1
  }

• POST

  get_customer

  One customer with addresses, contacts, notes and jobs.

  read

  Returns one customer with service and billing addresses, saved contacts, special instructions, notes and the list of their jobs with status. Use it before creating a job so your agent reuses the right contact.

  POST /api/v1/kickserv/get_customer

  Input

  Input: get_customer

  Parameter	Type	Description
  customer_number required	string	Customer number from list_customers.

  Example response

  {
    "customer_number": "2218",
    "name": "Lee Residence",
    "billing_address": "41 Maple St, Austin, TX 78701",
    "contacts": [
      {
        "name": "Mrs. Lee",
        "email": "lee@example.com",
        "primary": true
      }
    ],
    "jobs": [
      {
        "job_number": "1037",
        "service_type": "Water heater replacement",
        "status": "complete"
      }
    ]
  }

• POST

  list_jobs

  Jobs with status, service type, customer, assigned techs and scheduled date.

  read

  Returns jobs 30 per page, filtered by status, scheduled date or technician. Use job_number in get_job and the write tools.

  POST /api/v1/kickserv/list_jobs

  Input

  Input: list_jobs

  Parameter	Type	Description
  status	enum	unscheduled, scheduled, in_progress, on_hold, canceled or complete.
  scheduled	enum	today, tomorrow, yesterday, this_week, next_week, last_week, this_month, next_month, last_month, this_year or last_year.
  employee	string	Only jobs assigned to this employee.
  page	integer	Page number. Default: 1.

  Example response

  {
    "jobs": [
      {
        "job_number": "1037",
        "service_type": "Water heater replacement",
        "customer": "Lee Residence",
        "status": "complete",
        "scheduled_on": "2026-10-09",
        "employees": [
          "Dana Ruiz"
        ]
      }
    ],
    "page": 1
  }

• POST

  get_job

  Full job: description, scope of work, charges, schedule events, time entries, notes and invoice status.

  read

  Returns one job or opportunity with its internal description, the customer-facing scope of work, charges with the running total, schedule events, time entries, notes and whether an invoice exists and is paid.

  POST /api/v1/kickserv/get_job

  Input

  Input: get_job

  Parameter	Type	Description
  job_number required	string	Job number from list_jobs, list_opportunities or get_job.

  Example response

  {
    "job_number": "1042",
    "service_type": "Water heater replacement",
    "customer": "Lee Residence",
    "status": "new",
    "description": "Website lead: 40 gal tank leaking",
    "scope_of_work": "Replace the 40 gallon gas water heater.",
    "charges": [],
    "total": "0.00",
    "events": [],
    "time_entries": [],
    "invoice": null
  }

• POST

  list_opportunities

  Opportunities with customer, service type and whether an estimate was sent.

  read

  Returns opportunities from the Opportunities page. A new opportunity appears under the New tab; in the app an opportunity can be marked won or lost.

  POST /api/v1/kickserv/list_opportunities

  Input

  Input: list_opportunities

  Parameter	Type	Description
  stage	enum	new, won or lost. Default: new.
  page	integer	Page number. Default: 1.

  Example response

  {
    "opportunities": [
      {
        "job_number": "1042",
        "service_type": "Water heater replacement",
        "customer": "Lee Residence",
        "stage": "new",
        "estimate_sent": false,
        "created_on": "2026-10-10"
      }
    ],
    "page": 1
  }

• POST

  list_invoices

  Invoices with customer, total, balance and whether they were sent and viewed.

  read

  Returns the invoices shown on the Invoices page, from its unpaid or paid tab. Each has a sent flag and a viewed flag, the same as the blue letter and purple eye icons in the app.

  POST /api/v1/kickserv/list_invoices

  Input

  Input: list_invoices

  Parameter	Type	Description
  tab	enum	unpaid or paid. Default: unpaid.
  page	integer	Page number. Default: 1.

  Example response

  {
    "invoices": [
      {
        "job_number": "1037",
        "customer": "Lee Residence",
        "total": "480.00",
        "balance_remaining": "480.00",
        "sent": true,
        "viewed": true
      }
    ],
    "page": 1
  }

• POST

  create_customer

  New person or company contact with service and billing address.

  write

  Creates a customer and returns its customer_number. It sends nothing to the customer and one edit in Kickserv undoes it, so it runs without asking first. Search with list_customers before creating one, to avoid duplicates.

  POST /api/v1/kickserv/create_customer

  Input

  Input: create_customer

  Parameter	Type	Description
  name required	string	Person or company name.
  is_company	boolean	Company instead of a person. Default: false.
  email	string	Customer email.
  phone	string	Phone number.
  service_address	object	street, city, state, zip_code, country.
  billing_address	object	Same fields. Default: the service address.

  Example response

  {
    "customer_number": "2219",
    "name": "Rivera Dental",
    "status": "created"
  }

• POST

  create_job

  New job, or a new opportunity to estimate first, for a customer.

  write

  Creates a job for a customer and returns its job_number. With as_opportunity set to true it creates an opportunity under the New tab instead. The description is internal and the scope of work is shown to the customer. It sends nothing to the customer, so it runs without asking first.

  POST /api/v1/kickserv/create_job

  Input

  Input: create_job

  Parameter	Type	Description
  customer_number required	string	Customer number from list_customers.
  service_type required	string	Service type as named in your account.
  description	string	Internal description, not shown to the customer.
  scope_of_work	string	Customer-facing scope of work.
  as_opportunity	boolean	Create an opportunity for an estimate instead of a job. Default: false.

  Example response

  {
    "job_number": "1051",
    "type": "opportunity",
    "stage": "new",
    "customer_number": "2218",
    "service_type": "Water heater replacement"
  }

• POST

  add_charge

  Add one charge item to the estimate or invoice of a job or opportunity.

  write

  Adds one charge line and returns the running total of the job. Call it once per line. Nothing reaches the customer until you send the estimate or invoice, so it runs without asking first.

  POST /api/v1/kickserv/add_charge

  Input

  Input: add_charge

  Parameter	Type	Description
  job_number required	string	Job number from list_jobs, list_opportunities or get_job.
  item required	string	Charge item from your account, or a new item name.
  description	string	Line description.
  quantity	string	Decimal, e.g. 1 or 2.5. Default: 1.
  price_per_unit	string	Price as a decimal, e.g. 129.00.
  taxable	boolean	Apply sales tax. Default: the item setting.

  Example response

  {
    "job_number": "1042",
    "charge": {
      "item": "Labor",
      "quantity": "2.5",
      "price_per_unit": "95.00",
      "line_total": "237.50"
    },
    "total": "886.50"
  }

• POST

  schedule_event

  Add a work event to a job, optionally assigned to a technician.

  asks first write

  Adds an event with a start time, an optional end, a task type and an optional technician. Without a technician the event stays unassigned. Depending on your reminder settings, Kickserv can send reminders for the event. By default you confirm each call; you can switch that off for this tool.

  POST /api/v1/kickserv/schedule_event

  Input

  Input: schedule_event

  Parameter	Type	Description
  job_number required	string	Job number from list_jobs, list_opportunities or get_job.
  starts_at required	datetime	ISO 8601 with time zone.
  ends_at	datetime	End of the event.
  task_type	string	Task type as named in your account, e.g. Work. Default: Work.
  employee	string	Technician to assign. Default: unassigned.
  description	string	Notes for the technician.

  Example response

  {
    "job_number": "1050",
    "event_id": "ev_3381",
    "task_type": "Work",
    "starts_at": "2026-10-15T09:00:00-05:00",
    "employee": "Dana Ruiz",
    "job_status": "scheduled"
  }

• POST

  log_time_entry

  Record hours worked on a job by an employee.

  write

  Adds a time entry to the job and returns it. Hours are a decimal. It reaches no one and an admin can delete the entry in Kickserv, so it runs without asking first.

  POST /api/v1/kickserv/log_time_entry

  Input

  Input: log_time_entry

  Parameter	Type	Description
  job_number required	string	Job number from list_jobs, list_opportunities or get_job.
  hours required	string	Number of hours as a decimal, e.g. 2.5.
  date required	date	Day the work was done.
  employee required	string	Employee name.
  billable	boolean	Billable time. Default: true.
  note	string	What was done.

  Example response

  {
    "job_number": "1049",
    "time_entry_id": "te_7702",
    "employee": "Dana Ruiz",
    "date": "2026-10-09",
    "hours": "2.5",
    "billable": true,
    "note": "Installed water heater"
  }

• POST

  send_estimate

  Email the estimate of an opportunity to the customer.

  asks first write

  Emails the estimate to the main customer of the job and copies the addresses you add. Subject and message come from your Messaging Templates unless you set them. By default you confirm each call; you can switch that off for this tool.

  POST /api/v1/kickserv/send_estimate

  Input

  Input: send_estimate

  Parameter	Type	Description
  job_number required	string	Job number from list_jobs, list_opportunities or get_job.
  to	string[]	Recipient emails. Default: the main customer of the job.
  cc	string[]	Extra emails to copy.
  subject	string	Email subject. Default: your Messaging Templates subject.
  message	string	Custom message. Default: your Messaging Templates message.
  attach_pdf	boolean	Also attach a PDF copy. Default: your Messaging Templates setting.

  Example response

  {
    "job_number": "1042",
    "status": "sent",
    "sent_to": [
      "lee@example.com"
    ],
    "cc": [
      "office@example.com"
    ],
    "total": "886.50"
  }

• POST

  generate_invoice

  Create the invoice for a job from its charges. Nothing is sent.

  write

  Creates the invoice from the charges on the job, the same as Generate Invoice in the job header, and returns its total. It sends nothing to the customer and the invoice can be edited afterwards, so it runs without asking first.

  POST /api/v1/kickserv/generate_invoice

  Input

  Input: generate_invoice

  Parameter	Type	Description
  job_number required	string	Job number from list_jobs, list_opportunities or get_job.

  Example response

  {
    "job_number": "1037",
    "invoice_status": "not_sent",
    "total": "480.00",
    "balance_remaining": "480.00"
  }

• POST

  send_invoice

  Email the invoice of a job to the customer.

  asks first write

  Emails the invoice to the main customer of the job and copies the addresses you add. The invoice then shows as sent on the Invoices page. By default you confirm each call; you can switch that off for this tool.

  POST /api/v1/kickserv/send_invoice

  Input

  Input: send_invoice

  Parameter	Type	Description
  job_number required	string	Job number from list_jobs, list_opportunities or get_job.
  to	string[]	Recipient emails. Default: the main customer of the job.
  cc	string[]	Extra emails to copy.
  subject	string	Email subject. Default: your Messaging Templates subject.
  message	string	Custom message. Default: your Messaging Templates message.
  attach_pdf	boolean	Also attach a PDF copy. Default: your Messaging Templates setting.

  Example response

  {
    "job_number": "1037",
    "invoice_status": "sent",
    "sent_to": [
      "lee@example.com"
    ],
    "total": "480.00",
    "balance_remaining": "480.00"
  }

• POST

  record_payment

  Log a manual payment (check, cash, other) on a job and mark the invoice paid. No card is charged.

  asks first write

  Logs the payment type on the job, then marks the invoice paid when mark_paid is true. Kickserv does not bring the balance to zero for manual payments on its own, so the type is recorded first. No card is charged. By default you confirm each call; you can switch that off for this tool.

  POST /api/v1/kickserv/record_payment

  Input

  Input: record_payment

  Parameter	Type	Description
  job_number required	string	Job number from list_jobs, list_opportunities or get_job.
  amount required	string	Amount as a decimal, e.g. 480.00.
  method required	string	Payment type as named in your account, e.g. Check.
  paid_on	date	Default: today.
  mark_paid	boolean	Mark the invoice paid afterwards. Default: true.

  Example response

  {
    "job_number": "1037",
    "amount": "480.00",
    "method": "Check",
    "paid_on": "2026-10-10",
    "invoice_status": "paid",
    "balance_remaining": "0.00"
  }

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.