REST API Referansı

Genel Bakış

LeadHub, harici araçların verilerinizi (lead'ler, pipeline'lar, otomasyonlar, formlar ve daha fazlası) okumasına ve yazmasına olanak tanıyan eksiksiz bir REST API içerir. Zapier ile entegrasyon, özel panolar oluşturma, web sitenizi bağlama veya herhangi bir şeyi otomatikleştirme için kullanın.

---

Temel URL

Tüm API istekleri şu adrese gönderilir:

https://yourdomain.com/api/v1

yourdomain.com yerine gerçek LeadHub alan adınızı yazın.

---

Kimlik Doğrulama

Her istek (health check hariç) bir API anahtarı gerektirir.

API anahtarlarını yönetici panelinde Ayarlar → API Anahtarları bölümünden oluşturun. Talimatlar için Ayarlar sayfasına bakın.

Her istekte Authorization başlığında Bearer token olarak API anahtarınızı ekleyin:

Authorization: Bearer lh_your_api_key_here

API anahtarı olmadan veya geçersiz bir anahtarla istek gönderirseniz 401 Unauthorized yanıtı alırsınız.

---

Hız Sınırlaması

Her API anahtarı varsayılan olarak saatte 1.000 istekle sınırlıdır (anahtar başına yapılandırılabilir). Bu sınırı aşarsanız 429 Too Many Requests yanıtı alırsınız.

Her yanıt, kullanımınızı takip etmenize yardımcı olacak şu başlıkları içerir:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1711580400

X-RateLimit-Reset, sınırınızın sıfırlanacağı Unix zaman damgasıdır.

---

Sayfalama

Kayıt listesi döndüren uç noktalar sayfalamayı destekler. Şu sorgu parametrelerini ekleyin:

Parametre	Varsayılan	Maksimum
page	1	—
per_page	15	100

Örnek: GET /api/v1/leads?page=2&per_page=25

---

Yanıt Formatı

Başarılı Yanıt

{
  "data": { ... },
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 15,
    "total": 73,
    "from": 1,
    "to": 15
  },
  "links": {
    "first": "https://yourdomain.com/api/v1/leads?page=1",
    "last": "https://yourdomain.com/api/v1/leads?page=5",
    "prev": null,
    "next": "https://yourdomain.com/api/v1/leads?page=2",
    "self": "https://yourdomain.com/api/v1/leads?page=1"
  }
}

Tek kayıt yanıtlarında (show, create, update) data kayıt nesnesini içerir ve meta atlanır.

Hata Yanıtı

{
  "status": "error",
  "message": "The given data was invalid.",
  "code": "VALIDATION_FAILED",
  "errors": {
    "email": ["The email field must be a valid email address."]
  }
}

Yaygın hata kodları:

Kod	HTTP Durumu	Anlam
UNAUTHORIZED	401	API anahtarı eksik veya geçersiz
FORBIDDEN	403	API anahtarında gerekli kapsam yok
NOT_FOUND	404	Kayıt mevcut değil
VALIDATION_FAILED	422	İstek verisi doğrulamayı geçemedi
RATE_LIMITED	429	Çok fazla istek
SERVER_ERROR	500	Beklenmedik sunucu hatası

---

Sağlık Kontrolü

Kimlik doğrulama gerekmez.

GET /api/v1/health

Yanıt:

{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "2026-03-28T09:15:00+00:00"
}

Diğer istekleri yapmadan önce LeadHub örneğinizin erişilebilir olup olmadığını kontrol etmek için kullanın.

---

Lead'ler

Gerekli kapsam: Almak için read:leads, oluşturmak/güncellemek için write:leads, silmek için delete:leads.

Lead'leri Listele

GET /api/v1/leads

Filtreleme sorgu parametreleri:

Parametre	Açıklama
source	Kaynağa göre filtrele (örn. facebook, website)
status	Duruma göre filtrele (örn. new, contacted, qualified)
pipeline_id	Pipeline ID'ye göre filtrele
stage_id	Pipeline aşaması ID'ye göre filtrele
assigned_user_id	Atanan kullanıcı ID'ye göre filtrele
tag	Etiket adına göre filtrele
search	Ad, e-posta veya telefona göre ara
created_after	ISO 8601 tarihi — bu tarihten sonra oluşturulan lead'ler
created_before	ISO 8601 tarihi — bu tarihten önce oluşturulan lead'ler
starred	true — yalnızca yıldızlı lead'leri göster
sort	Sıralama alanı: created_at, updated_at, lead_score, first_name, last_name, email
direction	asc veya desc (varsayılan: desc)

Lead Al

GET /api/v1/leads/{id}

Lead Oluştur

POST /api/v1/leads

İstek gövdesi (JSON):

{
  "first_name": "Sarah",
  "last_name": "Johnson",
  "email": "[email protected]",
  "phone": "+14155551234",
  "source": "website",
  "status": "new",
  "pipeline_id": 1,
  "pipeline_stage_id": 2,
  "assigned_user_id": 5,
  "notes": "Interested in the enterprise plan.",
  "custom_fields": {
    "budget": "10000"
  },
  "tags": ["hot-lead", "enterprise"]
}

first_name zorunludur. Diğer tüm alanlar isteğe bağlıdır.

Lead Güncelle

PUT /api/v1/leads/{id}
PATCH /api/v1/leads/{id}

Yalnızca güncellemek istediğiniz alanları gönderin. Oluşturmayla aynı alanlar.

Lead Sil

DELETE /api/v1/leads/{id}

Lead'e Etiket Ekle

POST /api/v1/leads/{id}/tags

Gövde: { "tag": "vip-client" }

Lead'den Etiket Kaldır

DELETE /api/v1/leads/{id}/tags/{tag}

---

Pipeline'lar

Gerekli kapsam: read:pipelines veya write:pipelines

GET    /api/v1/pipelines
POST   /api/v1/pipelines
GET    /api/v1/pipelines/{id}
PUT    /api/v1/pipelines/{id}
PATCH  /api/v1/pipelines/{id}
DELETE /api/v1/pipelines/{id}

Pipeline Aşamaları

GET    /api/v1/pipelines/{pipeline_id}/stages
POST   /api/v1/pipelines/{pipeline_id}/stages
GET    /api/v1/pipelines/{pipeline_id}/stages/{stage_id}
PUT    /api/v1/pipelines/{pipeline_id}/stages/{stage_id}
PATCH  /api/v1/pipelines/{pipeline_id}/stages/{stage_id}
DELETE /api/v1/pipelines/{pipeline_id}/stages/{stage_id}

---

Etiketler (Tags)

Gerekli kapsam: read:tags veya write:tags

GET    /api/v1/tags
POST   /api/v1/tags
GET    /api/v1/tags/{id}
PUT    /api/v1/tags/{id}
PATCH  /api/v1/tags/{id}
DELETE /api/v1/tags/{id}

---

Kullanıcılar (Users)

Gerekli kapsam: read:users, write:users veya delete:users

GET    /api/v1/users
POST   /api/v1/users
GET    /api/v1/users/{id}
PUT    /api/v1/users/{id}
PATCH  /api/v1/users/{id}
DELETE /api/v1/users/{id}

---

Formlar (Forms)

Gerekli kapsam: read:forms, write:forms veya delete:forms

GET    /api/v1/forms
POST   /api/v1/forms
GET    /api/v1/forms/{id}
PUT    /api/v1/forms/{id}
PATCH  /api/v1/forms/{id}
DELETE /api/v1/forms/{id}

Form Gönder

POST /api/v1/forms/{id}/submissions

Gövde: form alan değerlerini anahtar-değer çiftleri olarak gönderin.

---

Otomasyonlar (Automations)

Gerekli kapsam: read:automations, write:automations veya delete:automations

GET    /api/v1/automations
POST   /api/v1/automations
GET    /api/v1/automations/{id}
PUT    /api/v1/automations/{id}
PATCH  /api/v1/automations/{id}
DELETE /api/v1/automations/{id}

---

Entegrasyonlar (Integrations)

Gerekli kapsam: read:integrations veya write:integrations

GET    /api/v1/integrations/types
GET    /api/v1/integrations
POST   /api/v1/integrations
GET    /api/v1/integrations/{id}
PUT    /api/v1/integrations/{id}
PATCH  /api/v1/integrations/{id}
DELETE /api/v1/integrations/{id}

GET /api/v1/integrations/types mevcut entegrasyon türlerinin listesini döndürür (Facebook, Google Ads, Mailgun, vb.).

---

Gelen Lead Alımı

Harici kaynaklardan, webhook'lardan veya Zapier ve Make gibi kodsuz araçlardan lead oluşturmak için basitleştirilmiş bir uç nokta.

POST /api/inbound/leads?tenant={workspace-slug}

Authorization: Bearer {api_key} ile kimlik doğrulayın ve çalışma alanı slug'ını sorgu parametresi olarak geçin.

İstek gövdesi:

{
  "email": "[email protected]",
  "first_name": "Sarah",
  "last_name": "Johnson",
  "phone": "+14155551234",
  "company": "Tech Corp",
  "source": "zapier",
  "notes": "Came from newsletter signup",
  "tags": ["newsletter"],
  "custom_fields": {
    "utm_campaign": "spring-promo"
  }
}

email zorunludur. Diğer tüm alanlar isteğe bağlıdır.

Başarılı yanıt (201):

{
  "status": "created",
  "lead_id": 1842,
  "is_duplicate": false
}

Lead zaten mevcutsa (e-posta veya telefonla eşleşme), is_duplicate true olur ve mevcut lead'in ID'si döndürülür.

---

Kod Örnekleri

cURL

curl -X GET "https://yourdomain.com/api/v1/leads?status=new&per_page=25" \
  -H "Authorization: Bearer lh_your_api_key_here" \
  -H "Accept: application/json"

curl -X POST "https://yourdomain.com/api/v1/leads" \
  -H "Authorization: Bearer lh_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Sarah","email":"[email protected]","source":"api"}'

PHP

$apiKey = 'lh_your_api_key_here';
$baseUrl = 'https://yourdomain.com/api/v1';

// List leads
$response = file_get_contents($baseUrl . '/leads', false, stream_context_create([
    'http' => [
        'header' => "Authorization: Bearer {$apiKey}\r\nAccept: application/json\r\n",
    ],
]));
$leads = json_decode($response, true);

// Create a lead
$ch = curl_init($baseUrl . '/leads');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer {$apiKey}",
    "Content-Type: application/json",
    "Accept: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'first_name' => 'Sarah',
    'email'      => '[email protected]',
    'source'     => 'api',
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

JavaScript (fetch)

const apiKey = 'lh_your_api_key_here';
const baseUrl = 'https://yourdomain.com/api/v1';

// List leads
const response = await fetch(`${baseUrl}/leads?status=new`, {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Accept': 'application/json',
  },
});
const { data, meta } = await response.json();

// Create a lead
const createResponse = await fetch(`${baseUrl}/leads`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
    'Accept': 'application/json',
  },
  body: JSON.stringify({
    first_name: 'Sarah',
    email: '[email protected]',
    source: 'website',
  }),
});
const newLead = await createResponse.json();