# Apivom Atlas Portal — TOBB Company Card (MERSIS) API

> Official Turkish trade-registry (MERSIS) company data — four company-card detail levels plus branch cards, resold per query. 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/tobb/api/v1/balance
```

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

### Company Card 1 — Basic info (v2, Merkez array) — $0.40 per query

Core registry record by tax number: trade name, MERSIS no, registry office, status. v2 contract (TOBB 2026-09-11): `data.Merkez` is an ARRAY — one element for companies, several for sole proprietors whose businesses share one TCKN/VKN. Iterate the array; do not read `Merkez` as an object.

```
POST https://atlas.apivom.com/tobb/api/v1/query/company-card-basic-v2
Content-Type: application/json
x-api-key: <your API key>

{
  "VergiNo": "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.

### Branch Card — Branch registry record — $0.65 per query

Branch (şube) registry record by MERSIS number.

```
POST https://atlas.apivom.com/tobb/api/v1/query/branch-card
Content-Type: application/json
x-api-key: <your API key>

{
  "MersisNo": "0123456789012345"
}
```

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.

### Company Card 2 — Address, capital & NACE (v2, Merkez array) — $0.65 per query

Card 1 plus structured address (AdresDetay), capital detail (SermayeDetay) and NACE codes (Naceler) per business. `data.Merkez` is an ARRAY (see Card 1 v2).

```
POST https://atlas.apivom.com/tobb/api/v1/query/company-card-address-nace-v2
Content-Type: application/json
x-api-key: <your API key>

{
  "VergiNo": "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.

### Company Card 3 — Partners, board & representatives (v2, Merkez array) — $1.25 per query

Cards 1–2 plus partners (Ortaklar), board members (AktifUyeler), authorised representatives (AktifTemsilciler) and auditors (Denetciler) per business. `data.Merkez` is an ARRAY (see Card 1 v2).

```
POST https://atlas.apivom.com/tobb/api/v1/query/company-card-partners-v2
Content-Type: application/json
x-api-key: <your API key>

{
  "VergiNo": "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.

### Company Card 4 — Full record incl. branches & gazette PDF (v2, Merkez array) — $1.55 per query

Cards 1–3 plus bankruptcy/concordat (IflasKonkordato), up to 50 active branches (Subeler) and the latest Trade Registry Gazette announcement as base64 PDF (SonGazete) per business. `data.Merkez` is an ARRAY (see Card 1 v2).

```
POST https://atlas.apivom.com/tobb/api/v1/query/company-card-full-v2
Content-Type: application/json
x-api-key: <your API key>

{
  "VergiNo": "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/tobb/llms.txt)