> For the complete documentation index, see [llms.txt](https://docs.fraudcheck.co.za/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fraudcheck.co.za/consumer-service/getting-started.md).

# Getting Started

This guide walks you through making your first API call. The flow is simple: authenticate to get a token, build a JSON request for the service you want, and POST it to the relevant endpoint.

## Prerequisites

Before you begin, you'll need:

* An account with API access
* Your account email and password
* Access enabled for the service(s) you intend to call

If you don't yet have access to a particular service, contact your account manager.

{% hint style="info" %}
All code examples in this documentation use `https://consumer-service-api.fraudcheckonline.co.za` as the base URL. See [Environments & Base URL](/consumer-service/environments-and-base-url.md) for details.
{% endhint %}

{% stepper %}
{% step %}

#### Authenticate

Exchange your email and password for a short-lived bearer token.

```bash
curl -X POST "https://consumer-service-api.fraudcheckonline.co.za/auth/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "email=your-email@example.com&password=your-password"
```

```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}
```

Store the `access_token` securely. Tokens expire after **1 hour** - request a new one when you start receiving `401 Unauthorized` responses. See the [Authentication](/consumer-service/authentication.md) guide for full details, language samples, and refresh patterns.
{% endstep %}

{% step %}

#### Build a request

Every service uses the same request shape: a JSON body containing the fields needed for that specific service. You only need to send the fields that service requires - extra fields are safely ignored, and missing optional fields default to empty.

Here's a minimal request for an identity verification:

```json
{
  "IdentityNo": "8601015800086",
  "FirstName": "John",
  "LastName": "Smith",
  "ConsentObtainedByDataSubject": true
}
```

A few rules apply across every service:

* **Consent is mandatory.** Include `ConsentObtainedByDataSubject` and set it to the boolean value `true` on every request.
* **Names should match the ID document.** Spelling differences cause match failures.
* **`IdentityNo` is the 13-digit South African ID number** for SA-resident services. Some services accept passport numbers - check the service-specific docs.

Each service's reference page lists exactly which fields it requires.
{% endstep %}

{% step %}

#### Call the service

Add your token to the `Authorization` header and POST the request to the service endpoint:

```bash
curl -X POST "https://consumer-service-api.fraudcheckonline.co.za/consumer-service/idv/kyc/verify" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "IdentityNo": "8601015800086",
    "FirstName": "John",
    "LastName": "Smith",
    "ConsentObtainedByDataSubject": true
  }'
```

A successful response always includes a `transaction_id`, a `screening_result` (or service-specific equivalent like `verification_passed`), and the data the service is designed to return.

```json
{
  "transaction_id": "TXN-20260411-ABC123",
  "verification_passed": true,
  "screening_result": "ACCEPT",
  "names": "JOHN",
  "surname": "SMITH",
  "date_of_birth": "1986-01-01"
}
```

**Always store the `transaction_id`** - it's your audit reference and the key for retrieving results later.
{% endstep %}

{% step %}

#### Handle the response

Most services return one of three outcomes:

| Result   | Meaning                              | What to do                |
| -------- | ------------------------------------ | ------------------------- |
| `ACCEPT` | The check passed                     | Proceed with the workflow |
| `REVIEW` | A partial match or warning was found | Route to manual review    |
| `REJECT` | The check failed                     | Decline or escalate       |

Some services use additional values like `PENDING` (for asynchronous services) or `FAIL` (for unexpected processing errors). Each service's docs spell out the values it can return.
{% endstep %}
{% endstepper %}

## Synchronous vs asynchronous services

Most services are **synchronous** - you call once and the full result is returned in the response.

A few services are **asynchronous**: the initial response acknowledges the request with `screening_result: "PENDING"`, and the final result is fetched later by polling the transaction endpoint:

```http
GET /consumer-service/transactions/{transaction_id}
```

Asynchronous services include Fraud Listing Lookup, Matric Verification, and Tertiary Verification. Each one's docs explain how long to wait and how often to poll.

## Errors

The API uses standard HTTP status codes. The most common ones you'll encounter:

| HTTP | Meaning                            | Action                                   |
| ---- | ---------------------------------- | ---------------------------------------- |
| 400  | Invalid input or wrong format      | Check the request body                   |
| 401  | Missing, invalid, or expired token | Request a new token                      |
| 403  | No access to this service          | Contact your account manager             |
| 422  | Required field missing             | Add the missing field shown in `details` |
| 500  | Server error                       | Retry with exponential backoff           |

A negative result (e.g. an ID that fails verification) is **not** an error - it's an HTTP `200` with `screening_result: "REJECT"`. Reserve error handling for actual HTTP error codes.

## Where to next

* [**Authentication**](/consumer-service/authentication.md) - full details on tokens, expiry, and refresh
* **Service references** - pick the service you need from the sidebar (Identity, Credit, Fraud, Compliance, Verification)
* [**Cost Center Reporting**](/consumer-service/cost-center-reporting.md) - query historical transactions by cost center, search consumers, and analyse operator success rates

If you get stuck, contact support with the `transaction_id` from any failing call - it's the fastest way for us to help.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.fraudcheck.co.za/consumer-service/getting-started.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.