API docs — ATMList

Overview

The ATMList B2B API is designed for regulated workloads: predictable schemas, idempotent reads, regional edge caching, and audit-friendly request IDs on every response. Integrate from mobile apps, authorization systems, or batch analytics — without stitching together operator PDFs, map scrapes, and ad-hoc fee tables.

Location intelligence — coordinates validated against operator feeds, OSM, and on-the-ground signals.
Fee intelligence — surcharges and FX margins normalized per market and card program.
Risk signals — per-ATM scores for issuer fraud and step-up authentication.

Quickstart

1
Request sandbox access
Email [email protected] or book a demo — we issue sandbox keys with Southeast Asia and EU sample coverage within one business day.
2
Make your first call
List ATMs near a coordinate with `GET /v1/atms?near=lat,lng`. No SDK required.
3
Personalize with BIN
Pass `bin` on lookups to mark surcharge-free machines and alliance partners for your card program.
4
Go live
Swap `sk_test_` keys for `sk_live_` after security review. Production traffic is billed per successful lookup tier on your order form.

Authentication

Authenticate with a secret API key issued for sandbox (sk_test_) or production (sk_live_). Send the key as a Bearer token. Keys are scoped to your contract — geography, risk signal depth, and bulk export rights vary by plan.

Headerhttp

Authorization: Bearer sk_live_xxxxxxxx
Accept: application/json
X-Request-Id: 7f3c9e2a-optional-client-correlation-id

Never embed live keys in mobile binaries or public repositories. Use your backend or a tokenization layer for BIN data; the API accepts bin_token on fee endpoints where raw BIN transmission is restricted.

Errors & limits

Errors return a JSON body with error.code, error.message, and request_id. Default sandbox limit is 60 requests per minute; production tiers scale to 10,000+ RPM with burst headroom. Successful lookups include standard rate-limit headers.

Code	HTTP	Meaning
invalid_request	400	Missing or malformed parameters (e.g. invalid `near` coordinates).
authentication_failed	401	API key missing, revoked, or not authorized for this environment.
forbidden	403	Endpoint or expansion not included on your commercial plan.
not_found	404	Unknown `atm_id` or delisted machine.
rate_limited	429	Too many requests. Retry after `Retry-After` header (seconds).

REST endpoints

GET/v1/atms

List ATMs nearby

Return verified ATMs around a latitude/longitude, ranked by distance.

The primary lookup for in-app ATM finders and travel products. Responses include location, operator, network affiliations, normalized surcharge data, and a fraud-risk band. Use optional BIN parameters to personalize fee and surcharge-free eligibility without sending a full PAN.

Query parameters

nearrequired

string

Comma-separated `lat,lng` (WGS-84). Example: `1.2804,103.8510`.

radius_m

integer

Search radius in meters. Default `2000`, max `25000`.

limit

integer

Page size. Default `50`, max `200`.

bin

string

First 6–8 digits of the card (BIN/IIN). Enables surcharge-free and alliance hints for the card program.

include

string

Comma-separated expansions: `fee`, `risk`, `hours`, `accessibility`. Default includes `fee` and `risk`.

cURLbash

curl -s "https://api.atmlist.com/v1/atms?near=1.2804,103.8510&radius_m=1500&limit=3" \
  -H "Authorization: Bearer sk_live_••••••••" \
  -H "Accept: application/json"

Responsejson

{
  "data": [
    {
      "id": "atm_sg_hsbc_marina_0182",
      "type": "atm",
      "name": "HSBC · Marina Bay",
      "operator": { "id": "hsbc", "name": "HSBC" },
      "location": {
        "lat": 1.2799,
        "lng": 103.8542,
        "address": "10 Marina Blvd, Singapore",
        "country": "SG"
      },
      "distance_m": 142,
      "networks": ["visa", "mastercard", "plus"],
      "fee": {
        "surcharge": { "amount": 0, "currency": "SGD" },
        "surcharge_free": true,
        "fx_markup_bps": null
      },
      "risk": { "score": 11, "band": "low", "updated_at": "2026-06-09T18:22:11Z" },
      "attributes": { "deposit": false, "contactless": true, "hours": "24/7" }
    }
  ],
  "meta": { "count": 128, "has_more": true, "cursor": "eyJvZmZzZXQiOjUwIn0" }
}

TypeScripttypescript

import { AtmList } from "@atmlist/sdk";

const client = new AtmList({ apiKey: process.env.ATMLIST_API_KEY! });

const { data } = await client.atms.listNearby({
  near: { lat: 1.2804, lng: 103.8510 },
  radiusMeters: 1500,
  bin: "454631",
  limit: 25,
});

console.log(data[0]?.fee.surchargeFree, data[0]?.risk.band);

GET/v1/atms/{atm_id}

Get ATM by ID

Fetch a single ATM record, including enrichment you have access to on your plan.

Use stable ATMList IDs returned from search or bulk feeds. Ideal for detail screens, authorization enrichment, and fraud workflows that need the latest risk score for one terminal.

Query parameters

bin

string

Optional BIN to personalize fee and network eligibility.

include

string

Same expansions as list nearby.

cURLbash

curl -s "https://api.atmlist.com/v1/atms/atm_sg_hsbc_marina_0182?include=fee,risk" \
  -H "Authorization: Bearer sk_live_••••••••"

GET/v1/atms/search

Search & filter

Query ATMs inside a bounding box or country with structured filters.

Designed for analytics pipelines, coverage maps, and issuer tools. Combine geographic bounds with operator, network, surcharge-free, accessibility, and risk filters.

Query parameters

bboxrequired

string

Southwest and northeast corners: `sw_lat,sw_lng,ne_lat,ne_lng`.

country

string

ISO 3166-1 alpha-2 country code. Alternative to `bbox` for national exports.

operator

string

Operator slug, e.g. `dbs`, `maybank`, `euronet`.

network

string

Alliance or scheme: `allpoint`, `global_atm_alliance`, `visa`, `mastercard`.

risk_band

string

Filter by `low`, `elevated`, or `high` fraud-risk band.

cursor

string

Opaque cursor from `meta.cursor` for pagination.

cURLbash

curl -s "https://api.atmlist.com/v1/atms/search?country=MY&operator=maybank&risk_band=low&limit=100" \
  -H "Authorization: Bearer sk_live_••••••••"

POST/v1/fees/estimate

Estimate withdrawal fees

Return an estimated total cost for a withdrawal at a specific ATM and card program.

Combines ATM surcharge intelligence, issuer interchange assumptions, and FX margin models. Send amount and withdrawal currency; optionally pass a BIN token instead of raw BIN when your security policy requires it.

Request body (JSON)

atm_idrequired

string

ATMList ID from a prior lookup.

amountrequired

object

`{ value, currency }` — withdrawal amount in local or account currency.

bin

string

6–8 digit BIN/IIN for program-specific surcharge rules.

bin_token

string

Tokenized BIN reference from your vault — preferred in production.

cURLbash

curl -s "https://api.atmlist.com/v1/fees/estimate" \
  -H "Authorization: Bearer sk_live_••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "atm_id": "atm_sg_euronet_changi_0441",
    "amount": { "value": 200, "currency": "SGD" },
    "bin": "454631"
  }'

Responsejson

{
  "atm_id": "atm_sg_euronet_changi_0441",
  "estimated_total": { "amount": 6.0, "currency": "SGD" },
  "breakdown": {
    "atm_surcharge": { "amount": 5.0, "currency": "SGD" },
    "issuer_fee": { "amount": 1.0, "currency": "SGD" },
    "fx_markup": null
  },
  "disclosure_text": "Includes ATM operator surcharge and issuer out-of-network fee.",
  "confidence": "high"
}

GET/v1/networks/match

Match card to networks

Resolve scheme, alliance, and partner-bank eligibility from a BIN.

Powers surcharge-free routing and in-app messaging before the customer commits to a machine. Does not require a specific ATM — pair with nearby search for ranked results.

Query parameters

binrequired

string

6–8 digit BIN/IIN.

country

string

ISO country where the withdrawal will occur — improves alliance resolution.

cURLbash

curl -s "https://api.atmlist.com/v1/networks/match?bin=454631&country=SG" \
  -H "Authorization: Bearer sk_live_••••••••"

GET/v1/risk/{atm_id}

Fraud risk score

Latest fraud-risk band and contributing signals for a terminal.

Used by issuers and risk platforms at authorization time. Scores refresh as skimming reports, tamper signals, and anomalous withdrawal patterns are ingested. Your plan controls signal depth in the payload.

Query parameters

signals

boolean

When `true`, include explainable signal codes (enterprise plans).

cURLbash

curl -s "https://api.atmlist.com/v1/risk/atm_vn_vpbank_d1_0091?signals=true" \
  -H "Authorization: Bearer sk_live_••••••••"

Responsejson

{
  "atm_id": "atm_vn_vpbank_d1_0091",
  "score": 78,
  "band": "elevated",
  "updated_at": "2026-06-10T04:01:00Z",
  "signals": [
    { "code": "skim_report_cluster", "weight": 0.42 },
    { "code": "terminal_tamper_anomaly", "weight": 0.31 }
  ]
}

ATM object

Core fields returned by list, search, and get endpoints. Additional properties may appear behind feature flags or enterprise expansions — clients should ignore unknown keys.

idstringStable ATMList identifier. Use for caching, webhooks, and audit trails.

namestringDisplay name combining operator and location label.

operatorobjectInstitution operating the terminal: `{ id, name, country? }`.

locationobjectWGS-84 coordinates, structured address, and ISO country code.

networksstring[]Schemes and alliances observed at the terminal (e.g. `visa`, `allpoint`).

feeobjectNormalized surcharge and program eligibility. Amounts use minor units where applicable.

riskobject`score` (0–100), `band` (`low` | `elevated` | `high`), and `updated_at`.

attributesobjectCapabilities: deposit, contactless, wheelchair access, hours, and more.

Webhooks

Subscribe to dataset and risk changes instead of polling. Configure endpoints in the customer console; deliveries are signed with HMAC-SHA256 using your webhook secret.

atm.updated
Location, attributes, or operator metadata changed for a watched ATM.
atm.delisted
Machine removed from the verified dataset (closed, relocated, duplicate).
risk.elevated
Fraud-risk band increased to `elevated` or `high` for a subscribed ATM or region.
fee.changed
Surcharge or fee model updated for an operator in a market you subscribe to.

GraphQL explorer and bulk SFTP feeds are provisioned on enterprise agreements. Questions? Contact sales or email [email protected].

Data API

Overview

Quickstart

Authentication

Errors & limits

List ATMs nearby

Get ATM by ID

Search & filter

Estimate withdrawal fees

Match card to networks

Fraud risk score

ATM object

Webhooks