APIキーとプログラムによるアクセス

すでにCRM、案件管理システム、社内ポータルを運用している場合、フォームを1件作成するたびにダッシュボードを操作する必要はありません。APIキーを使うと、自社のバックエンドからDS160.ioのv1 APIを直接呼び出し、フォームの作成、複製、クライアント情報入力リンクの生成を、自社のスケジュールで行えます。

APIキーはビジネスワークスペースで利用できます。各キーは1つのワークスペースに紐づいており、そのワークスペース内でのみ操作できます。

APIのベースURL

すべてのv1エンドポイントのルートは次のとおりです。

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

このドキュメントは代行会社のホワイトラベルドメインで公開されている場合がありますが、APIの呼び出し先は常にwww.ds160.ioです。このページのコードサンプルはすべて完全なURLを使っているため、書き換えずにそのままコピー＆ペーストできます。

エンドポイントリファレンス

/v1は安定版です。メジャーバージョン/v2を出さない限り、パスやフィールド名が予告なく変わることはありません（バージョン管理とサポートを参照）。下の表のパスはワークスペースのプレフィックス/workspaces/:workspaceId/からの相対パスで示しています。リクエストとレスポンスの完全な形式は、各エンドポイントのセクションで説明しています。

ボディとレスポンスはすべてJSONです。forms:readスコープはフォームのメタデータへの読み取り専用のアクセスを付与します。forms:writeは読み取りと書き込みの両方を付与するため、書き込みしか行わないキーでも追加の設定なしで読み取りができます。

1. APIキーを作成する

ワークスペース設定 → チームとアクセス → APIキーを開き、APIキーを作成をクリックします。わかりやすい名前を付け（連携ごとに1つのキーをおすすめします。例：Production CRM、Staging webhook handler）、連携に必要なスコープを選びます。

• forms:read：フォームのメタデータの読み取りのみ（一覧・取得）
• forms:write：フォームの作成。読み取りも付与されます
• forms:clone：既存のフォームを新しいフォームに複製
• client-links:write：クライアント情報入力リンクの生成

キーを発行できるのは、ワークスペースのオーナーと管理者だけです。

キーを作成をクリックすると、シークレットの全体が1回だけ表示されます。すぐにシークレット管理ツールにコピーしてください。このダイアログを閉じた後は、末尾の4文字しか表示されません。キーを紛失した場合は、そのキーを取り消して新しいキーを発行してください。

2. 認証

すべてのv1エンドポイントはAuthorization: Bearer <secret>ヘッダーを必要とします。

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"]

ワークスペースIDは、ダッシュボードのすべてのページのURL（/workspaces/<workspaceId>/...）に含まれています。キーのワークスペースはサーバー側で紐づけられているため、別のワークスペースのエンドポイントを誤ったキーで呼び出すと403 Forbiddenが返されます。

ヒント： 言語のタブは、このページのすべてのコード例で連動します。一度言語を選ぶと、ページ全体がそれに切り替わります。

3. フォームを作成する

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"]

呼び出しごとに、料金プランのフォームクレジットを1つ消費します（ダッシュボードからフォームを作成する場合と同じです）。ワークスペースのクレジットが残っていない場合、呼び出しは402 Payment Requiredを返します。チャージしてから再試行してください。

任意のnameフィールドで、フォームにわかりやすいラベル（最大200文字）を設定できます。省略すると名前が自動生成されます。どちらの場合も、後からダッシュボードでフォーム名を変更できます。

4. 既存のフォームを複製する

頻繁に作り直すテンプレート用のフォーム（たとえば同じ雇用主のJ-1プログラム）がある場合は、一から作成する代わりに複製しましょう。必要に応じてdisabledSectionsを渡すと、特定のフォームページをコピーから除外できます。指定したページは新しいフォームで空のフィールドに置き換えられ、クライアントが改めて入力します。

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"]

複製も、新しいフォームの作成と同じくフォームクレジットを1つ消費します。

disabledSectionsの有効な値

すべてのページをコピーするには、空の配列を渡してください（またはフィールド自体を省略してください）。それ以外の場合は、下の識別子を任意に組み合わせて使います。それ以外の値は400 Bad Requestを返します。

実際に存在するのは、そのフォームのビザカテゴリーに関係するセクションだけです。元のフォームにないページを指定しても、何も起こりません。

5. クライアント情報入力リンクを生成する

フォームを作成したら、クライアントが入力に使うトークン付きのURLを生成します。

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"]

リクエストボディ

レスポンスの例（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をクライアントに送ってください。URL内のトークンは単一の用途に限られ、expiresAtで失効します。クライアントが入力するために、それ以上の認証は必要ありません。同じリンクを開くshortUrlを送ることもできます。

クライアント情報入力リンクの取り消し

発行済みのクライアントリンクを取り消すv1エンドポイントはありません。ダッシュボード（ワークスペース → フォーム → 共有 → リンクを取り消す）から取り消してください。取り消しは即時かつ永続的で、リンクからの次のリクエストは401を返します。漏えいが疑われ、UIから取り消せる担当者がいない場合、最も安全な代替策はリンクの期限切れを待つことです（それに合わせてexpiresInDaysを短めに設定してください）。

defaultLanguageの有効な値

defaultLanguageは、受信者が最初にリンクを開いたときのクライアント情報入力画面の言語を決めます。下のコードのいずれかを使ってください。それ以外の値は400 Bad Requestを返します。短いコード（en、cnなど）はDS160.io内部のロケール識別子です。BCP-47の列は、<html lang>、hreflang、Intl.* APIで出力される値を示しています。APIリクエストでは短いコードを使ってください。BCP-47の形式は参考情報です。

クライアントリンクはパスワードと同様に扱う

urlはベアラー認証情報です。リンクを持っている人は誰でも、期限が切れるまで、2要素目の認証なしでフォームに入力できます。

• 信頼できる経路で送ってください。漏えいのおそれがある場所（公開チャット、検索エンジンにインデックスされるページ、共有バンドル）には掲載しないでください。
• ログでは?token=を伏せてください。jtiクレームだけであれば、ログに記録しても安全です。
• 漏えいが疑われる場合は取り消してください。取り消しは即時かつ永続的です。
• expiresInDaysはトレードオフです。短くすると漏えいの期間が短くなり、長くすると再発行の手間が減ります。

6. フォームを一覧表示・取得する

# 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()

これらの読み取り用エンドポイントは、forms:readスコープ（読み取り専用）またはforms:write（読み取りも付与）を受け付けます。

ページネーション

GET /v1/workspaces/:workspaceId/formsはページ分割されています。結果を順にたどるには、クエリパラメーター?limit=と?cursor=を渡します。

各レスポンスにはnextCursorフィールドが含まれます。次のページがない場合、nextCursorはnullです。例：

{
    "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…"
}

次のリクエストで?cursor=65f2a8a3…&limit=50を送ると、先に進めます。フォームはidにより新しい順に並んでいるため、呼び出しの合間に新しいフォームが作成されても、カーソルが読み取り位置を固定します。重複して表示されることはなく、ページ分割を始めた時点で存在していたフォームを見落とすこともありません。

フォームのstatusの値

フォームのメタデータの各レスポンスに含まれるstatusフィールドは、次のいずれかです。

通信形式ではアンダースコアを使います（in-progressではなくin_progress）。上の文字列とそのまま比較すれば、常に正しく判定できます。

APIを通じたPIIへのアクセス

v1のフォームメタデータのエンドポイント（GET /workspaces/:workspaceId/formsとGET /workspaces/:workspaceId/forms/:formId）が返すのは運用上のメタデータだけです：id、name、status、workspaceId、userId、preferredConsulate、createdAt、archivedAt、そして単一フォームのエンドポイントではapplicantConsent（同意を求めたリンクにおけるクライアントの最新の同意：acceptedAt、withdrawnAt、noticeVersion、またはnull）です。申請者の回答は公開されません。氏名、生年月日、パスポート番号、渡航歴など、DS-160のフィールドはいずれも/v1からは取得できません。

完成したDS-160のPDFとすべてのフィールドデータは、ダッシュボードからのみ、監査ログが記録される申請者の所有者のもとでアクセスできます。申請者が入力したデータを連携で読み取る必要がある場合は、自社のクライアント情報入力の流れで行ってください（まず自社のCRMがデータを収集し、それをDS160.ioに送ります）。APIがデータを返してくれることを前提にしないでください。

レート制限

各キーの上限は1分あたり60リクエストです。各レスポンスには次のヘッダーが含まれます。

上限を超えると、APIはRetry-Afterヘッダー付きで429 Too Many Requestsを返します。連携で正当な理由からより高い上限が必要な場合は、サポートにお問い合わせください。特定のキーについて上限を引き上げることができます。

冪等性と再試行

v1 APIはIdempotency-Keyヘッダーに対応していません。具体的には次のとおりです。

• POST /formsとPOST /forms/:formId/cloneは冪等ではなく、呼び出しのたびにフォームクレジットを1つ消費します。ネットワークのタイムアウト後に単純に再試行すると、重複したフォームが作成され、2つ目のクレジットが消費されます。
• POST /forms/:formId/client-linksも冪等ではありませんが、クレジットは消費しません。再試行すると、独自のjtiとexpiresAtを持つ2つ目のリンクが発行されるだけです。
• すべてのGETエンドポイントは、自由に再試行して問題ありません。

作成・複製で推奨する再試行の方法： POST /forms（または/clone）がタイムアウトしたり5xxを返したりした場合は、やみくもに再試行しないでください。代わりにGET /workspaces/:workspaceId/formsを呼び出し（フォームは新しい順に並びます）、指定したnameのフォームが直近数秒以内に作成されていないか確認します。作成されていれば、元の呼び出しは成功したものとして扱い、再試行は不要です。作成されていなければ、元の書き込みは確実に反映されていないため、再試行しても安全です。

今後のマイナーリリースでIdempotency-Keyに対応する可能性があります。連携ではそれを見越して設計しつつ、現時点ではそれに依存しないでください。

キーの取り消し

キーが漏えいした、使用を終える、または単に使われていない場合は、ワークスペース設定 → チームとアクセス → APIキー → 無効化から取り消してください。取り消しはただちに有効になり、そのキーからの次のリクエストは401 Unauthorizedを返します。取り消したキーは監査のために一覧に残りますが、再び有効にすることはできません。連携を動かし続ける必要がある場合は、新しいキーを発行してください。

ベストプラクティス

• 連携ごとに1つのキー。 システムを廃止するときに対象を絞って取り消しやすく、ダッシュボードのLast usedの列で、どの連携がまだ使われているかがわかります。
• 最小限のスコープ。 クライアントリンクを生成するだけのキーにforms:cloneは不要です。スコープを絞るほど、シークレットが漏えいしたときの影響範囲が小さくなります。
• シークレットは保管庫に保存する。 ソース管理にコミットしたり、フロントエンドのバンドルに埋め込んだりしないでください。すべてのブラウザタブで露出してしまいます。
• 定期的にローテーションする。 新しいキーを発行し、連携をそのキーに切り替えてから、古いキーを取り消します。ダッシュボードにはキーが最後に使われた日時が表示されるため、取り消す前に切り替えが完了したことを確認できます。

エラー

2xx以外のレスポンスは、すべて同じJSONの形式です。

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

errorの値は文字列です。スキーマ検証による400 Bad Requestの場合は、違反した各制約を記述したJSON配列をシリアライズしたものです。それ以外の場合は、そのまま表示したりログに記録したりできる短いメッセージです。

エンドツーエンドの例

フォームを作成し、クライアントリンクを発行して送信し、完了するまでポーリングする、入力の流れ全体をcurlで示します。実際の連携ではそれぞれのHTTPクライアントを使いますが、流れはどの言語でも同じです。

# 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).

この手順についての補足：

• ポーリングの間隔：5〜15分ごとで十分です。1分あたり60リクエストの上限があっても、1つのキーで処理中の数千件のフォームを余裕をもってポーリングできます。
• Webhookはまだ利用できません。完了時のプッシュ通知が必要な場合は、このページを確認するか、サポートにお問い合わせください。ロードマップに含まれています。
• 手順5（完成したPDFのダウンロード）には、現在はダッシュボードのセッションが必要です。v1 APIは意図的に申請者の回答を公開していません。APIを通じたPIIへのアクセスを参照してください。

バージョン管理とサポート

安定性。 /v1は安定版のAPIです。/v1の中では、メジャーバージョンを上げずに新しい任意フィールド、新しいエンドポイント、新しいenum値を追加しますが、既存のフィールドの名前変更、削除、型の変更は行いません。互換性のない変更が必要になった場合は/v2として公開し、/v1はそれと並行して少なくとも12か月間動作し続けます。

想定しておくべき後方互換性のある追加：

• 新しい任意のリクエストフィールドが随時追加されます。それらを送らない既存のリクエストは引き続き動作します。
• 新しいレスポンスフィールドが追加されることがあります。不明なフィールドは無視できるものとして扱い、将来のフィールドが現れても処理を失敗させないでください。
• status、defaultLanguage、disabledSectionsに新しいenum値が追加されます。不明な値でクラッシュせず、ログに記録して処理を続けてください。

サポート：

• より高いレート制限、カスタムドメイン、Webhookの先行アクセス、連携に関するご質問：担当のアカウントマネージャーまたはsupport@ds160.ioまでご連絡ください。
• v1 APIに関するバグ報告：同じアドレスまでお送りください。各レスポンスにはx-request-idヘッダーが含まれています。報告にその値を含めていただくと、ログから該当する呼び出しを特定できます。