> For the complete documentation index, see [llms.txt](https://developer.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://developer.fraudcheck.co.za/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](/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](/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.** Set `ConsentObtainedByDataSubject` to `true` (or `"Yes"` for the small number of services that use the string variant - see each service's docs).
* **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/verify/onfile" \
  -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**](/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**](/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.