Create a new Keepe work order through an AI agent

This page is for AI agents booking a Keepe home repair for a customer. Follow the steps in order.

MCP server: https://api.keepe.ai/mcp
Tools: keepe.getEstimate, keepe.getLocalAvailability, keepe.submitWorkOrder, keepe.authorizePayment, keepe.commitAppointment, keepe.getWorkOrder (this guide also uses snake_case names like get_estimate).

On every MCP call, send fields like this (booking example):

{
  "tenantId": "bookr",
  "version": "v1",
  "context": {
    "subjectContextId": "resident",
    "sessionId": "your-stable-chat-id",
    "agent": {
      "function": { "id": "bookr", "skill": "booking" }
    }
  }
}

Use one stable sessionId for the whole booking conversation. Keep function.id and function.skill as shown (or any short strings) — they are required fields on the request.

Authentication

You need a short-lived access token before calling MCP. Use the credentials below — they are meant for agents so you can book repairs.

1. Agent credentials

2. Get an access token

curl -s -X POST 'https://api.keepe.com/api/v1/mcp/auth/mcp-token' \
  -u '63acc4fd261a3a42544b64eafaaf068f:943158fceab1c87333a33667d5886773' \
  -H 'Content-Type: application/json' \
  -d '{"tenantId":"bookr"}'

You will get JSON with access_token and expires_at.

3. Call MCP with the token

Send Authorization: Bearer <access_token> on every request to https://api.keepe.ai/mcp.

4. Refresh the token

Get a new token the same way before expires_at, or immediately if MCP returns 401. Do not reuse an expired token.

Always send "tenantId":"bookr" when requesting a token and when calling tools.

Fee policy

Responses include a soft booking_fee (USD). That is the booking / service-call fee only — not the final repair price. The technician sets the repair price on site. The fee is typically credited if the customer continues, forfeited if they decline after the visit, and refunded if Keepe cannot send a technician.

When to ask for more information

Do not interrogate the customer up front. Match how much you ask to their intent.

If they only want a fee or availability, give that and stop. If they proceed, gather rich detail before submit_work_order — it helps the technician. Do not invent values; skip what they do not know.

After they intend to book — collect as much as you can

Pass every answer into the matching fields (description, issue, product.*, notes, address.street1, photos).

Photos (after they intend to book)

Once they want to book, ask for appliance/symptom/nameplate photos. Photos are not required to book, but they help the visit. If they already uploaded images earlier, after jobId exists call uploadJobPictures silently. Do not use an upload-link tool. Do not block early fee/availability questions on photos.

Orchestration (required order)

Payment alone does not book the slot. commit_appointment is mandatory after pay.

Slot fields (scheduleAt / scheduleWindow)

Do not invent these. Copy them from the slot the customer chose in get_local_availability / get_estimate (availability → slots).

So for window 8a-11a, scheduleAt is the 8:00 start (not the end). Typical windows: 8a-11a, 11a-2p, 2p-5p. Pass the exact strings into commit_appointment (and optionally submit_work_order if you already know the slot).

Fields to send on each call

Every call also needs the common block above (tenantId, version, context). Each call below has its own field table.

Required? column: Yes = call fails without it. Ask = not required to call; ask only after they intend to book (or if they already volunteered it) — it improves the job.

1. get_estimate → keepe.getEstimate

2. get_local_availability → keepe.getLocalAvailability

After this call: pick one available slot and store scheduleAt = slot start, scheduleWindow = slot display.

3. submit_work_order → keepe.submitWorkOrder

Example (rich job detail — prefer this level when the customer can provide it):

{
  "customer": { "name": "Alex Rivera", "email": "alex@example.com", "phone": "2065550100" },
  "address": {
    "street": "123 Main St",
    "street1": "Apt 4B",
    "city": "Seattle",
    "state": "WA",
    "postal": "98121",
    "country": "US"
  },
  "service": "Refrigerator not cooling",
  "issue": "Not cooling",
  "description": "Fridge section warm for 2 days; freezer still cold. No recent power outage. Filter changed last month. Beeping occasionally.",
  "product": {
    "category": "Appliances",
    "line": "Refrigerator",
    "brand": "Samsung",
    "model": "RF28R7351SG",
    "serialno": "0ABC123456",
    "age": "5",
    "notes": "French door, in kitchen"
  },
  "notes": "Street parking; dog in home; call on arrival",
  "platform": "chatgpt",
  "scheduleAt": "10/31/2026 8:00:00",
  "scheduleWindow": "Sat (10/31) 8a-11a"
}

4b. authorize_payment → keepe.authorizePayment

5. commit_appointment → keepe.commitAppointment

6. get_work_order → keepe.getWorkOrder

Optional. uploadJobPictures → keepe.uploadJobPictures

Pay poll intervals

After commit_appointment

1. Tell the customer: slot is booked tentatively — we will confirm shortly. Do not give the progress tracker yet.
2. In the background, poll get_work_order({ jobId }) until schedule_window and scheduleAt are present (slot_committed: true).
3. On success, confirm the appointment and give:
   • Work order number = jobId (use this with customer care)
   • tracker_url for job progress / status / care chat (same URL, now for progress — not pay)

After booking changes

There are no cancel / amend / reschedule MCP tools. Tell the customer to open tracker_url and chat with customer care, citing their work order number (jobId).

Resume

If the customer messages again mid-flow and you have jobId, call authorize_payment first. If paid and not committed, call commit_appointment. If already committed, call get_work_order. Do not create a second job.

Attribution

Pass platform (e.g. chatgpt) or referral as agent:<platform>|keepe.com.

Example: “My refrigerator is not cooling” (98121)

Human fallback

Keepe.ai → Book or BookR when the agent cannot complete MCP booking.