Upload a Custom Watchlist

Use this API to upload a custom watchlist

Upload a National ID and a Custom Document
Open Recipe
Upload a Custom Document
Open Recipe

This API corresponds to the Custom Watchlist merit, which lets you upload a comma-separated value (*.csv) file with up to 10,000 individual entries, and maximum file size of 10MB.

Each entry can have:

  • fullName: (Required) The full name of the user
  • documentNumber: (Required) The document number associated with the user
  • dateOfBirth: The user's date of birth in YYYY-MM-DD format
  • documentType: The document type associated with the document number. The documents can include:
    • Driving License
    • National ID
    • Passport
  • country: the document's country of issue (ISO-2 format)
  • Email address
  • Phone number


This API Requires a Webhook URL

Go here for more information on setting up a webhook listener.


File Upload Must Be Called Last

The file parameter must be at the end of the parameter list.

Example Requests

The following request uploads the file watchlist_file.csv.

curl --location --request POST 'https://api.getmati.com/safety/v1/upload/watchlists/file' \
  --header 'Content-Type: multipart/form-data' \
  --header 'Authorization: Bearer <access_token>' \
  --form 'watchlistId="10"' \
  --form 'csvSeparator=";"' \
  --form 'callbackUrl="https://some.callback.url/"' \
  --form 'file=@"/Users/user/files/watchlist_file.csv"'
Click Try It! to start a request and see the response here!