> ## Documentation Index > Fetch the complete documentation index at: https://docs.finowl.co/llms.txt > Use this file to discover all available pages before exploring further. # Validate a phone number > Check, format and classify a phone number, and get its country, original carrier and time zones. ### Good to know * **Send `country` for local numbers.** A number without a `+` prefix, such as `(415) 555-2671`, needs a country to be read. Use the country of your form, the user's billing address or their IP. Without it the result is `reason: missing_country`. * **Store `e164`.** It is the one format every SMS and voice provider accepts, and it makes duplicates easy to spot. * **`valid` is not "in service".** The number is in an assigned range, but Finowl doesn't call or text it. Send a one-time code when you need to know the user owns it. * **`carrier` is the original carrier.** It is the network the number range was first allocated to. Numbers that were ported keep their old carrier here. It is usually `null` for US and Canadian numbers. * **`fixed_line_or_mobile` is common.** In the US, Canada and some other countries, landlines and mobiles share ranges, so the type can't be told apart. Don't reject these as "not mobile". * **`location` can be just the country.** When the number has no finer area, which is common for mobile numbers, `location` is the country name, for example `India`. * **Time zones use the library's IANA names.** Some are older aliases, such as `Asia/Calcutta` rather than `Asia/Kolkata`. Toll-free and other national numbers can list every time zone in the country. * **Bad input is a `200`, not an error.** Unparseable numbers return `valid: false` with a `reason`. * **Nothing leaves Finowl.** Validation runs offline against Google's open-source libphonenumber data. Phone metadata from Google [libphonenumber](https://github.com/google/libphonenumber) (Apache 2.0), via the [nyaruka/phonenumbers](https://github.com/nyaruka/phonenumbers) Go port (MIT). Validate the email, phone and IP address together when someone registers. ## OpenAPI ````yaml api-reference/openapi.yaml POST /v1/phone/validate openapi: 3.1.0 info: title: Finowl API version: '1.0' description: > Check emails and passwords against known data breaches, predict gender from names and emails, check cold-email compliance, validate email addresses and phone numbers, look up companies by domain and geolocate IP addresses. Every endpoint is a JSON `POST` authenticated with a bearer API key. servers: - url: https://api.finowl.co description: Production security: - bearerAuth: [] tags: - name: Breaches description: Check whether an email or password appears in known data breaches. - name: Gender description: Predict gender from a name or email, one at a time or in batches. - name: Compliance description: >- Place an email address in a jurisdiction and return that jurisdiction's cold-email rule. - name: Email validation description: >- Check whether an email address can receive mail, and catch typos, disposable and role addresses. - name: Company description: Look up public company details from a domain or work email. - name: IP description: Geolocate an IP address and flag hosting, proxy and Tor traffic. - name: Phone description: Validate, format and classify a phone number. paths: /v1/phone/validate: post: tags: - Phone summary: Validate a phone number description: > Parses a phone number in almost any format, checks it against the numbering plan of its country and returns its type, standard formats, original carrier, location and time zones. Validation runs offline on Finowl's own infrastructure using Google's open-source libphonenumber metadata. Finowl does not call or text the number. Numbers that cannot be parsed are not rejected. They return `200` with `valid: false` and a `reason`. Costs **1 credit**. operationId: validatePhone requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - phone properties: phone: type: string minLength: 1 maxLength: 64 description: >- The number as the user typed it. Spaces, dashes, dots and brackets are fine. Start with `+` and the country calling code, or send `country`. example: (415) 555-2671 country: type: string pattern: ^[A-Za-z]{2}$ description: >- ISO 3166-1 alpha-2 code, in any case, used to read numbers written without a `+` prefix, such as `US` or `GB`. Ignored when the number starts with `+`. Unassigned codes such as `ZZ` return `invalid_input`. example: US examples: national: summary: National format with country value: phone: (415) 555-2671 country: US international: summary: International format value: phone: +44 7400 123456 invalid: summary: Too short value: phone: +1 415 555 country: US responses: '200': description: The check completed. Invalid numbers are still successful responses. content: application/json: schema: $ref: '#/components/schemas/PhoneValidationResult' examples: national: summary: Valid US number value: phone: (415) 555-2671 valid: true possible: true reason: null country_code: US country: United States calling_code: 1 type: fixed_line_or_mobile e164: '+14155552671' international: +1 415-555-2671 national: (415) 555-2671 carrier: null location: San Francisco, CA timezones: - America/Los_Angeles mobile: summary: Valid UK mobile value: phone: +44 7400 123456 valid: true possible: true reason: null country_code: GB country: United Kingdom calling_code: 44 type: mobile e164: '+447400123456' international: +44 7400 123456 national: 07400 123456 carrier: Three location: United Kingdom timezones: - Europe/Guernsey - Europe/Isle_of_Man - Europe/Jersey - Europe/London invalid: summary: Too short value: phone: +1 415 555 valid: false possible: false reason: too_short country_code: US country: United States calling_code: 1 type: unknown e164: '+1415555' international: +1 415555 national: '415555' carrier: null location: null timezones: [] missing_country: summary: No country value: phone: 020 7946 0958 valid: false possible: false reason: missing_country country_code: '' country: '' calling_code: null type: unknown e164: null international: null national: null carrier: null location: null timezones: [] '400': $ref: '#/components/responses/InvalidInput' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' '503': $ref: '#/components/responses/Unavailable' '504': $ref: '#/components/responses/Unconfirmed' components: schemas: PhoneValidationResult: type: object required: - phone - valid - possible - reason - country_code - country - calling_code - type - e164 - international - national - carrier - location - timezones properties: phone: type: string description: The number you sent. valid: type: boolean description: >- `true` when the number matches an assigned range in its country's numbering plan. It does not prove the number is in service. possible: type: boolean description: >- `true` when the number has a plausible length for its country. A possible number can still be invalid. reason: type: - string - 'null' enum: - unparseable - missing_country - too_short - too_long - invalid_number - null description: > Why the number is not valid. `null` when `valid` is `true`. - `unparseable`: the input does not look like a phone number. - `missing_country`: the number has no `+` prefix and no `country` was sent. - `too_short` or `too_long`: the number has the wrong length for its country. - `invalid_number`: the length is plausible, but the number is not in an assigned range. country_code: type: string description: ISO 3166-1 alpha-2 code of the number's country. Empty when unknown. country: type: string description: The country name for `country_code`. Empty when unknown. calling_code: type: - integer - 'null' description: The country calling code, such as `1` or `44`. `null` when unknown. type: type: string enum: - mobile - fixed_line - fixed_line_or_mobile - toll_free - premium_rate - shared_cost - voip - personal_number - pager - uan - voicemail - unknown description: > The kind of line, from the numbering plan. `fixed_line_or_mobile` is common in countries such as the US and Canada, where landline and mobile numbers share ranges. `uan` is a universal access number, a single number that routes to several lines. `unknown` for invalid numbers. e164: type: - string - 'null' description: >- The number in E.164 format, such as `+14155552671`. Store numbers in this format. `null` when the number could not be parsed. international: type: - string - 'null' description: >- The number formatted for international display. `null` when it could not be parsed. national: type: - string - 'null' description: >- The number formatted for display within its own country. `null` when it could not be parsed. carrier: type: - string - 'null' description: >- The carrier the number range was originally allocated to. Numbers can be ported, so the current carrier may differ. `null` when unknown, which is usual for landlines and for US and Canadian numbers. location: type: - string - 'null' description: >- A geographic description in English, such as `San Francisco, CA`, from the number's area code. Falls back to the country name, such as `India`, when there is no finer area. `null` when unknown. timezones: type: array items: type: string description: >- IANA time zones the number may be in, such as `America/Los_Angeles`, using libphonenumber's names (for example `Asia/Calcutta`). National numbers such as toll-free can list every zone in the country. Empty when unknown. Error: type: object required: - error properties: error: type: object required: - code properties: code: type: string description: >- A stable, machine-readable error code. See the Errors page for the full list. example: invalid_input responses: InvalidInput: description: The request body is not valid. Fix the request before trying again. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_input Unauthorized: description: The API key is missing, malformed or revoked. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: unauthorized TooManyRequests: description: > `rate_limited` (too many requests this minute), `quota_exceeded` (not enough credits) or `provider_rate_limited` (Finowl intelligence is busy). Check the `Retry-After` header. headers: Retry-After: description: Seconds to wait before trying again. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: rate_limited Unavailable: description: >- Finowl, or the service behind this endpoint, is temporarily unavailable. See the Errors page for whether the request was charged. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: provider_unavailable Unconfirmed: description: >- The lookup did not finish in time. It may or may not have run, and the request was charged. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: provider_response_unconfirmed securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your Finowl API key, for example `finowl_3f9a...`. Create keys in the dashboard under **API Keys**. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.