Contatos e endereços

Endereços

O serviço de Endereços retorna informações agregadas sobre localizações associadas a uma entidade, com base em dados públicos.

Falar com o comercial Ver o catálogo

Quando usar

Descrição

O serviço de Endereços fornece informações sobre localizações associadas à empresa, incluindo dados como a frequência com que cada endereço foi visualizado.

Também fornece um objeto agregado com todos os endereços relacionados à entidade consultada, facilitando análises e modelagens.

A consolidação de endereços similares é feita por meio de um código único de prédio (building code).

Requisição

Autenticação por chave de API (cabeçalho Authorization: Bearer), criada no painel com esta consulta no escopo.

POST /api/v1/{tenant}/empresas/enderecos

Campo	Obrigatório	Descrição
`document`	sim	CNPJ da empresa, com ou sem máscara.

{
  "document": "00.000.000/0000-00"
}

Campos de retorno

Campos dentro de data. [] indica lista.

Campo	Tipo
`TotalAddresses`	número
`TotalActiveAddresses`	número
`TotalWorkAddresses`	número
`TotalPersonalAddresses`	número
`TotalUniqueAddresses`	número
`TotalAddressPassages`	número
`TotalBadAddressPassages`	número
`OldestAddressPassageDate`	data
`NewestAddressPassageDate`	data
`Addresses[].Typology`	texto
`Addresses[].Title`	texto
`Addresses[].AddressMain`	texto
`Addresses[].Number`	texto
`Addresses[].Complement`	texto
`Addresses[].Neighborhood`	texto
`Addresses[].ZipCode`	texto
`Addresses[].City`	texto
`Addresses[].State`	texto
`Addresses[].Country`	texto
`Addresses[].Type`	texto
`Addresses[].AddressCurrentlyInRFSite`	booleano
`Addresses[].ComplementType`	texto
`Addresses[].BuildCode`	texto
`Addresses[].BuildingCode`	texto
`Addresses[].HouseholdCode`	texto
`Addresses[].AddressEntityAge`	número
`Addresses[].AddressEntityTotalPassages`	número
`Addresses[].AddressEntityBadPassages`	número
`Addresses[].AddressEntityCrawlingPassages`	número
`Addresses[].AddressEntityValidationPassages`	número
`Addresses[].AddressEntityQueryPassages`	número
`Addresses[].AddressEntityMonthAveragePassages`	número
`Addresses[].AddressGlobalAge`	número
`Addresses[].AddressGlobalTotalPassages`	número
`Addresses[].AddressGlobalBadPassages`	número
`Addresses[].AddressGlobalCrawlingPassages`	número
`Addresses[].AddressGlobalValidationPassages`	número
`Addresses[].AddressGlobalQueryPassages`	número
`Addresses[].AddressGlobalMonthAveragePassages`	número
`Addresses[].AddressNumberOfEntities`	número
`Addresses[].Priority`	número
`Addresses[].IsMainForEntity`	booleano
`Addresses[].IsRecentForEntity`	booleano
`Addresses[].IsMainForOtherEntity`	booleano
`Addresses[].IsRecentForOtherEntity`	booleano
`Addresses[].IsActive`	booleano
`Addresses[].IsRatified`	booleano
`Addresses[].IsLikelyFromAccountant`	booleano
`Addresses[].LastValidationDate`	data
`Addresses[].EntityFirstPassageDate`	data
`Addresses[].EntityLastPassageDate`	data
`Addresses[].GlobalFirstPassageDate`	data
`Addresses[].GlobalLastPassageDate`	data
`Addresses[].CreationDate`	data
`Addresses[].LastUpdateDate`	data
`Addresses[].HasOptIn`	booleano
`Addresses[].Latitude`	número
`Addresses[].Longitude`	número

Exemplo de resposta

Estrutura real da resposta, com valores fictícios.

{
  "execution_id": "00000000-0000-0000-0000-000000000000",
  "status": "success",
  "message": "Consulta realizada com sucesso",
  "query_name": "Endereços",
  "query_slug": "enderecos",
  "data": {
    "TotalAddresses": 0,
    "TotalActiveAddresses": 0,
    "TotalWorkAddresses": 0,
    "TotalPersonalAddresses": 0,
    "TotalUniqueAddresses": 0,
    "TotalAddressPassages": 0,
    "TotalBadAddressPassages": 0,
    "OldestAddressPassageDate": "2026-01-01",
    "NewestAddressPassageDate": "2026-01-01",
    "Addresses": [
      {
        "Typology": "texto",
        "Title": "texto",
        "AddressMain": "texto",
        "Number": "texto",
        "Complement": "texto",
        "Neighborhood": "texto",
        "ZipCode": "texto",
        "City": "texto",
        "State": "texto",
        "Country": "texto",
        "Type": "texto",
        "AddressCurrentlyInRFSite": false,
        "ComplementType": "texto",
        "BuildCode": "texto",
        "BuildingCode": "texto",
        "HouseholdCode": "texto",
        "AddressEntityAge": 0,
        "AddressEntityTotalPassages": 0,
        "AddressEntityBadPassages": 0,
        "AddressEntityCrawlingPassages": 0,
        "AddressEntityValidationPassages": 0,
        "AddressEntityQueryPassages": 0,
        "AddressEntityMonthAveragePassages": 0,
        "AddressGlobalAge": 0,
        "AddressGlobalTotalPassages": 0,
        "AddressGlobalBadPassages": 0,
        "AddressGlobalCrawlingPassages": 0,
        "AddressGlobalValidationPassages": 0,
        "AddressGlobalQueryPassages": 0,
        "AddressGlobalMonthAveragePassages": 0,
        "AddressNumberOfEntities": 0,
        "Priority": 0,
        "IsMainForEntity": false,
        "IsRecentForEntity": false,
        "IsMainForOtherEntity": false,
        "IsRecentForOtherEntity": false,
        "IsActive": false,
        "IsRatified": false,
        "IsLikelyFromAccountant": false,
        "LastValidationDate": "2026-01-01",
        "EntityFirstPassageDate": "2026-01-01",
        "EntityLastPassageDate": "2026-01-01",
        "GlobalFirstPassageDate": "2026-01-01",
        "GlobalLastPassageDate": "2026-01-01",
        "CreationDate": "2026-01-01",
        "LastUpdateDate": "2026-01-01",
        "HasOptIn": false,
        "Latitude": 0,
        "Longitude": 0
      }
    ]
  },
  "consulted_at": "2026-01-01T12:00:00Z",
  "query_cost": "0.100"
}

Cobrança e respostas

O valor é cobrado por consulta bem-sucedida.
200 — consulta processada (veja status no corpo da resposta)
401 — token ausente, inválido, inativo ou expirado
403 — serviço fora do escopo da chave, IP não autorizado ou limite de consumo excedido
422 — campo obrigatório ausente/inválido ou payload acima do limite do serviço
429 — limite de requisições por minuto da chave excedido
504 — tempo máximo de execução do serviço excedido