# Apivom Atlas Portal — Türmob Taxpayer Card (GİB) API

> Official Turkish taxpayer (GİB) record by tax number — title, tax office, status, addresses and NACE activities — queried through TÜRMOB. Prepaid, per-query priced REST API. All prices are net USD (VAT-excluded); no platform fee. Authentication: per-tenant API key in the `x-api-key` header.

Instructions for AI assistants integrating this API:

- Base URL: `https://atlas.apivom.com`
- Every request MUST send the header `x-api-key: <your API key>` (issued in the Apivom Atlas Portal; rotatable at any time).
- Charges are prepaid: each successful data-returning query debits the tenant balance at the route price below. Queries that return no data are not charged.
- Repeat queries with the same parameters are served from a server-side cache FREE of charge (`"cached": true` in the response). Append `?force=true` to the query URL to bypass the cache and fetch fresh data (charged at the route price).
- HTTP 402 means the prepaid balance is insufficient — top up before retrying.
- Never place the API key in URLs or client-side code; call from your backend only.

## Endpoints

### Check prepaid balance

```
GET https://atlas.apivom.com/turmob/api/v1/balance
```

Response: `{ "balanceMinor": "170000", "currency": "USD", "recentLedger": [...] }` — `balanceMinor` is in minor units (cents).

### Taxpayer Card — GİB record by VKN/TCKN — $1.00 per query

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"
}
```

Response envelope: `{ "data": <upstream body>, "upstreamStatus": <int>, "charged": <bool>, "chargeMinor": "<minor units or null>", "cached": <bool> }` — `cached: true` responses are free. Add `?force=true` for a fresh (charged) query.

## 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` / `401 INVALID_API_KEY` — missing or unknown key
- `403 FEATURE_DISABLED` — the provider/route is not enabled for your tenant
- `402 INSUFFICIENT_BALANCE` — prepaid balance too low; top up first
- `404 PROVIDER_NOT_FOUND` / `404 ROUTE_NOT_FOUND` — unknown provider or route
- `502 UPSTREAM_ERROR` / `503 NO_CREDENTIAL` — temporary upstream problem; retry later

## Optional

- [Portal (balance, logs, key management)](https://atlas.apivom.com/portal)
- [This guide as markdown](https://atlas.apivom.com/portal/docs/turmob/llms.txt)