API Anahtarları ve Programatik Erişim

Zaten bir CRM, dosya yönetim sistemi veya şirket içi bir portal kullanıyorsanız, her formu oluşturmak için panelde tek tek tıklamanız gerekmez. API anahtarları, backend’inizin DS160.io v1 API’sini doğrudan çağırmasını sağlar: form oluşturma, formları klonlama ve müşteri bağlantıları üretme işlemlerini kendi takviminize göre yapabilirsiniz.

API anahtarları kurumsal çalışma alanlarında kullanılabilir. Her anahtar tek bir çalışma alanına bağlıdır ve yalnızca o çalışma alanının içinde işlem yapabilir.

API temel URL’si

Tüm v1 uç noktalarının kökü şudur:

https://www.ds160.io/api/v1

Bu dokümanlar ajansınızın beyaz etiketli (white-label) alan adında barındırılıyor olabilir, ancak API çağrıları her zaman www.ds160.io adresine gider. Bu sayfadaki her kod örneği tam URL’yi kullanır; böylece yeniden yazmadan kopyalayıp yapıştırabilirsiniz.

Uç nokta referansı

/v1 kararlıdır: yollar ve alan adları, bir /v2 ana sürümü olmadan siz farkına varmadan değişmez (bkz. Sürüm yönetimi ve destek). Aşağıdaki tablodaki yollar, /workspaces/:workspaceId/ çalışma alanı önekine göre gösterilmiştir; istek ve yanıtların tam yapıları her uç noktanın kendi bölümünde açıklanmıştır.

Tüm gövdeler ve yanıtlar JSON biçimindedir. forms:read kapsamı form meta verilerine salt okunur erişim verir; forms:write hem okuma hem yazma izni verir, yani yalnızca yazma yapan bir anahtar da okuma erişimine ek bir şey yapmadan sahip olur.

1. API anahtarı oluşturun

Çalışma alanı ayarları → Ekip ve erişim → API anahtarları bölümünü açın ve API anahtarı oluştur düğmesine tıklayın. Açıklayıcı bir ad seçin (her entegrasyon için bir anahtar öneririz, ör. Production CRM veya Staging webhook handler), ardından entegrasyonun ihtiyaç duyduğu kapsamları seçin:

• forms:read: yalnızca form meta verilerini okuma (listeleme / getirme)
• forms:write: form oluşturma; okuma iznini de verir
• forms:clone: mevcut bir formu yeni bir forma kopyalama
• client-links:write: müşteri bağlantıları üretme

Anahtarları yalnızca çalışma alanının Sahipleri ve Yöneticileri oluşturabilir.

Anahtar oluştur düğmesine tıkladığınızda platform size tam gizli anahtarı bir kez gösterir. Bunu hemen gizli anahtar yöneticinize kopyalayın: bu pencere kapandıktan sonra yalnızca son dört karakter bir daha gösterilir. Bir anahtarı kaybederseniz onu iptal edin ve yeni bir anahtar oluşturun.

2. Kimlik doğrulayın

Tüm v1 uç noktaları bir Authorization: Bearer <secret> başlığı bekler.

export DS160_KEY="...the secret you just copied..."
export DS160_WORKSPACE="your-workspace-id"

curl https://www.ds160.io/api/v1/workspaces/$DS160_WORKSPACE/forms \
  -H "Authorization: Bearer $DS160_KEY"

const key = process.env.DS160_KEY;
const workspaceId = process.env.DS160_WORKSPACE;

const response = await fetch(`https://www.ds160.io/api/v1/workspaces/${workspaceId}/forms`, {
    headers: { Authorization: `Bearer ${key}` },
});
const { forms } = await response.json();

import os
import requests

key = os.environ["DS160_KEY"]
workspace_id = os.environ["DS160_WORKSPACE"]

response = requests.get(
    f"https://www.ds160.io/api/v1/workspaces/{workspace_id}/forms",
    headers={"Authorization": f"Bearer {key}"},
)
forms = response.json()["forms"]

Çalışma alanı kimliği, her panel sayfasının URL’sinde görünür (/workspaces/<workspaceId>/...). Anahtarın çalışma alanı sunucu tarafında bağlanır: başka bir çalışma alanının uç noktasını yanlış anahtarla çağırmak 403 Forbidden döndürür.

İpucu: dil sekmeleri bu sayfadaki tüm kod parçaları arasında senkronize olur. Dilinizi bir kez seçin, sayfanın geri kalanı da ona uyar.

3. Form oluşturun

curl -X POST https://www.ds160.io/api/v1/workspaces/$DS160_WORKSPACE/forms \
  -H "Authorization: Bearer $DS160_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Smith / B1 — 2026-05" }'
# → { "formId": "65f2…" }

const response = await fetch(
    `https://www.ds160.io/api/v1/workspaces/${workspaceId}/forms`,
    {
        method: "POST",
        headers: {
            Authorization: `Bearer ${key}`,
            "Content-Type": "application/json",
        },
        body: JSON.stringify({ name: "Smith / B1 — 2026-05" }),
    }
);
const { formId } = await response.json();

response = requests.post(
    f"https://www.ds160.io/api/v1/workspaces/{workspace_id}/forms",
    headers={
        "Authorization": f"Bearer {key}",
        "Content-Type": "application/json",
    },
    json={"name": "Smith / B1 — 2026-05"},
)
form_id = response.json()["formId"]

Her çağrı, faturalandırma planınızdan bir form kredisi kullanır (panelden form oluşturmakla aynı şekilde). Çalışma alanınızın kredisi kalmadıysa çağrı 402 Payment Required döndürür; yeniden denemeden önce kredi yükleyin.

İsteğe bağlı name alanı, form için okunabilir bir etiket belirler (en fazla 200 karakter). Otomatik oluşturulan bir ad almak için bu alanı göndermeyin; her iki durumda da formu daha sonra panelden yeniden adlandırabilirsiniz.

4. Mevcut bir formu klonlayın

Sık sık yeniden düzenlediğiniz bir şablon formunuz varsa (örneğin aynı işverenin J-1 programı), sıfırdan başlamak yerine onu klonlayın. Belirli form sayfalarını kopyanın dışında bırakmak için isteğe bağlı olarak disabledSections gönderebilirsiniz; listelediğiniz her şey yeni formda boş alanlarla değiştirilir, böylece müşteri o bölümleri baştan doldurur:

curl -X POST https://www.ds160.io/api/v1/workspaces/$DS160_WORKSPACE/forms/$SOURCE_FORM_ID/clone \
  -H "Authorization: Bearer $DS160_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "disabledSections": ["spouse-info-page", "security-background-page-5"] }'
# → { "formId": "65f3…" }

const response = await fetch(
    `https://www.ds160.io/api/v1/workspaces/${workspaceId}/forms/${sourceFormId}/clone`,
    {
        method: "POST",
        headers: {
            Authorization: `Bearer ${key}`,
            "Content-Type": "application/json",
        },
        body: JSON.stringify({
            disabledSections: ["spouse-info-page", "security-background-page-5"],
        }),
    }
);
const { formId } = await response.json();

response = requests.post(
    f"https://www.ds160.io/api/v1/workspaces/{workspace_id}/forms/{source_form_id}/clone",
    headers={
        "Authorization": f"Bearer {key}",
        "Content-Type": "application/json",
    },
    json={"disabledSections": ["spouse-info-page", "security-background-page-5"]},
)
form_id = response.json()["formId"]

Klonlama, yeni form oluşturmak gibi bir form kredisi kullanır.

Geçerli disabledSections değerleri

Her sayfayı kopyalamak için boş bir dizi gönderin (veya alanı hiç göndermeyin). Aksi takdirde aşağıdaki tanımlayıcıların herhangi bir birleşimini kullanın; başka herhangi bir değer 400 Bad Request döndürür.

Yalnızca formun vize kategorisiyle ilgili bölümler gerçekten bulunur; kaynak formda olmayan bir sayfayı listelemenin hiçbir etkisi olmaz.

5. Müşteri bağlantısı üretin

Bir form oluşturulduktan sonra, müşterinin formu doldurmak için kullanabileceği token içeren bir URL üretin:

curl -X POST https://www.ds160.io/api/v1/workspaces/$DS160_WORKSPACE/forms/$FORM_ID/client-links \
  -H "Authorization: Bearer $DS160_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "expiresInDays": 7, "defaultLanguage": "en" }'

const response = await fetch(
    `https://www.ds160.io/api/v1/workspaces/${workspaceId}/forms/${formId}/client-links`,
    {
        method: "POST",
        headers: {
            Authorization: `Bearer ${key}`,
            "Content-Type": "application/json",
        },
        body: JSON.stringify({ expiresInDays: 7, defaultLanguage: "en" }),
    }
);
const { url, token, expiresAt } = await response.json();

response = requests.post(
    f"https://www.ds160.io/api/v1/workspaces/{workspace_id}/forms/{form_id}/client-links",
    headers={
        "Authorization": f"Bearer {key}",
        "Content-Type": "application/json",
    },
    json={"expiresInDays": 7, "defaultLanguage": "en"},
)
link = response.json()
# link["url"], link["token"], link["expiresAt"]

İstek gövdesi

Örnek yanıt (200 OK)

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI2NmMxYmQ0ZjZmNGFkNTQwMzMxNDhmYmEiLCJmb3JtSWQiOiI2NWYyYTkxMTNkZjAxYzAwMTI3YjY4MmEiLCJ3b3Jrc3BhY2VJZCI6IjY1ZjJhOTAwM2RmMDFjMDAxMjdiNjgwYSIsImV4cCI6MTc0ODA0ODI0NywiaWF0IjoxNzQ3NDQzNDQ3LCJkZWZhdWx0TGFuZ3VhZ2UiOiJlbiIsImhpZGVCcmFuZGluZyI6ZmFsc2V9.SiGNATuRe",
    "url": "https://intake.your-agency.com/client-intake/65f2a9113df01c00127b682a?token=eyJhbGciOi…",
    "shortUrl": "https://intake.your-agency.com/c/Ab3dE7gH9jKm?s=api",
    "expiresAt": "2026-05-24T01:50:46.000Z"
}

url adresini müşterinize gönderin. URL’deki token tek amaçlıdır ve expiresAt anında süresi dolar; müşterinin formu doldurması için başka bir kimlik doğrulama gerekmez. Dilerseniz aynı bağlantıyı açan shortUrl adresini de gönderebilirsiniz.

Müşteri bağlantısını iptal etme

Verilmiş müşteri bağlantılarını iptal etmek için bir v1 uç noktası yoktur; iptali panelden yapın (Çalışma alanı → Form → Paylaşım → Bağlantıyı iptal et). İptal anında ve kalıcı olarak geçerli olur: bağlantının yaptığı bir sonraki istek 401 döndürür. Bir sızıntıdan şüpheleniliyorsa ve arayüzden iptal edebilecek kimse yoksa, en güvenli geri dönüş yolu bağlantının süresinin dolmasını beklemektir (expiresInDays değerini buna göre sınırlayın).

Geçerli defaultLanguage değerleri

defaultLanguage, alıcı bağlantıyı ilk açtığında müşteri arayüzünün dilini belirler. Aşağıdaki kodlardan herhangi birini kullanın; başka herhangi bir değer 400 Bad Request döndürür. Kısa kodlar (en, cn, …) DS160.io’nun dahili dil tanımlayıcılarıdır; BCP-47 sütunu <html lang>, hreflang ve Intl.* API’lerinde kullandığımız değeri gösterir. API isteklerinde kısa kodu kullanın; BCP-47 biçimi bilgi amaçlıdır.

Müşteri bağlantılarını şifre gibi koruyun

url bir taşıyıcı (bearer) kimlik bilgisidir: elinde bulunduran herkes, süresi dolana kadar ikinci bir doğrulama adımı olmadan formu doldurabilir.

• Güvenilir bir kanal üzerinden gönderin; sızabileceği yerlerde paylaşmayın (herkese açık sohbetler, arama motorlarında dizinlenen sayfalar, paylaşılan paketler).
• Günlüklerde ?token= değerini maskeleyin. Yalnızca jti claim’ini günlüğe yazmak güvenlidir.
• Sızıntıdan şüphelendiğinizde iptal edin; iptal anında ve kalıcı olarak geçerli olur.
• expiresInDays bir dengedir: daha kısa = daha küçük sızıntı penceresi, daha uzun = daha az yeniden bağlantı üretme zahmeti.

6. Formları listeleyin veya getirin

# All forms in the workspace
curl https://www.ds160.io/api/v1/workspaces/$DS160_WORKSPACE/forms \
  -H "Authorization: Bearer $DS160_KEY"

# A single form by id
curl https://www.ds160.io/api/v1/workspaces/$DS160_WORKSPACE/forms/$FORM_ID \
  -H "Authorization: Bearer $DS160_KEY"

// All forms in the workspace
const listResponse = await fetch(`https://www.ds160.io/api/v1/workspaces/${workspaceId}/forms`, {
    headers: { Authorization: `Bearer ${key}` },
});
const { forms } = await listResponse.json();

// A single form by id
const formResponse = await fetch(`https://www.ds160.io/api/v1/workspaces/${workspaceId}/forms/${formId}`, {
    headers: { Authorization: `Bearer ${key}` },
});
const form = await formResponse.json();

# All forms in the workspace
forms = requests.get(
    f"https://www.ds160.io/api/v1/workspaces/{workspace_id}/forms",
    headers={"Authorization": f"Bearer {key}"},
).json()["forms"]

# A single form by id
form = requests.get(
    f"https://www.ds160.io/api/v1/workspaces/{workspace_id}/forms/{form_id}",
    headers={"Authorization": f"Bearer {key}"},
).json()

Bu okuma uç noktaları forms:read (salt okunur) veya forms:write (okuma iznini de verir) kapsamını kabul eder.

Sayfalama

GET /v1/workspaces/:workspaceId/forms sayfalıdır. Sonuçlar arasında ilerlemek için ?limit= ve ?cursor= sorgu parametrelerini gönderin:

Her yanıt bir nextCursor alanı içerir. Başka sayfa kalmadığında nextCursor değeri null olur. Örnek:

{
    "forms": [
        { "id": "65f2a911…", "name": "Smith / B1", "status": "in_progress", "workspaceId": "65f2a900…", "userId": "65f2a8f0…", "preferredConsulate": null, "createdAt": "2026-05-14T09:12:33.000Z", "archivedAt": null },
        { "id": "65f2a8a3…", "name": "Garcia / F1", "status": "completed", "workspaceId": "65f2a900…", "userId": "65f2a8f0…", "preferredConsulate": "MAD", "createdAt": "2026-05-13T18:01:09.000Z", "archivedAt": null }
    ],
    "nextCursor": "65f2a8a3…"
}

Bir sonraki istekte ?cursor=65f2a8a3…&limit=50 göndererek ilerleyin. Formlar id’ye göre en yeniden eskiye sıralanır; bu nedenle çağrılar arasında yeni formlar oluşturulsa bile cursor okuma konumunuzu sabitler: yinelenen kayıt görmezsiniz ve sayfalamaya başladığınız anda var olan hiçbir şeyi kaçırmazsınız.

Formun status değerleri

Her form meta verisi yanıtındaki status alanı şunlardan biridir:

Aktarım biçimi alt çizgi kullanır (in-progress değil, in_progress). Yukarıdaki dizelerle olduğu gibi karşılaştırma yapmak her zaman çalışır.

API üzerinden kişisel verilere (PII) erişim

v1 form meta verisi uç noktaları (GET /workspaces/:workspaceId/forms ve GET /workspaces/:workspaceId/forms/:formId) yalnızca operasyonel meta verileri döndürür: id, name, status, workspaceId, userId, preferredConsulate, createdAt, archivedAt ve tek form uç noktasında applicantConsent (onay isteyen bir bağlantıda müşterinin en son onayı: acceptedAt, withdrawnAt ve noticeVersion ya da null). Bu uç noktalar başvuru sahibinin cevaplarını göstermez: adlar, doğum tarihleri, pasaport numaraları, seyahat geçmişi veya başka herhangi bir DS-160 alanı /v1 üzerinden erişilebilir değildir.

Tamamlanmış DS-160 PDF’lerine ve tüm alan verilerine yalnızca panel üzerinden, başvuru sahibinin denetim kaydı tutulan sahibi altında erişilebilir. Entegrasyonunuzun başvuru sahibinin girdiği verileri okuması gerekiyorsa bunu kendi müşteri bilgi toplama akışınız üzerinden yapın (önce CRM’iniz verileri toplar, siz de bunları DS160.io’ya aktarırsınız); API’nin bu verileri size geri vereceğini asla varsaymayın.

Hız sınırları

Her anahtar dakikada 60 istekle sınırlıdır. Her yanıt şunları içerir:

Sınırı aşarsanız API, Retry-After başlığıyla birlikte 429 Too Many Requests döndürür. Entegrasyonunuzun gerçekten daha yüksek bir sınıra ihtiyacı varsa destek ekibiyle iletişime geçin; belirli anahtarlar için sınırı yükseltebiliriz.

Yeniden denemeler ve idempotans

v1 API bir Idempotency-Key başlığını desteklemez. Somut olarak:

• POST /forms ve POST /forms/:formId/clone idempotent değildir ve her çağrıda bir form kredisi kullanır. Bir ağ zaman aşımından sonra yapılan düşüncesiz bir yeniden deneme, yinelenen bir form oluşturur ve ikinci bir krediyi harcar.
• POST /forms/:formId/client-links da idempotent değildir ancak kredi kullanmaz: yeniden denenen bir çağrı yalnızca kendi jti ve expiresAt değerlerine sahip ikinci bir bağlantı üretir.
• Tüm GET uç noktaları serbestçe yeniden denenebilir.

Oluşturma/klonlama için önerilen yeniden deneme yöntemi: bir POST /forms (veya /clone) çağrısı zaman aşımına uğrarsa ya da 5xx döndürürse körü körüne yeniden denemeyin. Bunun yerine GET /workspaces/:workspaceId/forms çağrısını yapın (formlar en yeniden eskiye sıralanır) ve gönderdiğiniz name ile son birkaç saniye içinde bir form oluşturulup oluşturulmadığını kontrol edin. Oluşturulduysa ilk çağrıyı başarılı sayın ve yeniden denemeyi atlayın. Oluşturulmadıysa ilk yazma işlemi kesinlikle gerçekleşmemiştir ve yeniden denemek güvenlidir.

İleriki bir ara sürümde Idempotency-Key desteği ekleyebiliriz; entegrasyonlar buna hazırlıklı olmalı ancak bugün buna güvenmemelidir.

Bir anahtarı iptal etme

Bir anahtar sızdırıldıysa, kullanım ömrü dolduysa veya yalnızca kullanılmıyorsa, onu Çalışma alanı ayarları → Ekip ve erişim → API anahtarları → İptal et bölümünden iptal edin. İptal hemen geçerli olur: anahtarın yaptığı bir sonraki istek 401 Unauthorized döndürür. İptal edilen anahtarlar denetim amacıyla listede kalır ancak yeniden etkinleştirilemez; entegrasyonun çalışmaya devam etmesi gerekiyorsa yeni bir anahtar oluşturun.

En iyi uygulamalar

• Her entegrasyon için bir anahtar. Bir sistem devreden çıkarıldığında hedefli olarak iptal etmek daha kolaydır ve paneldeki Son kullanım sütunu hangi entegrasyonların hâlâ etkin olduğunu gösterir.
• En az kapsam. Yalnızca müşteri bağlantısı üreten bir anahtarda forms:clone olmamalıdır. Daha dar kapsamlar, gizli anahtar sızarsa daha küçük bir hasar alanı demektir.
• Gizli anahtarları bir kasada saklayın. Bunları asla kaynak kod deposuna eklemeyin veya bir frontend paketine gömmeyin; aksi halde her tarayıcı sekmesi onları açığa çıkarır.
• Düzenli olarak yenileyin. Yeni bir anahtar oluşturun, entegrasyonu ona geçirin, ardından eskisini iptal edin. Panel bir anahtarın en son ne zaman kullanıldığını gösterir; böylece iptal etmeden önce geçişin tamamlandığını doğrulayabilirsiniz.

Hatalar

2xx dışındaki tüm yanıtlar aynı JSON yapısını paylaşır:

{ "error": "human-readable message" }

error değeri bir dizedir. Şema doğrulamasından gelen 400 Bad Request için bu, ihlal edilen her kısıtlamayı açıklayan serileştirilmiş bir JSON dizisidir; diğer tüm durumlarda doğrudan gösterebileceğiniz veya günlüğe yazabileceğiniz kısa bir mesajdır.

Uçtan uca örnek

curl kullanan eksiksiz bir bilgi toplama akışı: form oluşturun, müşteri bağlantısı üretin, gönderin ve tamamlanmasını yoklayın. Gerçek entegrasyonlar kendi HTTP istemcilerini kullanır; yapı her dilde aynıdır.

# 0. credentials (set once)
export DS160_KEY="..."
export DS160_WORKSPACE="65f2a900..."

# 1. Create a form. Capture the formId from the response.
FORM_ID=$(curl -s -X POST \
  https://www.ds160.io/api/v1/workspaces/$DS160_WORKSPACE/forms \
  -H "Authorization: Bearer $DS160_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Smith / B1 — 2026-05" }' \
  | jq -r .formId)

# 2. Mint a client intake link valid for 14 days.
LINK_JSON=$(curl -s -X POST \
  https://www.ds160.io/api/v1/workspaces/$DS160_WORKSPACE/forms/$FORM_ID/client-links \
  -H "Authorization: Bearer $DS160_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "expiresInDays": 14, "defaultLanguage": "en" }')

CLIENT_URL=$(echo "$LINK_JSON" | jq -r .url)

# 3. Send $CLIENT_URL to the applicant through your usual channel
#    (email, secure portal, etc.). The applicant fills in the form.

# 4. Poll for completion. Status transitions:
#    not_started → in_progress → completed
curl -s https://www.ds160.io/api/v1/workspaces/$DS160_WORKSPACE/forms/$FORM_ID \
  -H "Authorization: Bearer $DS160_KEY" \
  | jq .status
# → "completed" when the applicant has finished

# 5. Download the DS-160 PDF from the dashboard
#    (no v1 endpoint for this today).

Bu örnekle ilgili birkaç not:

• Yoklama sıklığı: 5–15 dakikada bir fazlasıyla yeterlidir. Dakikada 60 isteklik sınırla tek bir anahtar, işlemdeki binlerce formu rahatça yoklayabilir.
• Webhook’lar henüz kullanılamıyor. Tamamlanma için anlık bildirimlere ihtiyacınız varsa bu sayfayı takip edin veya destek ekibiyle iletişime geçin; yol haritamızda yer alıyor.
• 5. adım (tamamlanmış PDF’i indirmek) bugün için bir panel oturumu gerektirir. v1 API, başvuru sahibinin cevaplarını bilerek göstermez; bkz. API üzerinden kişisel verilere (PII) erişim.

Sürüm yönetimi ve destek

Kararlılık. /v1 kararlı API yüzeyidir. /v1 içinde ana sürümü yükseltmeden yeni isteğe bağlı alanlar, yeni uç noktalar ve yeni enum değerleri ekleriz; ancak mevcut hiçbir alanın adını değiştirmez, onu kaldırmaz veya türünü değiştirmeyiz. Bir gün geriye dönük uyumsuz bir değişiklik gerekirse bu değişiklik /v2 altında yayımlanır ve /v1 onunla birlikte en az 12 ay çalışmaya devam eder.

Hazırlıklı olmanız gereken geriye dönük uyumlu eklemeler:

• Zamanla yeni isteğe bağlı istek alanları eklenecektir. Bunları göndermeyen mevcut istekler çalışmaya devam eder.
• Yeni yanıt alanları eklenebilir. Bilinmeyen alanları yok sayılabilir kabul edin; ileride yeni bir alan çıkarsa isteği başarısız saymayın.
• status, defaultLanguage ve disabledSections için yeni enum değerleri eklenecektir. Bilinmeyen değerlerde çökmeyin; günlüğe yazın ve devam edin.

Destek:

• Daha yüksek hız sınırları, özel alan adları, webhook erken erişimi ve entegrasyon soruları için: hesap yöneticinizle veya support@ds160.io adresiyle iletişime geçin.
• v1 API’ye yönelik hata bildirimleri: aynı adres. Her yanıt bir x-request-id başlığı içerir; çağrıyı günlüklerimizde tam olarak bulabilmemiz için bunu bildiriminize ekleyin.