Restricted lists

This endpoint checks whether a person's name appears in one or more restricted lists.

The lookup can also be done by CPF (the Brazilian individual taxpayer number) or CNPJ (the Brazilian company taxpayer number), with the taxId parameter.

Request

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

Parameters

Parameter	Description	Required
list	List to search (see the options below)	Yes
name	Name of the person being queried, from 3 to 200 characters — both ends included	Yes, if there is no taxId
taxId	CPF or CNPJ of the person being queried	No

You must inform name or taxId. When both come in the same call, taxId is used and name is ignored.

List options (list):

Value	List
auxilioemergencial	Emergency assistance beneficiaries
bacen	Brazilian central bank
candidatoseleitorais	Election candidates
ceis	Registration of Disreputable and Suspended Companies (CEIS)
cepim	Prevented Private Non-Profit Entities Register (CEPIM)
cnep	National Register of Punished Companies (CNEP)
cvm	Brazilian Securities Commission (CVM) register
diariooficial	Government gazette
europeias	European sanctions
leniencia	Leniency agreements
ofacsdn	SDN list of the US Office of Foreign Assets Control (OFAC)
onu	UN sanctions
pep	Politically Exposed Persons (PEP) register
todas	Searches every available list. See the warning below.
trabalhoescravo	Slave labor
uk	United Kingdom sanctions

The value of list is the same identifier that comes back in data[].list (in v2) and in data.lists (in v1), always in lowercase.

‼️ list=todas queries all sixteen lists and bills for all sixteen

If the todas ("all") option is used, the lookup is performed across every list and the amount billed corresponds to the sum of each individual query. So make sure this is the right option for your scenario.

todas also requires the nextid.bureaus.restrictedLists.allLists permission. A key that only has nextid.bureaus.restrictedLists.oneList queries any individual list normally, but gets 401 when asking for todas.

Lookup by name

The comparison is by substring contained in the name, case-insensitive. Searching for silva returns every record whose name contains silva in any position.

Lookup by taxId

taxId accepts a CPF or a CNPJ, with or without the mask. What decides between the two is the number of characters once the separators are removed: 11 is a CPF, 14 is a CNPJ. Any other length does not raise an error — the lookup simply finds nothing.

Some of the lists publish the CPF masked. That is why a lookup by CPF also searches for the corresponding masked form (***.456.789-** for the CPF 12345678909), and the records found that way come flagged in reconciliation.

Headers

Authorization: ApiKey <your-api-key>

Example request

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

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

Lookup by CPF:

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

Response

The fields below describe the response of v2, the recommended version and the one used in the examples on this page. v1 returns a data in another format — see Versions.

Each item of data is a list + source file pair, with the records found in it.

Field	Description	Type
id	Unique ID of the request	String
version	API version	String
data	List of the lookup results, grouped by list and source file	Object[]
data[].list	Identifier of the list, the same one accepted in the list parameter	String
data[].file	Source file, in the YYYYMMDD_LIST.csv format	String
data[].found	Records found in that file	Object[]
data[].found[].name	Name as it appears in the list	String
data[].found[].taxId	CPF or CNPJ as it appears in the list, possibly masked	String
data[].found[].reconciliation	How the record was matched against the taxId queried. Only appears when there is information.	String
data[].found[].candidates	Candidates recorded at the source for that record. Only appears when the source provides them.	Object[]
metadata	Object with the metadata of the request	Object
metadata.timeSpent	Request time, in milliseconds	Number

‼️ data is a list, not an object

Code written to read data.found gets undefined. And the empty response is [], not { "found": false }.

Calling /restricted-lists without stating the version hands the call over to v1, which has another format. Always inform the version in the URL.

When the lookup is done by taxId and a group contains at least one record whose reconciliation is exact, the remaining records of that group are discarded — only the exact match is left.

🚧 Do not compare reconciliation against a closed list

The confirmed values are exact, for a direct match of the document, and unavailable, for a record whose taxId at the source comes masked and could not be checked. The source may bring other values.

Treat exact as the confirmed match and any other value as a result to be checked, instead of comparing against a closed list.

JSON examples

Here is a JSON example of the response.

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
  }
}

When nothing is found

data comes back as an empty list.

Status Code: 200

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

Response headers

Header	When it appears
Nextid-ReqId	On every response. Carries the request identifier, the same one as the id field of the body.

Errors

Code	When it happens
401 Unauthorized	API key missing, invalid, without any of the restricted-list permissions, or asking for list=todas without the nextid.bureaus.restrictedLists.allLists permission.
404 Not Found	The version informed in the URL does not exist. Only v1 and v2 are accepted.
422 Unprocessable Entity	list missing or outside the options, or name shorter than 3 or longer than 200 characters without taxId having been informed.
500 Internal Server Error	Unexpected failure during processing.

Example of a response with a list outside the options:

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"
  }
}

The format of the error responses is described in HTTP response codes.

Versions

Version	Status	What changes
v2	Recommended	data is a list, grouped by list and file, with the records found. It says who was found.
v1	Available	data is an object with found, lists and files. It is what answers when the version is omitted from the URL.

v2 is the version described on this page. Always state the version in the call path: /restricted-lists without a version keeps answering as v1, in the old format.

The data of v1

Kept as a record for those already integrated with v1. It says whether there was a result, not who was found: found is just true or false, and lists/files say in which list and in which file there was a result. The names and documents found do not appear in this version.

Field	Description	Type
data	Object with the result of the lookup	Object
data.found	Was the name found in the list searched?	Boolean
data.lists	Identifiers of the lists that produced a result	String[]
data.files	Source files of the results, in the YYYYMMDD_LIST.csv format	String[]

The id, version and metadata fields are the same as on v2.

Status Code: 200

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

When nothing is found, found comes back false and both lists come back empty:

Status Code: 200

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