Enriquecimento

Enriquecimento reverso por celular

POST consome créditos

O preço desta operação para a sua conta fica em Configurações → Planos, já com o valor negociado do seu workspace.

Dado um celular brasileiro (11 dígitos: DDD + 9XXXXXXXX), retorna o CPF mais provável e os dados públicos da pessoa para pré-qualificar o lead: identidade (nome, sexo, cidade), empresas onde é sócio (CNPJ, razão social, matriz/filial, total) e cargo/departamento (LinkedIn, quando houver).

🔒 NÃO retorna contato — nada de celular, telefone ou e-mail.

⚡ Consome créditos por HIT. Celular sem CPF correspondente = grátis (no-data billing). O mesmo celular consultado de novo em 30 dias (API ou MCP) = grátis.

Formato aceito: dígitos puros (41999998888), com máscara ((41) 99999-8888) ou com prefixo 55 (5541999998888). O 3º dígito precisa ser 9 (celular) — fixo de 10 dígitos é rejeitado.

Ranking de CPF: quando o celular aparece com vários CPFs, o de maior nº de ocorrências é o primário (ranking.confidence); os concorrentes vêm mascarados.

Fallback: celular que a base TAMZ não conhece segue automaticamente para uma fonte externa; nesse caso ranking vem null.

Rate limit: 60 req/min

01

Testar ao vivo

Autorização

Sua API key, gerada em /developer/api-keys. Gratuita para começar.

Sua requisição

curl -X POST 'https://tamz.ai/api/v1/enrichment/reverse-phone' \
  -H 'Authorization: Bearer tamz_SUA_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "phone": "41999998888"
}'
02

Corpo da requisição

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

phone*string

Celular a enriquecer: 11 dígitos DDD + 9XXXXXXXX (aceita máscara e prefixo 55).

03

Exemplo de retorno

{
  "data": {
    "cpf": "string",
    "identity": {
      "nome": "string",
      "sexo": "string",
      "cidade": "string",
      "uf": "string"
    },
    "ranking": {
      "cpf": "string",
      "confidence": 0,
      "totalRecords": 0,
      "primaryOccurrences": 0,
      "distinctCpfs": 0,
      "alternatives": [
        {
          "cpfMasked": "string",
          "occurrences": 0
        }
      ]
    },
    "companies": {
      "total": 0,
      "items": [
        {
          "cnpj": "string",
          "razaoSocial": "string",
          "nomeFantasia": "string",
          "tipo": "string",
          "cnpjRoot": "string",
          "papel": "string",
          "equityPct": 0
        }
      ]
    },
    "disputed": true,
    "other_candidates": [
      {
        "cpfMasked": "string",
        "occurrences": 0
      }
    ],
    "linkedin": {
      "url": "string",
      "role": {
        "jobTitle": "string",
        "department": "string",
        "seniority": "string"
      }
    }
  },
  "meta": {
    "credits_used": 0,
    "found": true,
    "source": "tamz"
  }
}
{
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Invalid parameters"
  }
}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing API key. Use Authorization: Bearer tamz_xxx or X-API-Key header"
  }
}
{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient credits",
    "required": 10,
    "available": 3,
    "upgrade_path": "/settings/plans",
    "next_action": "Top up credits and retry — zero-result searches are never charged."
  }
}
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "retry_after": 42
  }
}
{
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Invalid parameters"
  }
}
04

Respostas e códigos

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

Começar grátis