---
last_updated: 2026-08-09
tags: [fanavaran, api, read, lookups]
source: fanavaran-module-docs
---

# 02 — Read APIs & Lookups

All read calls use the same business headers as write APIs (`authenticationToken`, `CorpId`, `ContractId`, `Location`).

Lookup responses are **tenant-specific**. Cache directory:

```text
files/fanavaran-lookups/{clientKey}/
```

Config: `src/fanavaran/fanavaran-lookup.config.ts`  
Service: `FanavaranLookupService`  
Local HTTP: `LookupsController` / `LookupsService` (`src/lookups/`)

Fanavaran base (docs often call this **BaseURL1**):

```text
https://apimanager.iraneit.com/BimeApiManager/api/BimeApi/v2.0
```

Example catalogue URL:

```text
{BaseURL1}/car/base-info/driving-licence-types
→ YARA: GET /lookups/driving-licence-types
```

---

## 1. Policy inquiry (guilty party)

| Item | Value |
|------|-------|
| Endpoint | `GET /Api/BimeApi/v2.0/common/Policies/inquiry-my-policies` |
| Query | `InsuranceLineId=5` (third-party), `NationalCode={insurerNationalCode}` |
| Usage | Resolve `PolicyId` for GEN.03 |
| Selection | `selectLatestActiveFanavaranPolicy` — latest non-expired by `EndDate` |
| Cache | `fanavaranSync.baseClaim.policyId` (resolve-once) |
| Force refresh | Manual preview `forceRefreshPolicy=true` only |

**Errors (YARA messages):**

- No policies → contact admin
- Latest expired → cannot send
- Invalid PolicyId/EndDate → contact admin

**Do not** treat UI `resolvePolicy=true` as cache-bust (deprecated; ignored for re-inquiry).

---

## 2. Driver / person inquiry

Used when building GEN.12 to resolve `DriverId`.

| Item | Value |
|------|-------|
| Endpoint | `GET /Api/BimeApi/v2.0/common/parties/inquiry-by-unique-identifier` |
| Usage | `resolveDriverFanavaranId(clientKey, nationalCode, birthday, driverIsInsurer)` via `FanavaranLookupService` |
| Cache | `fanavaranSync.damageCase.driverId` and `blameCase.parties[].person.fanavaranDriverId` |

Prefer cache before live call.

---

## 3. Remote lookup catalogue

Base: `https://apimanager.iraneit.com/BimeApiManager/api/BimeApi/v2.0`

| Name | Fanavaran path | Local YARA route | Used for |
|------|----------------|------------------|----------|
| accident-causes | `/car/base-info/accident-causes` | `GET /lookups/accident-causes` | Accident cause options |
| accident-report-type | `/car/code-list/accident-report-type` | `GET /lookups/accident-report-type` | Defaults / UI |
| vehicle-use-types | `/car/base-info/vehicle-use-types` | `GET /lookups/vehicle-use-types` | Vehicle use |
| dmg-pay-method | `/car/code-list/dmg-pay-method` | `GET /lookups/dmg-pay-method` | Pay method |
| driving-licence-types | `/car/base-info/driving-licence-types` | `GET /lookups/driving-licence-types` | Licence type |
| accident-culprit-type | `/car/code-list/accident-culprit-type` | `GET /lookups/accident-culprit-type` | Culprit type |
| inspection-place | `/car/code-list/inspection-place` | `GET /lookups/inspection-place` | GEN.08 |
| drop-amount-status | `/car/code-list/drop-amount-status` | `GET /lookups/drop-amount-status` | GEN.08 |
| car-components | `/car/base-info/car-components` | `GET /lookups/car-components` | `DmgSectionId` |
| accident-level | `/car/code-list/accident-level` | `GET /lookups/accident-level` | Section severity |
| expert-status | `/car/code-list/expert-status` | `GET /lookups/expert-status` | Expertise status |
| vehicle-kinds | `/car/base-info/vehicle-kinds` | `GET /lookups/vehicle-kinds` | GEN.12 `VehicleKindId` |
| person-role | `/common/code-list/person-role` | `GET /lookups/person-role` | Roles |
| insurance-corp | `/common/code-list/insurance-corp` | via fanavaran + resolve | GEN.12 `InsuranceCorpId` |
| file-types | `/common/base-info/file-types` | `GET /lookups/file-types` | GEN.07 `FileTypeId` |
| cities | `/common/base-info/cities` | `GET /lookups/cities` | City ids |
| provinces | `/common/base-info/Provinces` | `GET /lookups/provinces` | Provinces |
| dmg-case-type | `/car/code-list/dmg-case-type` | `GET /lookups/dmg-case-type` | GEN.12 |
| dmg-history-status | `/car/code-list/dmg-case-history-status` | `GET /lookups/dmg-history-status` | GEN.12 |
| used-place | `/car/code-list/used-place` | `GET /lookups/used-place` | Used place |
| dmg-business-line | `/car/code-list/dmg-business-line` | `GET /lookups/dmg-business-line` | Business line |

### Generic accessor

```http
GET /lookups/fanavaran
GET /lookups/fanavaran/{lookupName}
```

Lists / fetches by name for the **active** `FANAVARAN_CLIENT`.

---

## 4. Lookups module — Nest routes (`LookupsController`)

Auth: Bearer + `AuthGuard`. Active tenant from `FANAVARAN_CLIENT` / `CLIENT_ID`.

### 4.1 Cached Fanavaran catalogue (dedicated routes)

| Nest route | Fanavaran path |
|------------|----------------|
| `GET /lookups/accident-causes` | `/car/base-info/accident-causes` |
| `GET /lookups/accident-report-type` | `/car/code-list/accident-report-type` |
| `GET /lookups/vehicle-use-types` | `/car/base-info/vehicle-use-types` |
| `GET /lookups/dmg-pay-method` | `/car/code-list/dmg-pay-method` |
| `GET /lookups/driving-licence-types` | `/car/base-info/driving-licence-types` |
| `GET /lookups/accident-culprit-type` | `/car/code-list/accident-culprit-type` |
| `GET /lookups/inspection-place` | `/car/code-list/inspection-place` |
| `GET /lookups/drop-amount-status` | `/car/code-list/drop-amount-status` |
| `GET /lookups/car-components` | `/car/base-info/car-components` |
| `GET /lookups/accident-level` | `/car/code-list/accident-level` |
| `GET /lookups/expert-status` | `/car/code-list/expert-status` |
| `GET /lookups/vehicle-kinds` | `/car/base-info/vehicle-kinds` |
| `GET /lookups/person-role` | `/common/code-list/person-role` |
| `GET /lookups/file-types` | `/common/base-info/file-types` |
| `GET /lookups/cities` | `/common/base-info/cities` |
| `GET /lookups/provinces` | `/common/base-info/Provinces` |
| `GET /lookups/dmg-case-type` | `/car/code-list/dmg-case-type` |
| `GET /lookups/dmg-history-status` | `/car/code-list/dmg-case-history-status` |
| `GET /lookups/used-place` | `/car/code-list/used-place` |
| `GET /lookups/dmg-business-line` | `/car/code-list/dmg-business-line` |
| `GET /lookups/fanavaran` | catalogue metadata (names + URLs) |
| `GET /lookups/fanavaran/{lookupName}` | any configured name (incl. `insurance-corp`) |

### 4.2 Live inquiry helpers

| Nest route | Fanavaran path / notes |
|------------|------------------------|
| `GET /lookups/inquiry-by-vin?vin=` | `/car/vehicles/inquiry-by-vin` |
| `GET /lookups/my-policies?nationalCode=&insuranceLineId=` | `/common/Policies/inquiry-my-policies` |
| `GET /lookups/third-party-policy/:policyId` | `/car/third-party-car-policies/{id}` |
| `GET /lookups/body-policy/:policyId` | `/car/vehicle-hull-policies/{id}` |

### 4.3 UI accident field helpers (local / mapped)

| Nest route | Purpose |
|------------|---------|
| `GET /lookups/accident-way` | Accident way options |
| `GET /lookups/accident-reason` | Accident reason options (+ Fanavaran map when available) |
| `GET /lookups/accident-type` | Accident type options |
| `GET /lookups/accident-fields` | Combined way + reason + type |

---

## 5. Insurance corp resolve

| Item | Value |
|------|-------|
| Env | `INSURANCE_CORP_ID` = Persian **Caption** in insurance-corp list |
| Method | `FanavaranLookupService.resolveInsuranceCorpId(clientKey)` |
| Behavior | Fetch list once, match caption → numeric `Id`, cache |
| Parsian proven | `InsuranceCorpId=329` (for that deployment caption) |

---

## 6. Vehicle kind resolve

| Item | Value |
|------|-------|
| Input | Local `claimCase.vehicle.carType` (sedan/suv/…) |
| Method | Match Fanavaran `vehicle-kinds` Caption keywords |
| Cache | `fanavaranSync.damageCase.vehicleKindId` |
| Parsian proven | `VehicleKindId=6704` on sample case |

---

## 7. How lookups are used in project

1. First call for a tenant fetches from Fanavaran (authenticated).
2. Writes JSON under `files/fanavaran-lookups/{client}/`.
3. Subsequent reads prefer cache file.
4. Claim payload builders call `getFanavaranLookupRows(clientKey, name)` when mapping ids.
5. Outer car parts catalogue can align with Fanavaran car-components (`FANAVARAN_CAR_PARTS_CATALOG` / helpers).

**Dependency:** Auth must succeed for cold cache. Transient “try again later” triggers tenant backoff (see [09-error-handling.md](./09-error-handling.md)).