{"openapi":"3.1.0","info":{"title":"Phone Number Normalize and Policy Guard API","version":"1.0.0","description":"Inspect, normalize, compare, batch-check, and apply explicit policy to bounded phone-number strings using offline numbering-plan metadata. Processing is stateless and deterministic for the installed metadata version. The API never places a call, sends a message, queries a live carrier, or proves current assignment, reachability, ownership, or SMS capability."},"paths":{"/marketplace/rapid/phone/v1/inspect":{"post":{"tags":["Phone Number Inspect"],"summary":"Inspect phone number","description":"Parse, format, and inspect one bounded number with pinned offline numbering-plan metadata.","operationId":"inspectPhoneNumber","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneInspectRequest"},"examples":{"example":{"summary":"Inspect phone number","value":{"number":"+14155552671"}}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneInspectResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/marketplace/rapid/phone/v1/normalize":{"post":{"tags":["Phone Number Normalize"],"summary":"Normalize phone number","description":"Normalize one number to E.164, international, national, or RFC 3966 format with explicit extension handling.","operationId":"normalizePhoneNumber","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNormalizeRequest"},"examples":{"example":{"summary":"Normalize phone number","value":{"number":"020 7946 0018","default_region":"GB","output_format":"E164","include_extension":true}}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNormalizeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/marketplace/rapid/phone/v1/compare":{"post":{"tags":["Phone Number Compare"],"summary":"Compare phone numbers","description":"Compare two parsed identities with explicit national and extension semantics; ownership is not inferred.","operationId":"comparePhoneNumbers","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneCompareRequest"},"examples":{"example":{"summary":"Compare phone numbers","value":{"left":"+44 20 7946 0018","right":"020 7946 0018","right_default_region":"GB","extension_policy":"REQUIRE_EQUAL"}}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneCompareResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/marketplace/rapid/phone/v1/batch/inspect":{"post":{"tags":["Phone Number Batch Inspect"],"summary":"Inspect phone-number batch","description":"Inspect up to 1,000 phone numbers and return per-item errors plus exact normalized duplicate groups.","operationId":"inspectPhoneNumberBatch","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneBatchRequest"},"examples":{"example":{"summary":"Inspect phone-number batch","value":{"items":[{"reference":"crm-1","number":"+14155552671"},{"reference":"crm-2","number":"415-555-2671","default_region":"US"}]}}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneBatchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/marketplace/rapid/phone/v1/policy-check":{"post":{"tags":["Phone Number Policy"],"summary":"Check phone-number policy","description":"Enforce explicit region, type, possibility, validity, E.164, extension, premium-rate, and shared-cost policy.","operationId":"checkPhoneNumberPolicy","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhonePolicyRequest"},"examples":{"example":{"summary":"Check phone-number policy","value":{"number":"+14155552671","allowed_regions":["US","CA"],"allowed_types":["MOBILE","FIXED_LINE_OR_MOBILE"],"require_region_allowlist":true,"require_type_allowlist":true,"require_possible":true,"require_valid":true,"require_e164_input":true,"allow_extensions":false,"block_premium_rate":true,"block_shared_cost":true}}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhonePolicyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ParsedPhone":{"properties":{"country_code":{"type":"integer","title":"Country Code"},"national_number":{"type":"string","title":"National Number"},"extension":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Extension"},"region_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region Code"},"number_type":{"type":"string","enum":["FIXED_LINE","MOBILE","FIXED_LINE_OR_MOBILE","TOLL_FREE","PREMIUM_RATE","SHARED_COST","VOIP","PERSONAL_NUMBER","PAGER","UAN","VOICEMAIL","UNKNOWN"],"title":"Number Type"},"possible":{"type":"boolean","title":"Possible"},"possible_reason":{"type":"string","title":"Possible Reason"},"valid":{"type":"boolean","title":"Valid"},"valid_for_region":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Valid For Region"},"formats":{"$ref":"#/components/schemas/PhoneFormats"},"source_sha256":{"type":"string","title":"Source Sha256"},"metadata_version":{"type":"string","title":"Metadata Version"},"static_metadata_only":{"type":"boolean","const":true,"title":"Static Metadata Only","default":true},"currently_assigned_verified":{"type":"boolean","const":false,"title":"Currently Assigned Verified","default":false},"reachable_verified":{"type":"boolean","const":false,"title":"Reachable Verified","default":false},"ownership_verified":{"type":"boolean","const":false,"title":"Ownership Verified","default":false},"current_carrier_queried":{"type":"boolean","const":false,"title":"Current Carrier Queried","default":false},"sms_capability_verified":{"type":"boolean","const":false,"title":"Sms Capability Verified","default":false},"network_access_performed":{"type":"boolean","const":false,"title":"Network Access Performed","default":false},"payload_stored":{"type":"boolean","const":false,"title":"Payload Stored","default":false}},"additionalProperties":false,"type":"object","required":["country_code","national_number","extension","region_code","number_type","possible","possible_reason","valid","valid_for_region","formats","source_sha256","metadata_version"],"title":"ParsedPhone"},"PhoneBatchItem":{"properties":{"number":{"type":"string","maxLength":128,"minLength":1,"title":"Number"},"default_region":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Default Region"},"reference":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Reference"}},"additionalProperties":false,"type":"object","required":["number"],"title":"PhoneBatchItem"},"PhoneBatchRequest":{"properties":{"items":{"items":{"$ref":"#/components/schemas/PhoneBatchItem"},"type":"array","maxItems":1000,"minItems":1,"title":"Items"}},"additionalProperties":false,"type":"object","required":["items"],"title":"PhoneBatchRequest"},"PhoneBatchResponse":{"properties":{"status":{"type":"string","const":"COMPLETED","title":"Status","default":"COMPLETED"},"decision":{"type":"string","enum":["CLEAR","REVIEW_REQUIRED","BLOCKED"],"title":"Decision"},"item_count":{"type":"integer","title":"Item Count"},"valid_count":{"type":"integer","title":"Valid Count"},"invalid_count":{"type":"integer","title":"Invalid Count"},"duplicate_groups":{"items":{"items":{"type":"integer"},"type":"array"},"type":"array","title":"Duplicate Groups"},"items":{"items":{"$ref":"#/components/schemas/PhoneBatchResult"},"type":"array","title":"Items"},"ruleset_version":{"type":"string","title":"Ruleset Version","default":"2026-08-11"},"next_action":{"type":"string","title":"Next Action"}},"additionalProperties":false,"type":"object","required":["decision","item_count","valid_count","invalid_count","duplicate_groups","items","next_action"],"title":"PhoneBatchResponse"},"PhoneBatchResult":{"properties":{"index":{"type":"integer","title":"Index"},"reference":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reference"},"parsed":{"anyOf":[{"$ref":"#/components/schemas/ParsedPhone"},{"type":"null"}]},"decision":{"anyOf":[{"type":"string","enum":["CLEAR","REVIEW_REQUIRED","BLOCKED"]},{"type":"null"}],"title":"Decision"},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"}},"additionalProperties":false,"type":"object","required":["index","reference"],"title":"PhoneBatchResult"},"PhoneCompareRequest":{"properties":{"left":{"type":"string","maxLength":128,"minLength":1,"title":"Left"},"right":{"type":"string","maxLength":128,"minLength":1,"title":"Right"},"left_default_region":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Left Default Region"},"right_default_region":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Right Default Region"},"extension_policy":{"type":"string","enum":["REQUIRE_EQUAL","IGNORE"],"title":"Extension Policy","default":"REQUIRE_EQUAL"}},"additionalProperties":false,"type":"object","required":["left","right"],"title":"PhoneCompareRequest"},"PhoneCompareResponse":{"properties":{"status":{"type":"string","const":"COMPLETED","title":"Status","default":"COMPLETED"},"decision":{"type":"string","enum":["CLEAR","REVIEW_REQUIRED","BLOCKED"],"title":"Decision"},"match":{"type":"string","enum":["NOT_A_NUMBER","NO_MATCH","SHORT_NSN_MATCH","NSN_MATCH","EXACT_MATCH"],"title":"Match"},"same_identity":{"type":"boolean","title":"Same Identity"},"extension_equal":{"type":"boolean","title":"Extension Equal"},"extension_policy":{"type":"string","enum":["REQUIRE_EQUAL","IGNORE"],"title":"Extension Policy"},"left":{"$ref":"#/components/schemas/ParsedPhone"},"right":{"$ref":"#/components/schemas/ParsedPhone"},"findings":{"items":{"$ref":"#/components/schemas/PhoneFinding"},"type":"array","title":"Findings"},"ruleset_version":{"type":"string","title":"Ruleset Version","default":"2026-08-11"},"next_action":{"type":"string","title":"Next Action"}},"additionalProperties":false,"type":"object","required":["decision","match","same_identity","extension_equal","extension_policy","left","right","findings","next_action"],"title":"PhoneCompareResponse"},"PhoneFinding":{"properties":{"code":{"type":"string","title":"Code"},"severity":{"type":"string","enum":["LOW","MEDIUM","HIGH"],"title":"Severity"},"message":{"type":"string","title":"Message"},"evidence":{"additionalProperties":true,"type":"object","title":"Evidence"},"next_action":{"type":"string","title":"Next Action"}},"additionalProperties":false,"type":"object","required":["code","severity","message","next_action"],"title":"PhoneFinding"},"PhoneFormats":{"properties":{"e164":{"type":"string","title":"E164"},"international":{"type":"string","title":"International"},"national":{"type":"string","title":"National"},"rfc3966":{"type":"string","title":"Rfc3966"}},"additionalProperties":false,"type":"object","required":["e164","international","national","rfc3966"],"title":"PhoneFormats"},"PhoneInspectRequest":{"properties":{"number":{"type":"string","maxLength":128,"minLength":1,"title":"Number"},"default_region":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Default Region"}},"additionalProperties":false,"type":"object","required":["number"],"title":"PhoneInspectRequest"},"PhoneInspectResponse":{"properties":{"status":{"type":"string","const":"COMPLETED","title":"Status","default":"COMPLETED"},"decision":{"type":"string","enum":["CLEAR","REVIEW_REQUIRED","BLOCKED"],"title":"Decision"},"parsed":{"$ref":"#/components/schemas/ParsedPhone"},"findings":{"items":{"$ref":"#/components/schemas/PhoneFinding"},"type":"array","title":"Findings"},"ruleset_version":{"type":"string","title":"Ruleset Version","default":"2026-08-11"},"next_action":{"type":"string","title":"Next Action"}},"additionalProperties":false,"type":"object","required":["decision","parsed","findings","next_action"],"title":"PhoneInspectResponse"},"PhoneNormalizeRequest":{"properties":{"number":{"type":"string","maxLength":128,"minLength":1,"title":"Number"},"default_region":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Default Region"},"output_format":{"type":"string","enum":["E164","INTERNATIONAL","NATIONAL","RFC3966"],"title":"Output Format","default":"E164"},"include_extension":{"type":"boolean","title":"Include Extension","default":true}},"additionalProperties":false,"type":"object","required":["number"],"title":"PhoneNormalizeRequest"},"PhoneNormalizeResponse":{"properties":{"status":{"type":"string","const":"COMPLETED","title":"Status","default":"COMPLETED"},"decision":{"type":"string","enum":["CLEAR","REVIEW_REQUIRED","BLOCKED"],"title":"Decision"},"normalized":{"type":"string","title":"Normalized"},"output_format":{"type":"string","enum":["E164","INTERNATIONAL","NATIONAL","RFC3966"],"title":"Output Format"},"extension_included":{"type":"boolean","title":"Extension Included"},"parsed":{"$ref":"#/components/schemas/ParsedPhone"},"findings":{"items":{"$ref":"#/components/schemas/PhoneFinding"},"type":"array","title":"Findings"},"ruleset_version":{"type":"string","title":"Ruleset Version","default":"2026-08-11"},"next_action":{"type":"string","title":"Next Action"}},"additionalProperties":false,"type":"object","required":["decision","normalized","output_format","extension_included","parsed","findings","next_action"],"title":"PhoneNormalizeResponse"},"PhonePolicyRequest":{"properties":{"number":{"type":"string","maxLength":128,"minLength":1,"title":"Number"},"default_region":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Default Region"},"allowed_regions":{"items":{"type":"string"},"type":"array","maxItems":250,"title":"Allowed Regions"},"allowed_types":{"items":{"type":"string","enum":["FIXED_LINE","MOBILE","FIXED_LINE_OR_MOBILE","TOLL_FREE","PREMIUM_RATE","SHARED_COST","VOIP","PERSONAL_NUMBER","PAGER","UAN","VOICEMAIL","UNKNOWN"]},"type":"array","maxItems":12,"title":"Allowed Types"},"require_region_allowlist":{"type":"boolean","title":"Require Region Allowlist","default":false},"require_type_allowlist":{"type":"boolean","title":"Require Type Allowlist","default":false},"require_possible":{"type":"boolean","title":"Require Possible","default":true},"require_valid":{"type":"boolean","title":"Require Valid","default":true},"require_e164_input":{"type":"boolean","title":"Require E164 Input","default":false},"allow_extensions":{"type":"boolean","title":"Allow Extensions","default":true},"block_premium_rate":{"type":"boolean","title":"Block Premium Rate","default":true},"block_shared_cost":{"type":"boolean","title":"Block Shared Cost","default":false}},"additionalProperties":false,"type":"object","required":["number"],"title":"PhonePolicyRequest"},"PhonePolicyResponse":{"properties":{"status":{"type":"string","const":"COMPLETED","title":"Status","default":"COMPLETED"},"decision":{"type":"string","enum":["CLEAR","BLOCKED"],"title":"Decision"},"permitted":{"type":"boolean","title":"Permitted"},"parsed":{"$ref":"#/components/schemas/ParsedPhone"},"findings":{"items":{"$ref":"#/components/schemas/PhoneFinding"},"type":"array","title":"Findings"},"ruleset_version":{"type":"string","title":"Ruleset Version","default":"2026-08-11"},"static_metadata_only":{"type":"boolean","const":true,"title":"Static Metadata Only","default":true},"reachability_verified":{"type":"boolean","const":false,"title":"Reachability Verified","default":false},"ownership_verified":{"type":"boolean","const":false,"title":"Ownership Verified","default":false},"network_access_performed":{"type":"boolean","const":false,"title":"Network Access Performed","default":false},"payload_stored":{"type":"boolean","const":false,"title":"Payload Stored","default":false},"next_action":{"type":"string","title":"Next Action"}},"additionalProperties":false,"type":"object","required":["decision","permitted","parsed","findings","next_action"],"title":"PhonePolicyResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"tags":[{"name":"Phone Number Inspect","description":"A bounded, stateless phone-number preflight for agents, CRM intake, communications workflows, customer-data pipelines, and form validation."},{"name":"Phone Number Normalize","description":"A bounded, stateless phone-number preflight for agents, CRM intake, communications workflows, customer-data pipelines, and form validation."},{"name":"Phone Number Compare","description":"A bounded, stateless phone-number preflight for agents, CRM intake, communications workflows, customer-data pipelines, and form validation."},{"name":"Phone Number Batch Inspect","description":"A bounded, stateless phone-number preflight for agents, CRM intake, communications workflows, customer-data pipelines, and form validation."},{"name":"Phone Number Policy","description":"A bounded, stateless phone-number preflight for agents, CRM intake, communications workflows, customer-data pipelines, and form validation."}],"servers":[{"url":"https://api-production-9502.up.railway.app"}]}