Keys Locksmith

Return the locksmith service categories Keys supports and the information each needs. Read-only; changes nothing. Use at the start to ground the conversation in real Keys services rather than guessing. Do NOT invent services not in this list.

keys_get_service_types

Send 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_send_job_message

Builds 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, so it is always safe to call. 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_prepare_booking

Send 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_decide_additional_work

Save 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_set_key_type

Create 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_request_quotes

CALL 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_key_type_options

Sends 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.

keys_submit_request