Create fraud marker

Reports the fraud marker to BACEN (createFraudMarker, idempotent on a RequestId derived from X-Idempotency) and persists it once BACEN confirms. Always synchronous: an ambiguous outcome or a replay is reconciled inline — when this request’s operation already carries BACEN’s id, the marker BACEN serves under it (checked against the request’s document, key and fraud type) is persisted and answered with 201. With no id known yet the answer is 503 SPI-1010, retry with the same X-Idempotency: when BACEN never answered, the reconciliation sweep resends the create with the same RequestId (which BACEN dedups) and records the id, after which the retry is answered 201; when BACEN confirmed without an id, the operation goes to manual review and the retry is answered once an operator resolves it. 422 when BACEN refuses the marker.

POST /api/v1/dict/fraud-markers

Create fraud marker

cURL

curl --request POST \
  --url https://api.example.com/api/v1/dict/fraud-markers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "fraudType": "MULE_ACCOUNT",
  "ownerTaxId": "52998224725",
  "participantISPB": "12345678",
  "keyValue": "[e-mail]"
}
'

201

{
  "createdAt": "2026-06-14T12:00:00Z",
  "fraudType": "MULE_ACCOUNT",
  "id": "550e8400-e29b-41d4-a716-446655440002",
  "keyValueHash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "ownerTaxIdHash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "participantISPB": "12345678",
  "reportStatus": "SENT",
  "status": "ACTIVE",
  "updatedAt": "2026-06-14T12:00:00Z",
  "bacen": {
    "correlationId": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "lastModified": "2026-06-14T12:00:00Z",
    "responseTime": "2026-06-14T12:00:00Z"
  },
  "bacenCreationTime": "2026-06-14T12:00:00Z",
  "keyValue": "[e-mail]",
  "operationId": "01930000-0000-7000-8000-000000000000",
  "operationStatus": "COMPLETED",
  "originInfractionReportId": "550e8400-e29b-41d4-a716-446655440005",
  "originInfractionReporterISPB": "12345678",
  "originOperationId": "01930000-0000-7000-8000-000000000000",
  "ownerTaxId": "52998224725"
}

Autorizaciones

Authorization · string · header · requerido

JWT bearer token issued by the identity provider.

Encabezados

X-Idempotency · string · requerido

Required key used to prevent replaying the mutation.

Cuerpo

application/json

Fraud marker reported to BACEN first; only a CONFIRMED report is persisted locally, minimized — a rejection or ambiguous outcome creates no local row. Tracked by report_status=SENT + the durable operation intent (operationId) that created it; PII inputs (key value, owner tax ID) are hashed before storage.

fraudType · enum<string> · requerido

BACEN fraud classification: APPLICATION_FRAUD, MULE_ACCOUNT, SCAMMER_ACCOUNT, OTHER, or UNKNOWN

Opciones disponibles: APPLICATION_FRAUD, MULE_ACCOUNT, SCAMMER_ACCOUNT, OTHER, UNKNOWN

Ejemplo:

"MULE_ACCOUNT"

ownerTaxId · string · requerido

Plaintext owner tax ID (CPF/CNPJ) the marker is associated with, shaped as the SPI wire type PICpfCnpj: 11 digits for a CPF, 14 alphanumeric characters for a CNPJ. BACEN requires it in the clear and its pattern rejects a hash, so it is sent verbatim inside the signed body. The clear value is also kept in the operation request_body, the BACEN snapshot, the MED snapshot facts and the responses; the row column holds its HMAC hash. Never logged.

Pattern: ^([0-9]{11}|[0-9A-Z]{12}[0-9]{2})$

Ejemplo:

"52998224725"

participantISPB · string · requerido

ISPB (8 digits or uppercase letters) of the participant raising the fraud marker

Pattern: ^[0-9A-Z]{8}$

Ejemplo:

"12345678"

keyValue · string

Optional plaintext Pix key of the fraudster, informed when known so the key also receives the fraud mark; a blank value is treated as absent. The clear key travels in the signed BACEN body, the operation request_body, the BACEN snapshot, the MED snapshot facts and the fraud-marker responses; the row column holds its HMAC hash. Never logged. At most 77 characters, the ceiling BACEN publishes on a DICT key.

Maximum string length: 77

Ejemplo:

"[e-mail]"

Respuesta

201

application/json

Created

Persisted minimized fraud marker and the operation that created it.

createdAt · string · requerido

Record creation timestamp (RFC 3339, UTC)

Ejemplo:

"2026-06-14T12:00:00Z"

fraudType · string · requerido

BACEN fraud classification: APPLICATION_FRAUD, MULE_ACCOUNT, SCAMMER_ACCOUNT, OTHER, or UNKNOWN

Ejemplo:

"MULE_ACCOUNT"

id · string · requerido

BACEN-assigned fraud-marker resource UUID — the public, canonical identity of this record

Ejemplo:

"550e8400-e29b-41d4-a716-446655440002"

keyValueHash · string · requerido

HMAC hash of the marked Pix key value (hex); empty when no key was given

Ejemplo:

"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

ownerTaxIdHash · string · requerido

HMAC hash of the owner tax ID (hex); kept for consumers that index/audit on the minimized projection

Ejemplo:

"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

participantISPB · string · requerido

ISPB (8 digits or uppercase letters) of the participant that raised the fraud marker

Ejemplo:

"12345678"

reportStatus · string · requerido

BACEN report delivery state. Always SENT at rest (a resource row is persisted only once BACEN has confirmed it; a rejected or ambiguous attempt creates no row).

Ejemplo:

"SENT"

status · string · requerido

Local fraud-marker state: ACTIVE (counts toward fraud stats) or INACTIVE (retained for audit only)

Ejemplo:

"ACTIVE"

updatedAt · string · requerido

Last update timestamp (RFC 3339, UTC)

Ejemplo:

"2026-06-14T12:00:00Z"

bacen · object

BACEN's own operational envelope for its most recent interaction on this fraud marker, including its LastModified version; omitted when no BACEN interaction has ever landed on it.

Show child attributes

bacenCreationTime · string

When BACEN created this fraud marker (RFC 3339, UTC); distinct from createdAt

Ejemplo:

"2026-06-14T12:00:00Z"

keyValue · string

Clear Pix key value the caller informed or BACEN echoed (ExtendedFraudMarker.Key); omitted when no key is known

Ejemplo:

"[e-mail]"

operationId · string

Durable MED operation-intent id of the create that produced this marker; always present.

Ejemplo:

"01930000-0000-7000-8000-000000000000"

operationStatus · enum<string>

Durable operation-intent status. COMPLETED on an ordinary create; any other value means the marker was reconciled from BACEN inline (or a replay served the row an earlier attempt wrote) and the operation is still the reconciliation's to complete (the sweep, or an operator for MANUAL_REVIEW).

Opciones disponibles: COMPLETED, UNKNOWN_OUTCOME, MANUAL_REVIEW, SYNC_PENDING, RESERVED, SUBMITTED, CONFIRMED

Ejemplo:

"COMPLETED"

originInfractionReportId · string

BACEN-assigned infraction that originated this marker (ExtendedFraudMarker.InfractionReport.Id); omitted when there is none

Ejemplo:

"550e8400-e29b-41d4-a716-446655440005"

originInfractionReporterISPB · string

Reporter ISPB of the originating infraction (ExtendedFraudMarker.InfractionReport.ReporterParticipant); omitted when there is none

Ejemplo:

"12345678"

originOperationId · string

Durable operation-intent id that produced this snapshot's current state, when known

Ejemplo:

"01930000-0000-7000-8000-000000000000"

ownerTaxId · string

BACEN-observed clear owner tax ID (CPF/CNPJ) — ExtendedFraudMarker.TaxIdNumber; omitted when BACEN has never echoed one back

Ejemplo:

"52998224725"