# Batch checks

Send up to 100 provider-plan pairs in one request to `POST /v1/check/batch`. Each pair gets the same answer a single check would give. Batch checks are on Builder and above.

Source: https://inplan.io/docs/batch-checks · Updated 2026-10-30

## The request body

Send JSON with `Content-Type: application/json`. Put the pairs in `items`. Each item has `npi`, `plan_id` and an optional `year`. A top-level `year` applies to every item without its own.

curl:

```bash
curl https://api.inplan.io/v1/check/batch \
  -H "Authorization: Bearer $INPLAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items": [
        {"npi": "1184617268", "plan_id": "29276OH0970001"},
        {"npi": "1184617268", "plan_id": "H2526-001-000"},
        {"npi": "1376006148", "plan_id": "13262AR0230002"},
        {"npi": "1234567890", "plan_id": "29276OH0970001"}
      ]}'
```

JavaScript:

```javascript
const res = await fetch("https://api.inplan.io/v1/check/batch", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INPLAN_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    items: [
      {
        npi: "1184617268",
        plan_id: "29276OH0970001"
      },
      {
        npi: "1184617268",
        plan_id: "H2526-001-000"
      },
      {
        npi: "1376006148",
        plan_id: "13262AR0230002"
      },
      {
        npi: "1234567890",
        plan_id: "29276OH0970001"
      }
    ]
  }),
});
const body = await res.json();
console.log(body.data.summary);
```

Python:

```python
import os, requests

res = requests.post(
    "https://api.inplan.io/v1/check/batch",
    json={
        "items": [
            {
                "npi": "1184617268",
                "plan_id": "29276OH0970001"
            },
            {
                "npi": "1184617268",
                "plan_id": "H2526-001-000"
            },
            {
                "npi": "1376006148",
                "plan_id": "13262AR0230002"
            },
            {
                "npi": "1234567890",
                "plan_id": "29276OH0970001"
            }
        ]
    },
    headers={"Authorization": f"Bearer {os.environ['INPLAN_KEY']}"},
    timeout=30,
)
body = res.json()
print(body["data"]["summary"])
```

## Read the results

`data.summary` counts the answers. `data.results` holds one result for each item, in the order you sent them; `index` is the position in `items`. An item that fails validation carries an `error` instead of an answer, and the rest of the batch still answers.

Response (200 OK · response, shortened):

```json
{
  "request_id": "req_KHtLEQJ46JLKLkZZ",
  "data_as_of": "2026-10-29",
  "data": {
    "count": 4,
    "summary": {
      "listed": 2,
      "not_found": 1,
      "invalid": 1
    },
    "results": [
      {
        "index": 0,
        "npi": "1184617268",
        "plan_id": "29276OH0970001",
        "market": "aca",
        "in_network": true,
        "answer": "listed",
        "evidence": [
          {
            "plan_id": "29276OH0970001",
            "plan_year": 2026,
            "network_tier": "PARTICIPATING",
            "source": {
              "type": "insurer_directory",
              "as_of": "2026-07-27"
            }
          }
        ]
      },
      {
        "index": 1,
        "npi": "1184617268",
        "plan_id": "H2526-001-000",
        "market": "ma",
        "in_network": true,
        "answer": "listed",
        "evidence": [
          {
            "plan_id": "H2526-001-000",
            "plan_year": 2027,
            "accepting_new_patients": true,
            "provider_kind": "practitioner",
            "source": {
              "type": "plan_directory",
              "as_of": "2026-10-29"
            }
          }
        ]
      },
      {
        "index": 2,
        "npi": "1376006148",
        "plan_id": "13262AR0230002",
        "market": "aca",
        "in_network": null,
        "answer": "not_found",
        "evidence": []
      },
      {
        "index": 3,
        "npi": "1234567890",
        "plan_id": "29276OH0970001",
        "error": {
          "type": "invalid_npi",
          "title": "Invalid NPI",
          "detail": "\"1234567890\" fails the NPI check digit (Luhn with prefix 80840)."
        }
      }
    ]
  }
}
```

## How a batch counts

- Each item is one call against your monthly quota, including items that fail validation and repeated pairs.
- The per-second limit counts the request once.
- If your quota cannot cover every item, the whole batch answers `429 quota_exceeded` and nothing is counted.
- If a lookup fails on our side (`503`), the whole batch fails and nothing is counted. Retry it.

## Limits and errors

| Status | Type | When |
| --- | --- | --- |
| 400 | `batch_too_large` | More than 100 items. Split them. A rejected batch still counts its first 100 items. |
| 400 | `invalid_request` | No `items` array, or an empty one, or a body that is not JSON. |
| 403 | `plan_upgrade_required` | The key is on the Free plan. |
| 413 | `payload_too_large` | The body is over 64 KB. |
| 415 | `unsupported_media_type` | The `Content-Type` is not `application/json`. |