> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kairoconnect.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Batch scoring

> POST /score/batch — score up to 1,000 transactions per request

**Request**

```http theme={null}
POST {BASE_URL}/api/v1/score/batch
X-API-Key: <your-api-key>
Content-Type: application/json

{
  "transactions": [
    {
      "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
      "merchant_reference": "MERCH-TX-001",
      "user_token": "a3f2b8c9d1e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f901",
      "merchant_id": "merchant_001",
      "amount": "150000.00",
      "currency": "COP",
      "transaction_type": "PAYIN",
      "payment_method": "CARD",
      "card_bin": "411111",
      "client_type": "MOBILE_APP",
      "is_tax_applied": true,
      "timestamp": "2025-06-15T14:30:00Z",
      "ip_hash": "b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b201",
      "transaction_country": "CO",
      "mcc": "5812",
      "merchant_risk_tier": "MEDIUM",
      "merchant_age_days": 365
    }
  ]
}
```

**Response**

```http theme={null}
HTTP/1.1 200 OK
Content-Type: application/json

{
  "job_id": "batch-20250615-001",
  "total": 2,
  "completed": 2,
  "failed": 0,
  "results": [
    {
      "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
      "fraud_score": 0.15,
      "risk_level": "LOW",
      "decision": "APPROVE",
      "decision_source": "MODEL",
      "top_features": [
        {"feature": "amount_log", "importance": 0.05},
        {"feature": "channel_ord", "importance": -0.03}
      ],
      "model_version": "kairo-shield",
      "threshold_used": {
        "low_max": 0.25,
        "medium_max": 0.55,
        "high_max": 0.80
      },
      "processing_time_ms": 38.2,
      "scoring_timeout_ms": 500,
      "request_id": "req-batch-001",
      "uiaf_reportable": false
    }
  ],
  "errors": []
}
```

Scores multiple transactions in one request (offline path). Maximum **1,000** transactions per request.

**Authentication:** `X-API-Key`. Requires `fraud_detection_consent=true` on your client.

## Request body

The body is an object with a `transactions` array. See [Transaction fields reference](/docs/shield/reference/transaction-fields) for full details.

| Field | Type | Description |
| - | - | - |
| `transactions` | array | Transactions to score. Minimum 1, maximum 1,000 |

Each array item shares the same schema as `POST /score`. Required fields:

| Field | Type | Description |
| - | - | - |
| `transaction_id` | UUID | Unique per client (24 h idempotency) |
| `merchant_reference` | string | Your internal reference (1–128 characters) |
| `user_token` | string | User SHA-256 (64 hex) |
| `merchant_id` | string | Merchant ID on your platform |
| `amount` | decimal | Amount > 0 |
| `currency` | string | ISO 4217 (e.g. `COP`, `USD`) |
| `transaction_type` | string | See [Enums](/docs/shield/reference/enums) |
| `payment_method` | string | See [Enums](/docs/shield/reference/enums) |
| `timestamp` | datetime | ISO 8601 UTC |
| `ip_hash` | string | IP SHA-256 (64 hex) |
| `transaction_country` | string | ISO 3166-1 alpha-2 |
| `mcc` | string | Merchant Category Code (4 digits) |
| `merchant_risk_tier` | string | `LOW`, `MEDIUM`, or `HIGH` |

### Optional fields

Enrich scoring (device, geo, merchant, balances). Not required, but they improve rules and model features.

| Field | Type | When to send |
| - | - | - |
| `destination_account_token` | string | PAYOUT, TRANSFER, P2P, CASHOUT — destination account SHA-256 |
| `card_bin` | string | Card payments — first 6 digits (BIN) |
| `is_tax_applied` | boolean | Whether tax/VAT was applied. Default `false` |
| `device_fingerprint_hash` | string | Device fingerprint SHA-256 |
| `os_type` | string | `ANDROID`, `IOS`, `WINDOWS`, `MACOS`, … |
| `client_type` | string | `WEB`, `MOBILE_APP`, `API`, `POS`, … |
| `is_emulator` | boolean | `true` if the client detected an emulator |
| `is_vpn_proxy` | boolean | `true` if IP is VPN or proxy |
| `is_datacenter_ip` | boolean | `true` if IP is datacenter/hosting |
| `ip_country` | string | Country from IP (ISO alpha-2) |
| `destination_country` | string | Cross-border transfers |
| `merchant_age_days` | integer | Days since merchant onboarding |
| `origin_balance_before` | number | Origin balance before the transaction |
| `origin_balance_after` | number | Origin balance after (debits: before − amount) |
| `destination_balance_before` | number | Destination balance before credit |
| `destination_balance_after` | number | Destination balance after credit |

Full reference: [Transaction fields](/docs/shield/reference/transaction-fields).

> [!WARNING]
>
> **Do not send plaintext PII.** Use SHA-256 hashes for `user_token`, `ip_hash`, and account tokens.

See [Thresholds and decisions](/docs/shield/reference/thresholds) and [SHAP features](/docs/shield/reference/shap-features) to interpret each item in `results[]`.

## Response fields

| Field | Description |
| - | - |
| `job_id` | Batch job identifier |
| `total` | Submitted transactions |
| `completed` | Successfully scored |
| `failed` | Failures (see `errors`) |
| `results` | Array of scoring responses (same schema as `/score`) |
| `errors` | `{ "transaction_id": "...", "message": "..." }` per failed item |

## More request examples

**PAYIN — Bre-B**

```json theme={null}
{
  "transactions": [
    {
      "transaction_id": "660e8400-e29b-41d4-a716-446655440001",
      "merchant_reference": "MERCH-BREB-001",
      "user_token": "a3f2b8c9d1e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f901",
      "merchant_id": "merchant_001",
      "amount": "250000.00",
      "currency": "COP",
      "transaction_type": "PAYIN",
      "payment_method": "BREB",
      "is_tax_applied": false,
      "timestamp": "2025-06-15T14:30:00Z",
      "device_fingerprint_hash": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
      "os_type": "ANDROID",
      "client_type": "MOBILE_APP",
      "is_emulator": false,
      "ip_hash": "b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b201",
      "transaction_country": "CO",
      "mcc": "6012",
      "merchant_risk_tier": "MEDIUM",
      "merchant_age_days": 120
    }
  ]
}
```

**PAYOUT — bank transfer**

```json theme={null}
{
  "transactions": [
    {
      "transaction_id": "770e8400-e29b-41d4-a716-446655440002",
      "merchant_reference": "MERCH-PAYOUT-001",
      "user_token": "a3f2b8c9d1e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f901",
      "merchant_id": "merchant_001",
      "destination_account_token": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
      "amount": "500000.00",
      "currency": "COP",
      "transaction_type": "PAYOUT",
      "payment_method": "BANK_TRANSFER",
      "is_tax_applied": false,
      "timestamp": "2025-06-15T15:00:00Z",
      "client_type": "API",
      "ip_hash": "b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b201",
      "transaction_country": "CO",
      "destination_country": "CO",
      "mcc": "6010",
      "merchant_risk_tier": "MEDIUM",
      "merchant_age_days": 365
    }
  ]
}
```

Include `destination_account_token` for payouts and transfers to a destination account.

## Typical errors

* **403** — Fraud consent not granted
* **409** — Duplicate `transaction_id` within 24 h window (on an item)
* **422** — Empty array, more than 1,000 items, or validation on an element
* **504** — Scoring timeout on an item

## See also

* [Real-time scoring](/docs/shield/api/score)
* [Transaction fields](/docs/shield/reference/transaction-fields)
* [Allowed enums](/docs/shield/reference/enums)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.