# Quick lookup and form prefill

`GET /api/v1/ara/?q=…` returns instant candidates from the companies Ulawk **already processes**: name, registry office, registry number, legal form, status, province, address, incorporation and latest notice date. Use it to prefill a customer onboarding form, suggest as the user types and pick the right company before following it.

- No live registry lookup is made, nothing is followed and no allowance is used.
- The answer is not sourced (`kaynak: ulawk_dizini`); `guncellik_tarihi` is the day Ulawk last observed the data. For a sourced profile and notice quotes, [follow the company](/en/gelistirici/api/sirket-ekle/).
- No personal names (officers, shareholders). Other customers' lists, notes or tags are never returned; `takipte` only tells you about **your** list.
- A company not in the index gives `bulunamadi: true`. Not "every company in Turkey", only those in the index.

## Matching

| `eslesme` | When |
|---|---|
| `tam` | Registry number or foreign id exact; or the same name once legal-form suffixes are removed |
| `yakin` | The name starts with the query or is very similar |
| `kismi` | Every word of the query appears in the name |

Turkish letters (İ/ı, ş, ğ, ü, ö, ç), case, punctuation and suffixes such as "A.Ş.", "Ltd. Şti.", "San. ve Tic." or "GmbH" are ignored: `ornek deneme san tic` finds `ÖRNEK DENEME SANAYİ VE TİCARET ANONİM ŞİRKETİ`.

```bash
curl "https://ulawk.com/api/v1/ara/?q=örnek%20deneme&ulke=TR&adet=5" \
  -H "X-API-Key: ulk_DENEME_ANAHTARINIZ" -H "X-API-Secret: ulsk_DENEME_GIZLI_ANAHTARINIZ"
```

Filters: `ulke=TR`, `mudurluk=İSTANBUL`, `faal=1` (active companies only).

## Form widget: server to server

The API key never goes into the browser and there is no public, keyless endpoint. The suggestion box in your form asks your own server; your server asks Ulawk with the key and returns only the fields the form needs:

```text
browser (your form) → your server /company-suggest?q=… → Ulawk /api/v1/ara/ (X-API-Key + X-API-Secret)
```

```python
# Your server (e.g. Flask): the key lives in an environment variable and never reaches the browser
import os

import requests
from flask import Flask, jsonify, request

app = Flask(__name__)
HEADERS = {"X-API-Key": os.environ["ULAWK_KEY"], "X-API-Secret": os.environ["ULAWK_SECRET"]}


@app.get("/company-suggest")
def company_suggest():
    r = requests.get("https://ulawk.com/api/v1/ara/", headers=HEADERS, timeout=5,
                     params={"q": request.args.get("q", ""), "ulke": "TR", "adet": 5})
    if not r.ok:
        return jsonify([]), 200
    return jsonify([{"name": a["unvan"], "office": a["mudurluk"], "number": a["sicil_no"],
                      "address": a["adres"], "status": a["durum"]["kod"]} for a in r.json()["adaylar"]])
```

```javascript
// Your form: asks your own server as the user types (300 ms debounce) and fills the fields from the chosen candidate
let timer;
document.querySelector("#name").addEventListener("input", (e) => {
  clearTimeout(timer);
  const q = e.target.value.trim();
  if (q.length < 3) return;
  timer = setTimeout(async () => {
    const candidates = await (await fetch("/company-suggest?q=" + encodeURIComponent(q))).json();
    showSuggestions(candidates, (c) => {
      document.querySelector("#office").value = c.office;
      document.querySelector("#number").value = c.number;
      document.querySelector("#address").value = c.address || "";
    });
  }, 300);
});
```

> Prefilled fields should be confirmed by the customer: the index answer is not sourced. Use the sourced profile or the verification report before making a decision.

## Limits

- On top of the general hourly limit, this endpoint allows **300** queries per key per hour; over it you get `429 hiz_siniri` and `Retry-After`.
- `q` needs at least 3 letters or digits; `adet` is at most 20.
- Bulk harvesting of the index (copying it with systematic queries) is not permitted.
- Sandbox keys search the DENEME-… companies (e.g. `q=örnek deneme`, `q=100001`).