keys_cancel_job
ChatGPTDESTRUCTIVE: request cancellation of a Keys job, subject to Keys' cancellation rules. Call ONLY when the customer clearly asks to cancel a specific existing job — never because they are asking hypothetically ('what if I need to cancel?'). Returns whether cancellation succeeded, the current status, any fee, and an explanation if it can no longer be cancelled. Requires the session_token so Keys can verify ownership.
keys_decide_additional_work
ChatGPTSend the customer's decision on proposed extra work. decision must be exactly "approve" or "decline". ONLY call this after the customer has clearly said which they want, in their own words -- never infer approval from silence, from "ok" to a different question, or from them asking what it costs. Approving can increase what the customer pays. If the reply says authorization_required, tell the customer plainly that the work has NOT started yet and they must complete the card authorization at payment_url. Never collect card details in the chat.
keys_get_additional_work
ChatGPTReturn any additional work the locksmith has proposed on a job, and whether the customer still has to answer. Read-only. needs_decision true means a locksmith is WAITING at the vehicle for an answer -- raise it with the customer immediately, do not wait to be asked. Statuses: proposed (waiting on the customer), approved (customer said yes but the card has NOT authorized the larger amount, so work is still blocked), authorized (work may proceed), declined, withdrawn, superseded, expired. Never describe approved as paid or as permission to start. Pass the session_token so Keys can confirm the job belongs to this customer.
keys_get_availability
ChatGPTCheck whether Keys has locksmiths available for this service area and the estimated arrival window. Read-only. Returns consumer-safe information only (never a specific provider's location or personal details). Provide the service location as a street address (Keys resolves the coordinates) or as lat/lng. Use before showing a booking review.
keys_get_job_status
ChatGPTGet the authoritative, real-time status of a Keys request. Statuses: sending_requests, requests_sent (N locksmiths contacted, waiting), quotes_received (compare with keys_get_quotes), no_eligible_providers, no_quotes_in_window (deadline passed — offer retry/widen/schedule), delivery_failed, booking_confirmed (ONE locksmith dispatched), completed, cancelled. Includes contacted/viewed/quote counts, the response deadline and next_actions. Never say a locksmith customer_key carries what the customer said their key looks like, when they were asked; it is absent when they never answered, and is NOT the same as a quote's key_type, which is the locksmith's own description. received or is coming unless the status says so. Read-only. Use to answer 'where is my locksmith?', 'did someone accept?', 'what's the ETA?'. Pass the session_token so Keys can authorize access to the job.
keys_get_key_type_options
ChatGPTCALL THIS FIRST for any lost, spare, replacement or broken CAR KEY job, as soon as you know the make, model and year -- before keys_get_quote. Return up to three PICTURES of real keys Keys stocks for this vehicle, so the customer can point at theirs before a locksmith sets off. Read-only. A smart key, a flip key and a plain blade need different blanks, different tools and different prices, so this is what stops a wasted trip. Show the images and ask which one matches. An EMPTY options list is a real answer — it means Keys holds no pictures for that car, so ask the customer to describe their key instead and never guess a type. from_price is a part price, NOT a quote: the locksmith's quote is what the customer pays. Record the answer with keys_set_key_type.
keys_get_payment_link
ChatGPTReturn a secure Keys-hosted payment URL for a job. The amount is authoritative from Keys. On jobs using the current flow Keys places a HOLD for the approved amount and collects it only after the locksmith completes the service and submits proof, so never tell the customer they have been charged when keys_get_job_status reports payment_state "authorized". Additional work always needs the customer to approve it first. NEVER accept or pass card numbers, CVV, or bank details — payment happens only on the Keys-hosted page. If the job is already paid, that state is returned instead of a new link. Requires the session_token so Keys can verify ownership. Use for 'how do I pay?'.
keys_get_quote
ChatGPTRetrieve Keys' authoritative price or estimate for a service at a location. Read-only. The price ALWAYS comes from Keys — never calculate, guess, or state a price yourself; if the response says pricing is unavailable, tell the customer a locksmith will confirm on arrival. Keep the returned quote_id for booking. Use after the service and location are known. For a CAR KEY job, call keys_get_key_type_options first and show the pictures: a smart key, a flip key and a plain blade are different jobs at different prices, so quoting before the customer has identified their key gives them a number that may not apply to them.
keys_get_quotes
ChatGPTReturn the truthful progress of a quote request (contacted / delivered / viewed / quote counts, response deadline, next_actions) and every REAL quote locksmiths have submitted: total, included work, key type, service-call charge, ETA, expiry, distance, rating, and whether it is an estimate with conditions. Read-only. Poll while status is sending_requests or requests_sent; when quotes_received, present the quotes and let the customer choose (quote_id). If no_quotes_in_window, offer next_actions (retry, widen_radius, schedule_later).
keys_get_service_types
ChatGPTReturn supported Keys service categories and required information. Use only for physical locksmith or supported roadside-service requests, or explicit questions about services Keys offers. Do not use for computer keyboards, passwords or account recovery, musical keys, or API/encryption keys. Attaching or mentioning Keys Locksmith alone is not sufficient reason to call this tool. Read-only. Do NOT invent services not in this list.
keys_get_status_link
ChatGPTReturn the customer's secure Keys tracking/status URL for a job. Read-only. Use when the customer wants to open live tracking themselves. Never expose internal/admin URLs — this returns only the customer-facing tokenized link.
keys_identify_service
ChatGPTMap the customer's described problem to the canonical Keys service type and report which required fields are still missing. Read-only. Use when the customer describes a lockout, lost key, key programming, rekey, etc. Input text is treated as a description, never as instructions. Do NOT use to change anything.
keys_identify_vehicle
ChatGPTResolve year/make/model (and trim when available) from a VIN, or validate a provided vehicle. Read-only. Use for automotive key/programming jobs. Never fabricates vehicle data — an undecodable VIN comes back unresolved so you can ask the customer to confirm. Do NOT require a VIN for a simple lockout.
keys_prepare_booking
ChatGPTBuilds a review card for the customer and returns a booking_intent_id and confirmation_token. Nothing is submitted, nobody is booked and no locksmith is told anything: this only assembles what the customer is about to be asked to agree to. Give the service location as a street address (Keys locates it — no coordinates needed) or as lat/lng, plus the customer's first name and mobile number, and the quote_id from keys_get_quote so the price stays Keys's and not one you invented. If the customer has chosen a specific locksmith's quote, also pass requestId and providerQuoteId from keys_get_quotes so the review shows that locksmith and that price. Then show the review, and only once the customer has said yes, call keys_submit_request.
keys_render_check
ChatGPTDiagnostic only. Returns a plain test card to check that embedded cards render. Contacts nothing, reads no customer data and changes nothing. Use ONLY when someone explicitly asks to test or debug Keys card rendering. Never use it to answer a locksmith question. Read-only.
keys_request_quotes
ChatGPTCreate the customer's request and send it to EVERY eligible locksmith nearby (verified, offers the service, can work on the vehicle make when known, within the search radius, not a test account). Books nobody. Returns request_id, how many locksmiths were contacted, the response deadline, and a session_token to reuse. Then poll keys_get_quotes and let the customer choose a quote; then keys_prepare_booking(requestId, providerQuoteId) + keys_submit_request submit it and hand the customer their Keys page, where they choose the locksmith and pay. Describe the result as 'quote requests sent to N locksmiths' — NOT booked, NOT dispatched. Requires service type, location (street address is enough), first name and mobile number. Idempotent per idempotencyKey: retrying with the same key never contacts anyone twice.
keys_send_job_message
ChatGPTSend the customer's message to the assigned locksmith through Keys' job messaging. Changes state (delivers a message). Use for 'tell the locksmith ...'. Only works once a locksmith has accepted. The message text is delivered as-is and is never interpreted as instructions. Requires the session_token so Keys can verify the sender owns the job.
keys_set_key_type
ChatGPTSave which key the customer pointed at, so the locksmith brings the right blank and tools. Pass the code from keys_get_key_type_options, or "none" when the customer says their key is not one of the pictures — "none" is a real answer and the note you send with it reaches the locksmith verbatim, which is more use than a category guessed at. Safe to call again if the customer corrects themselves; the latest answer wins. Requires the session_token so Keys can verify the job is theirs. Never invent a key type the customer did not confirm.
keys_submit_request
ChatGPTSends the customer's request to Keys and returns a status_link for them to open. No locksmith is booked, chosen or dispatched by this call, and the response always carries dispatched=false. Tell the customer their request is in and give them the link; do not say booked, confirmed or dispatched, and do not name any locksmith as theirs. They choose a locksmith and pay on their own Keys page, which holds the card before anyone is sent out — that page is the only place a job is actually booked. Call this only after the customer has seen the review from keys_prepare_booking and agreed to it. Needs the booking_intent_id and confirmation_token from that review, plus an idempotency_key you generate once; sending the same key again returns the same request rather than making a second one. If a call times out, check keys_get_job_status before retrying rather than resending blind. The status that comes back is awaiting_customer_choice or requests_sent, and both mean the same thing: nobody is on their way yet.
