Kişi oluştur veya güncelle (upsert)


POST https://app.apsilo.com/api/public/v1/contacts

identities içindeki kimliklerden biri mevcut bir kişideyse o kişi güncellenir (200, created:false); yoksa yeni kişi oluşturulur (201, created:true). Etiket adları yoksa oluşturulur. Kimlikler farklı kişilere aitse 409 CONFLICT.

Gerekli kapsam: contacts:write

Parametreler

Parametre	Yer	Tip	Gereklilik	Açıklama
`Idempotency-Key`	başlık	string	isteğe bağlı	İsteğe özgü benzersiz değer (1–255 yazdırılabilir ASCII; ör. UUID). Aynı anahtar + aynı yol ve gövde 24 saat içinde kaydedilmiş yanıtı döner (`Idempotent-Replayed: true`); farklı gövde veya işlenmekte olan istek `409 IDEMPOTENCY_CONFLICT`. Hata yanıtları saklanmaz.
`X-Request-Id`	başlık	string	isteğe bağlı	İsteğe bağlı istek kimliğiniz (8–100 karakter: harf, rakam, `._:-`); yanıtta aynen döner ve kayıtlara işlenir.

İstek gövdesi

Alan	Tip	Gereklilik	Açıklama
`firstName`	string \| null	isteğe bağlı
`lastName`	string \| null	isteğe bağlı
`city`	string \| null	isteğe bağlı
`country`	string \| null	isteğe bağlı
`identities`	object[]	zorunlu	Eşleştirme anahtarları: bu kimliklerden biri mevcut bir kişideyse o kişi güncellenir. WhatsApp: telefon, e-posta: adres, Instagram/X/TikTok/Telegram: kullanıcı kimliği veya `@kullanıcıadı` (bekleyen kimlik).
`customFields`	object	isteğe bağlı	Özel alan anahtarı → değer (`GET /custom-fields`)
`tags`	string[]	isteğe bağlı	Eklenecek etiket adları (yoksa oluşturulur)
`optIn`	boolean	isteğe bağlı	Kimliklerin pazarlama/kampanya izni


{
  "firstName": "Ayşe",
  "lastName": "Yılmaz",
  "city": "İzmir",
  "country": "Türkiye",
  "identities": [
    {
      "channel": "whatsapp",
      "value": "+905321234567"
    },
    {
      "channel": "email",
      "value": "ayse.yilmaz@example.com"
    }
  ],
  "customFields": {
    "musteri_no": "C-10482"
  },
  "tags": [
    "VIP",
    "E-ticaret"
  ],
  "optIn": true
}

Yanıtlar

Durum	Açıklama
`200`	Mevcut kişi güncellendi
`201`	Kişi oluşturuldu
`401`	Kimlik doğrulanamadı. Olası kodlar: `API_KEY_INVALID`, `API_KEY_REVOKED`, `API_KEY_EXPIRED`.
`403`	Erişim reddedildi. Olası kodlar: `FEATURE_NOT_LICENSED`, `API_SCOPE_MISSING`, `IP_NOT_ALLOWED`, `LICENSE_EXPIRED`, `LICENSE_NOT_FOUND`, `FORBIDDEN`.
`409`	Çakışma. Olası kodlar: `CONFLICT`, `IDEMPOTENCY_CONFLICT`, `MEDIA_IN_USE`, `SOCIAL_APPROVAL_REQUIRED`, `SOCIAL_POST_NOT_EDITABLE`.
`422`	İşlenemeyen istek. Olası kodlar: `VALIDATION_FAILED`, `MESSAGING_WINDOW_CLOSED`, `CHANNEL_ACCOUNT_MISSING`, `CONTACT_BLOCKED`, `STORAGE_LIMIT_REACHED`, `SOCIAL_POST_INVALID`, `SOCIAL_PLATFORM_UNAVAILABLE`.
`429`	Hız sınırı aşıldı. Olası kodlar: `RATE_LIMITED`.
`500`	Sunucu hatası. Olası kodlar: `INTERNAL`.

Yanıt gövdesi

Alan	Tip	Gereklilik	Açıklama
`data`	ContactUpsertResult	zorunlu