Skip to main content
GET
/
onboarding
/
api
/
v1
/
know
/
business
/
{requestId}
Consultar Resultados KYB
curl --request GET \
  --url https://api-hml.valid.com/onboarding/api/v1/know/business/{requestId} \
  --header 'x-api-key: <api-key>'
{
  "result": {},
  "result.requestId": "<string>",
  "result.key": "<string>",
  "result.datasets": [
    {}
  ],
  "result.datasets[].dataset": "<string>",
  "result.datasets[].data": {}
}

​
Path Parameters

​
requestId
string
required
Identificador único da requisição obtido ao iniciar a consultaFormato: UUIDExemplo: 05be75cc-8f8a-414a-891f-434aa9b4e7a5

​
Response

A resposta retorna um objeto result com os dados estruturados da consulta KYB (Pessoa Jurídica).
​
result
object
Dados estruturados do resultado da consulta KYB (Pessoa Jurídica).
​
result.requestId
string
ID da requisição no onboardingExemplo: 05be75cc-8f8a-414a-891f-434aa9b4e7a5
​
result.key
string
CNPJ consultadoExemplo: 12345678000100
​
result.datasets
array
Lista de datasets de Pessoa Jurídica. Cada item possui dataset (identificador da consulta) e data (objeto com os dados).
​
result.datasets[].dataset
string
Identificador do tipo de dataset (ex: basic, kyc, addresses)Exemplo: basic
​
result.datasets[].data
object
Dados do dataset; a estrutura varia conforme o valor de dataset. Os tipos possíveis (KYB PJ) estão listados na seção abaixo.

​
Estrutura de data por tipo de dataset (KYB PJ)

O campo result.datasets[].data pode ser um dos objetos abaixo, conforme o dataset retornado.
Dados básicos da empresa (Pessoa Jurídica).
  • cnpj (string): CNPJ
  • name (string): Razão social
  • fantasyName (string): Nome fantasia
  • foundingDate (string): Data de fundação
  • dissolutionDate (string): Data de fechamento
  • nationality (string): País de registro
  • taxIdStatus (string): Status do CNPJ na Receita Federal
  • taxRegime (string): Regime tributário
  • companyType (string): Tipo de empresa
  • age (number): Idade da empresa em anos
  • isHeadquarter (boolean): É matriz do grupo
  • headquarterState (string): Estado da matriz
  • isConglomerate (boolean): É conglomerado
  • legalNature (object): Natureza jurídica (code, description)
  • activities (array): Atividades CNAE. Cada item possui: isMain (boolean), code (string), activity (string)
Lista de endereços. O array contém objetos com:
  • streetAddress (string): Logradouro completo
  • addressLocality (string): Cidade
  • addressRegion (string): Estado
  • postalCode (string): CEP
  • addressCountry (string): País
  • complement (string): Complemento
  • neighborhood (string): Bairro
  • isActive (boolean): Endereço ativo
  • isMain (boolean): Endereço principal
Lista de telefones. O array contém objetos com:
  • number (string): Número de telefone
  • areaCode (string): Código de área
  • countryCode (string): Código de país
Indicadores de atividade da empresa.
  • employeesRange (string): Faixa de funcionários
  • incomeRange (string): Faixa de renda
  • hasActivity (boolean): Tem atividade
  • activityLevel (number): Nível de atividade
Grupo econômico de primeiro nível.
  • mainCompanyTaxId (string): CNPJ principal
  • economicGroupType (string): Tipo do grupo
  • companyDocNumbers (array): CNPJs do grupo
  • totalCompanies (number): Total de empresas
  • totalActiveCompanies (number): Empresas ativas
KYC, PEP e sanções.
  • isCurrentlyPEP (boolean): É PPE atualmente
  • isCurrentlySanctioned (boolean): Sancionado atualmente
  • pepHistory (array): Histórico de PPE. Cada item possui:
    • level (string): Nível do PPE
    • jobTitle (string): Cargo
    • state (string): Estado
    • isCurrentlyPEP (boolean): É PPE atualmente
  • sanctionsHistory (array): Histórico de sanções. Cada item possui:
    • source (string): Fonte da sanção
    • type (string): Tipo de sanção
    • isCurrentlySanctioned (boolean): Sancionado atualmente
Mídia e exposição.
  • mediaExposureLevel (string): Nível de exposição
  • celebrityLevel (string): Nível de celebridade
  • unpopularityLevel (string): Nível de impopularidade
  • newsItems (array): Cada item possui os seguintes campos:
    • title (string): Título da notícia
    • sourceName (string): Nome da fonte
    • url (string): URL da notícia
    • publicationDate (string): Data de publicação
Processos judiciais e administrativos.
  • processes (array): Lista de processos. O array contém objetos com:
    • number (string): Número do processo
    • courtLevel (number): Nível do tribunal
    • partyType (string): Tipo de parte no processo
    • status (string): Situação do processo
    • value (number): Valor do processo
  • totalProcesses (number): Total de processos
Certidões PGFN. O array contém objetos com:
  • origin (string): Origem
  • protocolNumber (string): Protocolo
  • fileUrl (string): URL do resultado
  • status (string): Status

​
Exemplo de resposta

{
  "result": {
    "requestId": "05be75cc-8f8a-414a-891f-434aa9b4e7a5",
    "key": "12345678000100",
    "datasets": [
      {
        "dataset": "basic",
        "data": {
          "cnpj": "12345678000100",
          "name": "EMPRESA EXEMPLO LTDA",
          "fantasyName": "Exemplo",
          "foundingDate": "2007-04-03T00:00:00Z",
          "nationality": "Brasil",
          "taxIdStatus": "REGULAR",
          "taxRegime": "LUCRO REAL",
          "companyType": "MATRIZ",
          "age": 17
        }
      },
      {
        "dataset": "kyc",
        "data": {
          "isCurrentlyPEP": false,
          "isCurrentlySanctioned": false,
          "pepHistory": [],
          "sanctionsHistory": []
        }
      }
    ]
  }
}