Listas Restritivas

Este endpoint verifica se o nome de uma pessoa se encontra em uma ou mais listas restritivas.

A busca também pode ser feita por CPF ou CNPJ, com o parâmetro taxId.

Request

GET /restricted-lists/v2?name={name}&list={list}

Parâmetros

Parâmetro	Descrição	Obrigatório
list	Lista desejada (ver opções abaixo)	Sim
name	Nome da pessoa consultada, de 3 a 200 caracteres — os dois extremos entram	Sim, se não houver taxId
taxId	CPF ou CNPJ da pessoa consultada	Não

É preciso informar name ou taxId. Quando os dois vêm na mesma chamada, o taxId é usado e o name é ignorado.

Opções de listas (list):

Valor	Lista
auxilioemergencial	Beneficiários do Auxílio Emergencial
bacen	Banco Central do Brasil
candidatoseleitorais	Candidatos eleitorais
ceis	Cadastro de Empresas Inidôneas e Suspensas (CEIS)
cepim	Cadastro de Entidades Privadas Sem Fins Lucrativos Impedidas (CEPIM)
cnep	Cadastro Nacional de Empresas Punidas (CNEP)
cvm	Cadastro da Comissão de Valores Mobiliários (CVM)
diariooficial	Diário Oficial
europeias	Sanções europeias
leniencia	Acordos de leniência
ofacsdn	Lista SDN da Agência de Controle de Ativos Estrangeiros dos EUA (OFAC)
onu	Sanções da ONU
pep	Cadastro de Pessoas Expostas Politicamente (PEP)
todas	Busca em todas as listas disponíveis. Veja o aviso abaixo.
trabalhoescravo	Trabalho escravo
uk	Sanções do Reino Unido

O valor de list é o mesmo identificador que volta em data[].list (na v2) e em data.lists (na v1), sempre em minúsculas.

‼️ list=todas consulta as dezesseis listas e cobra as dezesseis

Caso seja utilizado o parâmetro todas, a busca será realizada em todas as listas e o valor tarifado será correspondente a somatória de cada consulta individual. Dessa forma, certifique-se que este é o parâmetro ideal para o seu cenário.

todas também exige a permissão nextid.bureaus.restrictedLists.allLists. Uma chave que só tem nextid.bureaus.restrictedLists.oneList consulta qualquer lista individual normalmente, mas recebe 401 ao pedir todas.

Busca por nome

A comparação é por trecho contido no nome, sem diferenciar maiúsculas de minúsculas. Buscar por silva retorna todo registro cujo nome contenha silva em qualquer posição.

Busca por taxId

O taxId aceita CPF ou CNPJ, com ou sem máscara. O que decide qual dos dois é o número de caracteres depois de removidos os separadores: 11 é CPF, 14 é CNPJ. Qualquer outro tamanho não gera erro — a consulta simplesmente não encontra nada.

Parte das listas publica o CPF mascarado. Por isso a busca por CPF procura também a forma mascarada correspondente (***.456.789-** para o CPF 12345678909), e os registros encontrados assim vêm marcados em reconciliation.

Headers

Authorization: ApiKey <sua-chave-de-api>

Exemplo Request

GET /restricted-lists/v2?name=Joao da Silva&list=ofacsdn

curl -i -G 'https://api.nxcd.app/restricted-lists/v2' \
  --header 'Authorization: ApiKey SUA_CHAVE_AQUI' \
  --data-urlencode 'name=Joao da Silva' \
  --data-urlencode 'list=ofacsdn'

Busca por CPF:

curl -i -G 'https://api.nxcd.app/restricted-lists/v2' \
  --header 'Authorization: ApiKey SUA_CHAVE_AQUI' \
  --data-urlencode 'taxId=12345678909' \
  --data-urlencode 'list=pep'

Response

Os campos abaixo descrevem a resposta da v2, a versão recomendada e a usada nos exemplos desta página. A v1 devolve um data com outro formato — veja Versões.

Cada item de data é um par lista + arquivo de origem, com os registros encontrados nele.

Campo	Descrição	Tipo
id	ID único da requisição	String
version	Versão da API	String
data	Lista dos resultados da busca, agrupados por lista e arquivo de origem	Object[]
data[].list	Identificador da lista, o mesmo aceito no parâmetro list	String
data[].file	Arquivo de origem, no formato AAAAMMDD_LISTA.csv	String
data[].found	Registros encontrados nesse arquivo	Object[]
data[].found[].name	Nome como consta na lista	String
data[].found[].taxId	CPF ou CNPJ como consta na lista, podendo vir mascarado	String
data[].found[].reconciliation	Como o registro foi casado com o taxId consultado. Só aparece quando há informação.	String
data[].found[].candidates	Candidatos registrados na origem para esse registro. Só aparece quando a origem os traz.	Object[]
metadata	Objeto com os metadados da requisição	Object
metadata.timeSpent	Tempo da requisição, em milissegundos	Number

‼️ data é uma lista, não um objeto

Um código escrito para ler data.found recebe undefined. E a resposta vazia é [], não { "found": false }.

Chamar /restricted-lists sem indicar a versão entrega a chamada para a v1, que tem outro formato. Sempre informe a versão na URL.

Quando a busca é feita por taxId e um grupo contém pelo menos um registro com reconciliation igual a exact, os demais registros daquele grupo são descartados — sobra só o casamento exato.

🚧 Não compare reconciliation contra uma lista fechada

Os valores confirmados são exact, para o casamento direto do documento, e unavailable, para o registro cujo taxId na origem vem mascarado e não pôde ser conferido. A origem pode trazer outros valores.

Trate exact como o casamento confirmado e qualquer outro valor como resultado a conferir, em vez de comparar contra uma lista fechada.

Exemplos JSON

Veja um exemplo em JSON da resposta.

Status Code: 200

{
  "id": "13cfec7c-b238-4820-a4d1-5173e4c1418e",
  "version": "v2",
  "data": [
    {
      "list": "pep",
      "file": "20210802_PEP.csv",
      "found": [
        {
          "name": "JOAO DA SILVA",
          "taxId": "***.456.789-**",
          "reconciliation": "unavailable"
        }
      ]
    }
  ],
  "metadata": {
    "timeSpent": 10000
  }
}

Quando nada é encontrado

data vem como lista vazia.

Status Code: 200

{
  "id": "13cfec7c-b238-4820-a4d1-5173e4c1418e",
  "version": "v2",
  "data": [],
  "metadata": {
    "timeSpent": 10000
  }
}

Headers de resposta

Header	Quando aparece
Nextid-ReqId	Em todas as respostas. Traz o identificador da requisição, o mesmo do campo id do corpo.

Erros

Código	Quando ocorre
401 Unauthorized	Chave de API ausente, inválida, sem nenhuma das permissões de listas restritivas, ou pedindo list=todas sem a permissão nextid.bureaus.restrictedLists.allLists.
404 Not Found	A versão informada na URL não existe. Só v1 e v2 são aceitas.
422 Unprocessable Entity	list ausente ou fora das opções, ou name com menos de 3 ou mais de 200 caracteres sem que taxId tenha sido informado.
500 Internal Server Error	Falha inesperada durante o processamento.

Exemplo de resposta com list fora das opções:

Status Code: 422

{
  "id": "13cfec7c-b238-4820-a4d1-5173e4c1418e",
  "error": {
    "statusCode": 422,
    "error": "Unprocessable Entity",
    "message": "The \"list\" query param is required and should be one of the following options: auxilioemergencial - bacen - candidatoseleitorais - ceis - cepim - cnep - cvm - diariooficial - europeias - leniencia - ofacsdn - onu - pep - todas - trabalhoescravo - uk"
  }
}

O formato das respostas de erro está descrito em Códigos HTTP das respostas.

Versões

Versão	Situação	O que muda
v2	Recomendada	data é uma lista, agrupada por lista e arquivo, com os registros encontrados. Diz quem foi encontrado.
v1	Disponível	data é um objeto com found, lists e files. É o que responde quando a versão é omitida na URL.

A v2 é a versão descrita nesta página. Informe sempre a versão no caminho da chamada: /restricted-lists sem versão continua respondendo pela v1, no formato antigo.

O data da v1

Registro para quem já integrou na v1. Ela diz se houve resultado, não quem foi encontrado: found é apenas true ou false, e lists/files dizem em que lista e em que arquivo houve resultado. Os nomes e documentos encontrados não aparecem nesta versão.

Campo	Descrição	Tipo
data	Objeto com o resultado da busca	Object
data.found	Nome encontrado na lista buscada?	Boolean
data.lists	Identificadores das listas em que houve resultado	String[]
data.files	Arquivos de origem dos resultados, no formato AAAAMMDD_LISTA.csv	String[]

Os campos id, version e metadata são os mesmos da v2.

Status Code: 200

{
  "id": "13cfec7c-b238-4820-a4d1-5173e4c1418e",
  "version": "v1",
  "data": {
    "found": true,
    "lists": [
      "ofacsdn"
    ],
    "files": [
      "20210802_OFACSDN.csv"
    ]
  },
  "metadata": {
    "timeSpent": 10000
  }
}

Quando nada é encontrado, found vem false e as duas listas vêm vazias:

Status Code: 200

{
  "id": "13cfec7c-b238-4820-a4d1-5173e4c1418e",
  "version": "v1",
  "data": {
    "found": false,
    "lists": [],
    "files": []
  },
  "metadata": {
    "timeSpent": 10000
  }
}