Sign in
GET/simulate

Simulate savings returns

What a balance would earn in one product (sourceKey) or at a plain rate (rate): interest, end balance and the rate for each stretch, with an intro bonus ending on time and fixed rates held to the end of the term.

View as Markdown
All endpoints

EndpointsChangelog

Pass rateChange to see a variable rate moving (e.g. -0.5). AER compounded annually, gross, nothing added or withdrawn; the response lists every assumption. An illustration, not advice.

Cost

2 DS Credits

per request

Scope

rates:read

Same data as

—

the DepositScout website

Request

GET https://depositscout.com/api/developer/v1/simulate

  • amount*query · number

    Balance in pounds.

    Example: 50000

  • sourceKeyquery · string

    Product from /rates. Pass this or rate.

    Example: example-bank-easy-saver

  • ratequery · number

    An AER to simulate instead of a product, e.g. 4.5.

  • monthsquery · integer

    Period, 1 to 120. Defaults to a fixed product's term, otherwise 12.

    Example: 12

  • rateChangequery · number

    Percentage points to move variable rates by, e.g. -0.5.

    Example: -0.5

Example

shell
curl "https://depositscout.com/api/developer/v1/simulate?amount=50000&sourceKey=example-bank-easy-saver&months=12&rateChange=-0.5" \
  -H "Authorization: Bearer $DS_API_KEY"

Try it

Runs against this site. A ds_test_ key is free and returns sample data in the real shape; a live key returns real data and spends credits. The key is kept in this tab only.

No key yet? Create an account or sign in for a free test key.
GET /api/developer/v1/simulate?amount=50000
as curl
curl "/api/developer/v1/simulate?amount=50000" \
  -H "Authorization: Bearer ds_test_…"

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.

response.json
{
  "data": {
    "…": "the item"
  },
  "meta": {
    "requestId": "req_7f3a9c2d1b4e5a6f7c8d",
    "generatedAt": "2026-09-21T09:00:00.000Z",
    "creditsCharged": 2,
    "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.

401missing_api_key— No Authorization header, or it isn't a Bearer token.
401 missing_api_key.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"
}
403insufficient_scope— The key doesn't carry the scope the endpoint needs.
403 insufficient_scope.json
{
  "error": "insufficient_scope",
  "message": "This key doesn't have the 'rates:read' scope.",
  "requestId": "req_7f3a9c2d1b4e5a6f7c8d",
  "docs": "https://depositscout.com/developers/docs#insufficient_scope",
  "required": "rates:read"
}
402insufficient_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.
402 insufficient_credits.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": 2,
  "balance": 0,
  "topUp": "https://depositscout.com/developer/credits"
}
429rate_limited— Burst or daily limit hit. Retry-After tells you when.
429 rate_limited.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. Back to all endpoints.