> 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/commercial-service/getting-started.md).

# Getting Started

Make your first API call in four steps.

{% stepper %}
{% step %}
**Authenticate**

Call the token endpoint with your email and password to get a JWT access token. The token is valid for 60 minutes.

```bash
curl -X POST "https://commercial-service-api.fraudcheckonline.co.za/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "yourpassword"}'
```

**Response:**

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

Store the `access_token` value - you will send it as a `Bearer` token on every subsequent request.
{% endstep %}

{% step %}
**Build a request**

Every commercial service request shares the same JSON body structure. Required fields vary by service, but the key inputs are:

* `CompanyName` or `CompanyRegNo` - identifies the business being checked
* `ConsentObtainedByDataSubject` - must be `true` to confirm POPIA consent
* `EnquiryReason` - required for some services

```json
{
  "CompanyName": "Example Company (Pty) Ltd",
  "CompanyRegNo": "2021/123456/07",
  "ConsentObtainedByDataSubject": true,
  "EnquiryReason": "01"
}
```

{% endstep %}

{% step %}
**Call the service**

Send the request to the relevant endpoint with your access token in the `Authorization` header.

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

curl -X POST "$BASE_URL/quickvet" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "CompanyName": "Example Company (Pty) Ltd",
    "CompanyRegNo": "2021/123456/07",
    "ConsentObtainedByDataSubject": true
  }'
```

{% endstep %}

{% step %}
**Handle the response**

All responses include a `success` flag and a `transaction_id`. Use the `transaction_id` to retrieve results again later on services that support it.

```json
{
  "success": true,
  "transaction_id": "a1b2c3d4-...",
  "product": "PREVETCOM",
  "match": { ... },
  "result": { ... }
}
```

A `success: false` response means the API call itself failed - check the `detail` field for the error message. A negative screening outcome (e.g. a match on a watchlist) returns `success: true` with a `screening_result` of `REJECT` or `REVIEW`.
{% endstep %}
{% endstepper %}