# Welcome

The Consumer Service is a suite of APIs for verifying, screening, and assessing risk on **natural persons** — individual people. If your workflow involves onboarding a customer, paying a beneficiary, screening an applicant, or running a compliance check on a human being, you're in the right place.

> **Consumer means individuals only.** These endpoints are designed for natural persons identified by an ID number, passport, or refugee file number. For verifying companies, trusts, or other legal entities, see the **Commercial Service** instead.

## What you can do here

The Consumer Service brings together everything you need to know about a person into a single, consistent API. You can:

* **Confirm who someone is** — verify their ID, retrieve their official photograph, check government records, and confirm their bank account belongs to them.
* **Assess their risk** — pull a credit profile, get a combined credit and fraud score, check fraud listings, and detect SIM swaps before sending an OTP.
* **Meet compliance obligations** — screen against sanctions, PEP, and adverse media lists; check AML watchlists; verify refugee status; and capture POPIA consent on every request.
* **Verify their history** — check their address, employment, qualifications (matric and tertiary), and identity documents.

Every service is exposed as a simple JSON-over-HTTPS endpoint, authenticated with a bearer token, and returns a transaction ID you can use for audit and follow-up.

## Service categories

The services are organised into five categories. Browse the sidebar or jump straight to a category:

| Category         | What's in it                                                                                              |
| ---------------- | --------------------------------------------------------------------------------------------------------- |
| **Identity**     | Real-time ID verification, enhanced ID with photograph, refugee status, ID failover                       |
| **Credit**       | Credit Check (full bureau profile), Credit Score (decision-ready scoring)                                 |
| **Fraud**        | Fraud Listing Lookup (SAFPS), SIM Swap Detection                                                          |
| **Compliance**   | Watchlist Screening (sanctions, PEP, crime, regulatory), Comprehensive Watchlist with adverse media       |
| **Verification** | Account Verification, Address Lookup, Document Authentication, Matric Verification, Tertiary Verification |

There's also a **Reporting** section covering the Cost Center endpoints, which let you query your historical transactions, search consumers, and analyse operator success rates.

## How it works

Every Consumer Service endpoint follows the same shape:

1. **Authenticate.** Exchange your email and password for a bearer token at `/token`. Tokens last one hour.
2. **POST a JSON request** to the service endpoint with the consumer's identity details, the fields the service needs, and a consent flag.
3. **Receive a synchronous response** containing a `transaction_id`, an outcome (`ACCEPT` / `REVIEW` / `REJECT`), and the service-specific data.

A small number of services are asynchronous — they acknowledge the request immediately with `PENDING` and let you fetch the final result by polling `GET /transactions/{transaction_id}`. Each service's reference page makes its sync/async behaviour clear.

## Consent is mandatory

Because every Consumer Service request involves personal data about an individual, **explicit consent from the data subject is required for every call.** Each request includes a `ConsentObtainedByDataSubject` field that you must set to `true` (or `"Yes"` for the small number of services that use the string variant).

You are responsible for obtaining and retaining proof of that consent in line with POPIA and any other regulations that apply to your workflow. Save the `transaction_id` from each call alongside your consent record — the two together form a complete audit trail.

## Where to start

If this is your first time integrating, work through these in order:

1. [**Getting Started**](https://docs.fraudcheck.co.za/broken-reference) — make your first call in five minutes.
2. [**Authentication**](https://docs.fraudcheck.co.za/broken-reference) — token lifecycle, refresh patterns, and secure storage.
3. **Your service of choice** — pick from the sidebar based on what you're trying to do.

If you already know which service you need, jump straight to its reference page. Each one is self-contained and includes request and response schemas, code samples, error handling, and decisioning guidance.

## Need something else?

* **Verifying a company, trust, or other legal entity?** Use the **Commercial Service**.
* **Stuck on an integration?** Contact support with the `transaction_id` from any failing call — it's the fastest way for us to help you.