> 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/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. --- # 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/cost-center-reporting.md?ask=&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.