Add leads to Kickserv as opportunities

1. Search Customers for the caller by name or phone first, because the New Opportunity form either picks a saved contact or creates a new one with Create a New Contact.
2. Select Add New in the navigation bar, then Opportunity, or open Jobs > Opportunities and select Add Opportunity.
3. Pick a service, write the internal-only description, then the customer-facing scope of work.
4. Select a contact from your customer records, or choose Create a New Contact, then select Create Opportunity.
5. Each lead takes a search and two forms, and a lead read at 10 p.m. often waits until morning, when the customer may have booked someone else.

Three lead emails came in overnight from the website and the ads form. Add each one to Kickserv as an opportunity, reuse the customer if we already have them, and tell me which service type you picked.

1. 01

   Read the lead into fields

   Your agent pulls name, phone, email, service address and the request out of each message. A lead with no phone and no email is not added; it goes back to you, since Kickserv could never send that person an estimate.

2. 02

   Look for the customer before creating one

   It searches list_customers by phone, then email, then street address. On a match it opens get_customer and reads the job list, so a lead from someone with an opportunity already open for the same service is reported as a repeat instead of becoming a second opportunity.

3. 03

   Stop on a new address for a known customer

   When a known customer asks for work at a different address, for example a landlord with a second rental, the agent asks whether that is a new service location. Kickserv wants service locations under a parent record with a unique company name, so it does not guess.

4. 04

   Create the customer and the opportunity

   For a new person it calls create_customer with the service address and lets billing default to it. Then create_job with as_opportunity opens the opportunity under the service type from your account that matches the request; when nothing matches, the agent asks rather than adding a new service type.

5. 05

   Keep the raw lead inside, not on the estimate

   The original message and its source go in the internal description. The scope of work gets one plain sentence, because Kickserv shows the scope of work to the customer.

Leads read: 3
New customer and opportunity: Priya Nair, 18 Cedar Ct, Water heater replacement, opportunity 1063
Existing customer, new opportunity: Lee Residence, Drain cleaning, opportunity 1064
Repeat lead, not added: Tom Becker already has opportunity 1058 (AC tune-up) under New
Needs you: Becker asks for a second address, 77 Ridge Rd. Add it as a service location?

• Kickserv keeps a new opportunity under the New tab of the Opportunities page until an estimate event is scheduled or an estimate is sent.
• Kickserv keeps the job description internal to your team, while the scope of work is the external field the customer sees.
• A Kickserv service location must have a unique company name and is linked to a parent customer, with billing set to the parent, the service address or a new address.
• Kickserv staff users need the Contacts permission (create/modify) to add customers; viewing contacts and jobs cannot be turned off for any user.
• Kickserv Customer Sources under Settings record where customers come from and can be offered as a choice on the Kickserv Contact Form.

create_customer and create_job change only your own Kickserv data and reach no one else, so they run without asking first.

Sources: Kickserv help: Opportunities · Kickserv help: Customers and Contacts · Kickserv help: Settings · Kickserv blog: Contact Form creates unscheduled opportunities

curl https://cotlet.dev/api/v1/kickserv/create_job \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customer_number":"2231","service_type":"Water heater replacement","description":"Lead from website form, 11:40 p.m.: 40 gal tank leaking in garage","scope_of_work":"Inspect and replace the 40 gallon gas water heater.","as_opportunity":true}'

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

MCP: add https://cotlet.dev/mcp/v1 with the same key; the tool is kickserv_create_job. Example data.

• Build and send Kickserv estimates from your notes
• Invoice completed Kickserv jobs and email the invoices
• Log check and cash payments on Kickserv invoices
• Kickserv API and MCP server: every tool
• All use cases