# Credit Check

Credit Check returns a comprehensive credit bureau profile for a South African consumer - demographics, address and employment history, credit accounts, defaults, debt counselling status, recent enquiries, and an overall credit summary. Use it for credit risk assessment, loan origination, affordability analysis, and creditworthiness verification.

Two variants are available:

| Variant                  | Endpoint                             | Includes payment profile                         |
| ------------------------ | ------------------------------------ | ------------------------------------------------ |
| **Standard**             | `/credit-check`                      | No                                               |
| **With payment profile** | `/credit-check-with-payment-profile` | Yes - month-by-month payment history per account |

Both variants accept the same request and return the same response shape.

## When to use this

Use this service to:

* Assess credit risk on a loan or credit application
* Determine an appropriate credit limit
* Verify creditworthiness during onboarding
* Detect defaults, judgements, and active debt counselling
* Analyse payment history (with the payment profile variant)

## How it works

Submit the consumer's identity details and the prescribed purpose for the enquiry in a single POST request. The service queries the credit bureau and returns a synchronous response containing consumer details, history, accounts, and a credit summary. Results can also be retrieved later by transaction ID.

| Property              | Value                                                                             |
| --------------------- | --------------------------------------------------------------------------------- |
| Response type         | `Synchronous`                                                                     |
| Typical response time | 2–5s (up to 60s under load)                                                       |
| Result retrieval      | Returned inline; also retrievable via `GET /credit-check/result/{transaction_id}` |
| Consent required      | `Yes`                                                                             |
| Region                | South Africa                                                                      |

***

## Authentication

```http
Authorization: Bearer {your_access_token}
```

***

## Endpoints

```http
POST /credit-check
POST /credit-check-with-payment-profile
GET  /credit-check/result/{transaction_id}
```

***

## Request

### Headers

| Header          | Required | Value              |
| --------------- | -------- | ------------------ |
| `Authorization` | Yes      | `Bearer {token}`   |
| `Content-Type`  | Yes      | `application/json` |

### Body parameters

| Field                                          | Type    | Required | Description                                                       |
| ---------------------------------------------- | ------- | -------- | ----------------------------------------------------------------- |
| `IdentityNo`                                   | string  | Yes      | 13-digit South African ID number                                  |
| `FirstName`                                    | string  | Yes      | Consumer's first name                                             |
| `LastName`                                     | string  | Yes      | Consumer's surname                                                |
| `PrescribedPurpose`                            | string  | Yes      | Purpose code for the enquiry (e.g. `CREDITCHECK`, `MORTGAGEPRED`) |
| `ConsentObtainedByDataSubject`                 | boolean | Yes      | Must be `true`. Confirms POPIA consent.                           |
| `SecondName`                                   | string  | No       | Middle name                                                       |
| `CellNo`                                       | string  | No       | Cell phone number                                                 |
| `EmailAddress`                                 | string  | No       | Email address                                                     |
| `EnquiryReason`                                | string  | No       | Reason for the enquiry (e.g. `REQUEST`, `DISPUTE`, `PROMOTION`)   |
| `EnquiryAmount`                                | string  | No       | Enquiry amount in Rands                                           |
| `BirthDate`                                    | string  | No       | Date of birth (`YYYY-MM-DD`)                                      |
| `Sex`                                          | string  | No       | `M` or `F`                                                        |
| `MaritalStatus`                                | string  | No       | Marital status                                                    |
| `AddressLine1`, `Suburb`, `City`, `PostalCode` | string  | No       | Address fields                                                    |
| `Occupation`, `Employer`, `Salary`             | string  | No       | Employment fields                                                 |

### Example request

```json
{
  "IdentityNo": "8601015800086",
  "FirstName": "John",
  "LastName": "Smith",
  "SecondName": "David",
  "CellNo": "27712345678",
  "EmailAddress": "john.smith@email.com",
  "PrescribedPurpose": "CREDITCHECK",
  "ConsentObtainedByDataSubject": true,
  "EnquiryReason": "REQUEST",
  "EnquiryAmount": "10000"
}
```

***

## Response

### Top-level fields

| Field                  | Type    | Description                                                                   |
| ---------------------- | ------- | ----------------------------------------------------------------------------- |
| `transaction_id`       | string  | Unique identifier for this request                                            |
| `success`              | boolean | Whether the request was processed                                             |
| `response_status`      | string  | `SUCCESS`, `NO_MATCH`, or `ERROR`                                             |
| `processing_time`      | string  | Time taken in seconds                                                         |
| `consumer_info`        | object  | Demographics and personal information                                         |
| `addresses`            | array   | Address history                                                               |
| `aka_names`            | array   | Known alternative names                                                       |
| `telephone_history`    | object  | Current and previous phone numbers                                            |
| `employment_history`   | array   | Employment records                                                            |
| `accounts`             | array   | Credit accounts (with payment history when using the payment-profile variant) |
| `defaults`             | array   | Default records                                                               |
| `debt_counselling`     | array   | Active debt counselling records                                               |
| `enquiries`            | array   | Recent credit enquiries                                                       |
| `credit_summary`       | object  | Aggregated credit statistics                                                  |
| `has_defaults`         | boolean | Whether the consumer has any defaults                                         |
| `has_debt_counselling` | boolean | Whether the consumer is under debt counselling                                |

### `credit_summary` fields

| Field                    | Description                         |
| ------------------------ | ----------------------------------- |
| `total_accounts`         | Total credit accounts on file       |
| `active_accounts`        | Open accounts                       |
| `closed_accounts`        | Closed accounts                     |
| `current_defaults`       | Outstanding defaults                |
| `current_judgements`     | Outstanding judgements              |
| `adverse_accounts`       | Accounts with adverse indicators    |
| `revolving_balance`      | Credit card / revolving balance     |
| `instalment_balance`     | Instalment credit balance           |
| `total_credit_exposure`  | Total credit limit / exposure       |
| `payment_history_months` | Months of payment history available |

### `accounts[]` fields

| Field               | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| `account_no`        | Account number                                               |
| `bank`              | Lender / provider                                            |
| `account_type`      | e.g. `CREDIT CARD`, `PERSONAL LOAN`, `HOME LOAN`             |
| `account_status`    | `Open` / `Closed`                                            |
| `opened_date`       | Account open date                                            |
| `balance`           | Current balance                                              |
| `credit_limit`      | Credit limit                                                 |
| `payment_history[]` | Month-by-month payment status (payment-profile variant only) |

### Example response (abbreviated)

```json
{
  "transaction_id": "d41d8cd98f00b204e9800998ecf8427e",
  "success": true,
  "response_status": "SUCCESS",
  "processing_time": "2.5",
  "consumer_info": {
    "consumer_no": "123456789",
    "surname": "SMITH",
    "forename1": "JOHN",
    "forename2": "DAVID",
    "gender": "M",
    "date_of_birth": "1986-01-15",
    "identity_no": "8601015800086",
    "marital_status": "Single",
    "telephone_number": "0712345678",
    "email_address": "john.smith@email.com"
  },
  "addresses": [
    {
      "address_line1": "123 Main Street",
      "suburb": "Sandton",
      "city": "Johannesburg",
      "postal_code": "2146",
      "province": "Gauteng",
      "status": "Current",
      "record_date": "2024-01-14"
    }
  ],
  "accounts": [
    {
      "account_no": "001234567890",
      "bank": "FNB",
      "account_type": "CREDIT CARD",
      "account_status": "Open",
      "opened_date": "2019-06-15",
      "balance": "2500.50",
      "credit_limit": "10000",
      "payment_history": [
        { "month_key": "202401", "status": "Paid", "days_past_due": "0" }
      ]
    }
  ],
  "defaults": [
    {
      "default_date": "2023-06-15",
      "default_amount": "5000",
      "default_reason": "Payment Default",
      "default_status": "Outstanding"
    }
  ],
  "debt_counselling": [
    { "status": "Active", "date_entered": "2023-01-15" }
  ],
  "credit_summary": {
    "total_accounts": "5",
    "active_accounts": "4",
    "current_defaults": "1",
    "current_judgements": "0",
    "adverse_accounts": "1",
    "revolving_balance": "7500.50",
    "instalment_balance": "45000",
    "total_credit_exposure": "52500.50"
  },
  "enquiries": [
        {
            "consumer_no": "008471100",
            "date_of_enquiry": "20260430",
            "enq_subscriber_name": "Fraudcheck (Pty) Ltd",
            "enq_subscriber_contact": "Fraudcheck 0112625252",
            "enq_type_cd": "39",
            "enq_type_desc": "FRAUD DETECT/PREVENT",
            "own_account": "Y",
            "loan_reason_cd": "",
            "loan_reason_desc": "",
            "enq_ref_no": "00000000000",
            "industry_cd": "OT",
            "industry_desc": "Other",
            "message": ""
        },
        {
            "consumer_no": "008471100",
            "date_of_enquiry": "20260417",
            "enq_subscriber_name": "Foschini Retail Group (Pt",
            "enq_subscriber_contact": "Foschini 0860834834",
            "enq_type_cd": "43",
            "enq_type_desc": "AFFORDABILITY ASSMNT",
            "own_account": "N",
            "loan_reason_cd": "",
            "loan_reason_desc": "",
            "enq_ref_no": "00000000000",
            "industry_cd": "CL",
            "industry_desc": "Clothing",
            "message": ""
        } ],    
    "credit_summary": {
          "consumer_no": "008471100",
          "curr_own_enq": "001",
          "prev_own_enq": "000",
          "curr_other_enq": "106",
          "prev_other_enq": "000",
          "curr_jdgmnt": "000",
          "prev_jdgmnt": "000",
          "other_jdgmnt": "000",
          "curr_notices": "000",
          "prev_notices": "000",
          "other_notices": "000",
          "curr_default": "005",
          "prev_default": "000",
          "curr_trace_alerts": "000",
          "prev_trace_alerts": "000",
          "active_accounts": "000",
          "curr_positive_loans": "000",
          "curr_higest_mia": "000",
          "prev_positive_accounts": "000",
          "prev_higest_mia": "000",
          "closed_accounts": "000",
          "adverse_accounts": "000",
          "mnths_in_arrears": "000",
          "curr_balance": "000000000",
          "curr_monthly_installment": "000000000",
          "cummulative_arrears_amount": "000000000",
          "filler": ""
    },
    "has_defaults": true,
    "has_debt_counselling": true,
    "account_count": 0,
    "address_count": 4,
    "aka_names_count": 3,
    "employment_count": 3,
    "enquiry_count": 100
}
```

***

## Retrieving results later

Re-fetch a previously completed credit check by transaction ID:

```http
GET /credit-check/result/{transaction_id}
Authorization: Bearer {your_access_token}
```

***

## Errors

| HTTP | Code            | Meaning                                      | Action                       |
| ---- | --------------- | -------------------------------------------- | ---------------------------- |
| 401  | `unauthorized`  | Token missing or expired                     | Refresh your access token    |
| 403  | `forbidden`     | Account lacks access to this service         | Contact your account manager |
| 422  | `invalid_input` | Required field missing or consent not `true` | Provide all required fields  |
| 500  | `server_error`  | Unexpected error                             | Contact support              |

***

## Code examples

{% tabs %}
{% tab title="cURL" %}

```bash
BASE_URL="https://consumer-service-api.fraudcheckonline.co.za/consumer-service"

curl -X POST "$BASE_URL/credit-check" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "IdentityNo": "8601015800086",
    "FirstName": "John",
    "LastName": "Smith",
    "PrescribedPurpose": "CREDITCHECK",
    "ConsentObtainedByDataSubject": true,
    "EnquiryReason": "REQUEST",
    "EnquiryAmount": "10000"
  }'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

BASE_URL = "https://consumer-service-api.fraudcheckonline.co.za/consumer-service"

response = requests.post(
    f"{BASE_URL}/credit-check",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
    },
    json={
        "IdentityNo": "8601015800086",
        "FirstName": "John",
        "LastName": "Smith",
        "PrescribedPurpose": "CREDITCHECK",
        "ConsentObtainedByDataSubject": True,
        "EnquiryReason": "REQUEST",
        "EnquiryAmount": "10000",
    },
    timeout=60,
)
data = response.json()
summary = data["credit_summary"]

print(f"{data['consumer_info']['forename1']} {data['consumer_info']['surname']}")
print(f"Active accounts: {summary['active_accounts']}")
print(f"Current defaults: {summary['current_defaults']}")
print(f"Total exposure: R{summary['total_credit_exposure']}")

if data["has_defaults"]:
    print(f"⚠️  {len(data['defaults'])} default(s) on file")
if data["has_debt_counselling"]:
    print("⚠️  Consumer is under debt counselling")
```

{% endtab %}

{% tab title="JavaScript (Node.js)" %}

```javascript
const BASE_URL = "https://consumer-service-api.fraudcheckonline.co.za/consumer-service";

const response = await fetch(`${BASE_URL}/credit-check`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    IdentityNo: "8601015800086",
    FirstName: "John",
    LastName: "Smith",
    PrescribedPurpose: "CREDITCHECK",
    ConsentObtainedByDataSubject: true,
    EnquiryReason: "REQUEST",
    EnquiryAmount: "10000",
  }),
});
const data = await response.json();
const s = data.credit_summary;

console.log(`Active: ${s.active_accounts}, Defaults: ${s.current_defaults}, Exposure: R${s.total_credit_exposure}`);
if (data.has_defaults) console.warn(`⚠️  ${data.defaults.length} default(s) on file`);
```

{% endtab %}
{% endtabs %}

***

## Risk indicators at a glance

When triaging a credit check programmatically, these fields give you a fast read on risk:

| Indicator              | Where to find it                       | Treat as risk if…       |
| ---------------------- | -------------------------------------- | ----------------------- |
| Active defaults        | `credit_summary.current_defaults`      | `> 0`                   |
| Outstanding judgements | `credit_summary.current_judgements`    | `> 0`                   |
| Adverse accounts       | `credit_summary.adverse_accounts`      | `> 0`                   |
| Debt counselling       | `has_debt_counselling`                 | `true`                  |
| Credit exposure        | `credit_summary.total_credit_exposure` | High relative to income |

***

## Compliance & consent

* Obtain explicit consent from the data subject before submitting a request.
* Set `ConsentObtainedByDataSubject` to `true` to confirm consent has been captured.
* Always supply a valid `PrescribedPurpose` matching the actual reason for the check.
* Retain proof of consent and the `transaction_id` for each enquiry in line with NCA and POPIA requirements.

***

## FAQ

<details>

<summary>Which variant should I use?</summary>

Use **Standard** (`/credit-check`) when you only need accounts, balances, and the credit summary. Use **With payment profile** (`/credit-check-with-payment-profile`) when you need month-by-month payment status per account for affordability or scoring models.

</details>

<details>

<summary>What's the difference between `defaults` and `adverse_accounts`?</summary>

`defaults` is an array of distinct default records (with date, amount, and status). `adverse_accounts` is a count in the credit summary representing accounts that carry adverse payment indicators - the two overlap but are not identical.

</details>

<details>

<summary>Can the same enquiry be reused?</summary>

Yes - fetch any previous result via `GET /credit-check/result/{transaction_id}` without consuming a new enquiry.

</details>

<details>

<summary>What client timeout should I configure?</summary>

Up to 60 seconds. Most checks complete in 2–5 seconds.

</details>

***

## Changelog

| Date       | Version | Change           |
| ---------- | ------- | ---------------- |
| 2026-04-11 | v1.0    | Initial release. |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fraudcheck.co.za/credit-and-financial-risk/credit-check.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.