Create a fraud marker

Registers a DICT fraud marker for the taxpayer identified by taxIdNumber, optionally linked to a Pix key. requestId is the caller-provided idempotency key. Repeating a requestId with the same payload returns the same marker; repeating it with a different payload is rejected. The participant is determined by the authenticated tenant. When BACEN’s outcome is not known yet, the operation answers the retryable 502 / PIX-0141: nothing is registered here, and BACEN may still register the marker. Resend with the same requestId until the answer is not 502 / PIX-0141; a new requestId can register a second marker. A 504 / PIX-0054 leaves the outcome unknown too: resend it the same way.

POST /dict/fraud-markers

Create a fraud marker

cURL

curl --request POST \
  --url https://api.example.com/dict-hub/v1/dict/fraud-markers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "fraudType": "APPLICATION_FRAUD",
  "requestId": "3f2f6a52-a5b7-4f1a-9b0f-64d3f4b6c111",
  "taxIdNumber": "12345678901",
  "key": "[phone]"
}
'

201

{
  "creationTime": "2026-08-21T10:00:00Z",
  "fraudType": "APPLICATION_FRAUD",
  "id": "0b843bcc-7c1a-4a12-9c88-8d3a5d70e6a1",
  "lastModified": "2026-08-21T10:00:00Z",
  "status": "REGISTERED",
  "taxIdNumber": "12345678901",
  "infractionReport": {
    "id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
    "reporterParticipant": "18236120"
  },
  "key": "[phone]"
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Body

application/json

fraudType · enum<string> · required

BACEN DICT fraud type (UNKNOWN is read-only, never creatable)

Available options: APPLICATION_FRAUD, MULE_ACCOUNT, SCAMMER_ACCOUNT, OTHER

Example:

"APPLICATION_FRAUD"

requestId · string<uuid> · required

Caller-minted create idempotency key, forwarded verbatim to the provider

Example:

"3f2f6a52-a5b7-4f1a-9b0f-64d3f4b6c111"

taxIdNumber · string · required

CPF or CNPJ (numeric or alphanumeric per IN RFB 2.229/2024) being marked, checked against BACEN/RFB check digits. Mask, surrounding whitespace, and lowercase are accepted and normalized to the canonical unformatted uppercase form before use.

Example:

"12345678901"

key · string

Optional Pix key tied to the marker. Maximum 77 BYTES UTF-8, not characters -- the schema deliberately does not declare maxLength (OpenAPI's maxLength counts characters, which would under-bound a multi-byte key); the byte-length limit is enforced at runtime (the service implementation).

Example:

"[phone]"

Response

201

application/json

Fraud marker registered.

creationTime · string<date-time> · required

When the marker was registered at the provider (RFC 3339 UTC)

Example:

"2026-08-21T10:00:00Z"

fraudType · enum<string> · required

Available options: APPLICATION_FRAUD, MULE_ACCOUNT, SCAMMER_ACCOUNT, OTHER, UNKNOWN

Example:

"APPLICATION_FRAUD"

id · string<uuid> · required

Directory fraud-marker id

Example:

"0b843bcc-7c1a-4a12-9c88-8d3a5d70e6a1"

lastModified · string<date-time> · required

When the marker was last modified at the provider (RFC 3339 UTC)

Example:

"2026-08-21T10:00:00Z"

status · enum<string> · required

Available options: REGISTERED, CANCELLED

Example:

"REGISTERED"

taxIdNumber · string · required

CPF (11 digits) or CNPJ (14 characters: 12 uppercase alphanumeric characters followed by 2 digits, unformatted, per IN RFB 2.229/2024) marked

Example:

"12345678901"

infractionReport · object

The infraction report the provider created this marker from, when applicable

Show child attributes

key · string

Pix key linked to the marker, when one was supplied on create

Example:

"[phone]"