{"openapi":"3.1.0","info":{"title":"Zapitra API","version":"1.0.0","description":"Business intelligence APIs for your software. Four APIs share one key, one account, and one account-level monthly record allowance: Lead Recovery (prioritize stale leads), Reconciliation (compare datasets), Verification (check claims against evidence), and Revenue Leakage (detect commercial discrepancies). Every financial conclusion traces to supplied numeric evidence; customer text is always treated as data. Zapitra.","contact":{"name":"Zapitra","url":"https://www.zapitra.com"}},"servers":[{"url":"https://www.zapitra.com","description":"Production"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"tags":[{"name":"Data Preparation","description":"Deterministic normalization, matching, comparison, and deduplication"},{"name":"Intelligence","description":"Anomaly detection, scoring, and explanation"},{"name":"Orchestration","description":"Run multiple operations over one payload"},{"name":"Lead Recovery","description":"Lead recovery scoring"},{"name":"Reconciliation","description":"Dataset reconciliation and financial exposure"},{"name":"Verification","description":"Claim verification against supplied evidence"},{"name":"Revenue Leakage","description":"Revenue-leakage detection across commercial records"},{"name":"System","description":"Health and status"}],"paths":{"/api/v1/normalize":{"post":{"tags":["Data Preparation"],"summary":"Normalize messy business fields","description":"Standardizes names, companies, emails, phones, dates, currencies, and monetary values into consistent structured values. Returns both the original and normalized value for every field. Deterministic; no AI. Cost: 1 credit per record.","operationId":"normalize","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"description":"A single record object, or an array of records (max 1000).","oneOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{"type":"object","additionalProperties":true}}]},"types":{"type":"object","additionalProperties":{"type":"string","enum":["auto","string","company","email","phone","number","currency","date"]},"description":"Optional per-field normalization strategy. Inferred from the field name when omitted."}}},"examples":{"singleRecord":{"summary":"Normalize one record","value":{"data":{"company":" ACME, INC. ","amount":"$1,245.00","date":"9/6/26"}}}}}}},"responses":{"200":{"description":"Normalized record(s)","content":{"application/json":{"schema":{"type":"object"},"examples":{"singleRecord":{"summary":"Normalized output","value":{"request_id":"req_9f2c1a7b3e5d4c8f0a1b2c3d","normalized":{"company":"acme","amount":1245,"date":"2026-09-06"},"fields":{"company":{"original":" ACME, INC. ","normalized":"acme","type":"company","changed":true}},"usage":{"credits_used":1,"credits_remaining":998}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/match":{"post":{"tags":["Data Preparation"],"summary":"Match two records","description":"Determines whether two records represent the same underlying entity or transaction, with a weighted, per-field explanation and a 0..1 confidence. Deterministic; no AI. Cost: 1 credit.","operationId":"match","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["left","right"],"properties":{"left":{"type":"object","additionalProperties":true},"right":{"type":"object","additionalProperties":true},"threshold":{"type":"number","minimum":0,"maximum":1,"description":"Match cutoff (default 0.85)."},"weights":{"type":"object","additionalProperties":{"type":"number"},"description":"Per-field weight overrides."}}},"examples":{"customer":{"summary":"Two customer records","value":{"left":{"customer_name":"Acme Incorporated","email":"billing@acme.com","invoice_number":"INV-1002"},"right":{"customer_name":"ACME Inc.","email":"billing@acme.com","invoice_number":"INV1002"}}}}}}},"responses":{"200":{"description":"Match result","content":{"application/json":{"schema":{"type":"object"},"examples":{"matched":{"summary":"Records represent the same customer","value":{"request_id":"req_9f2c1a7b3e5d4c8f0a1b2c3d","match":true,"confidence":0.97,"threshold":0.85,"matched_fields":["customer_name","email","invoice_number"],"different_fields":[],"reasons":["email matches (normalized)","customer_name is highly similar (0.94)"],"usage":{"credits_used":1,"credits_remaining":998}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/compare":{"post":{"tags":["Data Preparation"],"summary":"Compare two records","description":"Returns deterministic field-level differences between two records, including signed deltas for numeric fields and distinct missing-field classification. Cost: 1 credit.","operationId":"compare","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["left","right"],"properties":{"left":{"type":"object","additionalProperties":true},"right":{"type":"object","additionalProperties":true}}},"examples":{"amounts":{"summary":"Compare two invoice amounts","value":{"left":{"amount":1250,"status":"open"},"right":{"amount":1200,"status":"open"}}}}}}},"responses":{"200":{"description":"Comparison result","content":{"application/json":{"schema":{"type":"object"},"examples":{"diff":{"summary":"One amount differs","value":{"request_id":"req_9f2c1a7b3e5d4c8f0a1b2c3d","equal":false,"differences":[{"field":"amount","left":1250,"right":1200,"kind":"amount_changed","difference":-50}],"fields_compared":2,"fields_equal":1,"usage":{"credits_used":1,"credits_remaining":998}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/dedupe":{"post":{"tags":["Data Preparation"],"summary":"Find duplicate records","description":"Finds likely duplicate records within a supplied dataset, grouped transitively with an explanation per group. Identifies only — never merges or deletes. Deterministic; no AI. Cost: 1 credit per record (max 500 records).","operationId":"dedupe","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["records"],"properties":{"records":{"type":"array","items":{"type":"object","additionalProperties":true},"minItems":1,"maxItems":500},"fields":{"type":"array","items":{"type":"string"},"description":"Restrict comparison to these fields."},"threshold":{"type":"number","minimum":0,"maximum":1,"description":"Duplicate cutoff (default 0.9)."},"weights":{"type":"object","additionalProperties":{"type":"number"}}}},"examples":{"customers":{"summary":"Dedupe a small customer list","value":{"records":[{"email":"billing@acme.com","company":"Acme Incorporated"},{"email":"sales@globex.com","company":"Globex"},{"email":"billing@acme.com","company":"ACME Inc."}]}}}}}},"responses":{"200":{"description":"Duplicate groups","content":{"application/json":{"schema":{"type":"object"},"examples":{"found":{"summary":"One duplicate group","value":{"request_id":"req_9f2c1a7b3e5d4c8f0a1b2c3d","duplicate_groups":[{"records":[0,2],"confidence":0.96,"reasons":["email matches","company matches"]}],"summary":{"records_checked":3,"possible_duplicates":2,"groups":1},"usage":{"credits_used":3,"credits_remaining":997}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/anomalies":{"post":{"tags":["Intelligence"],"summary":"Detect anomalous records","description":"Flags unusual or inconsistent records using robust statistics (median/MAD outliers), coverage-based missing values, rare categorical values, currency inconsistency, and possible duplicates. Neutral language; every anomaly cites evidence. Deterministic; no AI. Cost: 3 credits; metered per record (max 1000).","operationId":"anomalies","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["records"],"properties":{"records":{"type":"array","items":{"type":"object","additionalProperties":true},"minItems":1,"maxItems":1000},"fields":{"type":"array","items":{"type":"string"},"description":"Restrict checks to these fields."},"zThreshold":{"type":"number","minimum":1,"maximum":20,"description":"Modified z-score cutoff (default 3.5)."}}},"examples":{"invoices":{"summary":"Invoice list with one outlier","value":{"records":[{"id":"INV-1","amount":100,"currency":"USD"},{"id":"INV-2","amount":105,"currency":"USD"},{"id":"INV-3","amount":98000,"currency":"USD"}]}}}}}},"responses":{"200":{"description":"Detected anomalies","content":{"application/json":{"schema":{"type":"object"},"examples":{"outlier":{"summary":"One amount outlier","value":{"request_id":"req_9f2c1a7b3e5d4c8f0a1b2c3d","anomalies":[{"type":"amount_outlier","severity":"high","confidence":0.93,"record_index":2,"field":"amount","explanation":"amount of 98000 is 950.5x the median (103) for comparable records.","evidence":{"field":"amount","value":98000,"median":103,"modified_z_score":41.2}}],"summary":{"records_analyzed":3,"anomalies_found":1,"by_type":{"amount_outlier":1}},"usage":{"credits_used":3,"credits_remaining":997}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/score":{"post":{"tags":["Intelligence"],"summary":"Score a finding or factors","description":"Assigns an explainable 0..1 score (with a low/medium/high level) from either explicit weighted factors or a Zapitra finding. Every score is backed by the factors that produced it. Deterministic. Cost: 1 credit.","operationId":"score","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"score_type":{"type":"string","enum":["match_confidence","finding_confidence","anomaly_confidence","reconciliation_confidence","data_quality","review_priority","generic"]},"factors":{"type":"array","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"number","minimum":0,"maximum":1},"weight":{"type":"number","minimum":0},"note":{"type":"string"}}}},"finding":{"type":"object","additionalProperties":true,"description":"A Zapitra finding to derive factors from."}},"description":"Provide either `factors` or a `finding`."},"examples":{"factors":{"summary":"Score from explicit factors","value":{"score_type":"match_confidence","factors":[{"name":"email_match","value":1,"weight":2,"note":"Email matches exactly"},{"name":"name_similarity","value":0.9,"note":"Names are highly similar"}]}}}}}},"responses":{"200":{"description":"Score result","content":{"application/json":{"schema":{"type":"object"},"examples":{"high":{"summary":"High-confidence score","value":{"request_id":"req_9f2c1a7b3e5d4c8f0a1b2c3d","score":0.97,"level":"high","score_type":"match_confidence","reasons":["Email matches exactly (100%, weight 2)","Names are highly similar (90%)"],"usage":{"credits_used":1,"credits_remaining":998}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/explain":{"post":{"tags":["Intelligence"],"summary":"Explain a finding","description":"Produces a plain-English explanation of a Zapitra finding, referencing ONLY the evidence present on the supplied finding — it never invents evidence, and states explicitly when evidence is missing. Deterministic. Cost: 1 credit.","operationId":"explain","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["finding"],"properties":{"finding":{"type":"object","additionalProperties":true,"description":"A finding from reconcile, verify, match, dedupe, anomalies, revenue-leak, or score."}}},"examples":{"conflict":{"summary":"Explain an amount conflict","value":{"finding":{"result":"conflict","confidence":0.94,"evidence":[{"field":"amount","expected":12500,"actual":11750}]}}}}}}},"responses":{"200":{"description":"Explanation","content":{"application/json":{"schema":{"type":"object"},"examples":{"explained":{"summary":"Explanation with evidence","value":{"request_id":"req_9f2c1a7b3e5d4c8f0a1b2c3d","explanation":"This result was classified as \"conflict\". For amount, the expected value was 12500 while the actual value was 11750. Confidence in this result is 94%.","evidence":[{"field":"amount","expected":12500,"actual":11750}],"fields":["amount"],"confidence":0.94,"missing_evidence":[],"alternative_explanations":[],"recommended_next_step":"Evidence supports this result; no further review is required.","usage":{"credits_used":1,"credits_remaining":998}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/analyze":{"post":{"tags":["Orchestration"],"summary":"Run multiple operations","description":"Runs several Zapitra operations over one payload, reusing the same service logic as the dedicated endpoints. Operations run independently (partial failure is reported per-operation) and only operations that actually executed are charged. Supported operations: normalize, match, compare, dedupe, anomalies, reconcile. Cost: the combined credit cost of the operations that ran.","operationId":"analyze","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["operations","data"],"properties":{"operations":{"type":"array","minItems":1,"maxItems":12,"items":{"type":"string","enum":["normalize","match","compare","dedupe","anomalies","reconcile"]}},"data":{"type":"object","properties":{"records":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Dataset for normalize/dedupe/anomalies."},"left":{"description":"Record or array of records (match/compare/reconcile)."},"right":{"description":"Record or array of records (match/compare/reconcile)."}}},"options":{"type":"object","additionalProperties":true,"description":"Per-operation options keyed by operation name."}}},"examples":{"prepAndInspect":{"summary":"Normalize, dedupe, and scan for anomalies in one call","value":{"operations":["normalize","dedupe","anomalies"],"data":{"records":[{"email":"a@acme.com","company":"Acme Inc","amount":100},{"email":"a@acme.com","company":"ACME Incorporated","amount":100},{"email":"b@globex.com","company":"Globex","amount":100000}]}}}}}}},"responses":{"200":{"description":"Combined results","content":{"application/json":{"schema":{"type":"object"},"examples":{"combined":{"summary":"Three operations executed","value":{"request_id":"req_9f2c1a7b3e5d4c8f0a1b2c3d","results":{"normalize":{"normalized":[],"fields":[]},"dedupe":{"duplicate_groups":[{"records":[0,1],"confidence":0.95,"reasons":["email matches"]}],"summary":{"records_checked":3,"possible_duplicates":2,"groups":1}},"anomalies":{"anomalies":[{"type":"amount_outlier","severity":"high","confidence":0.9,"record_index":2,"field":"amount","explanation":"amount is far above the median.","evidence":{}}],"summary":{"records_analyzed":3,"anomalies_found":1,"by_type":{"amount_outlier":1}}}},"operations_run":["normalize","dedupe","anomalies"],"summary":{"requested":3,"succeeded":3,"failed":0,"records_processed":3},"usage":{"credits_used":5,"credits_remaining":995}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/leads/recovery":{"post":{"tags":["Lead Recovery"],"summary":"Score a single lead","description":"Analyze a single lead (or a { leads: [] } batch as a convenience) and return a Recovery Score with a recommended next action.","operationId":"recoverLead","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadInput"},"examples":{"single":{"summary":"High-value roofing estimate","value":{"lead_id":"lead_123","industry":"roofing","status":"estimate_sent","lead_age_days":28,"last_contact_days":19,"estimate_value":12000,"explicit_rejection":false}}}}}},"responses":{"200":{"description":"Recovery result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecoveryResult"},"examples":{"highPriority":{"summary":"High-priority follow-up","value":{"request_id":"req_9f2c1a7b3e5d4c8f0a1b2c3d","lead_id":"lead_123","recovery_score":78,"priority":"high","recommended_action":"follow_up","recommended_channel":"phone","recommended_timing":"today","reason":"High-value estimate sent 19 days ago with no explicit rejection.","confidence":0.82,"scoring_version":"1.0.0"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/leads/recovery/batch":{"post":{"tags":["Lead Recovery"],"summary":"Score a batch of leads","description":"Analyze up to 1000 leads and return per-lead results plus an aggregated summary.","operationId":"recoverLeadsBatch","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchInput"}}}},"responses":{"200":{"description":"Batch recovery result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResult"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/reconcile":{"post":{"tags":["Reconciliation"],"summary":"Reconcile two datasets","description":"Compare two datasets (e.g. CRM vs billing) using configurable primary/secondary keys and comparison fields. Returns exact/probable/unmatched classifications, conflicts, duplicates, needs_review items, and evidence-backed financial exposure. Metered by total records processed (source_a + source_b).","operationId":"reconcile","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReconcileInput"},"examples":{"crmVsInvoices":{"summary":"CRM opportunities vs issued invoices","value":{"source_a":{"name":"crm","records":[{"email":"acme@example.com","customer":"Acme Co","amount":25000,"status":"won"}]},"source_b":{"name":"billing","records":[{"email":"acme@example.com","customer":"Acme Co","amount":22000,"status":"paid"}]},"matching":{"primary_keys":["email"],"secondary_keys":["customer"],"compare_fields":["amount","status"],"amount_field":"amount"}}}}}}},"responses":{"200":{"description":"Reconciliation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReconcileResult"},"examples":{"amountConflict":{"summary":"Matched on email with an amount conflict","value":{"request_id":"req_9f2c1a7b3e5d4c8f0a1b2c3d","status":"completed","summary":{"source_a_name":"crm","source_b_name":"billing","source_a_count":1,"source_b_count":1,"records_processed":2,"exact_matches":0,"probable_matches":0,"conflicts":1,"duplicates":0,"unmatched_source_a":0,"unmatched_source_b":0,"needs_review":1,"processing_time_ms":3},"financial_exposure":{"field":"amount","currency":null,"net_difference":3000,"absolute_exposure":3000,"items":[]},"usage":{"records_processed":2}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/verify":{"post":{"tags":["Verification"],"summary":"Verify a claim against evidence","description":"Determine whether a claim is supported by supplied evidence. Deterministic (no LLM required); customer text is treated strictly as data and injection attempts are ignored. Returns verified | unsupported | contradicted | insufficient_evidence with the supporting/contradicting evidence and a confidence score.","operationId":"verify","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyInput"},"examples":{"verifiedBalance":{"summary":"A balance claim confirmed by an invoice amount","value":{"claim":"Customer owes $47,250","evidence":[{"source":"billing","record_id":"inv_881","field":"amount","value":47250}]}}}}}},"responses":{"200":{"description":"Verification result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyResult"},"examples":{"verified":{"summary":"Claim supported by evidence","value":{"request_id":"req_9f2c1a7b3e5d4c8f0a1b2c3d","result":"verified","supported":true,"confidence":1,"evidence":[{"source":"billing","record_id":"inv_881","field":"amount","value":47250}],"contradictions":[],"missing_evidence":[],"injection_detected":false,"reasoning":"Claimed balance matches the supplied invoice amount exactly."}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/revenue-leak":{"post":{"tags":["Revenue Leakage"],"summary":"Detect possible revenue leakage","description":"Analyze orders, invoices, payments, and credits for possible revenue leakage: missing invoices, amount mismatches, underpayments, duplicates, and status conflicts. Every monetary conclusion traces to supplied numbers; exposure is reported cautiously as potential vs verified.","operationId":"revenueLeak","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevenueLeakInput"},"examples":{"orderWithoutInvoice":{"summary":"A won order that was never invoiced","value":{"orders":[{"order_id":"ORD-1","amount":18000,"status":"won"}],"invoices":[],"payments":[]}}}}}},"responses":{"200":{"description":"Revenue-leak analysis result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevenueLeakResult"},"examples":{"missingInvoice":{"summary":"A won order that was never invoiced","value":{"request_id":"req_9f2c1a7b3e5d4c8f0a1b2c3d","status":"completed","summary":{"records_analyzed":1,"findings":1,"processing_time_ms":2},"financial_exposure":{"potential":18000,"verified":0,"currency":null},"findings":[{"type":"missing_invoice","message":"Order ORD-1 is marked won but has no matching invoice.","monetary_class":"potential","amount":18000,"currency":null,"confidence":0.9,"evidence":[{"source":"orders","record_id":"ORD-1","field":"amount","value":18000}],"challenges":[]}]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/usage":{"get":{"tags":["System"],"summary":"Get current usage","description":"Returns the calling workspace's authoritative monthly record usage, plan allowance, billing window, and a per-API records breakdown. Read-only: never metered and never blocked by the record quota.","operationId":"getUsage","responses":{"200":{"description":"Current usage snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"401":{"$ref":"#/components/responses/Error"}}}},"/api/health":{"get":{"tags":["System"],"summary":"Health check","description":"Unauthenticated liveness/readiness probe. Returns service status and non-sensitive config readiness (names only, never secret values). Not billable.","operationId":"getHealth","security":[],"responses":{"200":{"description":"Service health","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"Service degraded (e.g. database unavailable)","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Provide your API key as a Bearer token: `Authorization: Bearer zap_live_...`"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Zapitra-Key","description":"Alternate to Bearer auth: send your API key in the `X-Zapitra-Key` header."}},"schemas":{"LeadInput":{"type":"object","required":["status","lead_age_days"],"properties":{"lead_id":{"type":"string","maxLength":200,"description":"Your identifier, echoed back on the response."},"industry":{"type":"string","enum":["hvac","plumbing","electrical","roofing","automotive","b2b_sales","generic"],"default":"generic"},"status":{"type":"string","enum":["new","contacted","quote_requested","estimate_sent","proposal_sent","negotiating","no_response","closed_won","closed_lost","opted_out"]},"lead_age_days":{"type":"integer","minimum":0,"description":"Days since the lead was created."},"last_contact_days":{"type":"integer","minimum":0},"contact_attempts":{"type":"integer","minimum":0},"estimate_value":{"type":"number","minimum":0},"source":{"type":"string","maxLength":120},"explicit_rejection":{"type":"boolean"},"opted_out":{"type":"boolean"},"previous_customer":{"type":"boolean"},"prior_engagement":{"type":"boolean"},"invalid_contact":{"type":"boolean"},"duplicate":{"type":"boolean"},"closed_lost_reason":{"type":"string","maxLength":500},"repeat_service":{"type":"boolean"},"first_name":{"type":"string","maxLength":120}}},"BatchInput":{"type":"object","required":["leads"],"properties":{"leads":{"type":"array","minItems":1,"maxItems":1000,"items":{"$ref":"#/components/schemas/LeadInput"}}}},"RecoveryResult":{"type":"object","properties":{"request_id":{"type":"string"},"lead_id":{"type":["string","null"]},"recovery_score":{"type":"integer","minimum":0,"maximum":100},"priority":{"type":"string","enum":["high","medium","low"]},"recommended_action":{"type":"string","enum":["follow_up","nurture","deprioritize","archive"]},"recommended_channel":{"type":"string","enum":["sms","email","phone","none"]},"recommended_timing":{"type":"string","enum":["today","this_week","this_month","none"]},"reason":{"type":"string"},"suggested_message":{"type":"string"},"confidence":{"type":"number","minimum":0,"maximum":1},"factors":{"type":"array","items":{"type":"object","properties":{"factor":{"type":"string"},"impact":{"type":"string","enum":["positive","negative","neutral"]},"score_effect":{"type":"integer"},"detail":{"type":"string"}}}},"scoring_version":{"type":"string"}}},"ReconcileInput":{"type":"object","required":["source_a","source_b","matching"],"properties":{"source_a":{"$ref":"#/components/schemas/ReconcileSource"},"source_b":{"$ref":"#/components/schemas/ReconcileSource"},"matching":{"type":"object","required":["primary_keys"],"properties":{"primary_keys":{"type":"array","items":{"type":"string"},"minItems":1},"secondary_keys":{"type":"array","items":{"type":"string"}},"compare_fields":{"type":"array","items":{"type":"string"}},"amount_field":{"type":"string","description":"Field used to compute financial exposure."},"date_fields":{"type":"array","items":{"type":"string"}},"status_fields":{"type":"array","items":{"type":"string"}}}}}},"ReconcileSource":{"type":"object","required":["name","records"],"properties":{"name":{"type":"string"},"records":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"ReconcileResult":{"type":"object","properties":{"request_id":{"type":"string"},"status":{"type":"string","enum":["completed"]},"summary":{"type":"object","properties":{"source_a_name":{"type":"string"},"source_b_name":{"type":"string"},"source_a_count":{"type":"integer"},"source_b_count":{"type":"integer"},"records_processed":{"type":"integer"},"exact_matches":{"type":"integer"},"probable_matches":{"type":"integer"},"conflicts":{"type":"integer"},"duplicates":{"type":"integer"},"unmatched_source_a":{"type":"integer"},"unmatched_source_b":{"type":"integer"},"needs_review":{"type":"integer"},"processing_time_ms":{"type":"integer"}}},"matches":{"type":"array","items":{"type":"object","properties":{"classification":{"type":"string","enum":["exact_match","probable_match","unmatched","conflict","duplicate","needs_review"]},"confidence":{"type":"number","minimum":0,"maximum":1},"matched_on":{"type":"string","enum":["primary","secondary","none"]},"keys":{"type":"array","items":{"type":"string"}},"key_value":{"type":["string","null"]},"source_a_index":{"type":["integer","null"]},"source_b_index":{"type":["integer","null"]},"field_diffs":{"type":"array","items":{"type":"object"}}}}},"findings":{"type":"array","items":{"type":"object"}},"financial_exposure":{"type":["object","null"],"properties":{"field":{"type":"string"},"currency":{"type":["string","null"]},"net_difference":{"type":"number"},"absolute_exposure":{"type":"number"},"items":{"type":"array","items":{"type":"object"}}}},"usage":{"type":"object","properties":{"records_processed":{"type":"integer"}}}}},"BatchResult":{"type":"object","properties":{"request_id":{"type":"string"},"results":{"type":"array","items":{"$ref":"#/components/schemas/RecoveryResult"}},"summary":{"type":"object","properties":{"total_leads":{"type":"integer"},"high_priority_count":{"type":"integer"},"medium_priority_count":{"type":"integer"},"low_priority_count":{"type":"integer"},"total_pipeline_value":{"type":"number"},"high_priority_pipeline_value":{"type":"number"},"processing_time_ms":{"type":"integer"}}}}},"VerifyInput":{"type":"object","required":["claim"],"properties":{"claim":{"type":"string","maxLength":5000,"description":"The claim to verify. Treated as data, never as instructions."},"evidence":{"type":"array","description":"Supplied evidence items. Only these values are ever used; nothing is fabricated.","items":{"type":"object","required":["value"],"properties":{"source":{"type":"string"},"record_id":{"type":["string","null"]},"field":{"type":"string"},"value":{}}}}}},"VerifyResult":{"type":"object","properties":{"request_id":{"type":"string"},"result":{"type":"string","enum":["verified","unsupported","contradicted","insufficient_evidence"]},"supported":{"type":"boolean"},"confidence":{"type":"number","minimum":0,"maximum":1},"evidence":{"type":"array","items":{"type":"object"}},"contradictions":{"type":"array","items":{"type":"object"}},"missing_evidence":{"type":"array","items":{"type":"string"}},"injection_detected":{"type":"boolean","description":"True when injection-like content was seen and ignored."},"reasoning":{"type":"string"}}},"RevenueLeakInput":{"type":"object","description":"Provide at least one of orders, invoices, payments, or credits.","properties":{"orders":{"type":"array","items":{"type":"object","additionalProperties":true}},"invoices":{"type":"array","items":{"type":"object","additionalProperties":true}},"payments":{"type":"array","items":{"type":"object","additionalProperties":true}},"credits":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"RevenueLeakResult":{"type":"object","properties":{"request_id":{"type":"string"},"status":{"type":"string","enum":["completed"]},"summary":{"type":"object","properties":{"records_analyzed":{"type":"integer"},"findings":{"type":"integer"},"processing_time_ms":{"type":"integer"}}},"financial_exposure":{"type":["object","null"],"properties":{"potential":{"type":"number"},"verified":{"type":"number"},"currency":{"type":["string","null"]}}},"findings":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"},"monetary_class":{"type":["string","null"]},"amount":{"type":["number","null"]},"currency":{"type":["string","null"]},"confidence":{"type":"number"},"evidence":{"type":"array","items":{"type":"object"}},"challenges":{"type":"array","items":{"type":"string"}}}}}}},"Error":{"type":"object","required":["error"],"description":"Standard error envelope returned by every endpoint. `code` is a stable machine-readable string; `request_id` should be quoted in support requests.","properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_request","invalid_json","payload_too_large","unauthorized","invalid_api_key","revoked_api_key","forbidden","not_found","conflict","usage_limit_exceeded","rate_limit_exceeded","internal_error"]},"message":{"type":"string"},"request_id":{"type":"string","example":"req_9f2c1a7b3e5d4c8f0a1b2c3d"},"details":{"type":"object","description":"Optional structured context. For usage_limit_exceeded this carries records_used, records_limit, records_remaining, upgrade_required, and recommended_plan.","additionalProperties":true}}}}},"Usage":{"type":"object","properties":{"plan":{"type":"string","example":"free"},"period":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}},"usage":{"type":"object","properties":{"records_used":{"type":"integer","example":420},"records_limit":{"type":"integer","example":1000},"records_remaining":{"type":"integer","example":580},"percentage":{"type":"number","example":42}}},"by_api":{"type":"object","additionalProperties":{"type":"integer"},"description":"Records processed this period, keyed by product code."}}}},"responses":{"Error":{"description":"Standard error envelope with a request_id for support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"summary":"Missing or invalid API key","value":{"error":{"code":"unauthorized","message":"Missing API key. Provide it as `Authorization: Bearer <key>` or an `X-Zapitra-Key: <key>` header.","request_id":"req_9f2c1a7b3e5d4c8f0a1b2c3d"}}},"usageLimit":{"summary":"Monthly record allowance exceeded","value":{"error":{"code":"usage_limit_exceeded","message":"This request would exceed your monthly record allowance.","request_id":"req_9f2c1a7b3e5d4c8f0a1b2c3d","details":{"code":"MONTHLY_RECORD_LIMIT_REACHED","records_used":1000,"records_requested":5,"records_limit":1000,"records_remaining":0,"upgrade_required":true,"recommended_plan":"developer"}}}},"rateLimit":{"summary":"Burst rate limit exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"Too many requests. Slow down and retry shortly.","request_id":"req_9f2c1a7b3e5d4c8f0a1b2c3d"}}}}}}}}}}