Watch a CPF/CNPJ for antifraud signal

curl --request POST \
  --url https://spi.sandbox.lerian.net/api/v1/dict/persons/watchlist \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "taxIdNumber": "<string>"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://spi.sandbox.lerian.net/api/v1/dict/persons/watchlist"

	payload := strings.NewReader("{\n  \"taxIdNumber\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({taxIdNumber: '<string>'})
};

fetch('https://spi.sandbox.lerian.net/api/v1/dict/persons/watchlist', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://spi.sandbox.lerian.net/api/v1/dict/persons/watchlist"

payload = { "taxIdNumber": "<string>" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "consecutiveFailures": 123,
  "createdAt": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "taxIdNumber": "<string>",
  "lastAttemptAt": "<string>",
  "lastObservedAt": "<string>",
  "lastWatermark": "<string>",
  "quarantinedAt": "<string>",
  "removedAt": "<string>"
}

{
  "correlationId": "req-7a3f9c2e",
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Watch a CPF/CNPJ for antifraud signal

Admits a document to the antifraud watchlist. Once watched, BACEN’s ecosystem-wide antifraud counters for that document (getPersonStatistics) are observed on a configured cadence, and a canonical observation fact is emitted whenever BACEN’s own watermark moves. Idempotent: re-adding a watched document changes nothing; re-adding a removed one resumes it with its dedupe baseline intact. Rejected with 422 once the participant’s document cap is reached, because every watched document is a recurring call against a shared BACEN budget.

POST

api

dict

persons

watchlist

Watch a CPF/CNPJ for antifraud signal

curl --request POST \
  --url https://spi.sandbox.lerian.net/api/v1/dict/persons/watchlist \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "taxIdNumber": "<string>"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://spi.sandbox.lerian.net/api/v1/dict/persons/watchlist"

	payload := strings.NewReader("{\n  \"taxIdNumber\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({taxIdNumber: '<string>'})
};

fetch('https://spi.sandbox.lerian.net/api/v1/dict/persons/watchlist', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://spi.sandbox.lerian.net/api/v1/dict/persons/watchlist"

payload = { "taxIdNumber": "<string>" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "consecutiveFailures": 123,
  "createdAt": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "taxIdNumber": "<string>",
  "lastAttemptAt": "<string>",
  "lastObservedAt": "<string>",
  "lastWatermark": "<string>",
  "quarantinedAt": "<string>",
  "removedAt": "<string>"
}

{
  "correlationId": "req-7a3f9c2e",
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "correlationId": "req-7a3f9c2e",
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Autorizaciones

Authorization

string

header

requerido

JWT bearer token issued by the identity provider.

Cuerpo

application/json

taxIdNumber

string

requerido

CPF (11 digits) or CNPJ (14 characters — alphanumeric since IN RFB 2.229/2024) to watch. Sent in the body, never in the URL, because it is PII. Re-adding a document already watched returns the existing entry unchanged; re-adding one previously removed resumes watching the same entry, preserving its last observation.

Respuesta

Created

consecutiveFailures

integer<int64>

requerido

How many observation attempts have failed back to back. Any success resets it to zero.

createdAt

string

requerido

When the document was admitted (RFC 3339).

string<uuid>

requerido

Opaque entry id. Remove addresses this, never the document.

taxIdNumber

string

requerido

The watched CPF/CNPJ.

lastAttemptAt

string

When the poll last TRIED this document, successfully or not. Diverging from lastObservedAt means BACEN is refusing this subject.

lastObservedAt

string

When BACEN's counters were last read for this document. Absent until the first observation.

lastWatermark

string

BACEN's own freshness marker for the last observation — the composite of the four PersonStatistics block watermarks. This, not the read time, is what changes when the counters change. BACEN's counters are up to 12 hours stale by regulation, so a recent read never means recent data.

quarantinedAt

string

When repeated failures parked this document. A parked document is no longer polled and no longer counted by the readiness staleness check — one unreadable subject must not take the rail unready. Removing and re-adding it resumes surveillance.

removedAt

string

When surveillance was stopped, if it was. Removal is a soft stop: observations already emitted are never retracted.