Every API here is available over the APIs.io API and to AI agents over MCP.
{"openapi":"3.0.0","info":{"title":"ActuallyCare API","version":"1.0.0","description":"# AI-Ready REST API for Real Estate Transaction Management\n\nThis API provides comprehensive endpoints for managing real estate transactions, including:\n- **Escrows**: Complete transaction lifecycle management\n- **Listings**: Property inventory and marketing\n- **Clients**: Contact and relationship management\n- **Appointments**: Calendar and scheduling\n- **Leads**: Lead qualification and conversion pipeline\n\n## AI Integration\nThis API is fully compatible with:\n- Anthropic Claude (Sonnet 4.6, Opus 4.6, Haiku 4.5)\n- Anthropic Claude MCP (Model Context Protocol)\n- Custom AI agents and automation\n\n## Authentication\nAll endpoints require authentication via:\n- JWT Bearer tokens (for user sessions)\n- API Keys (for external integrations and AI agents)","contact":{"name":"ActuallyCare Support","email":"support@actuallycare.com","url":"https://www.actuallycare.com"},"license":{"name":"Proprietary","url":"https://www.actuallycare.com/legal"}},"servers":[{"url":"https://api.actuallycare.com/v1","description":"Production server"},{"url":"http://localhost:3001/v1","description":"Development server"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token obtained from /auth/login endpoint"},"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key for external integrations and AI agents"}},"responses":{"UnauthorizedError":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"NO_AUTH_TOKEN"},"message":{"type":"string","example":"No authentication token provided"}}}}}}}},"NotFoundError":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"NOT_FOUND"},"message":{"type":"string","example":"Resource not found"}}}}}}}},"ValidationError":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Invalid request data"},"details":{"type":"array","items":{"type":"string"}}}}}}}}},"ServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"INTERNAL_ERROR","message":"An internal error occurred","errorId":"ERR_1782972632_k4n9qz","correlationId":"6a1d94e7-2c8b-4f53-a0e9-7b3c5d218f64"},"timestamp":"2026-07-01T22:41:12.408Z"}}}},"RateLimitError":{"description":"Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.","headers":{"Retry-After":{"description":"Seconds until the current rate-limit window resets and requests will be accepted again","schema":{"type":"integer","example":900}},"RateLimit-Limit":{"description":"Request ceiling for the current window","schema":{"type":"integer","example":500}},"RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer","example":0}},"RateLimit-Reset":{"description":"Seconds until the current window resets","schema":{"type":"integer","example":512}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"RATE_LIMIT_EXCEEDED","message":"Too many requests from this IP, please try again later.","errorId":"3f2b8c14-9d6e-4a71-b5c2-e8f0a1d47c96"}}}}}},"parameters":{"pageParam":{"in":"query","name":"page","schema":{"type":"integer","minimum":1,"default":1},"description":"Page number for pagination"},"limitParam":{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Number of items per page (default 25, max 100)"},"idParam":{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Unique identifier (UUID)"}},"schemas":{"PublicPlan":{"type":"object","properties":{"key":{"type":"string","enum":["agent","team","broker"]},"name":{"type":"string","example":"ActuallyCare+ Agent"},"priceMonthly":{"type":"integer","description":"Monthly price in cents","example":10000},"priceYearly":{"type":"integer","description":"Yearly price in cents","example":120000},"trialDays":{"type":"integer","example":30},"seats":{"type":"integer","example":1},"recommended":{"type":"boolean","description":"True for the single recommended \"Most Popular\" anchor tier (DEC-531 § 6). Marketing + in-app cards read this so they can't drift.","example":false},"features":{"type":"array","items":{"type":"string"}}}},"Contact":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string"},"last_name":{"type":"string"},"full_name":{"type":"string","description":"Generated from first and last name (read-only)"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"contact_type":{"type":"string","enum":["buyer","seller","agent","lender","title_officer","inspector","appraiser","contractor","client","vendor","other"]},"contact_status":{"type":"string"},"company":{"type":"string"},"license_number":{"type":"string"},"street_address":{"type":"string"},"city":{"type":"string"},"state":{"type":"string","description":"Two-letter state code"},"zip_code":{"type":"string"},"notes":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"is_archived":{"type":"boolean","description":"Whether the contact is archived (hidden from default lists). Active contacts are false.","example":false},"archived_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ScannedBusinessCard":{"type":"object","description":"Structured output from the card-scan model. Every printed field is\nnullable — a card that omits a mobile number yields null, not \"\".\nMirrors CARD_SCHEMA in contacts/services/card-scan.service.js.\n","required":["isBusinessCard","confidence"],"properties":{"isBusinessCard":{"type":"boolean","description":"False if the image is not a business card"},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"jobTitle":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true,"description":"Primary/office number, as printed"},"mobile":{"type":"string","nullable":true},"website":{"type":"string","nullable":true},"addressLine":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"postalCode":{"type":"string","nullable":true},"licenseNumber":{"type":"string","nullable":true,"description":"DRE/BRE or other licence number if printed"},"confidence":{"type":"string","enum":["high","medium","low"]},"model":{"type":"string","description":"Model id that produced the extraction"},"usage":{"type":"object","nullable":true,"description":"Token usage reported by the provider"}}},"Escrow":{"type":"object","description":"Real estate transaction (escrow) record","required":["property_address"],"properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier","example":"550e8400-e29b-41d4-a716-446655440000"},"user_id":{"type":"string","format":"uuid","description":"Owner/agent ID"},"property_address":{"type":"string","description":"Full property address","example":"123 Main St, Tehachapi, CA 93561"},"city":{"type":"string","description":"City name","example":"Tehachapi"},"state":{"type":"string","description":"State abbreviation","example":"CA"},"zip_code":{"type":"string","description":"ZIP code","example":"93561"},"purchase_price":{"type":"number","format":"double","minimum":0,"description":"Purchase price in USD","example":500000},"escrow_status":{"type":"string","enum":["active","pending","closed","cancelled"],"description":"Current status","example":"active"},"acceptance_date":{"type":"string","format":"date","description":"Offer acceptance date","example":"2025-01-15"},"closing_date":{"type":"string","format":"date","description":"Expected closing date","example":"2025-03-01"},"buyers":{"type":"array","description":"List of buyers","items":{"$ref":"#/components/schemas/Person"}},"sellers":{"type":"array","description":"List of sellers","items":{"$ref":"#/components/schemas/Person"}},"listing_agent":{"$ref":"#/components/schemas/Agent"},"selling_agent":{"$ref":"#/components/schemas/Agent"},"escrow_company":{"type":"string","description":"Escrow/title company name","example":"First American Title"},"escrow_officer":{"type":"string","description":"Escrow officer name","example":"Jane Smith"},"property_type":{"type":"string","enum":["single_family","condo","townhouse","multi_family","land","commercial"],"example":"single_family"},"bedrooms":{"type":"integer","minimum":0,"example":3},"bathrooms":{"type":"number","format":"float","minimum":0,"example":2.5},"square_feet":{"type":"integer","minimum":0,"example":2400},"lot_size":{"type":"number","format":"float","minimum":0,"description":"Lot size in acres","example":0.25},"year_built":{"type":"integer","minimum":1800,"maximum":2100,"example":2015},"contingencies":{"type":"array","description":"Active contingencies","items":{"type":"object","properties":{"type":{"type":"string","example":"inspection"},"due_date":{"type":"string","format":"date"},"status":{"type":"string","enum":["pending","satisfied","waived","removed"]}}}},"earnest_money":{"type":"number","format":"double","minimum":0,"description":"Earnest money deposit amount","example":10000},"commission_rate":{"type":"number","format":"float","minimum":0,"maximum":100,"description":"Commission percentage","example":3},"notes":{"type":"string","description":"Internal notes"},"version":{"type":"integer","description":"Optimistic locking version","example":1},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"last_modified_by":{"type":"string","format":"uuid","description":"Last user to modify record"}}},"Listing":{"type":"object","description":"Property listing record","required":["address","list_price"],"properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"mls_number":{"type":"string","description":"MLS listing number","example":"ML123456"},"address":{"type":"string","example":"456 Oak Ave, Tehachapi, CA 93561"},"city":{"type":"string","example":"Tehachapi"},"state":{"type":"string","example":"CA"},"zip_code":{"type":"string","example":"93561"},"list_price":{"type":"number","format":"double","minimum":0,"example":425000},"status":{"type":"string","enum":["active","pending","sold","withdrawn","expired"],"example":"active"},"property_type":{"type":"string","enum":["single_family","condo","townhouse","multi_family","land","commercial"],"example":"single_family"},"bedrooms":{"type":"integer","minimum":0,"example":4},"bathrooms":{"type":"number","format":"float","minimum":0,"example":3},"square_feet":{"type":"integer","minimum":0,"example":2800},"lot_size":{"type":"number","format":"float","minimum":0,"example":0.5},"year_built":{"type":"integer","example":2010},"description":{"type":"string","description":"Property description"},"listing_date":{"type":"string","format":"date"},"expiration_date":{"type":"string","format":"date"},"photos":{"type":"array","items":{"type":"string","format":"uri"}},"virtual_tour_url":{"type":"string","format":"uri"},"showing_instructions":{"type":"string"},"days_on_market":{"type":"integer","minimum":0},"price_per_sqft":{"type":"number","format":"float"},"version":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Client":{"type":"object","description":"Client/contact record","required":["first_name","last_name","client_type"],"properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"first_name":{"type":"string","example":"John"},"last_name":{"type":"string","example":"Doe"},"email":{"type":"string","format":"email","example":"john.doe@example.com"},"phone":{"type":"string","example":"(555) 123-4567"},"client_type":{"type":"string","enum":["buyer","seller","both"],"example":"buyer"},"status":{"type":"string","enum":["active","inactive","closed"],"example":"active"},"source":{"type":"string","description":"Lead source","example":"Zillow"},"budget_min":{"type":"number","format":"double","minimum":0},"budget_max":{"type":"number","format":"double","minimum":0},"preferred_locations":{"type":"array","items":{"type":"string"}},"property_preferences":{"type":"object","properties":{"bedrooms_min":{"type":"integer"},"bathrooms_min":{"type":"number","format":"float"},"square_feet_min":{"type":"integer"},"property_types":{"type":"array","items":{"type":"string"}}}},"pre_approved":{"type":"boolean","description":"Pre-approved for financing"},"pre_approval_amount":{"type":"number","format":"double"},"notes":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"version":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Appointment":{"type":"object","description":"Calendar appointment/showing","required":["title","start_time","end_time"],"properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"title":{"type":"string","example":"Property Showing - 123 Main St"},"description":{"type":"string"},"appointment_type":{"type":"string","enum":["showing","inspection","signing","meeting","call","other"],"example":"showing"},"start_time":{"type":"string","format":"date-time","example":"2025-02-01T14:00:00Z"},"end_time":{"type":"string","format":"date-time","example":"2025-02-01T15:00:00Z"},"location":{"type":"string","example":"123 Main St, Tehachapi, CA 93561"},"client_id":{"type":"string","format":"uuid"},"listing_id":{"type":"string","format":"uuid"},"escrow_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["scheduled","completed","cancelled","no_show"],"example":"scheduled"},"attendees":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"}}}},"reminder_sent":{"type":"boolean"},"notes":{"type":"string"},"version":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Lead":{"type":"object","description":"Prospective client lead","required":["name"],"properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"Jane Smith"},"email":{"type":"string","format":"email","example":"jane.smith@example.com"},"phone":{"type":"string","example":"(555) 987-6543"},"source":{"type":"string","description":"How lead was acquired","example":"Website Form"},"status":{"type":"string","enum":["new","contacted","qualified","unqualified","converted","lost"],"example":"new"},"lead_type":{"type":"string","enum":["buyer","seller","both"],"example":"buyer"},"interest_level":{"type":"string","enum":["hot","warm","cold"],"example":"warm"},"budget":{"type":"number","format":"double"},"timeline":{"type":"string","description":"Expected timeline","example":"3-6 months"},"message":{"type":"string","description":"Initial inquiry message"},"notes":{"type":"string"},"last_contact_date":{"type":"string","format":"date-time"},"next_follow_up":{"type":"string","format":"date-time"},"converted_to_client_id":{"type":"string","format":"uuid"},"version":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Person":{"type":"object","properties":{"name":{"type":"string","example":"John Doe"},"email":{"type":"string","format":"email","example":"john@example.com"},"phone":{"type":"string","example":"(555) 123-4567"}}},"Agent":{"type":"object","properties":{"name":{"type":"string","example":"Alex Rivera"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"license":{"type":"string","description":"Real estate license number","example":"DRE #02209852"},"brokerage":{"type":"string","example":"Associated Real Estate"}}},"SuccessResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","description":"Response data (varies by endpoint)"},"timestamp":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Invalid request data"},"errorId":{"type":"string","description":"Unique identifier for this error occurrence — include it in support requests","example":"ERR_1782972632_ab12cd"},"correlationId":{"type":"string","format":"uuid","description":"Request correlation ID for tracing this request through logs","example":"b7e4c2a8-3f6d-4e29-9c41-8d5a2f7e1b93"},"details":{"description":"Present only on operational errors that attach extra detail — omitted otherwise. Shape varies by error: an array of per-field failures for validation errors, an object for others (e.g. { locked_until } on ACCOUNT_LOCKED)."}}},"timestamp":{"type":"string","format":"date-time"}}},"PaginationMeta":{"type":"object","description":"Pagination metadata for list endpoints. List responses nest this object as `data.meta`, alongside the resource array keyed by the resource name (e.g. `data.escrows`, `data.contacts`, `data.leads`).\n","properties":{"page":{"type":"integer","description":"Current page number (1-based)","example":1},"limit":{"type":"integer","description":"Items per page","example":25},"total":{"type":"integer","description":"Total matching records across all pages","example":231},"totalPages":{"type":"integer","description":"Total number of pages","example":10},"hasMore":{"type":"boolean","description":"True when more pages exist after the current one","example":true}}},"Webhook":{"type":"object","properties":{"id":{"type":"string","description":"Webhook ID (wh_ prefix followed by 12 characters)","example":"wh_abc123def456"},"url":{"type":"string","format":"uri","description":"Endpoint that receives event deliveries"},"events":{"type":"array","description":"Subscribed event names (entity.action format)","items":{"type":"string","example":"escrow.created"}},"has_secret":{"type":"boolean","description":"Whether a signing secret is set. The secret itself is write-only and is never returned."},"active":{"type":"boolean"},"brokerage_id":{"type":"string","format":"uuid","nullable":true,"description":"Brokerage that owns the subscription"},"team_id":{"type":"string","format":"uuid","nullable":true,"description":"Team the subscription is limited to; null means every event in the brokerage"},"last_triggered":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}}},"x-business-rules":{"escrows":{"description":"Rules for real estate transaction management","rules":[{"id":"escrow-address-required","field":"property_address","rule":"Property address is mandatory for all escrows","severity":"error"},{"id":"escrow-future-closing","field":"closing_date","rule":"Closing date must be in the future when creating new escrow","severity":"warning","exception":"Can set past date for historical imports"},{"id":"escrow-positive-price","field":"purchase_price","rule":"Purchase price must be positive if provided","severity":"error","validation":"purchase_price > 0"},{"id":"escrow-address-immutable","field":"property_address","rule":"Property address cannot be changed after escrow creation","severity":"error","applies_to":["update"]},{"id":"escrow-status-transitions","field":"escrow_status","rule":"Valid status transitions are pending→active→closed or pending→cancelled","severity":"error","valid_transitions":{"pending":["active","cancelled"],"active":["closed","cancelled"],"closed":[],"cancelled":[]}},{"id":"escrow-price-documentation","field":"purchase_price","rule":"Price changes should be documented in notes or audit log","severity":"warning","applies_to":["update"]},{"id":"escrow-broker-approval","field":"closing_date","rule":"Closing date changes may require broker approval","severity":"warning","applies_to":["update"],"context":"Changes affecting timeline should notify broker"},{"id":"escrow-archive-before-delete","rule":"Only archived escrows can be permanently deleted","severity":"error","applies_to":["delete"]},{"id":"escrow-contingency-dates","field":"contingencies","rule":"Contingency removal dates must be before closing date","severity":"warning"},{"id":"escrow-earnest-money","field":"earnest_money_amount","rule":"Earnest money typically 1-3% of purchase price","severity":"info","validation":"earnest_money_amount between (purchase_price * 0.01) and (purchase_price * 0.03)"}]},"listings":{"description":"Rules for property listing management","rules":[{"id":"listing-address-required","field":"address","rule":"Property address is mandatory","severity":"error"},{"id":"listing-price-required","field":"list_price","rule":"List price must be provided","severity":"error"},{"id":"listing-positive-price","field":"list_price","rule":"List price must be positive","severity":"error","validation":"list_price > 0"},{"id":"listing-future-expiration","field":"expiration_date","rule":"Expiration date must be in the future","severity":"warning"},{"id":"listing-reasonable-bedrooms","field":"bedrooms","rule":"Bedrooms should be between 0 and 20","severity":"warning","validation":"bedrooms >= 0 AND bedrooms <= 20"},{"id":"listing-reasonable-bathrooms","field":"bathrooms","rule":"Bathrooms should be between 0 and 15","severity":"warning","validation":"bathrooms >= 0 AND bathrooms <= 15"},{"id":"listing-positive-sqft","field":"square_feet","rule":"Square footage must be positive if provided","severity":"error","validation":"square_feet > 0"},{"id":"listing-status-transitions","field":"status","rule":"Valid status transitions are active→pending→sold or active→withdrawn/expired","severity":"error","valid_transitions":{"active":["pending","withdrawn","expired"],"pending":["sold","active"],"sold":[],"withdrawn":["active"],"expired":["active"]}},{"id":"listing-mls-sync","field":"mls_number","rule":"MLS number should match Multiple Listing Service records","severity":"warning","context":"Validate against MLS database if integrated"}]},"clients":{"description":"Rules for client contact management","rules":[{"id":"client-name-required","field":"first_name, last_name","rule":"Client must have at least first name or last name","severity":"error"},{"id":"client-contact-method","field":"email, phone","rule":"Client must have at least one contact method (email or phone)","severity":"warning"},{"id":"client-valid-email","field":"email","rule":"Email must be valid format if provided","severity":"error","validation":"Valid email regex"},{"id":"client-budget-range","field":"budget_min, budget_max","rule":"Minimum budget must be less than maximum budget","severity":"error","validation":"budget_min < budget_max"},{"id":"client-positive-budget","field":"budget_min, budget_max","rule":"Budget values must be positive","severity":"error","validation":"budget_min >= 0 AND budget_max > 0"},{"id":"client-type-required","field":"client_type","rule":"Client type must be specified (buyer, seller, both)","severity":"error","validation":"client_type IN ['buyer', 'seller', 'both']"},{"id":"client-duplicate-check","field":"email, phone","rule":"Check for duplicate clients with same email or phone","severity":"warning","context":"Warn before creating duplicate contacts"}]},"appointments":{"description":"Rules for appointment and showing management","rules":[{"id":"appointment-title-required","field":"title","rule":"Appointment must have a title","severity":"error"},{"id":"appointment-time-required","field":"start_time, end_time","rule":"Start and end times are required","severity":"error"},{"id":"appointment-end-after-start","field":"start_time, end_time","rule":"End time must be after start time","severity":"error","validation":"end_time > start_time"},{"id":"appointment-reasonable-duration","field":"start_time, end_time","rule":"Appointment duration should be between 15 minutes and 8 hours","severity":"warning","validation":"duration BETWEEN 15 minutes AND 8 hours"},{"id":"appointment-future-time","field":"start_time","rule":"Appointments should be scheduled in the future","severity":"warning","exception":"Can create past appointments for records"},{"id":"appointment-business-hours","field":"start_time","rule":"Showings typically during business hours (8 AM - 8 PM)","severity":"info","context":"Warn for appointments outside typical hours"},{"id":"appointment-status-transitions","field":"status","rule":"Valid status transitions are scheduled→completed/cancelled/no_show","severity":"error","valid_transitions":{"scheduled":["completed","cancelled","no_show"],"completed":[],"cancelled":[],"no_show":[]}}]},"leads":{"description":"Rules for lead qualification and management","rules":[{"id":"lead-name-required","field":"name","rule":"Lead must have a name","severity":"error"},{"id":"lead-contact-method","field":"email, phone","rule":"Lead must have at least one contact method","severity":"warning"},{"id":"lead-source-tracking","field":"source","rule":"Lead source should be tracked for marketing analytics","severity":"warning","context":"Important for ROI calculation"},{"id":"lead-status-progression","field":"status","rule":"Leads should progress through stages new→contacted→qualified→converted","severity":"info","valid_transitions":{"new":["contacted","unqualified","lost"],"contacted":["qualified","unqualified","lost"],"qualified":["converted","lost"],"unqualified":["contacted"],"converted":[],"lost":["contacted"]}},{"id":"lead-interest-level","field":"interest_level","rule":"Interest level helps prioritize follow-up (hot > warm > cold)","severity":"info","validation":"interest_level IN ['hot', 'warm', 'cold']"},{"id":"lead-conversion-creates-client","rule":"Converting a lead should create a corresponding client record","severity":"error","applies_to":["convert"],"context":"Use /leads/{id}/convert endpoint"}]},"general":{"description":"Cross-entity business rules","rules":[{"id":"california-compliance","rule":"All transactions must comply with California DRE regulations","severity":"info","context":"Broker license 01910265, Officer Josh Riley 01365477"},{"id":"data-retention","rule":"Transaction records must be retained for 3 years minimum","severity":"info","context":"California DRE requirement"},{"id":"audit-trail","rule":"All modifications should maintain audit trail","severity":"info","context":"Optimistic locking version field tracks changes"},{"id":"user-data-isolation","rule":"Users can only access their own data or team data","severity":"error","context":"Enforced by user_id filtering in all queries"},{"id":"price-formatting","rule":"Prices should be stored as numbers, formatted as currency for display","severity":"info","context":"Use toLocaleString('en-US', {style:'currency', currency:'USD'})"},{"id":"date-formatting","rule":"Dates stored as ISO 8601 format (YYYY-MM-DD)","severity":"info","context":"Use YYYY-MM-DD for date fields"}]}}},"security":[{"bearerAuth":[]},{"apiKey":[]}],"tags":[{"name":"Authentication","description":"User authentication and session management"},{"name":"Escrows","description":"Real estate transaction management"},{"name":"Listings","description":"Property inventory and marketing"},{"name":"Clients","description":"Contact and relationship management"},{"name":"Appointments","description":"Calendar and scheduling"},{"name":"Leads","description":"Lead qualification and conversion"},{"name":"Contacts","description":"Contact database — people and vendors across all transactions"},{"name":"Webhooks","description":"Outbound webhook subscriptions for event notifications"},{"name":"Billing","description":"Subscription plans, checkout, and billing management"},{"name":"API Keys","description":"API key management for external integrations"},{"name":"AI","description":"AI-powered natural language query interface"},{"name":"Health","description":"System health and monitoring endpoints"}],"x-ai-integration":{"anthropic":{"enabled":true,"models":["claude-opus-5","claude-sonnet-5","claude-haiku-4-5-20251001"],"tool_use":true,"mcp_server":{"available":true,"location":"apps/mcp/","description":"Standalone MCP server for Claude Desktop integration"},"embeddings":{"provider":"voyage-ai","model":"voyage-3.5-lite","description":"Voyage AI embeddings for semantic search and clustering"}},"considerations":{"rate_limits":"AI endpoints have stricter rate limits (10/min production, 50/min development)","authentication":"Use X-API-Key header for AI agent authentication","best_practices":["Use operationId for function naming consistency","Check x-consequential before write operations","Implement retry logic for rate limit errors","Cache OpenAPI spec locally to reduce fetches"]}},"paths":{"/billing/public-plans":{"get":{"operationId":"getPublicPlans","summary":"Get public plan pricing","description":"Returns the current subscription plans with pricing in cents. This endpoint requires no authentication and is the source of truth for pricing shown on the marketing site. Responses are cacheable (5 minutes in browsers, 1 hour at the CDN edge).","tags":["Billing"],"security":[],"responses":{"200":{"description":"Available plans","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"plans":{"type":"array","items":{"$ref":"#/components/schemas/PublicPlan"}},"currency":{"type":"string","example":"usd"},"version":{"type":"string","description":"Pricing version date"}}}}}}}},"429":{"$ref":"#/components/responses/RateLimitError"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/billing/public-checkout":{"post":{"operationId":"createPublicCheckout","summary":"Start checkout without an account","description":"Creates a Stripe Checkout session for a new customer who doesn't have an account yet. Only the agent plan is available through this endpoint; team and brokerage subscriptions require an account and the authenticated checkout endpoint. Returns the Stripe-hosted checkout URL to redirect the visitor to.","tags":["Billing"],"x-consequential":true,"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","description":"Email address for the new customer and Stripe Checkout session"},"planKey":{"type":"string","enum":["agent"],"default":"agent","description":"Subscription plan tier (only agent is available without an account)"},"interval":{"type":"string","enum":["monthly","yearly"],"default":"monthly","description":"Billing interval (defaults to monthly)"}}}}}},"responses":{"200":{"description":"Checkout session created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"url":{"type":"string","description":"Stripe-hosted checkout page to redirect to"},"sessionId":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimitError"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/billing/plans":{"get":{"operationId":"getBillingPlans","summary":"Get plans with checkout identifiers","description":"Returns the subscription plans for the in-app billing page. Same plans as the public endpoint, plus the identifiers needed to start an authenticated checkout. Prices here are in dollars.","tags":["Billing"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Available plans","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","enum":["agent","te
# --- truncated at 32 KB (126 KB total) ---
# Full source: https://artifacts.apis.io/actuallycare-com/openapi/_original/actuallycare-com-v1-openapi.json