# Quick lookup (prefill) `GET https://ulawk.com/api/v1/ara/` Instant candidates from the Ulawk index: name, registry office, registry number, legal form, status, province, address, incorporation and latest notice date. Only companies Ulawk already processes are returned; no live registry lookup is made, nothing is followed and no allowance is used. No personal names and nothing about other customers is returned. Searches by name, registry number or foreign id; Turkish letters, case and legal-form suffixes (A.Ş., Ltd. Şti., GmbH …) are ignored. Without a match you get `bulunamadi: true`; follow the company with `sirket-ekle`. This endpoint has its own hourly query limit; bulk harvesting of the index is not permitted. ## Authentication Two headers on every request: `X-API-Key` and `X-API-Secret`. ## Query parameters - `q` (string, required) — Name, registry number or id (at least 3 letters/digits). - `ulke` (string) — Country filter (TR, GB …); all if omitted. - `adet` (integer) — Max candidates (default 10, max 20). - `mudurluk` (string) — Only this registry office (Turkey). - `faal` (string) — 1 → only companies whose status is FAAL. ## Response ### 200 — Candidates (may be empty). - `sorgu` (string, zorunlu) - `ulke` (string, null, zorunlu) — Country filter or null (all). - `adet` (integer, zorunlu) - `kaynak` (string, zorunlu) Değerler: ulawk_dizini. - `bulunamadi` (boolean, zorunlu) — No candidate in the index: follow the company to build a sourced profile. - `aciklama` (string, zorunlu) - `takibe_al` (string (uri), zorunlu) — Follow endpoint (`POST`). - `adaylar[]` (HizliSorguAdayi[], zorunlu) - `adaylar[].ulke` (string, zorunlu) — ISO country code (TR; abroad the record's country, ZZ = LEI). - `adaylar[].kimlik` (string, zorunlu) — Index id: in Turkey `OFFICE/registry root` (e.g. İSTANBUL/325075), abroad the registry id. - `adaylar[].mudurluk` (string, null, zorunlu) — Trade registry office (Turkey only); pass it to `sirket-ekle` as is. - `adaylar[].sicil_no` (string, null, zorunlu) — Registry number (Turkey only). - `adaylar[].unvan` (string, zorunlu) — Name (in Turkey as written in the latest gazette notice). - `adaylar[].hukuki_bicim` (object, zorunlu) - `adaylar[].hukuki_bicim.kod` (string, zorunlu) — Ulawk form code (TR_AS, TR_LTD, YB_GMBH …; BILINMIYOR if unknown). - `adaylar[].hukuki_bicim.yerel` (string, null, zorunlu) — Local name. - `adaylar[].hukuki_bicim.en` (string, null, zorunlu) — English name. - `adaylar[].hukuki_bicim.iso` (string, null, zorunlu) — ISO 20275 (ELF) code; null without an exact match in the list. - `adaylar[].hukuki_bicim.kategori` (string, zorunlu) — Standard category: ANONIM, LIMITED, SAHIS_SIRKETI, KOOPERATIF, SUBE … - `adaylar[].durum` (object, zorunlu) - `adaylar[].durum.kod` (string, zorunlu) Değerler: FAAL, IFLAS_KONKORDATO, TASFIYEDE, KAPANDI, BILINMIYOR. - `adaylar[].durum.ad` (string, zorunlu) - `adaylar[].durum.yerel` (string, zorunlu) — Wording in the source or notice. - `adaylar[].durum.uluslararasi` (string, zorunlu) — International equivalent (ACTIVE, PENDING_DISSOLUTION, CLOSED …). - `adaylar[].il` (string, null, zorunlu) — Province (from the registry office; Turkey only). - `adaylar[].adres` (string, null, zorunlu) — Registered address (from the identity section of the sourced profile; null if none). - `adaylar[].kurulus` (string (date), null, zorunlu) — Incorporation date (YYYY-MM-DD) or null. - `adaylar[].son_ilan_tarihi` (string (date), null, zorunlu) — Latest notice/event date in the index. - `adaylar[].kaynak` (string, zorunlu) Değerler: ulawk_dizini. - `adaylar[].guncellik_tarihi` (string (date), null, zorunlu) — The day Ulawk last observed the data; it does not mean the answer is current. - `adaylar[].eslesme` (string, zorunlu) — tam: registry no / id exact or same bare name · yakin: name starts with the query or is very similar · kismi: all words appear. Değerler: tam, yakin, kismi. - `adaylar[].skor` (number, zorunlu) — 0–1 similarity. - `adaylar[].takipte` (boolean, zorunlu) — Whether the company is on YOUR list (other customers' lists are never disclosed). - `adaylar[].sirket_id` (integer | string, null, zorunlu) — Your company id when followed (`/api/v1/sirketler/{id}/`). - `adaylar[].profil` (string (uri), null, zorunlu) — Sourced profile address when followed. ```json { "sorgu": "örnek deneme", "ulke": "TR", "adet": 3, "kaynak": "ulawk_dizini", "bulunamadi": false, "aciklama": "Yalnız Ulawk dizinindeki şirketler; canlı sicil sorgusu yapılmaz ve yanıt kaynaklı değildir. Kaynaklı profil için şirketi takibe alın.", "takibe_al": "https://ulawk.com/api/v1/sirket-ekle/", "adaylar": [ { "ulke": "TR", "kimlik": "DENEME-100001", "mudurluk": "İSTANBUL", "sicil_no": "DENEME-100001", "unvan": "ÖRNEK DENEME SANAYİ VE TİCARET ANONİM ŞİRKETİ", "hukuki_bicim": { "kod": "TR_AS", "yerel": "Anonim şirket", "en": "Joint-stock company", "iso": "W2SQ", "kategori": "ANONIM" }, "durum": { "kod": "FAAL", "ad": "Faal", "yerel": "Faal", "uluslararasi": "ACTIVE" }, "il": "İSTANBUL", "adres": "Örnek Mahallesi Deneme Caddesi No:1 İstanbul", "kurulus": "2015-03-02", "son_ilan_tarihi": "2026-10-16", "kaynak": "ulawk_dizini", "guncellik_tarihi": "2026-10-01", "eslesme": "tam", "skor": 1.0, "takipte": true, "sirket_id": "DENEME-100001", "profil": "https://ulawk.com/api/v1/sirketler/DENEME-100001/" }, { "ulke": "TR", "kimlik": "DENEME-TASFIYE", "mudurluk": "ANTALYA", "sicil_no": "DENEME-TASFIYE", "unvan": "ÖRNEK DENEME İNŞAAT LİMİTED ŞİRKETİ (TASFİYE HALİNDE)", "hukuki_bicim": { "kod": "TR_LTD", "yerel": "Limited şirket", "en": "Limited liability company", "iso": "R5UT", "kategori": "LIMITED" }, "durum": { "kod": "TASFIYEDE", "ad": "Tasfiye halinde", "yerel": "Tasfiye halinde", "uluslararasi": "PENDING_DISSOLUTION" }, "il": "ANTALYA", "adres": "Örnek Mahallesi Deneme Caddesi No:1 Antalya", "kurulus": "2011-02-14", "son_ilan_tarihi": "2026-10-12", "kaynak": "ulawk_dizini", "guncellik_tarihi": "2026-10-01", "eslesme": "yakin", "skor": 0.871, "takipte": false, "sirket_id": null, "profil": null } ] } ``` ### 400 — `gecersiz_parametre` (q too short, invalid ulke or adet). ```json { "hata": "gecersiz_parametre", "detay": "q en az 3 harf ya da rakam olmalı.", "hata_ayrinti": { "kod": "gecersiz_parametre", "mesaj": "q en az 3 harf ya da rakam olmalı.", "taraf": "istemci", "kaynak": null, "tekrar_denenebilir": false, "tekrar_sn": null } } ``` ### 405 — GET expected (`yontem`). ```json { "hata": "yontem", "detay": "GET bekleniyor.", "hata_ayrinti": { "kod": "yontem", "mesaj": "GET bekleniyor.", "taraf": "istemci", "kaynak": null, "tekrar_denenebilir": false, "tekrar_sn": null } } ``` ### 401 — Missing or invalid key (`yetkisiz`). ```json { "hata": "yetkisiz", "detay": "Geçerli X-API-Key başlığı gerekli (panel › API).", "hata_ayrinti": { "kod": "yetkisiz", "mesaj": "Geçerli X-API-Key başlığı gerekli (panel › API).", "taraf": "istemci", "kaynak": null, "tekrar_denenebilir": false, "tekrar_sn": null } } ``` ### 429 — Hourly rate limit exceeded (`hiz_siniri`); the Retry-After header gives the seconds until reset. Retry-After: `2494` ```json { "hata": "hiz_siniri", "detay": "Saatlik istek sınırı aşıldı (600). Bir sonraki saatte tekrar deneyin.", "hata_ayrinti": { "kod": "hiz_siniri", "mesaj": "Saatlik istek sınırı aşıldı (600). Bir sonraki saatte tekrar deneyin.", "taraf": "istemci", "kaynak": null, "tekrar_denenebilir": true, "tekrar_sn": 2494 } } ``` ### 500 — Unexpected error (`ic_hata`, taraf ulawk); retry shortly. Retry-After: `60` ```json { "hata": "ic_hata", "detay": "Beklenmeyen bir hata oluştu; kısa süre sonra yeniden deneyin.", "hata_ayrinti": { "kod": "ic_hata", "mesaj": "Beklenmeyen bir hata oluştu; kısa süre sonra yeniden deneyin.", "taraf": "ulawk", "kaynak": null, "tekrar_denenebilir": true, "tekrar_sn": 60 } } ``` ## Request ```bash curl "https://ulawk.com/api/v1/ara/?q=%C3%B6rnek+deneme&ulke=TR&adet=3" \ -H "X-API-Key: ulk_DENEME_ANAHTARINIZ" \ -H "X-API-Secret: ulsk_DENEME_GIZLI_ANAHTARINIZ" ```