API de validação e formatação de telefone

Dados globais de telefonia

Um número, formatos consistentes

Envie números em formato nacional, internacional ou irregular e receba formatos padronizados e metadados de validação para 242 países e territórios.

Entrada original+1 212 867 5309

Saída E.164+12128675309

ValidaçãoisValid e isPossible

FormataçãoNacional, internacional e E.164

ClassificaçãoCelular, linha fixa, VoIP e outros

LocalizaçãoRegião, código de área e local

Parâmetros de entrada

Número e contexto de endereço

Parâmetro	Obrigatoriedade	Descrição
`number`	Obrigatório	Número de telefone em formato nacional, internacional ou E.164.
`address`	Condicional	Código ISO do país, nome do país, cidade ou região usados para interpretar um número nacional.

Quando address se torna obrigatório

Se number não começar com + e um código de discagem internacional, informe um contexto como BR, Brasil ou São Paulo.

BRBrasilSão PauloRio de JaneiroPortugal

GET

Autenticação pela query string

Solicitação GET básica

cURL

curl "https://api.genderapi.io/api/phone?key=YOUR_API_KEY&number=%2B12128675309&address=US"

Codificação de URL: codifique + como %2B e espaços como %20. Prefira as funções URL/URLSearchParams da linguagem em vez de montar a string manualmente.

POST

Autenticação Bearer

Solicitação POST no servidor

Envie o número e o address opcional em JSON, com a chave da API no cabeçalho Authorization.

cURL

curl -X POST "https://api.genderapi.io/api/phone" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"number":"+12128675309","address":"US"}'

JavaScript

const response = await fetch("https://api.genderapi.io/api/phone", {
  method: "POST", headers: { "Content-Type": "application/json", "Authorization": "Bearer YOUR_API_KEY" },
  body: JSON.stringify({ number: "+12128675309", address: "United States" })
});

Resposta da API

Validação, formatação e metadados

JSON

{
  "status": true, "remaining_credits": 15709, "expires": 0, "duration": "18ms",
  "regionCode": "US", "countryCode": 1, "country": "United States",
  "national": "(212) 867-5309", "international": "+1 212-867-5309", "e164": "+12128675309",
  "isValid": true, "isPossible": true, "numberType": "FIXED_LINE_OR_MOBILE",
  "nationalSignificantNumber": "2128675309", "rawInput": "+1 212 867 5309",
  "isGeographical": true, "areaCode": "212", "location": "New York City (Manhattan)"
}

Campos da resposta

Campo	Tipo	Descrição
`status`	boolean	Indica se a solicitação foi concluída com sucesso.
`remaining_credits`	integer	Créditos disponíveis após a solicitação.
`expires`	integer	Data de expiração dos créditos em formato de timestamp UNIX.
`duration`	string	Tempo de processamento no servidor.
`regionCode`	string	Código de região ISO 3166-1 alfa-2 detectado.
`countryCode`	integer	Código de discagem internacional.
`country`	string	Nome do país em formato legível.
`national`	string	Número formatado para uso nacional.
`international`	string	Número formatado para exibição internacional.
`e164`	string	Representação canônica no padrão E.164.
`isValid`	boolean	Indica se o número atende às regras regionais de validação.
`isPossible`	boolean	Indica se o número pode existir com base em sua estrutura.
`numberType`	string	Categoria de número detectada.
`nationalSignificantNumber`	string	Número nacional sem o código de discagem do país.
`rawInput`	string	Número original enviado na solicitação.
`isGeographical`	boolean	Indica se o número pode ser associado a uma área geográfica.
`areaCode`	string	Segmento de código de área detectado.
`location`	string	Local associado ao código de área.

Referência de classificação

Valores de tipo de número

FIXED_LINE

Linha fixa vinculada a uma localização geográfica.

MOBILE

Número móvel ou celular.

FIXED_LINE_OR_MOBILE

O plano de numeração não diferencia linha fixa de celular.

TOLL_FREE

Número gratuito com custo pago pelo destinatário.

PREMIUM_RATE

Número de serviço com tarifa premium.

SHARED_COST

O custo da chamada é dividido entre quem liga e quem recebe.

VOIP

Número de telefone por voz sobre IP.

PERSONAL_NUMBER

Número pessoal que pode redirecionar para outra linha.

PAGER

Número de notificação de pager.

UAN

Número de acesso universal usado como contato comercial compartilhado.

VOICEMAIL

Número dedicado de acesso ao correio de voz.

UNKNOWN

Não foi possível determinar a categoria do número.

Perguntas frequentes

Perguntas frequentes sobre a API de telefone

O que a API de validação de telefone faz?

Ela valida e normaliza números de telefone, devolve formatos nacional, internacional e E.164 e identifica região, tipo de número e metadados geográficos quando disponíveis.

Qual é a diferença entre isValid e isPossible?

isValid verifica o número segundo as regras regionais de numeração; isPossible indica que a estrutura pode representar um número, mesmo quando não é possível confirmar sua validade.

Quando address é obrigatório?

Informe address quando o número não começar com o sinal de mais e o código de discagem internacional. O valor pode ser um código ISO de país, nome do país, cidade ou região.

Como enviar caracteres especiais?

Codifique espaços, sinais de mais e outros caracteres especiais na URL dos parâmetros GET. Os corpos JSON de solicitações POST são codificados pelo cliente HTTP.

Próxima referência

Monitore uso e cota

Uso e cotaEntenda créditos e limites →Bibliotecas clienteInstale um pacote de validação de telefone →