> 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/cost-center-reporting.md).

# Cost Center Reporting

The Cost Center Reporting endpoints let you query the transactions you've already submitted to the API, group them by cost center (sub-client or operator), and analyse operator performance. Use them to build dashboards, run audits, search for a specific consumer's history, or report on how each of your operators is performing.

Three endpoints are available:

| Endpoint                         | Purpose                                                          |
| -------------------------------- | ---------------------------------------------------------------- |
| `GET /cost-center/transactions`  | List individual transactions with filtering and pagination       |
| `GET /cost-center/summary`       | Aggregated transaction counts and amounts grouped by cost center |
| `GET /cost-center/success-rates` | Per-operator success rate analysis for ID verification services  |

All three endpoints are scoped to your authenticated account - you can only see your own transactions, and any cost center you query must belong to your account.

## When to use this

Use these endpoints to:

* Build a transaction dashboard or audit log for your account
* Look up a specific consumer's verification history by name or ID number
* Reconcile transaction volumes and costs by operator or department
* Measure how successfully each operator is using ID verification services
* Identify failed transactions for support investigation

## Authentication

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

All endpoints require a valid bearer token. Results are automatically scoped to the `account_id` carried in the token - no account parameter is needed.

## List transactions

```http
GET /cost-center/transactions
```

Returns a paginated list of transactions matching the filters you supply. Results are ordered by `received_datetime` descending (newest first).

### Query parameters

| Parameter          | Type    | Description                                   |
| ------------------ | ------- | --------------------------------------------- |
| `start_date`       | date    | Filter from this date (`YYYY-MM-DD`)          |
| `end_date`         | date    | Filter up to this date (`YYYY-MM-DD`)         |
| `cost_center`      | integer | Filter to a single cost center ID             |
| `firstname`        | string  | Partial, case-insensitive match on first name |
| `lastname`         | string  | Partial, case-insensitive match on surname    |
| `id_number`        | string  | Partial match on identity number              |
| `reference_no`     | string  | Partial match on your internal reference      |
| `service_type`     | string  | Filter by service code (e.g. `BIDCHK1`)       |
| `screening_result` | string  | One of `ACCEPT`, `REVIEW`, `REJECT`, `FAIL`   |
| `limit`            | integer | Page size, 1–500 (default 500)                |
| `offset`           | integer | Records to skip for pagination (default 0)    |

### Example request

```bash
curl -G "https://consumer-service-api.fraudcheckonline.co.za/consumer-service/cost-center/transactions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode "start_date=2026-01-01" \
  --data-urlencode "end_date=2026-01-31" \
  --data-urlencode "cost_center=101" \
  --data-urlencode "limit=100"
```

### Example response

```json
{
  "success": true,
  "total_records": 250,
  "returned_records": 100,
  "transactions": [
    {
      "transaction_id": "a1b2c3d4e5f6...",
      "service_type": "BIDCHK1",
      "screening_result": "ACCEPT",
      "firstname": "John",
      "lastname": "Smith",
      "identity_no": "8601015800086",
      "reference_no": "REF001",
      "cost_center": 101,
      "received_datetime": "2026-01-15T10:30:00",
      "selling_price": 2.50
    }
  ],
  "filters_applied": {
    "start_date": "2026-01-01",
    "end_date": "2026-01-31",
    "cost_center": 101,
    "limit": 100,
    "offset": 0
  }
}
```

### Transaction fields

| Field                                  | Description                                           |
| -------------------------------------- | ----------------------------------------------------- |
| `transaction_id`                       | Unique transaction identifier                         |
| `service_type`                         | Service code (e.g. `BIDCHK1`, `CREDITCHK2`)           |
| `screening_result`                     | `ACCEPT`, `REVIEW`, `REJECT`, or `FAIL`               |
| `firstname`, `lastname`, `identity_no` | Consumer details as submitted on the original request |
| `reference_no`                         | Your internal reference, if supplied                  |
| `cost_center`                          | Cost center ID, or `null` if none was assigned        |
| `received_datetime`                    | When the transaction was received (UTC)               |
| `selling_price`                        | Price charged for the transaction                     |

### Pagination

* Maximum **500 records** per page.
* Use `offset` to walk through larger result sets:

```bash
# Page 1 (records 1–500)
GET /cost-center/transactions?limit=500&offset=0

# Page 2 (records 501–1000)
GET /cost-center/transactions?limit=500&offset=500
```

* `total_records` in the response shows the total matching the filter; `returned_records` shows the count in the current page.

## Cost center summary

```http
GET /cost-center/summary
```

Returns transaction counts and total spend grouped by cost center over an optional date range.

### Query parameters

| Parameter    | Type | Description                 |
| ------------ | ---- | --------------------------- |
| `start_date` | date | Period start (`YYYY-MM-DD`) |
| `end_date`   | date | Period end (`YYYY-MM-DD`)   |

### Example request

```bash
curl -G "https://consumer-service-api.fraudcheckonline.co.za/consumer-service/cost-center/summary" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode "start_date=2026-01-01" \
  --data-urlencode "end_date=2026-01-31"
```

### Example response

```json
{
  "success": true,
  "summary_period": "2026-01-01 to 2026-01-31",
  "cost_centers": [
    {
      "cost_center": 101,
      "transaction_count": 150,
      "total_amount": 375.00,
      "service_types": ["BIDCHK1", "CREDITCHK2"]
    },
    {
      "cost_center": 102,
      "transaction_count": 85,
      "total_amount": 212.50,
      "service_types": ["BIDCHK1"]
    }
  ],
  "total_transactions": 235,
  "total_amount": 587.50
}
```

## Operator success rates

```http
GET /cost-center/success-rates
```

Calculates a success rate per cost center for **ID verification services only** (`BIDCHK1`, `BIDCHK2`). Useful for measuring how well each operator is capturing accurate consumer details.

### Formula

```
success_rate = ACCEPT / (ACCEPT + REJECT) × 100
```

Only transactions with `screening_result` of `ACCEPT` or `REJECT` are counted. `REVIEW`, `FAIL`, and `null` results are excluded.

### Query parameters

| Parameter    | Type | Description                          |
| ------------ | ---- | ------------------------------------ |
| `start_date` | date | Analysis period start (`YYYY-MM-DD`) |
| `end_date`   | date | Analysis period end (`YYYY-MM-DD`)   |

### Example request

```bash
curl -G "https://consumer-service-api.fraudcheckonline.co.za/consumer-service/cost-center/success-rates" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode "start_date=2026-01-01" \
  --data-urlencode "end_date=2026-01-31"
```

### Example response

```json
{
  "success": true,
  "analysis_period": "2026-01-01 to 2026-01-31",
  "service_types_included": ["BIDCHK1", "BIDCHK2"],
  "operators": [
    {
      "cost_center": 101,
      "operator_name": "Operator 101",
      "total_transactions": 200,
      "accept_count": 180,
      "reject_count": 20,
      "success_rate": 90.0,
      "average_weighting": 1.0
    },
    {
      "cost_center": 102,
      "operator_name": "Operator 102",
      "total_transactions": 150,
      "accept_count": 120,
      "reject_count": 30,
      "success_rate": 80.0,
      "average_weighting": 0.8
    }
  ],
  "overall_success_rate": 85.71,
  "total_transactions_analyzed": 350
}
```

Operators are returned sorted by success rate (highest first), then by transaction count.

## Errors

| HTTP | Meaning                                                               | Action                               |
| ---- | --------------------------------------------------------------------- | ------------------------------------ |
| 400  | Invalid query parameter (bad date format, out-of-range `limit`, etc.) | Check the parameter and retry        |
| 401  | Token missing or expired                                              | Refresh your access token            |
| 403  | The requested `cost_center` does not belong to your account           | Use a cost center your account owns  |
| 500  | Server error                                                          | Retry; contact support if persistent |

## Common workflows

### Look up a specific consumer's history

```bash
GET /cost-center/transactions?firstname=John&lastname=Smith
GET /cost-center/transactions?id_number=8601015800086
```

### Find all failed transactions in the last week

```bash
GET /cost-center/transactions?screening_result=FAIL&start_date=2026-04-04
```

### Build a monthly billing report

```bash
GET /cost-center/summary?start_date=2026-03-01&end_date=2026-03-31
```

### Identify your best- and worst-performing operators

```bash
GET /cost-center/success-rates?start_date=2026-01-01&end_date=2026-03-31
```

### Walk through a large result set

```bash
# Fetch all matching transactions in pages of 500
GET /cost-center/transactions?start_date=2026-01-01&end_date=2026-01-31&limit=500&offset=0
GET /cost-center/transactions?start_date=2026-01-01&end_date=2026-01-31&limit=500&offset=500
GET /cost-center/transactions?start_date=2026-01-01&end_date=2026-01-31&limit=500&offset=1000
```

Stop paging when `returned_records` is less than `limit`.

## Notes

* All timestamps are returned in **UTC**.
* Date filters apply to the `received_datetime` field - when the transaction was first received, not when its result was finalised.
* Text searches (`firstname`, `lastname`, `id_number`, `reference_no`) are case-insensitive partial matches.
* Transactions submitted without a `CostCenter` value appear with `cost_center: null`. You can include or exclude them by filtering on a specific cost center.
* These endpoints are read-only and do not consume verification credits.