{"openapi":"3.1.0","info":{"title":"ALCBar Matching API","version":"1.0.0 (match-2026.10.15)","description":"The Right Lawyer. The Right Time. The Right Price. Lawyer matching, pricing information, availability and consent-based introductions. ALCBar does not give legal advice.","contact":{"email":"support@alcbar.com"}},"servers":[{"url":"https://match.alcbar.com"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"API key issued by ALCBar (alc_...)"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}},"request_id":{"type":"string"}}}}},"paths":{"/v1/matches":{"post":{"operationId":"find_attorneys","summary":"Find and rank lawyers (also POST /v1/attorneys/search).","description":"Find licensed lawyers for a matter and rank them by practice-area fit, location, years licensed, timing, price and preferences, with plain-language reasons, data sources and gaps. Returns up to 5 by default, or an honest no-match. Not legal advice.","security":[{"bearer":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"description":{"description":"Short description of the legal need in the user's words. Used only to pick a practice area; not stored.","type":"string","maxLength":2000},"practice_area":{"description":"Practice area, e.g. 'Landlord-Tenant Law', 'Family Law', 'Criminal Law'","type":"string","maxLength":80},"subpractice_area":{"type":"string","maxLength":80},"matter_type":{"type":"string","maxLength":80},"category":{"type":"string","enum":["civil","criminal","administrative","transactional","family","other"]},"procedural_stage":{"type":"string","enum":["not_started","pre_filing","filed","hearing_scheduled","trial","post_judgment","appeal","transaction","unknown"]},"client_side":{"description":"Which side the user is on. ALCBar has no record of which side lawyers usually represent, so results carry a warning to ask.","type":"string","enum":["tenant","landlord","employee","employer","plaintiff","defendant","buyer","seller","other","unknown"]},"service_needed":{"type":"string","enum":["advice_consultation","negotiation","document_preparation","litigation","ongoing_representation","unknown"]},"state":{"type":"string","minLength":2,"maxLength":40,"description":"US state, two-letter code or name, e.g. CA or California"},"county":{"type":"string","maxLength":80},"city":{"type":"string","maxLength":80},"zip":{"description":"5-digit ZIP code, only if the user agreed to share it","type":"string","pattern":"^\\d{5}$"},"court":{"type":"string","maxLength":120},"remote_ok":{"description":"User is willing to work with a lawyer remotely (phone or video) anywhere in the state","type":"boolean"},"urgency":{"type":"string","enum":["emergency","critical_deadline","soon","routine","long_term"]},"deadline_date":{"description":"A deadline the USER reported (hearing, filing, response). ALCBar does not verify or calculate deadlines.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"deadline_type":{"type":"string","enum":["hearing","filing","response","other"]},"consultation_by":{"description":"Latest date the user wants a first consultation","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"representation_start_by":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Date as YYYY-MM-DD"},"budget_max":{"description":"Total budget the user mentioned, in US dollars","type":"number","minimum":0,"maximum":10000000},"budget_min":{"type":"number","minimum":0,"maximum":10000000},"billing_preference":{"type":"string","enum":["hourly","flat_fee","contingency","retainer","any"]},"max_consultation_fee":{"description":"0 means the user wants a free first consultation","type":"number","minimum":0,"maximum":10000},"payment_plan_needed":{"type":"boolean"},"reduced_fee_eligible":{"description":"User may qualify for pro bono, legal aid or reduced fees","type":"boolean"},"languages":{"maxItems":5,"type":"array","items":{"type":"string","maxLength":40}},"language_required":{"description":"True if the language is essential, not just preferred","type":"boolean"},"min_years_licensed":{"type":"integer","minimum":0,"maximum":60},"accessibility_needs":{"type":"string","maxLength":200},"communication":{"type":"string","enum":["phone","email","video","in_person","any"]},"exclude_attorney_ids":{"maxItems":50,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"priorities":{"description":"What matters most, in order. Shifts ranking weights.","maxItems":4,"type":"array","items":{"type":"string","enum":["price","speed","experience","proximity"]}},"include_unconfirmed_practice_area":{"description":"Also include licensed lawyers whose practice areas are not on record (labeled clearly)","type":"boolean"},"attribution_token":{"description":"Signed campaign/partner token issued by ALCBar, if the user arrived through a partner link","type":"string","maxLength":600},"preference_set_id":{"description":"Saved criteria from update_matching_preferences","type":"string","maxLength":40},"limit":{"type":"integer","minimum":1,"maximum":10}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/attorneys/search":{"post":{"operationId":"searchAttorneys","summary":"Same as POST /v1/matches.","description":"Find licensed lawyers for a matter and rank them by practice-area fit, location, years licensed, timing, price and preferences, with plain-language reasons, data sources and gaps. Returns up to 5 by default, or an honest no-match. Not legal advice.","security":[{"bearer":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"description":{"description":"Short description of the legal need in the user's words. Used only to pick a practice area; not stored.","type":"string","maxLength":2000},"practice_area":{"description":"Practice area, e.g. 'Landlord-Tenant Law', 'Family Law', 'Criminal Law'","type":"string","maxLength":80},"subpractice_area":{"type":"string","maxLength":80},"matter_type":{"type":"string","maxLength":80},"category":{"type":"string","enum":["civil","criminal","administrative","transactional","family","other"]},"procedural_stage":{"type":"string","enum":["not_started","pre_filing","filed","hearing_scheduled","trial","post_judgment","appeal","transaction","unknown"]},"client_side":{"description":"Which side the user is on. ALCBar has no record of which side lawyers usually represent, so results carry a warning to ask.","type":"string","enum":["tenant","landlord","employee","employer","plaintiff","defendant","buyer","seller","other","unknown"]},"service_needed":{"type":"string","enum":["advice_consultation","negotiation","document_preparation","litigation","ongoing_representation","unknown"]},"state":{"type":"string","minLength":2,"maxLength":40,"description":"US state, two-letter code or name, e.g. CA or California"},"county":{"type":"string","maxLength":80},"city":{"type":"string","maxLength":80},"zip":{"description":"5-digit ZIP code, only if the user agreed to share it","type":"string","pattern":"^\\d{5}$"},"court":{"type":"string","maxLength":120},"remote_ok":{"description":"User is willing to work with a lawyer remotely (phone or video) anywhere in the state","type":"boolean"},"urgency":{"type":"string","enum":["emergency","critical_deadline","soon","routine","long_term"]},"deadline_date":{"description":"A deadline the USER reported (hearing, filing, response). ALCBar does not verify or calculate deadlines.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"deadline_type":{"type":"string","enum":["hearing","filing","response","other"]},"consultation_by":{"description":"Latest date the user wants a first consultation","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"representation_start_by":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Date as YYYY-MM-DD"},"budget_max":{"description":"Total budget the user mentioned, in US dollars","type":"number","minimum":0,"maximum":10000000},"budget_min":{"type":"number","minimum":0,"maximum":10000000},"billing_preference":{"type":"string","enum":["hourly","flat_fee","contingency","retainer","any"]},"max_consultation_fee":{"description":"0 means the user wants a free first consultation","type":"number","minimum":0,"maximum":10000},"payment_plan_needed":{"type":"boolean"},"reduced_fee_eligible":{"description":"User may qualify for pro bono, legal aid or reduced fees","type":"boolean"},"languages":{"maxItems":5,"type":"array","items":{"type":"string","maxLength":40}},"language_required":{"description":"True if the language is essential, not just preferred","type":"boolean"},"min_years_licensed":{"type":"integer","minimum":0,"maximum":60},"accessibility_needs":{"type":"string","maxLength":200},"communication":{"type":"string","enum":["phone","email","video","in_person","any"]},"exclude_attorney_ids":{"maxItems":50,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"priorities":{"description":"What matters most, in order. Shifts ranking weights.","maxItems":4,"type":"array","items":{"type":"string","enum":["price","speed","experience","proximity"]}},"include_unconfirmed_practice_area":{"description":"Also include licensed lawyers whose practice areas are not on record (labeled clearly)","type":"boolean"},"attribution_token":{"description":"Signed campaign/partner token issued by ALCBar, if the user arrived through a partner link","type":"string","maxLength":600},"preference_set_id":{"description":"Saved criteria from update_matching_preferences","type":"string","maxLength":40},"limit":{"type":"integer","minimum":1,"maximum":10}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/matches/requirements":{"post":{"operationId":"get_matching_requirements","summary":"Which details are missing for a good match.","description":"Given what is known about a legal matter, list the missing details that would improve a lawyer match and the questions to ask. Does not answer the legal question.","security":[{"bearer":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"description":{"description":"Short description of the legal need in the user's words. Used only to pick a practice area; not stored.","type":"string","maxLength":2000},"practice_area":{"description":"Practice area, e.g. 'Landlord-Tenant Law', 'Family Law', 'Criminal Law'","type":"string","maxLength":80},"subpractice_area":{"type":"string","maxLength":80},"matter_type":{"type":"string","maxLength":80},"category":{"type":"string","enum":["civil","criminal","administrative","transactional","family","other"]},"procedural_stage":{"type":"string","enum":["not_started","pre_filing","filed","hearing_scheduled","trial","post_judgment","appeal","transaction","unknown"]},"client_side":{"description":"Which side the user is on. ALCBar has no record of which side lawyers usually represent, so results carry a warning to ask.","type":"string","enum":["tenant","landlord","employee","employer","plaintiff","defendant","buyer","seller","other","unknown"]},"service_needed":{"type":"string","enum":["advice_consultation","negotiation","document_preparation","litigation","ongoing_representation","unknown"]},"state":{"type":"string","minLength":2,"maxLength":40,"description":"US state, two-letter code or name, e.g. CA or California"},"county":{"type":"string","maxLength":80},"city":{"type":"string","maxLength":80},"zip":{"description":"5-digit ZIP code, only if the user agreed to share it","type":"string","pattern":"^\\d{5}$"},"court":{"type":"string","maxLength":120},"remote_ok":{"description":"User is willing to work with a lawyer remotely (phone or video) anywhere in the state","type":"boolean"},"urgency":{"type":"string","enum":["emergency","critical_deadline","soon","routine","long_term"]},"deadline_date":{"description":"A deadline the USER reported (hearing, filing, response). ALCBar does not verify or calculate deadlines.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"deadline_type":{"type":"string","enum":["hearing","filing","response","other"]},"consultation_by":{"description":"Latest date the user wants a first consultation","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"representation_start_by":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Date as YYYY-MM-DD"},"budget_max":{"description":"Total budget the user mentioned, in US dollars","type":"number","minimum":0,"maximum":10000000},"budget_min":{"type":"number","minimum":0,"maximum":10000000},"billing_preference":{"type":"string","enum":["hourly","flat_fee","contingency","retainer","any"]},"max_consultation_fee":{"description":"0 means the user wants a free first consultation","type":"number","minimum":0,"maximum":10000},"payment_plan_needed":{"type":"boolean"},"reduced_fee_eligible":{"description":"User may qualify for pro bono, legal aid or reduced fees","type":"boolean"},"languages":{"maxItems":5,"type":"array","items":{"type":"string","maxLength":40}},"language_required":{"description":"True if the language is essential, not just preferred","type":"boolean"},"min_years_licensed":{"type":"integer","minimum":0,"maximum":60},"accessibility_needs":{"type":"string","maxLength":200},"communication":{"type":"string","enum":["phone","email","video","in_person","any"]},"exclude_attorney_ids":{"maxItems":50,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"priorities":{"description":"What matters most, in order. Shifts ranking weights.","maxItems":4,"type":"array","items":{"type":"string","enum":["price","speed","experience","proximity"]}},"include_unconfirmed_practice_area":{"description":"Also include licensed lawyers whose practice areas are not on record (labeled clearly)","type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/attorneys/compare":{"post":{"operationId":"compare_attorneys","summary":"Compare 2 to 5 lawyers.","description":"Compare 2 to 5 lawyers returned by ALCBar: practice fit, location, years licensed, fees, availability, verification gaps and trade-offs. Pass match_id to use the user's criteria.","security":[{"bearer":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"attorney_ids":{"minItems":2,"maxItems":5,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"match_id":{"description":"The match_id from find_attorneys, so comparisons use the same criteria","type":"string","maxLength":40},"priorities":{"description":"What matters most, in order. Shifts ranking weights.","maxItems":4,"type":"array","items":{"type":"string","enum":["price","speed","experience","proximity"]}},"criteria":{"maxItems":7,"type":"array","items":{"type":"string","enum":["price","timing","experience","location","practice_fit","languages","verification"]}}},"required":["attorney_ids"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/pricing/estimates":{"post":{"operationId":"estimate_legal_cost","summary":"Fee information with sources; never a guess.","description":"Fee information for a matter type or a specific lawyer, labeled as published fees, confirmed quotes or sourced market figures. Says plainly when data is insufficient instead of guessing. Not a quote.","security":[{"bearer":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"practice_area":{"type":"string","maxLength":80},"description":{"description":"Short description of the legal need in the user's words. Used only to pick a practice area; not stored.","type":"string","maxLength":2000},"state":{"type":"string","minLength":2,"maxLength":40,"description":"US state, two-letter code or name, e.g. CA or California"},"scope":{"type":"string","enum":["consultation_only","limited_scope","full_representation","unknown"]},"billing_preference":{"type":"string","enum":["hourly","flat_fee","contingency","retainer","any"]},"budget_max":{"description":"Total budget the user mentioned, in US dollars","type":"number","minimum":0,"maximum":10000000},"attorney_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/availability/check":{"post":{"operationId":"check_attorney_availability","summary":"Reported or confirmed availability.","description":"Latest availability lawyers have reported or confirmed to ALCBar, with last-checked time and certainty (reported, tentative, confirmed). There is no live calendar access.","security":[{"bearer":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"attorney_ids":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"wanted_by":{"description":"Latest acceptable consultation date","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"time_zone":{"type":"string","maxLength":60},"appointment_type":{"type":"string","enum":["in_person","phone","video","any"]}},"required":["attorney_ids"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/referrals":{"post":{"operationId":"request_attorney_introduction","summary":"Create a consent-based introduction. Send Idempotency-Key to make retries safe.","description":"Record a client-authorized introduction to ONE lawyer. Call only after the user has seen the lawyer's name, the exact details to be shared, and explicitly agreed. Shares only the fields the user authorized. Returns a referral id and a private status token.","security":[{"bearer":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":100}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"attorney_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"match_id":{"type":"string","maxLength":40},"practice_area":{"type":"string","maxLength":80},"state":{"type":"string","minLength":2,"maxLength":40,"description":"US state, two-letter code or name, e.g. CA or California"},"contact":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"email":{"type":"string","maxLength":200,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"phone":{"type":"string","pattern":"^[0-9+().\\- ]{7,25}$"}},"additionalProperties":false},"matter_summary":{"type":"string","minLength":10,"maxLength":2000,"description":"Summary the USER read and approved for sharing with this lawyer"},"preferred_contact_method":{"type":"string","enum":["email","phone","either"]},"preferred_timeframe":{"type":"string","maxLength":120},"consent":{"type":"object","properties":{"confirmed":{"type":"boolean","const":true,"description":"Must be true only after the user explicitly agreed to share the listed fields with this lawyer"},"recipient_attorney_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Must equal attorney_id: the user agreed to share with THIS lawyer"},"fields_authorized":{"minItems":1,"type":"array","items":{"type":"string","enum":["name","email","phone","matter_summary","preferred_timeframe"]}},"user_statement":{"description":"The user's own words of consent, if available","type":"string","maxLength":300}},"required":["confirmed","recipient_attorney_id","fields_authorized"],"additionalProperties":false},"idempotency_key":{"description":"Same key on retries prevents a duplicate referral","type":"string","minLength":8,"maxLength":100},"attribution_token":{"description":"Signed campaign/partner token issued by ALCBar, if the user arrived through a partner link","type":"string","maxLength":600}},"required":["attorney_id","state","contact","matter_summary","preferred_contact_method","consent"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/preferences":{"put":{"operationId":"update_matching_preferences","summary":"Save or change matching criteria (24-hour retention).","description":"Save or change matching criteria (location, budget, timing, practice area, language, priorities) for this conversation. No personal contact details. Deleted automatically after 24 hours.","security":[{"bearer":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"preference_set_id":{"description":"Omit to create a new set","type":"string","maxLength":40},"criteria":{"type":"object","properties":{"description":{"description":"Short description of the legal need in the user's words. Used only to pick a practice area; not stored.","type":"string","maxLength":2000},"practice_area":{"description":"Practice area, e.g. 'Landlord-Tenant Law', 'Family Law', 'Criminal Law'","type":"string","maxLength":80},"subpractice_area":{"type":"string","maxLength":80},"matter_type":{"type":"string","maxLength":80},"category":{"type":"string","enum":["civil","criminal","administrative","transactional","family","other"]},"procedural_stage":{"type":"string","enum":["not_started","pre_filing","filed","hearing_scheduled","trial","post_judgment","appeal","transaction","unknown"]},"client_side":{"description":"Which side the user is on. ALCBar has no record of which side lawyers usually represent, so results carry a warning to ask.","type":"string","enum":["tenant","landlord","employee","employer","plaintiff","defendant","buyer","seller","other","unknown"]},"service_needed":{"type":"string","enum":["advice_consultation","negotiation","document_preparation","litigation","ongoing_representation","unknown"]},"state":{"type":"string","minLength":2,"maxLength":40,"description":"US state, two-letter code or name, e.g. CA or California"},"county":{"type":"string","maxLength":80},"city":{"type":"string","maxLength":80},"zip":{"description":"5-digit ZIP code, only if the user agreed to share it","type":"string","pattern":"^\\d{5}$"},"court":{"type":"string","maxLength":120},"remote_ok":{"description":"User is willing to work with a lawyer remotely (phone or video) anywhere in the state","type":"boolean"},"urgency":{"type":"string","enum":["emergency","critical_deadline","soon","routine","long_term"]},"deadline_date":{"description":"A deadline the USER reported (hearing, filing, response). ALCBar does not verify or calculate deadlines.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"deadline_type":{"type":"string","enum":["hearing","filing","response","other"]},"consultation_by":{"description":"Latest date the user wants a first consultation","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"representation_start_by":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Date as YYYY-MM-DD"},"budget_max":{"description":"Total budget the user mentioned, in US dollars","type":"number","minimum":0,"maximum":10000000},"budget_min":{"type":"number","minimum":0,"maximum":10000000},"billing_preference":{"type":"string","enum":["hourly","flat_fee","contingency","retainer","any"]},"max_consultation_fee":{"description":"0 means the user wants a free first consultation","type":"number","minimum":0,"maximum":10000},"payment_plan_needed":{"type":"boolean"},"reduced_fee_eligible":{"description":"User may qualify for pro bono, legal aid or reduced fees","type":"boolean"},"languages":{"maxItems":5,"type":"array","items":{"type":"string","maxLength":40}},"language_required":{"description":"True if the language is essential, not just preferred","type":"boolean"},"min_years_licensed":{"type":"integer","minimum":0,"maximum":60},"accessibility_needs":{"type":"string","maxLength":200},"communication":{"type":"string","enum":["phone","email","video","in_person","any"]},"exclude_attorney_ids":{"maxItems":50,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"priorities":{"description":"What matters most, in order. Shifts ranking weights.","maxItems":4,"type":"array","items":{"type":"string","enum":["price","speed","experience","proximity"]}},"include_unconfirmed_practice_area":{"description":"Also include licensed lawyers whose practice areas are not on record (labeled clearly)","type":"boolean"}},"additionalProperties":false,"description":"Fields to set or change. Do not include names, emails or phone numbers."},"clear_fields":{"maxItems":30,"type":"array","items":{"type":"string","maxLength":40}}},"required":["criteria"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/feedback":{"post":{"operationId":"submit_matching_feedback","summary":"Optional ratings on a match or introduction.","description":"Optional 1-5 ratings on match relevance, lawyer responsiveness, pricing and availability accuracy, satisfaction, and whether the lawyer was hired. No case details.","security":[{"bearer":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"match_id":{"type":"string","maxLength":40},"referral_id":{"type":"string","maxLength":40},"status_token":{"type":"string","maxLength":100},"relevance":{"type":"integer","minimum":1,"maximum":5},"responsiveness":{"type":"integer","minimum":1,"maximum":5},"pricing_accuracy":{"type":"integer","minimum":1,"maximum":5},"availability_accuracy":{"type":"integer","minimum":1,"maximum":5},"satisfaction_match":{"type":"integer","minimum":1,"maximum":5},"satisfaction_process":{"type":"integer","minimum":1,"maximum":5},"satisfaction_attorney":{"type":"integer","minimum":1,"maximum":5},"retained":{"type":"string","enum":["yes","no","undecided"]},"comment":{"description":"Optional. Do not include case details.","type":"string","maxLength":500}},"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/attorneys/{attorneyId}":{"get":{"operationId":"get_attorney_profile","summary":"A lawyer's matching profile","security":[{"bearer":[]}],"parameters":[{"name":"attorneyId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/referrals/{referralId}":{"get":{"operationId":"get_referral_status","summary":"Referral status (owner key with referral:read, or X-Referral-Token)","security":[{"bearer":[]}],"parameters":[{"name":"referralId","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Referral-Token","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/events":{"post":{"operationId":"ingest_event","summary":"Signed referral lifecycle event (scope events:write)","security":[{"bearer":[]}],"description":"Headers X-ALCBar-Timestamp (unix seconds, within 5 minutes) and X-ALCBar-Signature = hex HMAC-SHA256(secret, timestamp + '.' + raw body). Repeated event_id values are accepted once.","parameters":[{"name":"X-ALCBar-Timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-ALCBar-Signature","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"event_id":{"type":"string","minLength":6,"maxLength":100},"referral_id":{"type":"string","pattern":"^ref_[A-Za-z0-9_-]{8,40}$"},"type":{"type":"string","enum":["submitted","delivery_failed","attorney_acknowledged","attorney_responded","attorney_accepted","attorney_declined","consultation_requested","consultation_tentative","consultation_confirmed","consultation_rescheduled","consultation_cancelled","consultation_completed","engagement_reported","client_withdrew","survey_invited","survey_completed"]},"provenance":{"type":"string","enum":["attorney_reported","client_reported","integration_confirmed","admin_recorded"]},"occurred_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"reason_code":{"type":"string","maxLength":60},"data":{"type":"object","properties":{"scheduled_for":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"substantive":{"description":"For attorney_responded: true if more than an automatic acknowledgment","type":"boolean"},"engaged":{"type":"boolean"}},"additionalProperties":false}},"required":["event_id","referral_id","type","provenance","occurred_at"],"additionalProperties":false}}}},"responses":{"200":{"description":"Duplicate (already recorded)"},"202":{"description":"Recorded"},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/analytics/north-star":{"get":{"operationId":"analytics_north_star","summary":"North-star metric by cohort and source (scope analytics:read)","security":[{"bearer":[]}],"parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}},{"name":"group_by","in":"query","schema":{"type":"string","enum":["none","platform","partner","integration","campaign","practice_area","jurisdiction","attorney"]}}],"responses":{"200":{"description":"OK"},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/analytics/referral-funnel":{"get":{"operationId":"analytics_referral_funnel","summary":"Referral funnel (scope analytics:read)","security":[{"bearer":[]}],"parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}},{"name":"group_by","in":"query","schema":{"type":"string","enum":["none","platform","partner","integration","campaign","practice_area","jurisdiction","attorney"]}}],"responses":{"200":{"description":"OK"},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/analytics/performance":{"get":{"operationId":"analytics_performance","summary":"All referral metrics (scope analytics:read)","security":[{"bearer":[]}],"parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}},{"name":"group_by","in":"query","schema":{"type":"string","enum":["none","platform","partner","integration","campaign","practice_area","jurisdiction","attorney"]}}],"responses":{"200":{"description":"OK"},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/analytics/satisfaction":{"get":{"operationId":"analytics_satisfaction","summary":"Client satisfaction (scope analytics:read)","security":[{"bearer":[]}],"parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}},{"name":"group_by","in":"query","schema":{"type":"string","enum":["none","platform","partner","integration","campaign","practice_area","jurisdiction","attorney"]}}],"responses":{"200":{"description":"OK"},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/analytics/searches":{"get":{"operationId":"analytics_searches","summary":"Search volume by platform and outcome (scope analytics:read)","security":[{"bearer":[]}],"parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}},{"name":"group_by","in":"query","schema":{"type":"string","enum":["none","platform","partner","integration","campaign","practice_area","jurisdiction","attorney"]}}],"responses":{"200":{"description":"OK"},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/health":{"get":{"operationId":"health","security":[],"responses":{"200":{"description":"Process is up"}}}},"/ready":{"get":{"operationId":"ready","security":[],"responses":{"200":{"description":"Database reachable and lawyers indexed"},"503":{"description":"Not ready"}}}},"/mcp":{"post":{"operationId":"mcp","summary":"Model Context Protocol endpoint (Streamable HTTP, JSON-RPC 2.0)","security":[{},{"bearer":[]}],"responses":{"200":{"description":"JSON-RPC response"}}}}},"x-versioning":"The major version is in the path (/v1). Breaking changes get /v2; /v1 stays available for at least 6 months after /v2 ships, with a Deprecation header."}