{"openapi":"3.1.0","info":{"title":"address.bot API","version":"0.1.0","description":"Create postcard address verifications, test them in sandbox, and receive signed webhook events when recipients confirm mailed codes."},"servers":[{"url":"https://address.bot"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"Use `Bearer sk_test_...` for sandbox and `Bearer sk_live_...` for live mail."}},"schemas":{"AccountIntentRequest":{"type":"object","properties":{"owner_email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"business_name":{"type":"string","minLength":1,"maxLength":120},"onboarding_intent":{"type":"string","enum":["human_dashboard","agent_api","hybrid"]},"primary_use_case":{"type":"string","minLength":1,"maxLength":500},"webhook_url":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"metadata":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]}},"required":["owner_email","business_name","onboarding_intent","primary_use_case"]},"BillingSummary":{"type":"object","properties":{"object":{"type":"string","const":"billing_summary"},"mode":{"type":"string","enum":["test","live"]},"billing_configured":{"type":"boolean"},"billing_mode":{"anyOf":[{"type":"string","enum":["manual_invoice","auto_charge","credits"]},{"type":"null"}]},"balance_cents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"billing_email":{"anyOf":[{"type":"string"},{"type":"null"}]},"stripe_configured":{"type":"boolean"},"stripe_customer_configured":{"type":"boolean"},"default_payment_method_configured":{"type":"boolean"},"auto_charge_ready":{"type":"boolean"},"live_first_send_approved_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"live_per_request_cap_cents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"live_monthly_budget_cents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["object","mode","billing_configured","billing_mode","balance_cents","billing_email","stripe_configured","stripe_customer_configured","default_payment_method_configured","auto_charge_ready","live_first_send_approved_at","live_per_request_cap_cents","live_monthly_budget_cents"]},"CreateVerificationRequest":{"type":"object","properties":{"request_type":{"default":"address_confirmation","type":"string","enum":["address_confirmation","photo_required","video_walkthrough","property_condition","custom_media"]},"recipient":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"line1":{"type":"string","minLength":1,"maxLength":120},"line2":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"city":{"type":"string","minLength":1,"maxLength":80},"region":{"type":"string","minLength":1,"maxLength":80},"postal_code":{"type":"string","minLength":1,"maxLength":20},"country":{"default":"US","type":"string","minLength":2,"maxLength":2}},"required":["name","line1","city","region","postal_code"]},"instructions":{"anyOf":[{"type":"string","maxLength":1500},{"type":"null"}]},"recipient_message":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"evidence":{"default":[],"maxItems":10,"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["photo","video","note","signature","checkbox","code"]},"label":{"type":"string","minLength":1,"maxLength":120},"help_text":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"required":{"default":true,"type":"boolean"},"max_files":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":25},{"type":"null"}]},"max_size_mb":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":500},{"type":"null"}]}},"required":["kind","label"]}},"reference":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"metadata":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"tranche_key":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"qr_variant":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}]},"dry_run":{"default":false,"type":"boolean"}},"required":["recipient"]},"PreflightRequest":{"type":"object","properties":{"request_type":{"default":"address_confirmation","type":"string","enum":["address_confirmation","photo_required","video_walkthrough","property_condition","custom_media"]},"recipient":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"line1":{"type":"string","minLength":1,"maxLength":120},"line2":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"city":{"type":"string","minLength":1,"maxLength":80},"region":{"type":"string","minLength":1,"maxLength":80},"postal_code":{"type":"string","minLength":1,"maxLength":20},"country":{"default":"US","type":"string","minLength":2,"maxLength":2}},"required":["name","line1","city","region","postal_code"]},"instructions":{"anyOf":[{"type":"string","maxLength":1500},{"type":"null"}]},"recipient_message":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"evidence":{"default":[],"maxItems":10,"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["photo","video","note","signature","checkbox","code"]},"label":{"type":"string","minLength":1,"maxLength":120},"help_text":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"required":{"default":true,"type":"boolean"},"max_files":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":25},{"type":"null"}]},"max_size_mb":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":500},{"type":"null"}]}},"required":["kind","label"]}},"reference":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"metadata":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"tranche_key":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"qr_variant":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}]}},"required":["recipient"]},"PreflightResponse":{"type":"object","properties":{"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)$"},"object":{"type":"string","const":"preflight"},"mode":{"type":"string","enum":["test","live"]},"request_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expires_at":{"type":"string"},"normalized_request":{"type":"object","properties":{"request_type":{"default":"address_confirmation","type":"string","enum":["address_confirmation","photo_required","video_walkthrough","property_condition","custom_media"]},"recipient":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"line1":{"type":"string","minLength":1,"maxLength":120},"line2":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"city":{"type":"string","minLength":1,"maxLength":80},"region":{"type":"string","minLength":1,"maxLength":80},"postal_code":{"type":"string","minLength":1,"maxLength":20},"country":{"default":"US","type":"string","minLength":2,"maxLength":2}},"required":["name","line1","city","region","postal_code"]},"instructions":{"anyOf":[{"type":"string","maxLength":1500},{"type":"null"}]},"recipient_message":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"evidence":{"default":[],"maxItems":10,"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["photo","video","note","signature","checkbox","code"]},"label":{"type":"string","minLength":1,"maxLength":120},"help_text":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"required":{"default":true,"type":"boolean"},"max_files":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":25},{"type":"null"}]},"max_size_mb":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":500},{"type":"null"}]}},"required":["kind","label"]}},"reference":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"metadata":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"tranche_key":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"qr_variant":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}]}},"required":["recipient"]},"currency":{"type":"string","const":"usd"},"subtotal_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"estimated_total_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"committed":{"type":"boolean"},"confirmation_status":{"type":"string","enum":["pending","confirmed"]}},"required":["id","object","mode","request_count","expires_at","normalized_request","currency","subtotal_cents","estimated_total_cents","committed","confirmation_status"]},"VerificationPreview":{"type":"object","properties":{"object":{"type":"string","const":"verification_preview"},"mode":{"type":"string","enum":["test","live"]},"test_mode":{"type":"boolean"},"dry_run":{"type":"boolean","const":true},"committed":{"type":"boolean","const":false},"normalized_request":{"type":"object","properties":{"request_type":{"default":"address_confirmation","type":"string","enum":["address_confirmation","photo_required","video_walkthrough","property_condition","custom_media"]},"recipient":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"line1":{"type":"string","minLength":1,"maxLength":120},"line2":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"city":{"type":"string","minLength":1,"maxLength":80},"region":{"type":"string","minLength":1,"maxLength":80},"postal_code":{"type":"string","minLength":1,"maxLength":20},"country":{"default":"US","type":"string","minLength":2,"maxLength":2}},"required":["name","line1","city","region","postal_code"]},"instructions":{"anyOf":[{"type":"string","maxLength":1500},{"type":"null"}]},"recipient_message":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"evidence":{"default":[],"maxItems":10,"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["photo","video","note","signature","checkbox","code"]},"label":{"type":"string","minLength":1,"maxLength":120},"help_text":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"required":{"default":true,"type":"boolean"},"max_files":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":25},{"type":"null"}]},"max_size_mb":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":500},{"type":"null"}]}},"required":["kind","label"]}},"reference":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"metadata":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"tranche_key":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"qr_variant":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}]}},"required":["recipient"]},"currency":{"type":"string","const":"usd"},"line_items":{"type":"array","items":{}},"subtotal_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"estimated_total_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"cost_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"estimated_live_cost_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"warnings":{"type":"array","items":{"type":"string"}}},"required":["object","mode","test_mode","dry_run","committed","normalized_request","currency","line_items","subtotal_cents","estimated_total_cents","cost_cents","estimated_live_cost_cents","warnings"]},"Verification":{"type":"object","properties":{"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)$"},"object":{"type":"string","const":"verification"},"address_state_object_id":{"anyOf":[{"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)$"},{"type":"null"}]},"mode":{"type":"string","enum":["test","live"]},"test_mode":{"type":"boolean"},"status":{"type":"string","enum":["requested","queued_for_print","printed","mailed","delivered","undeliverable","expired"]},"request_type":{"type":"string","enum":["address_confirmation","photo_required","video_walkthrough","property_condition","custom_media"]},"instructions":{"anyOf":[{"type":"string"},{"type":"null"}]},"recipient_message":{"anyOf":[{"type":"string"},{"type":"null"}]},"submission_status":{"type":"string","enum":["not_started","in_progress","submitted","accepted","rejected"]},"batch_id":{"anyOf":[{"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)$"},{"type":"null"}]},"tranche_id":{"anyOf":[{"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)$"},{"type":"null"}]},"tranche_key":{"anyOf":[{"type":"string"},{"type":"null"}]},"qr_variant":{"type":"string"},"reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"recipient":{"type":"object","properties":{"name":{"type":"string"},"line1":{"type":"string"},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"type":"string"},"region":{"type":"string"},"postal_code":{"type":"string"},"country":{"type":"string"}},"required":["name","line1","line2","city","region","postal_code","country"]},"metadata":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"estimated_cost_cents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"actual_cost_cents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string"},"queued_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"printed_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"mailed_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"delivered_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"undeliverable_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"expires_at":{"type":"string"}},"required":["id","object","address_state_object_id","mode","test_mode","status","request_type","instructions","recipient_message","submission_status","batch_id","tranche_id","tranche_key","qr_variant","reference","recipient","metadata","estimated_cost_cents","actual_cost_cents","completed_at","created_at","queued_at","printed_at","mailed_at","delivered_at","undeliverable_at","expires_at"]},"VerificationList":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object","properties":{"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)$"},"object":{"type":"string","const":"verification"},"address_state_object_id":{"anyOf":[{"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)$"},{"type":"null"}]},"mode":{"type":"string","enum":["test","live"]},"test_mode":{"type":"boolean"},"status":{"type":"string","enum":["requested","queued_for_print","printed","mailed","delivered","undeliverable","expired"]},"request_type":{"type":"string","enum":["address_confirmation","photo_required","video_walkthrough","property_condition","custom_media"]},"instructions":{"anyOf":[{"type":"string"},{"type":"null"}]},"recipient_message":{"anyOf":[{"type":"string"},{"type":"null"}]},"submission_status":{"type":"string","enum":["not_started","in_progress","submitted","accepted","rejected"]},"batch_id":{"anyOf":[{"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)$"},{"type":"null"}]},"tranche_id":{"anyOf":[{"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)$"},{"type":"null"}]},"tranche_key":{"anyOf":[{"type":"string"},{"type":"null"}]},"qr_variant":{"type":"string"},"reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"recipient":{"type":"object","properties":{"name":{"type":"string"},"line1":{"type":"string"},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"type":"string"},"region":{"type":"string"},"postal_code":{"type":"string"},"country":{"type":"string"}},"required":["name","line1","line2","city","region","postal_code","country"]},"metadata":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"estimated_cost_cents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"actual_cost_cents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string"},"queued_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"printed_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"mailed_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"delivered_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"undeliverable_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"expires_at":{"type":"string"}},"required":["id","object","address_state_object_id","mode","test_mode","status","request_type","instructions","recipient_message","submission_status","batch_id","tranche_id","tranche_key","qr_variant","reference","recipient","metadata","estimated_cost_cents","actual_cost_cents","completed_at","created_at","queued_at","printed_at","mailed_at","delivered_at","undeliverable_at","expires_at"]}}},"required":["object","data"]},"WebhookPayload":{"type":"object","properties":{"event":{"type":"string","enum":["verification.queued","verification.printed","verification.mailed","verification.delivered","verification.undeliverable","verification.started","verification.media_uploaded","verification.submitted","verification.accepted","verification.rejected","verification.expired"]},"created":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"test_mode":{"type":"boolean"},"data":{"type":"object","properties":{"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)$"},"mode":{"type":"string","enum":["test","live"]},"test_mode":{"type":"boolean"},"status":{"type":"string","enum":["requested","queued_for_print","printed","mailed","delivered","undeliverable","expired"]},"request_type":{"type":"string","enum":["address_confirmation","photo_required","video_walkthrough","property_condition","custom_media"]},"submission_status":{"type":"string","enum":["not_started","in_progress","submitted","accepted","rejected"]},"recipient":{"type":"object","properties":{"name":{"type":"string"},"line1":{"type":"string"},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"type":"string"},"region":{"type":"string"},"postal_code":{"type":"string"},"country":{"type":"string"}},"required":["name","line1","line2","city","region","postal_code","country"]},"reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"metadata":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"estimated_cost_cents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"created_at":{"type":"string"},"delivered_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","mode","test_mode","status","request_type","submission_status","recipient","reference","metadata","estimated_cost_cents","created_at","delivered_at","completed_at"]}},"required":["event","created","test_mode","data"]},"ActionRequiredError":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"},"suggested_action":{"type":"string"},"details":{},"mode":{"type":"string","const":"live"},"required_amount_cents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"preflight_id":{"anyOf":[{"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)$"},{"type":"null"}]},"requires_action":{"type":"object","properties":{"type":{"type":"string"},"endpoint":{"type":"string"},"dashboard_path":{"type":"string"},"api_hint":{"type":"string"}},"required":["type"]}},"required":["error"]},"Error":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"},"suggested_action":{"type":"string"},"details":{}},"required":["error"]},"VerificationMedia":{"type":"object","properties":{"object":{"type":"string","const":"verification_media"},"verification_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)$"},"address_state_object_id":{"anyOf":[{"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)$"},{"type":"null"}]},"mode":{"type":"string","enum":["test","live"]},"status":{"type":"string","enum":["requested","queued_for_print","printed","mailed","delivered","undeliverable","expired"]},"submission_status":{"type":"string","enum":["not_started","in_progress","submitted","accepted","rejected"]},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"completion_payload":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"evidence_requirements":{"type":"array","items":{"type":"object","properties":{"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)$"},"kind":{"type":"string","enum":["photo","video","note","signature","checkbox","code"]},"label":{"type":"string","minLength":1,"maxLength":120},"help_text":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"required":{"type":"boolean"},"max_files":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":25},{"type":"null"}]},"max_size_mb":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":500},{"type":"null"}]},"sort_order":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","kind","label","help_text","required","max_files","max_size_mb","sort_order"]}},"media_assets":{"type":"array","items":{"type":"object","properties":{"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)$"},"requirement_id":{"anyOf":[{"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)$"},{"type":"null"}]},"requirement_label":{"anyOf":[{"type":"string"},{"type":"null"}]},"mime_type":{"type":"string"},"size_bytes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"original_filename":{"anyOf":[{"type":"string"},{"type":"null"}]},"upload_status":{"type":"string","enum":["created","uploaded","rejected","deleted"]},"created_at":{"type":"string"},"uploaded_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"download_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"download_url_expires_at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","requirement_id","requirement_label","mime_type","size_bytes","original_filename","upload_status","created_at","uploaded_at","download_url","download_url_expires_at"]}}},"required":["object","verification_id","address_state_object_id","mode","status","submission_status","completed_at","completion_payload","evidence_requirements","media_assets"]},"VerificationTimeline":{"type":"object","properties":{"object":{"type":"string","const":"verification_timeline"},"verification_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)$"},"address_state_object_id":{"anyOf":[{"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)$"},{"type":"null"}]},"mode":{"type":"string","enum":["test","live"]},"status":{"type":"string","enum":["requested","queued_for_print","printed","mailed","delivered","undeliverable","expired"]},"submission_status":{"type":"string","enum":["not_started","in_progress","submitted","accepted","rejected"]},"latest_task_definition_id":{"anyOf":[{"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)$"},{"type":"null"}]},"latest_task_version":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}]},"task_definitions":{"type":"array","items":{"type":"object","properties":{"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)$"},"evidence_session_id":{"anyOf":[{"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)$"},{"type":"null"}]},"version":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"request_type":{"type":"string","enum":["address_confirmation","photo_required","video_walkthrough","property_condition","custom_media"]},"instructions":{"anyOf":[{"type":"string"},{"type":"null"}]},"recipient_message":{"anyOf":[{"type":"string"},{"type":"null"}]},"evidence_requirements":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["photo","video","note","signature","checkbox","code"]},"label":{"type":"string","minLength":1,"maxLength":120},"help_text":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"required":{"type":"boolean"},"max_files":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":25},{"type":"null"}]},"max_size_mb":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":500},{"type":"null"}]},"sort_order":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["kind","label","help_text","required","max_files","max_size_mb","sort_order"]}},"task_status":{"type":"string","enum":["active","superseded","completed","cancelled"]},"source":{"type":"string","enum":["verification_create","owner_followup","agent_followup","system"]},"metadata":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"created_at":{"type":"string"}},"required":["id","evidence_session_id","version","request_type","instructions","recipient_message","evidence_requirements","task_status","source","metadata","created_at"]}},"task_inputs":{"type":"array","items":{"type":"object","properties":{"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)$"},"evidence_session_id":{"anyOf":[{"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)$"},{"type":"null"}]},"task_definition_id":{"anyOf":[{"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)$"},{"type":"null"}]},"actor_kind":{"type":"string","enum":["system","owner","agent","recipient","staff"]},"input_kind":{"type":"string"},"payload":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"created_at":{"type":"string"}},"required":["id","evidence_session_id","task_definition_id","actor_kind","input_kind","payload","created_at"]}},"evidence_events":{"type":"array","items":{"type":"object","properties":{"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)$"},"evidence_session_id":{"anyOf":[{"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)$"},{"type":"null"}]},"task_definition_id":{"anyOf":[{"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)$"},{"type":"null"}]},"physical_challenge_id":{"anyOf":[{"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)$"},{"type":"null"}]},"actor_kind":{"type":"string","enum":["system","owner","agent","recipient","staff","device","sensor","partner"]},"event_kind":{"type":"string"},"payload":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"created_at":{"type":"string"}},"required":["id","evidence_session_id","task_definition_id","physical_challenge_id","actor_kind","event_kind","payload","created_at"]}}},"required":["object","verification_id","address_state_object_id","mode","status","submission_status","latest_task_definition_id","latest_task_version","task_definitions","task_inputs","evidence_events"]},"FollowOnTaskRequest":{"type":"object","properties":{"request_type":{"default":"address_confirmation","type":"string","enum":["address_confirmation","photo_required","video_walkthrough","property_condition","custom_media"]},"instructions":{"anyOf":[{"type":"string","maxLength":1500},{"type":"null"}]},"recipient_message":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"evidence":{"default":[],"maxItems":10,"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["photo","video","note","signature","checkbox","code"]},"label":{"type":"string","minLength":1,"maxLength":120},"help_text":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"required":{"default":true,"type":"boolean"},"max_files":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":25},{"type":"null"}]},"max_size_mb":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":500},{"type":"null"}]}},"required":["kind","label"]}},"metadata":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]}}},"FollowOnTask":{"type":"object","properties":{"object":{"type":"string","const":"follow_on_task"},"verification_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)$"},"address_state_object_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)$"},"evidence_session_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)$"},"task_definition_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)$"},"version":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"request_type":{"type":"string","enum":["address_confirmation","photo_required","video_walkthrough","property_condition","custom_media"]},"instructions":{"anyOf":[{"type":"string"},{"type":"null"}]},"recipient_message":{"anyOf":[{"type":"string"},{"type":"null"}]},"evidence_requirements":{"type":"array","items":{"type":"object","properties":{"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)$"},"kind":{"type":"string","enum":["photo","video","note","signature","checkbox","code"]},"label":{"type":"string","minLength":1,"maxLength":120},"help_text":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"required":{"type":"boolean"},"max_files":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":25},{"type":"null"}]},"max_size_mb":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":500},{"type":"null"}]},"sort_order":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","kind","label","help_text","required","max_files","max_size_mb","sort_order"]}},"recipient_alert":{"type":"object","properties":{"provider":{"type":"string","const":"agentphone"},"channel":{"type":"string","enum":["phone","sms","mms","imessage","voice"]},"status":{"type":"string","enum":["sent","skipped","failed"]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["provider","channel","status","reason"]},"created_at":{"type":"string"}},"required":["object","verification_id","address_state_object_id","evidence_session_id","task_definition_id","version","request_type","instructions","recipient_message","evidence_requirements","created_at"]},"HermesRunRequest":{"type":"object","properties":{"mode":{"default":"plan","type":"string","enum":["plan","act"]},"goal":{"type":"object","properties":{"kind":{"type":"string","const":"jobsite_daily_evidence"},"total_days":{"default":7,"type":"integer","minimum":1,"maximum":30},"request_type":{"default":"property_condition","type":"string","enum":["address_confirmation","photo_required","video_walkthrough","property_condition","custom_media"]},"require_photo":{"default":true,"type":"boolean"},"require_video":{"default":false,"type":"boolean"},"require_note":{"default":true,"type":"boolean"},"require_signature":{"default":false,"type":"boolean"},"instructions_template":{"anyOf":[{"type":"string","maxLength":1500},{"type":"null"}]},"recipient_message_template":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]}},"required":["kind"]}},"required":["goal"]},"HermesRun":{"type":"object","properties":{"object":{"type":"string","const":"hermes_run"},"verification_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)$"},"address_state_object_id":{"anyOf":[{"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)$"},{"type":"null"}]},"goal_kind":{"type":"string","const":"jobsite_daily_evidence"},"total_days":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"current_day_index":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}]},"days_completed":{"type":"integer","minimum":0,"maximum":9007199254740991},"verification_status":{"type":"string","enum":["requested","queued_for_print","printed","mailed","delivered","undeliverable","expired"]},"submission_status":{"type":"string","enum":["not_started","in_progress","submitted","accepted","rejected"]},"latest_task_definition_id":{"anyOf":[{"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)$"},{"type":"null"}]},"latest_task_version":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}]},"run_mode":{"type":"string","enum":["plan","act"]},"status":{"type":"string","enum":["awaiting_delivery","awaiting_recipient_evidence","ready_for_next_day","completed","operator_attention_required"]},"next_action":{"type":"string","enum":["create_day_task","wait_for_delivery","wait_for_recipient_submission","complete_goal","stop_for_operator"]},"acted":{"type":"boolean"},"current_required_labels":{"type":"array","items":{"type":"string"}},"missing_required_labels":{"type":"array","items":{"type":"string"}},"uploaded_media_count":{"type":"integer","minimum":0,"maximum":9007199254740991},"report":{"type":"string"},"created_task_definition":{"anyOf":[{"type":"object","properties":{"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)$"},"evidence_session_id":{"anyOf":[{"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)$"},{"type":"null"}]},"version":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"request_type":{"type":"string","enum":["address_confirmation","photo_required","video_walkthrough","property_condition","custom_media"]},"instructions":{"anyOf":[{"type":"string"},{"type":"null"}]},"recipient_message":{"anyOf":[{"type":"string"},{"type":"null"}]},"evidence_requirements":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["photo","video","note","signature","checkbox","code"]},"label":{"type":"string","minLength":1,"maxLength":120},"help_text":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"required":{"type":"boolean"},"max_files":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":25},{"type":"null"}]},"max_size_mb":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":500},{"type":"null"}]},"sort_order":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["kind","label","help_text","required","max_files","max_size_mb","sort_order"]}},"task_status":{"type":"string","enum":["active","superseded","completed","cancelled"]},"source":{"type":"string","enum":["verification_create","owner_followup","agent_followup","system"]},"metadata":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"created_at":{"type":"string"}},"required":["id","evidence_session_id","version","request_type","instructions","recipient_message","evidence_requirements","task_status","source","metadata","created_at"]},{"type":"null"}]}},"required":["object","verification_id","address_state_object_id","goal_kind","total_days","current_day_index","days_completed","verification_status","submission_status","latest_task_definition_id","latest_task_version","run_mode","status","next_action","acted","current_required_labels","missing_required_labels","uploaded_media_count","report","created_task_definition"]},"HermesReport":{"type":"object","properties":{"object":{"type":"string","const":"hermes_report"},"verification_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)$"},"address_state_object_id":{"anyOf":[{"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)$"},{"type":"null"}]},"goal_kind":{"type":"string","const":"jobsite_daily_evidence"},"total_days":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"days_completed":{"type":"integer","minimum":0,"maximum":9007199254740991},"current_day_index":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}]},"verification_status":{"type":"string","enum":["requested","queued_for_print","printed","mailed","delivered","undeliverable","expired"]},"submission_status":{"type":"string","enum":["not_started","in_progress","submitted","accepted","rejected"]},"latest_task_definition_id":{"anyOf":[{"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)$"},{"type":"null"}]},"latest_task_version":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}]},"status":{"type":"string","enum":["awaiting_initial_hermes_task","awaiting_delivery","awaiting_recipient_evidence","in_progress","completed","operator_attention_required"]},"next_action":{"type":"string","enum":["run_hermes","wait_for_delivery","wait_for_recipient_submission","review_report","complete_goal","stop_for_operator"]},"current_required_labels":{"type":"array","items":{"type":"string"}},"missing_required_labels":{"type":"array","items":{"type":"string"}},"uploaded_media_count_current_task":{"type":"integer","minimum":0,"maximum":9007199254740991},"summary":{"type":"string"},"days":{"type":"array","items":{"type":"object","properties":{"day_index":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"task_definition_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)$"},"task_version":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"task_status":{"type":"string","enum":["active","superseded","completed","cancelled"]},"request_type":{"type":"string","enum":["address_confirmation","photo_required","video_walkthrough","property_condition","custom_media"]},"created_at":{"type":"string"},"submitted_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"uploaded_media_count":{"type":"integer","minimum":0,"maximum":9007199254740991},"required_labels":{"type":"array","items":{"type":"string"}},"missing_required_labels":{"type":"array","items":{"type":"string"}},"is_complete":{"type":"boolean"}},"required":["day_index","task_definition_id","task_version","task_status","request_type","created_at","submitted_at","uploaded_media_count","required_labels","missing_required_labels","is_complete"]}}},"required":["object","verification_id","address_state_object_id","goal_kind","total_days","days_completed","current_day_index","verification_status","submission_status","latest_task_definition_id","latest_task_version","status","next_action","current_required_labels","missing_required_labels","uploaded_media_count_current_task","summary","days"]},"ReviewRequestList":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object","properties":{"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)$"},"kind":{"type":"string"},"status":{"type":"string","enum":["pending","approved","rejected"]},"mode":{"type":"string","enum":["test","live"]},"preflight_id":{"anyOf":[{"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)$"},{"type":"null"}]},"verification_id":{"anyOf":[{"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)$"},{"type":"null"}]},"request_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}]},"reasons":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"payload":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"resolved_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string"}},"required":["id","kind","status","mode","preflight_id","verification_id","request_fingerprint","reasons","payload","resolved_at","created_at"]}}},"required":["object","data"]},"ReviewRequest":{"type":"object","properties":{"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)$"},"kind":{"type":"string"},"status":{"type":"string","enum":["pending","approved","rejected"]},"mode":{"type":"string","enum":["test","live"]},"preflight_id":{"anyOf":[{"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)$"},{"type":"null"}]},"verification_id":{"anyOf":[{"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)$"},{"type":"null"}]},"request_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}]},"reasons":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"payload":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"resolved_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string"}},"required":["id","kind","status","mode","preflight_id","verification_id","request_fingerprint","reasons","payload","resolved_at","created_at"]},"ResolveReviewRequest":{"type":"object","properties":{"decision":{"type":"string","enum":["approved","rejected"]}},"required":["decision"]},"BillingSetupSession":{"type":"object","properties":{"object":{"type":"string","const":"billing_setup_session"},"url":{"type":"string","format":"uri"}},"required":["object","url"]},"ConfirmBillingSetupRequest":{"type":"object","properties":{"session_id":{"type":"string","minLength":1}},"required":["session_id"]},"BillingSetupConfirmation":{"type":"object","properties":{"object":{"type":"string","const":"billing_setup_confirmation"},"payment_method_id":{"type":"string"},"card":{"type":"object","properties":{"brand":{"anyOf":[{"type":"string"},{"type":"null"}]},"last4":{"anyOf":[{"type":"string"},{"type":"null"}]},"funding":{"anyOf":[{"type":"string"},{"type":"null"}]},"exp_month":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"exp_year":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["brand","last4","funding","exp_month","exp_year"]}},"required":["object","payment_method_id","card"]},"BillingPortalSession":{"type":"object","properties":{"object":{"type":"string","const":"billing_portal_session"},"url":{"type":"string","format":"uri"}},"required":["object","url"]},"LiveApproval":{"type":"object","properties":{"object":{"type":"string","const":"live_approval"},"approved_at":{"type":"string"}},"required":["object","approved_at"]},"LivePolicy":{"type":"object","properties":{"object":{"type":"string","const":"live_policy"},"live_first_send_approved_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"live_per_request_cap_cents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"live_monthly_budget_cents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"current_month_live_spend_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["object","live_first_send_approved_at","live_per_request_cap_cents","live_monthly_budget_cents","current_month_live_spend_cents"]},"UpdateLivePolicyRequest":{"type":"object","properties":{"live_per_request_cap_cents":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"live_monthly_budget_cents":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]}}}}},"paths":{"/api/v1/account-intents":{"post":{"summary":"Start account setup","operationId":"createAccountIntent","description":"Creates a setup intent for a business owner. Include `webhook_url` if you want address.bot to send verification events to your application after keys are issued.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountIntentRequest"}}}},"responses":{"201":{"description":"Setup intent created"},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/preflight":{"post":{"summary":"Validate and price a postcard verification","operationId":"preflightVerification","description":"Use this before creating live mail. Sandbox keys can call it too, which keeps your integration flow identical.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreflightRequest"},"example":{"request_type":"address_confirmation","recipient":{"name":"Jane Resident","line1":"123 Main St","city":"Austin","region":"TX","postal_code":"78701","country":"US"},"recipient_message":"Scan the QR and enter the code to confirm mail access.","reference":"jane-main-mailbox","metadata":{"customer_id":"cus_123"}}}}},"responses":{"200":{"description":"Preflight estimate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreflightResponse"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/verifications":{"get":{"summary":"List postcard verifications","operationId":"listVerifications","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"status","in":"query","schema":{"type":"string","enum":["requested","queued_for_print","printed","mailed","delivered","undeliverable","expired"]}}],"responses":{"200":{"description":"Verification list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationList"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a postcard verification","operationId":"createVerification","description":"Creates one postcard request for one address. Send `dry_run: true` to validate and price the same body without creating a record, sending mail, or charging. The API response never exposes the private QR token or printed six-digit code.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Use a stable key for safe retries. Repeated creates with the same key return the existing verification."},{"name":"x-addressbot-max-cost-cents","in":"header","required":false,"schema":{"type":"integer","minimum":0},"description":"Optional live safety cap. If the confirmed live estimate exceeds this amount, no record is created and no charge is attempted. `x-max-cost-cents` is accepted as an alias."},{"name":"x-addressbot-preflight-id","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"Required for live creates."},{"name":"x-addressbot-confirm-live-cost","in":"header","required":false,"schema":{"type":"boolean"},"description":"Set to true to confirm the saved live preflight cost."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVerificationRequest"},"example":{"request_type":"address_confirmation","recipient":{"name":"Jane Resident","line1":"123 Main St","city":"Austin","region":"TX","postal_code":"78701","country":"US"},"recipient_message":"Scan the QR and enter the code to confirm mail access.","reference":"jane-main-mailbox","metadata":{"customer_id":"cus_123"}}}}},"responses":{"200":{"description":"Existing verification returned by idempotency, or a dry-run preview when `dry_run: true` is sent","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Verification"},{"$ref":"#/components/schemas/VerificationPreview"}]}}}},"201":{"description":"Verification created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Verification"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Live creation requires billing, policy, review, or preflight action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionRequiredError"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/verifications/{id}":{"get":{"summary":"Get a postcard verification","operationId":"getVerification","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Verification","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Verification"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Verification not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/verifications/{id}/simulate":{"post":{"summary":"Simulate recipient confirmation in sandbox","operationId":"simulateVerification","description":"Sandbox-only. Marks a test verification delivered and queues the same webhook shape used by live recipient confirmation.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Updated verification","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Verification"}}}},"400":{"description":"Only available for sandbox keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Verification not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/verifications/{id}/media":{"get":{"summary":"Get verification evidence and media","operationId":"getVerificationMedia","description":"Returns the evidence requirements and uploaded media assets for a verification, including short-lived signed download URLs.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Verification media","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationMedia"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Verification not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/verifications/{id}/timeline":{"get":{"summary":"Get the full verification timeline","operationId":"getVerificationTimeline","description":"Returns task definitions, task inputs, and evidence events for a verification in chronological order.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Verification timeline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationTimeline"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Verification not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/verifications/{id}/follow-on":{"post":{"summary":"Add a follow-on evidence task","operationId":"createFollowOnTask","description":"Issues a new versioned task definition against an existing verification, e.g. to request additional evidence after delivery.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FollowOnTaskRequest"}}}},"responses":{"200":{"description":"Follow-on task created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FollowOnTask"}}}},"400":{"description":"Invalid JSON body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Verification not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/verifications/{id}/hermes/run":{"post":{"summary":"Run the Hermes daily-evidence agent","operationId":"runHermes","description":"Plans or advances a multi-day jobsite evidence goal for a verification. `mode: \"plan\"` evaluates next steps; `mode: \"act\"` creates the next day's task when appropriate.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HermesRunRequest"}}}},"responses":{"200":{"description":"Hermes run result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HermesRun"}}}},"400":{"description":"Invalid JSON body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/verifications/{id}/hermes/report":{"get":{"summary":"Get the Hermes goal report","operationId":"getHermesReport","description":"Returns per-day progress for a jobsite daily-evidence goal. Goal parameters are supplied as query params.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"kind","in":"query","schema":{"type":"string","default":"jobsite_daily_evidence"}},{"name":"total_days","in":"query","schema":{"type":"integer","minimum":1,"maximum":30}},{"name":"request_type","in":"query","schema":{"type":"string"}},{"name":"require_photo","in":"query","schema":{"type":"boolean"}},{"name":"require_video","in":"query","schema":{"type":"boolean"}},{"name":"require_note","in":"query","schema":{"type":"boolean"}},{"name":"require_signature","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Hermes report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HermesReport"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/review-requests":{"get":{"summary":"List manual review requests","operationId":"listReviewRequests","description":"Owner-scoped. Lists live requests held for manual approval. Requires an owner-authorized key.","responses":{"200":{"description":"Review request list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewRequestList"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is not authorized for owner actions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/review-requests/{id}/resolve":{"post":{"summary":"Approve or reject a review request","operationId":"resolveReviewRequest","description":"Owner-scoped. Approves or rejects a held live request.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveReviewRequest"}}}},"responses":{"200":{"description":"Resolved review request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewRequest"}}}},"400":{"description":"Invalid JSON body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is not authorized for owner actions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/billing/setup":{"post":{"summary":"Start no-charge card setup","operationId":"createBillingSetupSession","description":"Owner-scoped. Returns a hosted Stripe setup session URL to save a card for future live auto-charge. No charge is made.","responses":{"200":{"description":"Billing setup session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingSetupSession"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is not authorized for owner actions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Business not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/billing/setup/confirm":{"post":{"summary":"Confirm a completed card setup","operationId":"confirmBillingSetup","description":"Owner-scoped. Confirms a finished Stripe setup session and records the saved payment method.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmBillingSetupRequest"}}}},"responses":{"200":{"description":"Billing setup confirmation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingSetupConfirmation"}}}},"400":{"description":"Invalid JSON body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is not authorized for owner actions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/billing/portal":{"post":{"summary":"Open the Stripe billing portal","operationId":"createBillingPortalSession","description":"Owner-scoped. Returns a hosted Stripe billing portal session URL.","responses":{"200":{"description":"Billing portal session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingPortalSession"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is not authorized for owner actions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Business not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/billing/live-approval":{"post":{"summary":"Approve the first live send","operationId":"approveLiveSends","description":"Owner-scoped. Records owner approval to begin sending live mail under the configured live policy.","responses":{"200":{"description":"Live approval recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiveApproval"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is not authorized for owner actions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/billing/live-policy":{"get":{"summary":"Get live spend policy","operationId":"getLivePolicy","description":"Owner-scoped. Returns per-request cap, monthly budget, and current month live spend.","responses":{"200":{"description":"Live policy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LivePolicy"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is not authorized for owner actions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Update live spend policy","operationId":"updateLivePolicy","description":"Owner-scoped. Sets the per-request cap and/or monthly live budget.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateLivePolicyRequest"}}}},"responses":{"200":{"description":"Updated live policy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LivePolicy"}}}},"400":{"description":"Invalid JSON body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key is not authorized for owner actions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/billing/summary":{"get":{"summary":"Check billing and live-send readiness","operationId":"getBillingSummary","responses":{"200":{"description":"Billing summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingSummary"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{"verificationEvent":{"post":{"summary":"Verification lifecycle event","description":"Sent to the webhook URL configured during setup. Verify `x-addressbot-signature`, an HMAC-SHA256 signature over `<timestamp>.<raw_body>` using your webhook secret.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayload"},"example":{"event":"verification.delivered","created":1770000000,"data":{"id":"00000000-0000-4000-8000-000000000001","mode":"test","status":"delivered","request_type":"address_confirmation","submission_status":"submitted","reference":"jane-main-mailbox","recipient":{"name":"Jane Resident","line1":"123 Main St","line2":null,"city":"Austin","region":"TX","postal_code":"78701","country":"US"},"metadata":{"customer_id":"cus_123"},"estimated_cost_cents":225,"created_at":"2026-05-21T12:00:00.000Z","delivered_at":"2026-05-21T12:05:00.000Z","completed_at":"2026-05-21T12:05:00.000Z"}}}}},"responses":{"200":{"description":"Your endpoint accepted the event"}}}}},"x-addressbot":{"zod_source":"OpenAPI component schemas are generated directly from the runtime Zod validators in lib/schemas.ts via z.toJSONSchema (io: \"input\"). There is no separate doc schema, so the published contract cannot drift from what the API actually validates and serializes.","sandbox":"`sk_test_...` keys use the same endpoints and payloads as live, return `test_mode: true`, and do not send live mail or charge a card. Sandbox simulate endpoints fire signed webhooks for integration testing.","live":"`sk_live_...` keys require a saved preflight id and `x-addressbot-confirm-live-cost: true` before a postcard is created. Use `dry_run: true` or `x-addressbot-max-cost-cents` to cap spend before side effects.","webhooks":"Webhook events are signed with `x-addressbot-signature` and include `x-addressbot-event` plus `x-addressbot-delivery` headers."}}