Türmob Taxpayer Card (GİB) — Integration guide
Official Turkish taxpayer (GİB) record by tax number — title, tax office, status, addresses and NACE activities — queried through TÜRMOB.
Machine-readable markdown — feed it to your AI assistant as integration instructions.
Authentication
x-api-key: <your API key> # required on every request; backend-only, never client-side
Endpoints
Balance
GET https://atlas.apivom.com/turmob/api/v1/balance
Taxpayer Card — GİB record by VKN/TCKN — $1.00 per query (excl. VAT)
Returns the official GİB taxpayer record for a tax number (VKN, 10 digits) or a Turkish citizen ID (TCKN, 11 digits) as `mukellef`: title (`unvan`, `kimlikUnvani`), company type (`sirketinTuru`), tax office (`vergiDairesiAdi`, `vergiDairesiKodu`), status (`durum`), registered addresses (`adresBilgileri[]`) and NACE activities where available. A checksum-invalid number is rejected upstream with 400 VALIDATION_ERROR and a number without a taxpayer record returns 404 — neither is charged or cached. Note: the sample number 1234567890 returns the provider's demonstration record and IS charged.
POST https://atlas.apivom.com/turmob/api/v1/query/taxpayer-card
Content-Type: application/json
x-api-key: <your API key>
{
"vknTckn": "1234567890"
}Repeat queries with the same parameters are served from cache FREE ("cached": true). Append ?force=true to bypass the cache and fetch fresh data (charged).
Commercial terms
- Initial prepayment: $1,700.00 opens the account. The full amount is your query balance; no part of it is a fee.
- Minimum top-up: $550.00 by bank transfer whenever needed; you are warned when the balance runs low.
- Balance validity: 24 months from your last top-up; every top-up extends the validity of the whole balance.
- No record, no charge: queries for which the registry has no record are free.
- Each card has a single price: a Card 4 query is charged at the Card 4 price, not the sum of Cards 1–4.
Error codes
401 MISSING_API_KEY / INVALID_API_KEY missing or unknown key 403 FEATURE_DISABLED provider/route not enabled for your tenant 402 INSUFFICIENT_BALANCE prepaid balance too low; top up first 404 PROVIDER_NOT_FOUND / ROUTE_NOT_FOUND unknown provider or route 502 UPSTREAM_ERROR / 503 NO_CREDENTIAL temporary upstream problem; retry later