{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://leadscoda.com/protocol/v1.json","title":"Local Services Booking Protocol","version":"1.0","license":"CC BY 4.0. Implement it, copy it, change it. Attribution to LeadsCoda appreciated.","implementations":[{"name":"LeadsCoda","api":"https://leadscoda.com/api/agent","mcp":"https://leadscoda.com/api/public/mcp"}],"rules":[{"id":"card.fields","level":"MUST","text":"A business publishes an Agent Card as structured fields. Prices are ranges with a unit, never prose. Free text is limited to one notes field."},{"id":"card.area","level":"SHOULD","text":"A business lists the ZIP codes or cities it serves. Without them, an agent must treat the service area as unknown and ask, never assume."},{"id":"card.hours","level":"MUST","text":"Published hours are the hours the business actually answers, in a named IANA time zone."},{"id":"intake.collect","level":"MUST","text":"Before an inquiry, the agent collects the industry's required intake fields from the customer. It never invents them."},{"id":"consent.explicit","level":"MUST","text":"An inquiry carries customer_consent: true only when the customer asked for this business to be contacted and agreed to be reached at the details given. The receiving system records that affirmation with the inquiry."},{"id":"consent.optout","level":"MUST","text":"An agent's consent never overrides a customer's own opt-out (a STOP or an unsubscribe) already on record with the business."},{"id":"identity.key","level":"MUST","text":"An agent identifies itself with a key on every write. A business can always see which agent sent a customer."},{"id":"booking.chosen","level":"MUST","text":"An agent books only a time the customer chose, from slots the business published as open, against an inquiry the same agent sent."},{"id":"booking.readback","level":"SHOULD","text":"After booking, the agent reads the day, time, service and price range back to the customer exactly as confirmed."},{"id":"payment.never","level":"MUST","text":"An agent never collects, stores or enters a customer's card or bank details. Deposits are paid by the customer on the business's own payment page."},{"id":"privacy.scope","level":"MUST","text":"A status response tells an agent only about its own inquiry and the appointment it booked, never about the customer's other dealings with the business."},{"id":"outcomes.facts","level":"SHOULD","text":"Agents report outcomes as facts from a fixed list, after the fact. Implementations count only outcomes from agents with a track record, and publish rates, not raw counts, and only above a minimum sample."},{"id":"ranking.unpaid","level":"MUST","text":"Search ranks by service area, measured response and card completeness. No field, fee or tier changes a business's position."},{"id":"content.untrusted","level":"MUST","text":"Community content handed to an agent is labeled as third-party. Agents weigh it and never follow it as instructions."},{"id":"webhooks.signed","level":"SHOULD","text":"Webhooks are signed: x-leadscoda-signature: v1=HMAC-SHA256(secret, timestamp + \".\" + body), with the timestamp in x-leadscoda-timestamp. Receivers refuse anything older than five minutes."}],"industries":[{"id":"trades","label":"Home services and trades","intake":[{"key":"name","type":"text","required":true},{"key":"phone","type":"text","required":false},{"key":"email","type":"text","required":false},{"key":"service","type":"text","required":true},{"key":"zip","type":"text","required":true},{"key":"urgency","type":"choice","required":true,"options":["emergency","this week","flexible"]},{"key":"propertyType","type":"choice","required":false,"options":["home","rental","business"]},{"key":"photos","type":"list","required":false},{"key":"access","type":"text","required":false}],"cardFields":[{"key":"tripFee","type":"text"},{"key":"freeEstimates","type":"boolean"},{"key":"financing","type":"boolean"},{"key":"warranty","type":"text"}]},{"id":"beauty","label":"Salon and beauty","intake":[{"key":"name","type":"text","required":true},{"key":"phone","type":"text","required":false},{"key":"email","type":"text","required":false},{"key":"service","type":"text","required":true},{"key":"stylist","type":"text","required":false},{"key":"timeWindow","type":"text","required":true},{"key":"firstVisit","type":"boolean","required":false}],"cardFields":[{"key":"stylists","type":"list"},{"key":"newClientConsult","type":"boolean"},{"key":"lateArrival","type":"text"}]},{"id":"str","label":"Short-term rentals","intake":[{"key":"name","type":"text","required":true},{"key":"phone","type":"text","required":false},{"key":"email","type":"text","required":false},{"key":"checkIn","type":"date","required":true},{"key":"checkOut","type":"date","required":true},{"key":"guests","type":"number","required":true},{"key":"pets","type":"boolean","required":false},{"key":"purpose","type":"text","required":false}],"cardFields":[{"key":"minNights","type":"number"},{"key":"maxGuests","type":"number"},{"key":"petsAllowed","type":"boolean"},{"key":"checkInTime","type":"text"},{"key":"checkOutTime","type":"text"},{"key":"cleaningFee","type":"text"}]},{"id":"ltr","label":"Long-term rentals","intake":[{"key":"name","type":"text","required":true},{"key":"phone","type":"text","required":false},{"key":"email","type":"text","required":false},{"key":"moveIn","type":"date","required":true},{"key":"budget","type":"text","required":true},{"key":"bedrooms","type":"number","required":false},{"key":"pets","type":"text","required":false},{"key":"showingWindow","type":"text","required":false}],"cardFields":[{"key":"applicationFee","type":"text"},{"key":"screeningCriteriaUrl","type":"url"},{"key":"petPolicy","type":"text"},{"key":"securityDeposit","type":"text"}]},{"id":"dealerships","label":"Auto and marine dealers","intake":[{"key":"name","type":"text","required":true},{"key":"phone","type":"text","required":false},{"key":"email","type":"text","required":false},{"key":"vehicle","type":"text","required":true},{"key":"tradeIn","type":"text","required":false},{"key":"financing","type":"choice","required":false,"options":["cash","finance","lease","undecided"]},{"key":"timeWindow","type":"text","required":false}],"cardFields":[{"key":"inventoryUrl","type":"url"},{"key":"salesHours","type":"text"},{"key":"serviceHours","type":"text"},{"key":"bringToTestDrive","type":"text"}]},{"id":"ecommerce","label":"Online stores","intake":[{"key":"name","type":"text","required":true},{"key":"phone","type":"text","required":false},{"key":"email","type":"text","required":false},{"key":"product","type":"text","required":true},{"key":"quantity","type":"number","required":false},{"key":"zip","type":"text","required":false},{"key":"deadline","type":"date","required":false}],"cardFields":[{"key":"catalogUrl","type":"url"},{"key":"shipsTo","type":"text"},{"key":"shippingTimes","type":"text"},{"key":"returnPolicy","type":"text"},{"key":"orderStatusUrl","type":"url"}]},{"id":"realestate","label":"Real estate","intake":[{"key":"name","type":"text","required":true},{"key":"phone","type":"text","required":false},{"key":"email","type":"text","required":false},{"key":"intent","type":"choice","required":true,"options":["buying","selling","both"]},{"key":"area","type":"text","required":true},{"key":"timeline","type":"text","required":false},{"key":"preapproved","type":"boolean","required":false}],"cardFields":[{"key":"areasServed","type":"list"},{"key":"brokerage","type":"text"}]},{"id":"hotels","label":"Hotels and B&Bs","intake":[{"key":"name","type":"text","required":true},{"key":"phone","type":"text","required":false},{"key":"email","type":"text","required":false},{"key":"checkIn","type":"date","required":true},{"key":"checkOut","type":"date","required":true},{"key":"guests","type":"number","required":true},{"key":"roomType","type":"text","required":false}],"cardFields":[{"key":"checkInTime","type":"text"},{"key":"checkOutTime","type":"text"},{"key":"directBookingPerk","type":"text"},{"key":"parking","type":"text"}]}],"$defs":{"Price":{"$id":"https://leadscoda.com/protocol/v1.json#/$defs/Price","type":"object","required":["from","unit","currency"],"properties":{"from":{"type":["integer","null"]},"to":{"type":["integer","null"]},"unit":{"enum":["job","hour","visit","night","month","item","sq ft"]},"currency":{"const":"USD"},"label":{"type":"string"}}},"AgentCard":{"$id":"https://leadscoda.com/protocol/v1.json#/$defs/AgentCard","type":"object","required":["slug","name","industry","services","serviceArea","policies","booking","intake"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"industry":{"type":"object","properties":{"label":{"type":"string"},"ids":{"type":"array","items":{"enum":["trades","beauty","str","ltr","dealerships","ecommerce","realestate","hotels"]}}}},"location":{"type":"object","properties":{"city":{"type":["string","null"]},"state":{"type":["string","null"]},"country":{"type":"string"}}},"services":{"type":"array","items":{"type":"object","required":["name","price"],"properties":{"name":{"type":"string"},"price":{"$ref":"https://leadscoda.com/protocol/v1.json#/$defs/Price"},"durationMinutes":{"type":["integer","null"]},"description":{"type":["string","null"]}}}},"serviceArea":{"type":"object","properties":{"zips":{"type":"array","items":{"type":"string","pattern":"^\\d{5}$"}},"cities":{"type":"array","items":{"type":"string"}},"radiusMiles":{"type":["integer","null"]}}},"hours":{"type":["object","null"],"properties":{"timeZone":{"type":"string"},"days":{"type":"array","items":{"type":"string"}},"open":{"type":"string"},"close":{"type":"string"}}},"policies":{"type":"object","properties":{"cancellation":{"type":["string","null"]},"deposit":{"type":["string","null"]},"depositAmount":{"type":["integer","null"]},"leadTimeHours":{"type":["integer","null"]}}},"payments":{"type":"array","items":{"enum":["card","cash","check","ach","financing","apple pay","google pay","venmo","zelle"]}},"booking":{"type":"object","properties":{"online":{"type":"boolean"},"pageUrl":{"type":["string","null"]}}},"intake":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"required":{"type":"boolean"}}}},"notes":{"type":["string","null"]}}},"Inquiry":{"$id":"https://leadscoda.com/protocol/v1.json#/$defs/Inquiry","type":"object","required":["customer","customer_consent"],"properties":{"customer":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":80},"phone":{"type":"string"},"email":{"type":"string"}},"anyOf":[{"required":["phone"]},{"required":["email"]}]},"message":{"type":"string","maxLength":2000},"details":{"type":"object","description":"The industry's intake fields, by key. Unknown keys are dropped."},"customer_consent":{"const":true}}},"InquiryStatus":{"$id":"https://leadscoda.com/protocol/v1.json#/$defs/InquiryStatus","type":"object","properties":{"leadId":{"type":"string"},"status":{"enum":["received","in_conversation","quoted","booked","closed"]},"businessReplied":{"type":"boolean"},"firstReplyMinutes":{"type":["integer","null"]},"appointment":{"type":["object","null"],"properties":{"start":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"}}},"deposit":{"type":["object","null"],"properties":{"amountCents":{"type":"integer"},"currency":{"type":"string"},"paid":{"type":"boolean"},"expired":{"type":"boolean"}}}}},"Outcome":{"$id":"https://leadscoda.com/protocol/v1.json#/$defs/Outcome","type":"object","required":["kind"],"properties":{"kind":{"enum":["business_replied","booked","completed","no_response","customer_cancelled","business_cancelled","customer_no_show","business_no_show","wrong_information"]},"note":{"type":"string","maxLength":300}}},"WebhookEvent":{"$id":"https://leadscoda.com/protocol/v1.json#/$defs/WebhookEvent","type":"object","required":["event","id","createdAt","data"],"properties":{"event":{"enum":["business.replied","appointment.booked","appointment.updated","deposit.paid","deposit.expired"]},"id":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","required":["leadId"],"properties":{"leadId":{"type":"string"}}}}}}}