{"openapi":"3.2.0","info":{"title":"Phone Number Validator and Formatter API","description":"Validate, parse and format phone numbers worldwide. Returns validity, line type (mobile, fixed-line, VoIP, toll-free), country and calling code, plus E.164, international, national and RFC3966 formats. Batch validation of up to 100 numbers per call. Fast edge-hosted, ruleset-based validation powered by libphonenumber metadata (not a live carrier/HLR lookup).","version":"1.0.0"},"servers":[{"url":"https://uhecf.jojapi.net"}],"security":[{"ApiKeyAuth":[]}],"x-agent-commerce":{"catalog_url":"https://uhecf.jojapi.net/_jojapi/agent/plans","discovery_url":"https://uhecf.jojapi.net/.well-known/x402","directory_url":"https://agents.jojapi.net/apis/phone-number-validator","docs":"https://docs.jojapi.com/consumers/agents"},"paths":{"/validate":{"get":{"operationId":"get_validate","summary":"Validate & format a single phone number","description":"Returns validity, possibility, line type, country, calling code and all four formats. Invalid numbers still return HTTP 200 with valid:false and a reason.","responses":{"200":{"description":"Validation result","content":{"application/json":{"schema":{"type":"object","properties":{"input":{"type":"string"},"valid":{"type":"boolean"},"possible":{"type":"boolean"},"type":{"type":"string","example":"MOBILE"},"country":{"type":"string","nullable":true,"example":"DE"},"countryCallingCode":{"type":"string","nullable":true,"example":"49"},"formats":{"type":"object","properties":{"e164":{"type":"string","nullable":true},"international":{"type":"string","nullable":true},"national":{"type":"string","nullable":true},"rfc3966":{"type":"string","nullable":true}}},"reason":{"type":"string","nullable":true}}},"example":{"input":"+4915123456789","valid":true,"possible":true,"type":"MOBILE","country":"DE","countryCallingCode":"49","formats":{"e164":"+4915123456789","international":"+49 1512 3456789","national":"01512 3456789","rfc3966":"tel:+4915123456789"}}}}},"422":{"description":"Missing required `number` query param."}},"parameters":[{"name":"number","in":"query","description":"Phone number in E.164 (with +) or national format (provide country).","required":true,"schema":{"type":"string","example":"+4915123456789"}},{"name":"country","in":"query","description":"ISO 3166-1 alpha-2 region hint for numbers without a + prefix.","required":false,"schema":{"type":"string","example":"DE"}}]}},"/validate/batch":{"post":{"operationId":"post_validate_batch","summary":"Validate an array of phone numbers","description":"Validate up to 100 numbers in one request. Returns a per-number result array in the same order.","responses":{"200":{"description":"Per-number results","content":{"application/json":{"example":{"count":2,"results":[{"input":"+14155552671","valid":true,"possible":true,"type":"FIXED_LINE_OR_MOBILE","country":"US","countryCallingCode":"1","formats":{"e164":"+14155552671","international":"+1 415 555 2671","national":"(415) 555-2671","rfc3966":"tel:+14155552671"}},{"input":"bad","valid":false,"possible":false,"type":"UNKNOWN","country":null,"countryCallingCode":null,"formats":{"e164":null,"international":null,"national":null,"rfc3966":null},"reason":"NOT_A_NUMBER"}]}}}},"400":{"description":"Malformed JSON body."},"422":{"description":"Missing numbers array or batch larger than 100."}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["numbers"],"properties":{"numbers":{"type":"array","items":{"type":"string"},"maxItems":100},"defaultCountry":{"type":"string","description":"ISO 3166-1 alpha-2 hint applied to national-format numbers."}}},"example":{"numbers":["+4915123456789","+14155552671","bad"],"defaultCountry":"US"}}}}}},"/example":{"get":{"operationId":"get_example","summary":"Get an example number for a region","description":"Returns a valid example (mobile) number for the requested country, fully validated and formatted.","responses":{"200":{"description":"Example number result"},"422":{"description":"Invalid or missing country."}},"parameters":[{"name":"country","in":"query","required":true,"schema":{"type":"string","example":"DE"}},{"name":"type","in":"query","required":false,"schema":{"type":"string","example":"mobile"}}]}},"/calling-code":{"get":{"operationId":"get_calling_code","summary":"Look up a country calling code","description":"Returns the country calling code (e.g. 49 for DE) for an ISO 3166-1 alpha-2 country code. Returns 422 for an unknown or missing country.","responses":{"200":{"description":"Calling code","content":{"application/json":{"example":{"country":"DE","countryCallingCode":"49"}}}},"422":{"description":"Invalid or missing country."}},"parameters":[{"name":"country","in":"query","required":true,"schema":{"type":"string","example":"DE"}}]}},"/regions":{"get":{"operationId":"get_regions","summary":"List supported regions and calling codes","description":"Lists every supported ISO 3166-1 alpha-2 region together with its country calling code. Useful for building country pickers and for checking coverage.","responses":{"200":{"description":"Supported regions","content":{"application/json":{"example":{"count":248,"regions":[{"country":"US","countryCallingCode":"1"}]}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-JoJAPI-Key","description":"Your JoJ API key."}}}}