Validação de telefones em loteBETAcore beta

Normalize telefones para E.164 e devolva o tipo de linha (mobile, landline, mobile_or_landline, other). O país é a região de parsing. Até 1.000 por request.

Contrato estável; mudanças breaking apenas com deprecation prévio.

POST/v1/validate/phones

Visão geral

Validate a batch of phone numbers. Each item declares its `country` (used as the parsing region) and the raw `value`. The API parses numbers in any format and returns the E.164 form, `valid`, and the line `type` ∈ {mobile, landline, mobile_or_landline, other}. Each result carries `valid`, the `normalized` E.164 number and `type`. Up to 1000 phones per request.

URL base: https://api.normadata.io

Header de autenticação: X-API-Key: nd-...

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
items	array	sim	Array of items to validate (1–1000). Each item is the object described below.
items[].id	string	não	Client-provided correlation id, echoed back verbatim in the matching result.
items[].value	string	sim	Phone number in any format (with or without separators / country code).
items[].country	string	sim	ISO 3166-1 alpha-2 country code used as the parsing region.

Exemplo de requisição

cURL

curl -X POST https://api.normadata.io/v1/validate/phones \
  -H "X-API-Key: nd_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"items":[
    {"id":"1","value":"+54 (11) 4555-2233","country":"AR"},
    {"id":"2","value":"11987654321","country":"BR"}
  ]}'

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

type PhoneItem struct {
	ID      string `json:"id"`
	Value   string `json:"value"`
	Country string `json:"country"`
}

type PhoneResult struct {
	ID         string `json:"id"`
	Valid      bool   `json:"valid"`
	Normalized string `json:"normalized"`
	Type       string `json:"type"`
}

type PhoneResponse struct {
	Results []PhoneResult `json:"results"`
}

func main() {
	body, _ := json.Marshal(map[string][]PhoneItem{
		"items": {
			{ID: "1", Value: "+54 (11) 4555-2233", Country: "AR"},
			{ID: "2", Value: "11987654321", Country: "BR"},
		},
	})
	req, _ := http.NewRequest("POST", "https://api.normadata.io/v1/validate/phones", bytes.NewReader(body))
	req.Header.Set("X-API-Key", os.Getenv("NORMADATA_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()

	var out PhoneResponse
	json.NewDecoder(res.Body).Decode(&out)
	for _, r := range out.Results {
		fmt.Println(r.ID, r.Valid, r.Normalized, r.Type)
	}
}

Exemplo de resposta

Exemplo de resposta `200`

JSON

{
  "results": [
    {
      "id": "1",
      "valid": true,
      "normalized": "+541145552233",
      "type": "landline"
    },
    {
      "id": "2",
      "valid": true,
      "normalized": "+5511987654321",
      "type": "mobile"
    }
  ]
}

Erros comuns

Códigos de erro que você pode encontrar ao chamar este endpoint. O envelope completo está documentado na referência principal.

Código
INVALID_PHONE
MISSING_VALUE
empty_batch
batch_too_large
quota_exceeded

Ver todos os códigos de erro →

Notas

Validates that the number is well-formed for the country — it does not call the carrier or send a test SMS. Line type ∈ {mobile, landline, mobile_or_landline, other}. The envelope is shared by every endpoint: POST `{items:[…]}` (1–1000) → `{results:[…]}` correlated by `id`.

Endpoints relacionados

POST /v1/validate/tax-ids

Validação de Tax IDs em lote

POST /v1/validate/accounts

Validação de contas bancárias em lote

POST /v1/validate/emails

Validação de e-mails em lote

POST /v1/validate/records

Validação de registros completos

Acesso