Public API — Kontaklar

Bir web formu, reklam ya da CRM’den gelen kişiyi tek bir POST çağrısıyla Purvisor AI’ya taşırsın — üstelik aynı numarayı iki kez göndersen bile çift kayıt oluşmaz. /contacts uçları tam olarak Zapier ve Make’in “Create Contact” ve “Find Contact” adımlarını besleyen uçlardır: idempotent oluşturma (aynı telefon → mevcut kaydı döndürür) ve dizi döndüren arama (bulunamazsa 404 değil, boş dizi). Bu yüzden entegrasyon akışların “zaten var mı?” kontrolüyle uğraşmadan güvenle çalışır.

POST /contacts — Kontak oluştur (veya mevcut olanı döndür)

Yeni bir kontak yaratır. Ama önce telefona bakar: aynı kişi zaten varsa yeni kayıt açmaz, var olanı döndürür ve yanıta existing: true koyar. Bunu bir “getir-veya-oluştur” musluğu gibi düşün — kaç kez akıtırsan akıt, kişi bir tane kalır.

• Yeni kontak → HTTP 201, existing: false, source: "zapier", status: "new".
• Mevcut kontak bulundu → HTTP 200, existing: true (mevcut kaydın alanlarıyla).
• Kota dolu → HTTP 403, code: "quota_exceeded". Planının kişi adedi kotası dolduğunda kayıt açılmaz.

Dedupe nasıl çalışır?

Telefon numarası tam eşleşme veya son 10 hane substring eşleşmesiyle karşılaştırılır. Yani +90 532 111 22 33 ile 05321112233 aynı kişi sayılır (analiz: son-10-hane import dedupe mantığıyla birebir aynı). Bu, formdan 0532... gelirken CRM’inde +90532... duran numaraların yanlışlıkla ikiye bölünmesini önler.

Telefon en az 10 hane içermelidir; aksi halde uç 400 döner. Son-10-hane eşleşmesi için de en az 7 hane gerekir.

İstek gövdesi

Alanlar hem snake_case hem camelCase kabul edilir (örn. first_name veya firstName).

Yanıt şeması (serializeContact)

Hem POST hem GET, kontağı aynı düz şemayla döndürür; POST ayrıca bir existing bayrağı ekler.

Örnek — yeni kontak

curl -X POST https://app.purvisor.ai/api/v1/contacts \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Ayşe",
    "last_name": "Yılmaz",
    "phone": "+905321112233",
    "email": "ayse@ornek.com",
    "company": "Örnek A.Ş.",
    "title": "Satın Alma Müdürü"
  }'

HTTP 201 Created:

{
  "id": "48213",
  "first_name": "Ayşe",
  "last_name": "Yılmaz",
  "name": "Ayşe Yılmaz",
  "phone": "+905321112233",
  "email": "ayse@ornek.com",
  "company": "Örnek A.Ş.",
  "title": "Satın Alma Müdürü",
  "status": "new",
  "stage": "new",
  "lead_score": 0,
  "heat": "cold",
  "source": "zapier",
  "created_at": "2026-07-12T09:14:00.000Z",
  "existing": false
}

Örnek — aynı numara ikinci kez gönderilirse

Aynı telefonu (farklı biçimde bile olsa) tekrar gönderirsen yeni kayıt açılmaz; mevcut kayıt HTTP 200 ile existing: true olarak döner:

{
  "id": "48213",
  "first_name": "Ayşe",
  "last_name": "Yılmaz",
  "name": "Ayşe Yılmaz",
  "phone": "+905321112233",
  "status": "new",
  "stage": "new",
  "lead_score": 0,
  "heat": "cold",
  "source": "zapier",
  "created_at": "2026-07-12T09:14:00.000Z",
  "existing": true
}

GET /contacts — Kontak bul

Var olan kontakları arar. Zapier/Make “search” adımlarının beklediği gibi her zaman bir dizi döndürür — eşleşme yoksa boş dizi ([]) döner, asla 404 değil. phone veya search parametrelerinden en az biri zorunludur; ikisi de yoksa uç 400 döner.

phone ve search birlikte verilirse phone önceliklidir. Sonuçlar created_at alanına göre en yeniden en eskiye sıralanır.

Örnek — telefonla arama

curl "https://app.purvisor.ai/api/v1/contacts?phone=05321112233" \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

HTTP 200 OK — bir kontak dizisi:

[
  {
    "id": "48213",
    "first_name": "Ayşe",
    "last_name": "Yılmaz",
    "name": "Ayşe Yılmaz",
    "phone": "+905321112233",
    "email": "ayse@ornek.com",
    "company": "Örnek A.Ş.",
    "title": "Satın Alma Müdürü",
    "status": "new",
    "stage": "new",
    "lead_score": 0,
    "heat": "cold",
    "source": "zapier",
    "created_at": "2026-07-12T09:14:00.000Z"
  }
]

Örnek — metinle arama

curl "https://app.purvisor.ai/api/v1/contacts?search=Örnek%20A.%C5%9E.&limit=50" \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Eşleşme yoksa yanıt boş dizidir:

[]

Sorun giderme

İlgili