API reference

Fraud Reporting

POST/v1/fraud/reports

Report fraud cases involving individuals or businesses, Congolese or foreign — identity usurpation, forged documents, SIM swaps, account takeovers, money laundering and more — into RDCPASS’s national fraud case queue, one at a time or in bulk.

Create: POST /v1/fraud/reports
Batch: POST /v1/fraud/reports/batches
Retrieve: GET /v1/fraud/reports/{id}
Webhooks: fraud_report.created · fraud_report.status_changed

Overview

When your teams detect fraud involving a person or a company — Congolese or foreign, including cross-border cases — file it with RDCPASS. Each report opens a case with its own case_number, is reviewed by RDCPASS’s fraud investigation unit, and is correlated with reports from every other bank, operator and platform connected to the network. A SIM swap reported by a telecom operator in Lubumbashi can therefore protect the same citizen’s bank account in Kinshasa the same afternoon.

Confirmed cases feed the fraud network used by AML & CTF Screening and Credit Scoring (see How the network uses a case) and, where the facts call for it, are escalated to the competent authorities. You follow each case through its lifecycle with webhooks or by retrieving it.

Like every RDCPASS endpoint, this call requires the full authentication stack described in Authentication and supports the common Idempotency-Key and Prefer: respond-async headers.

Replaces Usurpation Reporting

Usurpation Reporting is now the identity_usurpation type of Fraud Reporting. The legacy path /v1/fraud/usurpation-reports remains an alias: requests sent to it create identity_usurpation reports, and those cases continue to emit the legacy usurpation_report.status_changed webhook alongside fraud_report.status_changed. New integrations should call /v1/fraud/reports.

Request modes

Fraud Reporting supports all four request modes. Use batch mode to import your historical case files in one pass. See Single, batch & async for the full model.

Mode	Endpoint	Returns
Single · synchronous	POST /v1/fraud/reports	200 with the fraud_report
Single · asynchronous	POST /v1/fraud/reports + Prefer: respond-async	202 with a job
Batch · synchronous	POST /v1/fraud/reports/batches	200 with every result — up to 50 items
Batch · asynchronous	POST /v1/fraud/reports/batches + Prefer: respond-async	202 with a batch — up to 10,000 items

Fraud types

Every report carries exactly one type. Choose the most specific type that describes the facts; use other only when none applies.

type	Description
identity_usurpation	Someone used a citizen’s identity — their RDCPASS ID, documents or personal data — to pass as them: opening an account, taking out credit, registering a SIM card.
document_forgery	A falsified, altered or counterfeit identity document was presented: passport, voter card, driving licence, national ID or a supporting document.
account_takeover	An existing customer account was taken over by a third party, for example after credential theft or a device compromise.
sim_swap	A SIM card was replaced or ported without the subscriber’s consent, typically to intercept one-time codes and mobile money.
money_laundering	Funds were placed, layered or integrated to disguise their illicit origin (anti-money laundering).
terrorist_financing	Funds were collected or moved to support terrorism or a terrorist organisation, whatever their origin.
robbery	Theft with violence or threat — for example a cash-in-transit or agent robbery — where the identity of a perpetrator or victim is known.
payment_fraud	Unauthorised card, mobile money or bank transfer payments, including card-not-present and merchant fraud.
phishing	Credentials or codes were obtained through deceptive messages, calls or websites impersonating a trusted organisation.
social_engineering	The victim was manipulated into performing the transaction themselves — fake relatives, fake agents, investment or romance scams.
insider_fraud	An employee, agent or contractor abused their authorised access to commit or facilitate fraud.
other	Any fraud that none of the types above describes. Explain the facts in description.

Request body

Send the following fields as JSON. As with every RDCPASS request, this is the plaintext shape before AES-256-GCM encryption — see Authentication.

Field	Type	Required	Description
type	string enum	Yes	The fraud category. One of the values in Fraud types above.
subject	object	No	The individual or business being reported — typically the author of the fraud. Optional: omit it when the author is unknown (a scam website, an unidentified caller). For an individual, provide identifier when you know it, otherwise any combination of full_name, date_of_birth, nationality and phone_number (at least one). For a company, provide business instead.
subject.role	string enum	No	What the subject is to the fraud: suspect (its author), victim (its target) or unknown. When victims are listed, defaults to suspect. Otherwise defaults from the type: victim for identity_usurpation, account_takeover, sim_swap, phishing and social_engineering; suspect for document_forgery, money_laundering, terrorist_financing and insider_fraud; unknown otherwise. Only suspects are ever flagged by other services — see How the network uses a case.
subject.identifier	object	No	An identity document: { "type": "rdcpass_id" \| "passport" \| "ceni" \| "driving_licence" \| "national_id", "value": "…" }. rdcpass_id (e.g. COD-2103-0214-4937) gives the fastest correlation.
subject.identifier.issuing_country	string	No	For a foreign document, the ISO 3166-1 alpha-3 issuing country, e.g. RWA. Foreign documents can be passport, national_id or driving_licence. Defaults to COD.
subject.full_name	string	No	The name as known to you, e.g. "Kabeya Mwamba Tshisekedi".
subject.date_of_birth	string	No	YYYY-MM-DD.
subject.nationality	string	No	ISO 3166-1 alpha-3, e.g. COD, RWA, FRA. Recommended for foreign nationals.
subject.phone_number	string	No	E.164 format, e.g. "+243812345678". Strongly recommended for sim_swap, phishing and social_engineering.
subject.business	object	No	A company instead of an individual. Cannot be combined with the individual fields above.
subject.business.identifier	object	No	A Congolese company: { "type": "rccm" \| "id_nat" \| "nif", "value": "…" }, e.g. CD/KIN/RCCM/23-B-01234.
subject.business.name	string	No	The company name. Required for a foreign or unregistered company.
subject.business.registration_number	string	No	The registration number in its own country, for a foreign company.
subject.business.country	string	No	ISO 3166-1 alpha-3 country of registration, e.g. ZAF, ARE. Defaults to COD.
victims	object[]	No	Who suffered the fraud, up to 50. Each victim takes the same fields as subject — an individual by identifier (Congolese or foreign), full_name, date_of_birth, nationality or phone_number, or a company in business — or is anonymous.
victims[].anonymous	boolean	No	true when the victim asked not to be named: send no identifying field. An anonymous victim is counted in the case but never matched by other services.
victims[].type / victims[].country	string	No	For an anonymous victim only: individual (default) or business, and its ISO 3166-1 alpha-3 country.
description	string	Yes	A factual account of what happened, how it was detected and what action you have already taken. Written for an investigator — no free-form opinions about the subject.
occurred_at	string	No	When the fraud took place, RFC 3339 timestamp (e.g. "2026-09-24T09:12:00Z").
location	object	No	Where it took place: { "country": "COD", "province": "Haut-Katanga", "city": "Lubumbashi" }. country is ISO 3166-1 alpha-3 and defaults to COD; use it for cross-border cases.
amount	object	No	The financial impact: { "value": 250000, "currency": "CDF" }. value is in the currency’s major unit; currency is any ISO 4217 code (CDF, USD, EUR, RWF…).
channel	string enum	No	Where the fraud happened. See Channels below.
evidence	object[]	No	Supporting material. Each item describes one file.
evidence[].type	string enum	Per item	image, document, transaction_log or audio.
evidence[].file	object	Per item	The file itself: { "data": "<base64>" } inline, or { "url": "https://…" } that RDCPASS fetches once when the report is created.
evidence[].description	string	Per item	What the file shows, e.g. "CCTV still from the Gombe branch, 18 June 2025".
reporter_reference	string	No	Your own case or ticket number. Echoed back on the report and in every webhook for it.

Channels

channel	Description
branch	At a physical branch, agency or point of sale.
online	On a website or web application.
mobile_app	In a mobile application.
ussd	Over a USSD session, including mobile money menus.
call_center	By telephone, through a call centre or customer service line.
other	Any other channel — describe it in description.

Evidence files accompany the case for its whole lifetime and are only accessible to RDCPASS investigators. Accepted formats are JPEG, PNG and PDF for image and document, CSV and PDF for transaction_log, and MP3 or WAV for audio. A signed URL you provide must stay valid for at least 15 minutes after the call.

Example request

A telecom operator reports a SIM swap followed by unauthorised mobile money transfers:

Request body (plaintext, before encryption)
{
  "type": "sim_swap",
  "subject": {
    "role": "suspect",
    "full_name": "Agent de vente non autorisé — kiosque Kenya",
    "phone_number": "+243970001122"
  },
  "victims": [
    {
      "identifier": {
        "type": "rdcpass_id",
        "value": "COD-2103-0214-4937"
      },
      "full_name": "Kabeya Mwamba Tshisekedi",
      "phone_number": "+243812345678"
    }
  ],
  "description": "SIM card replaced at an unauthorised agent in Lubumbashi, followed within 40 minutes by three mobile money transfers the customer did not initiate.",
  "occurred_at": "2026-09-24T09:12:00Z",
  "location": {
    "country": "COD",
    "province": "Haut-Katanga",
    "city": "Lubumbashi"
  },
  "amount": {
    "value": 2450000,
    "currency": "CDF"
  },
  "channel": "ussd",
  "evidence": [
    {
      "type": "transaction_log",
      "file": {
        "url": "https://files.example-bank.cd/cases/88213/transfers.csv"
      },
      "description": "Wallet transaction export for 24 September 2026"
    }
  ],
  "reporter_reference": "INC-2026-88213"
}

The same call as a full request in your language. Header values are illustrative placeholders — see Authentication to compute them.

report-fraud.sh
# Body shown in plaintext — encrypt it per /docs/authentication before sending.
curl https://api.rdcpass.cd/v1/fraud/reports \
  -X POST \
  -H "X-RDCPASS-Key-Id: key_live_8f2a1c0e9b" \
  -H "X-RDCPASS-Timestamp: 1790418900" \
  -H "X-RDCPASS-Nonce: 3c7e1a9d-2b4f-4d6a-8e15-9f0b7c2d4a61" \
  -H "X-RDCPASS-IV: q2Vh8Zk1pX0rT7mB" \
  -H "X-RDCPASS-Signature: b61d4e...9a07" \
  -H "Idempotency-Key: 5f0c2a8e-7d41-4b39-a6e2-1c9d8b3f7a50" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sim_swap",
    "subject": {
      "role": "suspect",
      "full_name": "Agent de vente non autorisé — kiosque Kenya",
      "phone_number": "+243970001122"
    },
    "victims": [
      {
        "identifier": {
          "type": "rdcpass_id",
          "value": "COD-2103-0214-4937"
        },
        "full_name": "Kabeya Mwamba Tshisekedi",
        "phone_number": "+243812345678"
      }
    ],
    "description": "SIM card replaced at an unauthorised agent in Lubumbashi, followed within 40 minutes by three mobile money transfers the customer did not initiate.",
    "occurred_at": "2026-09-24T09:12:00Z",
    "location": {
      "country": "COD",
      "province": "Haut-Katanga",
      "city": "Lubumbashi"
    },
    "amount": {
      "value": 2450000,
      "currency": "CDF"
    },
    "channel": "ussd",
    "evidence": [
      {
        "type": "transaction_log",
        "file": {
          "url": "https://files.example-bank.cd/cases/88213/transfers.csv"
        },
        "description": "Wallet transaction export for 24 September 2026"
      }
    ],
    "reporter_reference": "INC-2026-88213"
  }'

200 OK
{
  "id": "frd_5c8e1a7d42",
  "object": "fraud_report",
  "livemode": true,
  "case_number": "RDC-FRD-2026-004812",
  "status": "received",
  "type": "sim_swap",
  "subject": { "type": "individual", "role": "suspect", "country": "COD" },
  "victims": [{ "type": "individual", "country": "COD", "anonymous": false }],
  "reporter_reference": "INC-2026-88213",
  "created_at": "2026-09-26T10:15:02Z"
}

Response

A successful synchronous call returns 200 OK with the new fraud_report.

Field	Type	Description
id	string	Unique identifier of the report, prefixed frd_.
object	string	Always "fraud_report".
livemode	boolean	true in production, false in sandbox.
case_number	string	Human-readable case number, e.g. RDC-FRD-2026-004812. Quote it in any correspondence with RDCPASS or the authorities.
status	string enum	Current lifecycle status. Always "received" at creation. See Case lifecycle.
type	string enum	The fraud type you submitted.
subject	object \| null	{ "type": "individual" \| "business", "role", "country" }, or null when the report names no subject. Personal data is never echoed back.
victims	object[]	One entry per victim: { "type", "country", "anonymous" }.
reporter_reference	string \| null	Your reporter_reference, or null.
created_at	string	When the case was opened (RFC 3339).

Case lifecycle

Every case moves from received to under_review, then to one of three terminal statuses. Each change emits fraud_report.status_changed.

status	Meaning
received	The report is accepted and queued. Nothing has been assessed yet.
under_review	An RDCPASS investigator is assessing the report and correlating it with other cases and signals.
confirmed	The fraud is established. The case joins the fraud network: a suspect is flagged by AML & CTF Screening and weighs on Credit Scoring; a victim receives an identity-fraud alert.
dismissed	The report was not substantiated or was a duplicate. No further action.
escalated_to_authorities	The case was referred to the competent judicial, police or financial intelligence authorities. You may be contacted for further information.

Retrieve a report

Fetch the current state of a case at any time with GET /v1/fraud/reports/{id}:

curl https://api.rdcpass.cd/v1/fraud/reports/frd_5c8e1a7d42 \
  -H "X-RDCPASS-Key-Id: key_live_8f2a1c0e9b" \
  -H "X-RDCPASS-Timestamp: 1790418900" \
  -H "X-RDCPASS-Nonce: 3c7e1a9d-2b4f-4d6a-8e15-9f0b7c2d4a61" \
  -H "X-RDCPASS-Signature: b61d4e...9a07"

200 OK
{
  "id": "frd_5c8e1a7d42",
  "object": "fraud_report",
  "livemode": true,
  "case_number": "RDC-FRD-2026-004812",
  "status": "under_review",
  "type": "sim_swap",
  "subject": { "type": "individual", "role": "suspect", "country": "COD" },
  "victims": [{ "type": "individual", "country": "COD", "anonymous": false }],
  "reporter_reference": "INC-2026-88213",
  "created_at": "2026-09-26T10:15:02Z"
}

Webhooks

Two events cover the life of a case. Both use the standard envelope and signature described in webhooks.

Event	Sent when
fraud_report.created	A case is opened — including every case created from a batch or an async job.
fraud_report.status_changed	A case changes status. data.previous_attributes.status holds the prior value.
usurpation_report.status_changed	Legacy event, still delivered for cases created through /v1/fraud/usurpation-reports.

fraud_report.created
{
  "id": "evt_2d6f8a1c3e",
  "object": "event",
  "type": "fraud_report.created",
  "livemode": true,
  "created_at": "2026-09-26T10:15:02Z",
  "data": {
    "object": {
      "id": "frd_5c8e1a7d42",
      "object": "fraud_report",
      "case_number": "RDC-FRD-2026-004812",
      "status": "received",
      "type": "sim_swap",
      "reporter_reference": "INC-2026-88213"
    }
  }
}

fraud_report.status_changed
{
  "id": "evt_8b3e0f7a91",
  "object": "event",
  "type": "fraud_report.status_changed",
  "livemode": true,
  "created_at": "2026-09-29T14:32:00Z",
  "data": {
    "object": {
      "id": "frd_5c8e1a7d42",
      "object": "fraud_report",
      "case_number": "RDC-FRD-2026-004812",
      "type": "sim_swap",
      "status": "confirmed",
      "reporter_reference": "INC-2026-88213"
    },
    "previous_attributes": { "status": "under_review" }
  }
}

Batch: bulk historical case import

When you connect to RDCPASS, import the fraud cases you have already investigated so they strengthen the network from day one. Send up to 10,000 cases per asynchronous batch; each item takes the same fields as a single report, plus a required reference of your own that is echoed back in the results.

# Historical case import — body shown in plaintext; encrypt it per /docs/authentication
curl https://api.rdcpass.cd/v1/fraud/reports/batches \
  -X POST \
  -H "X-RDCPASS-Key-Id: key_live_8f2a1c0e9b" \
  -H "X-RDCPASS-Timestamp: 1790418900" \
  -H "X-RDCPASS-Nonce: 3c7e1a9d-2b4f-4d6a-8e15-9f0b7c2d4a61" \
  -H "X-RDCPASS-IV: q2Vh8Zk1pX0rT7mB" \
  -H "X-RDCPASS-Signature: b61d4e...9a07" \
  -H "Idempotency-Key: 5f0c2a8e-7d41-4b39-a6e2-1c9d8b3f7a50" \
  -H "Prefer: respond-async" \
  -H "Content-Type: application/json" \
  -d @historical-cases.json

historical-cases.json
{
  "items": [
    {
      "reference": "case-2025-00114",
      "type": "document_forgery",
      "subject": { "full_name": "Mbuyi Ilunga Nsimba", "date_of_birth": "1991-11-03" },
      "description": "Forged voter card presented to open a savings account at the Gombe branch.",
      "occurred_at": "2025-06-18T11:40:00Z",
      "location": { "province": "Kinshasa", "city": "Kinshasa" },
      "channel": "branch"
    },
    {
      "reference": "case-2025-00167",
      "type": "payment_fraud",
      "subject": { "identifier": { "type": "rdcpass_id", "value": "COD-1907-5521-0386" } },
      "description": "Card-not-present purchases disputed by the cardholder after a phishing SMS.",
      "occurred_at": "2025-08-02T19:05:00Z",
      "location": { "province": "Nord-Kivu", "city": "Goma" },
      "amount": { "value": 1480, "currency": "USD" },
      "channel": "online"
    }
  ]
}

202 Accepted
{
  "id": "bat_7c2e91f04a",
  "object": "batch",
  "service": "fraud_reporting",
  "status": "pending",
  "total_items": 3840,
  "processed_items": 0,
  "succeeded_items": 0,
  "failed_items": 0,
  "created_at": "2026-09-26T10:15:00Z",
  "completed_at": null,
  "results_url": "/v1/batches/bat_7c2e91f04a/results"
}

When the batch finishes you receive batch.completed (or batch.completed_with_errors). Page through the per-item results with GET /v1/batches/{batch_id}/results:

GET /v1/batches/bat_7c2e91f04a/results
{
  "object": "list",
  "data": [
    {
      "reference": "case-2025-00114",
      "status": "succeeded",
      "result": {
        "id": "frd_91a3e0c5b7",
        "object": "fraud_report",
        "livemode": true,
        "case_number": "RDC-FRD-2026-004813",
        "status": "received",
        "type": "document_forgery",
        "reporter_reference": null,
        "created_at": "2026-09-26T10:16:41Z"
      }
    },
    {
      "reference": "case-2025-00167",
      "status": "failed",
      "error": {
        "code": "invalid_identifier",
        "message": "identifier.value is not a valid rdcpass_id."
      }
    }
  ],
  "next_cursor": "cur_b3f10a92"
}

Batches of 50 items or fewer can be sent without Prefer: respond-async; the call then returns 200 OK with every result. Larger synchronous batches are rejected with 413 batch_too_large.

Asynchronous single report

Reports with large evidence files are best created asynchronously. Add Prefer: respond-async; RDCPASS returns 202 Accepted with a job immediately.

curl https://api.rdcpass.cd/v1/fraud/reports \
  -X POST \
  -H "X-RDCPASS-Key-Id: key_live_8f2a1c0e9b" \
  -H "X-RDCPASS-Timestamp: 1790418900" \
  -H "X-RDCPASS-Nonce: 3c7e1a9d-2b4f-4d6a-8e15-9f0b7c2d4a61" \
  -H "X-RDCPASS-IV: q2Vh8Zk1pX0rT7mB" \
  -H "X-RDCPASS-Signature: b61d4e...9a07" \
  -H "Idempotency-Key: 5f0c2a8e-7d41-4b39-a6e2-1c9d8b3f7a50" \
  -H "Prefer: respond-async" \
  -H "Content-Type: application/json" \
  -d @report.json

202 Accepted
{
  "id": "job_4b1d9e7a2c",
  "object": "job",
  "service": "fraud_reporting",
  "status": "pending",
  "created_at": "2026-09-26T10:15:00Z",
  "result_url": "/v1/jobs/job_4b1d9e7a2c"
}

When the job completes you receive job.completed with the fraud_report in data.result, followed by fraud_report.created. You can also poll GET /v1/jobs/{job_id}.

How the network uses a case

Once a case is confirmed or escalated_to_authorities, other RDCPASS services consult its subject and every named victim — across every organization on the network, without ever revealing the reporter, the description or the evidence. Cases that are received, under review or dismissed are never used. What happens depends on subject.role:

subject.role	Effect in other services
suspect	AML & CTF Screening returns a watchlists hit on the list "RDCPASS confirmed fraud cases", with the case number. Credit Scoring lowers the score and reports a fraud_history factor. Suspects are matched on RDCPASS ID or RCCM, or on name, date of birth and nationality.
victim	Never counts against the victim. AML & CTF Screening and Credit Scoring report identity_fraud_victim: true so you can apply extra verification — only on an exact RDCPASS ID or RCCM match, never on a name.
unknown	Recorded for investigators only. No effect in other services.

Any report is welcome

A report can name a subject, victims, both or neither — for example a phishing website with no known author and no identified victim. Reports with no identified party and no evidence are recorded but usually closed as dismissed; the more you identify, the more the case can protect others.

A money-laundering report does not replace your own legal reporting

Filing a money_laundering or terrorist_financing report with RDCPASS shares the case with the national identity network. It does not discharge any suspicious transaction reporting obligation your institution has towards CENAREF under the DRC’s AML/CTF framework — file that report through your usual channel as well, and never inform the subject that a report has been made. To screen customers before the fact, use AML & CTF Screening.

Report facts, not suspicions about a person’s character

A report names a real person and can restrict their access to services while it is reviewed. Every report is attributed to your application, audited, and reviewed as part of your production due diligence. Knowingly false or abusive reports are grounds for suspending production access.

Errors

Errors specific to this service, in the standard error format. See Errors for the full list.

HTTP	code	Description
400	invalid_identifier	subject.identifier.value is not valid for its type.
400	unsupported_identifier_type	subject.identifier.type is not one of the supported identifier types.
403	service_not_enabled	Fraud Reporting is not enabled on this application.
403	production_access_required	The call used production keys before the application’s production access was approved.
404	job_not_found	The job id passed to GET /v1/jobs/{job_id} does not exist.
404	batch_not_found	The batch id does not exist or belongs to another application.
413	batch_too_large	A synchronous batch contained more than 50 items. Resend it with Prefer: respond-async.
429	rate_limited	Too many requests in a short window. Retry with exponential backoff.

Next steps

AML & CTF Screening — Screen customers against sanctions, PEP and watchlists before they transact.
Single, batch & async — Jobs, batches, pagination and retries in detail.
Webhooks — Receive and verify fraud_report events.
Going to production — The due diligence required before production keys are issued.