# ISA allowance calculator (GET /calculators/isa-allowance)

Source: DepositScout Data API docs — https://depositscout.com/developers/docs/calculators.isa-allowance

What's left of this tax year's ISA allowance after what's been paid in, for an adult, Junior or Lifetime ISA, with the Lifetime ISA bonus and upcoming allowance changes.

---

- **Cost:** 1 DS Credit per request
- **Scope:** `any key`
- **Same data as:** the DepositScout website

## Request

`GET https://depositscout.com/api/developer/v1/calculators/isa-allowance`

| Parameter | In | Type | Example | Description |
| --- | --- | --- | --- | --- |
| type | query | enum | adult | Which allowance. Defaults to adult.`adult` `junior` `lifetime` |
| paidIn | query | number | 8000 | Paid in so far this tax year, in pounds. Defaults to 0. |

## Example

**curl**

```bash
curl "https://depositscout.com/api/developer/v1/calculators/isa-allowance?type=adult&paidIn=8000" \
  -H "Authorization: Bearer $DS_API_KEY"
```

**Node**

```javascript
const res = await fetch("https://depositscout.com/api/developer/v1/calculators/isa-allowance?type=adult&paidIn=8000", {
  headers: { Authorization: `Bearer ${process.env.DS_API_KEY}` },
});
const { data, meta } = await res.json();
console.log(meta.creditsCharged, data);
```

**Python**

```python
import os, requests

res = requests.get(
    "https://depositscout.com/api/developer/v1/calculators/isa-allowance?type=adult&paidIn=8000",
    headers={"Authorization": f"Bearer {os.environ['DS_API_KEY']}"},
)
body = res.json()
print(body["meta"]["creditsCharged"], body["data"])
```

**MCP (tool call)**

```mcptoolcall
curl https://depositscout.com/api/mcp \
  -H "Authorization: Bearer $DS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"calculators_isa_allowance","arguments":{"type":"adult","paidIn":8000}}}'
```

## Response

`data` is a single object. Every 2xx also sets `X-DS-Request-Id`, `X-DS-Credits-Charged`, `X-DS-Credits-Balance`, the `X-RateLimit-*` trio and an `ETag`.

```json
{
  "data": {
    "…": "the item"
  },
  "meta": {
    "requestId": "req_7f3a9c2d1b4e5a6f7c8d",
    "generatedAt": "2026-09-21T09:00:00.000Z",
    "creditsCharged": 1,
    "creditsBalance": 199,
    "attribution": "Rates powered by DepositScout — depositscout.com"
  }
}
```

## Errors

What this endpoint can return instead of data. Every error has the same shape: `error` (a stable code to branch on), `message` (what to do next), `requestId` and a `docs` link, plus the extra fields shown. None of them is charged.

401 `missing_api_key` — No Authorization header, or it isn't a Bearer token.

```json
{
  "error": "missing_api_key",
  "message": "Send your key as 'Authorization: Bearer ds_live_…'. Create one at https://depositscout.com/developer.",
  "requestId": "req_7f3a9c2d1b4e5a6f7c8d",
  "docs": "https://depositscout.com/developers/docs#missing_api_key"
}
```

402 `insufficient_credits` — Balance is lower than the call's cost. A list whose page you can't fully afford is cut to the rows your balance covers instead (meta.limit and X-DS-Limit-Reduced say so), so this only happens below one row's price. Body has required, balance and topUp.

```json
{
  "error": "insufficient_credits",
  "message": "Not enough DS Credits for this request. Top up at https://depositscout.com/developer/credits.",
  "requestId": "req_7f3a9c2d1b4e5a6f7c8d",
  "docs": "https://depositscout.com/developers/docs#insufficient_credits",
  "required": 1,
  "balance": 0,
  "topUp": "https://depositscout.com/developer/credits"
}
```

429 `rate_limited` — Burst or daily limit hit. Retry-After tells you when.

```json
{
  "error": "rate_limited",
  "message": "Too many requests. Retry after 12s.",
  "requestId": "req_7f3a9c2d1b4e5a6f7c8d",
  "docs": "https://depositscout.com/developers/docs#rate_limited",
  "retryAfter": 12
}
```

Every code is listed in the [shared error contract](https://depositscout.com/developers/docs#errors). Back to [all endpoints](https://depositscout.com/developers/docs#endpoints).