Clés d'API et accès programmatique

Si vous exploitez déjà un CRM, un système de gestion de dossiers ou un portail interne, vous n’avez pas besoin de naviguer dans le tableau de bord pour créer chaque formulaire. Les clés d’API permettent à votre backend d’appeler directement l’API v1 de DS160.io — de créer des formulaires, de les cloner et de générer des liens d’accueil clients selon votre propre calendrier.

Les clés d’API sont disponibles sur les workspaces de type Business. Chaque clé est rattachée à un seul workspace et ne peut agir qu’à l’intérieur de celui-ci.

URL de base de l’API

Tous les endpoints v1 ont pour racine :

https://ds160.io/api/v1

Cette documentation peut être hébergée sur le domaine en marque blanche de votre agence, mais les appels à l’API vont toujours vers ds160.io. Tous les exemples de code de cette page utilisent l’URL complète afin que vous puissiez copier-coller sans rien réécrire.

Référence des endpoints

/v1 est stable — les chemins et les noms de champs ne changeront pas sous vos pieds sans une version majeure /v2 (voir Versionnage et support). Les chemins du tableau ci-dessous sont indiqués relativement au préfixe de workspace /workspaces/:workspaceId/ ; les structures complètes des requêtes et des réponses sont documentées dans la section de chaque endpoint.

Tous les corps et réponses sont en JSON. Le scope forms:read accorde un accès en lecture seule aux métadonnées des formulaires ; forms:write accorde la lecture et l’écriture, de sorte qu’une clé qui ne fait qu’écrire dispose aussi de l’accès en lecture gratuitement.

1. Créer une clé d’API

Ouvrez Paramètres du workspace → Équipe et accès → Clés d’API et cliquez sur Créer une clé d’API. Choisissez un nom descriptif (nous recommandons une clé par intégration, p. ex. Production CRM ou Staging webhook handler), puis sélectionnez les scopes dont l’intégration a besoin :

• forms:read — lire uniquement les métadonnées des formulaires (lister / récupérer)
• forms:write — créer des formulaires ; accorde aussi la lecture
• forms:clone — dupliquer un formulaire existant
• client-links:write — générer des liens d’accueil clients

Seuls les Propriétaires et Administrateurs du workspace peuvent émettre des clés.

Lorsque vous cliquez sur Créer la clé, la plateforme vous montre le secret complet une seule fois. Copiez-le immédiatement dans votre gestionnaire de secrets — une fois cette fenêtre fermée, seuls les quatre derniers caractères seront affichés à nouveau. Si vous perdez une clé, révoquez-la et émettez-en une nouvelle.

2. S’authentifier

Tous les endpoints v1 attendent un en-tête Authorization: Bearer <secret>.

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

curl https://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://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://ds160.io/api/v1/workspaces/{workspace_id}/forms",
    headers={"Authorization": f"Bearer {key}"},
)
forms = response.json()["forms"]

L’id du workspace apparaît dans l’URL de chaque page du tableau de bord (/workspaces/<workspaceId>/...). Le workspace de la clé est lié côté serveur — appeler l’endpoint d’un autre workspace avec la mauvaise clé renvoie 403 Forbidden.

Astuce : les onglets de langage se synchronisent entre tous les extraits de cette page. Choisissez votre langage une fois et le reste de la page suivra.

3. Créer un formulaire

curl -X POST https://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://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://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"]

Chaque appel consomme un crédit de formulaire de votre forfait de facturation (comme la création d’un formulaire depuis le tableau de bord). Si votre workspace n’a plus de crédits, l’appel renvoie 402 Payment Required — rechargez avant de réessayer.

Le champ optionnel name définit une étiquette lisible pour le formulaire (jusqu’à 200 caractères). Omettez-le pour obtenir un nom généré automatiquement — dans tous les cas, vous pourrez renommer le formulaire depuis le tableau de bord plus tard.

4. Cloner un formulaire existant

Si vous disposez d’un formulaire modèle que vous réémettez fréquemment (par exemple, le même programme J-1 du même employeur), clonez-le plutôt que de repartir de zéro. Vous pouvez éventuellement passer disabledSections pour omettre des pages de formulaire spécifiques de la copie — tout ce que vous listez est remplacé par des champs vides dans le nouveau formulaire, afin que le client les remplisse à neuf :

curl -X POST https://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://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://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"]

Le clonage consomme un crédit de formulaire, tout comme la création d’un nouveau formulaire.

Valeurs valides de disabledSections

Passez un tableau vide (ou omettez entièrement le champ) pour copier toutes les pages. Sinon, utilisez n’importe quelle combinaison des identifiants ci-dessous — toute autre valeur renvoie 400 Bad Request.

Seules les sections pertinentes pour la catégorie de visa du formulaire sont réellement présentes ; lister une page qui n’existe pas dans le formulaire source n’a aucun effet.

5. Générer un lien d’accueil client

Une fois qu’un formulaire existe, générez une URL avec jeton que le client peut utiliser pour le remplir :

curl -X POST https://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://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://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"]

Corps de la requête

Exemple de réponse (200 OK)

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

Envoyez l’url à votre client. Le jeton dans l’URL est à usage unique et expire à expiresAt — aucune authentification supplémentaire n’est requise pour que le client le remplisse.

Révoquer un lien d’accueil client

Il n’existe aucun endpoint v1 pour révoquer les liens clients émis — révoquez depuis le tableau de bord (Workspace → Formulaire → Partage → Révoquer le lien). La révocation est immédiate et permanente : la prochaine requête effectuée par le lien renvoie 401. Si une fuite est suspectée et que personne n’est disponible pour révoquer depuis l’interface, la solution de repli la plus sûre est de laisser le lien expirer (limitez expiresInDays en conséquence).

Valeurs valides de defaultLanguage

defaultLanguage contrôle la langue de l’interface d’accueil client lorsque le destinataire ouvre le lien pour la première fois. Utilisez l’un des codes ci-dessous — toute autre valeur renvoie 400 Bad Request. Les codes courts (en, cn, …) sont les identifiants de locale internes de DS160.io ; la colonne BCP-47 indique ce que nous émettons dans <html lang>, hreflang et les API Intl.*. Utilisez le code court dans les requêtes à l’API ; la forme BCP-47 est informative.

Traitez les liens clients comme des mots de passe

L’url est un identifiant au porteur — quiconque la détient peut remplir le formulaire jusqu’à son expiration, sans second facteur.

• Envoyez-la par un canal de confiance ; ne la publiez pas dans des endroits susceptibles de fuiter (chat public, pages indexées par les moteurs de recherche, archives partagées).
• Masquez ?token= dans les logs. Le claim jti seul est sûr à journaliser.
• Révoquez à la moindre suspicion de fuite — la révocation est immédiate et permanente.
• expiresInDays est un compromis : plus court = fenêtre de fuite plus petite, plus long = moins de friction pour réémettre.

6. Lister ou récupérer des formulaires

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

# A single form by id
curl https://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://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://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://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://ds160.io/api/v1/workspaces/{workspace_id}/forms/{form_id}",
    headers={"Authorization": f"Bearer {key}"},
).json()

Ces endpoints de lecture acceptent le scope forms:read (lecture seule) ou forms:write (qui accorde aussi la lecture).

Pagination

GET /v1/workspaces/:workspaceId/forms est paginé. Passez les paramètres de query ?limit= et ?cursor= pour parcourir les résultats :

Chaque réponse inclut un champ nextCursor. Lorsqu’il n’y a plus de pages, nextCursor vaut null. Exemple :

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

Avancez en envoyant ?cursor=65f2a8a3…&limit=50 à la requête suivante. Les formulaires sont triés du plus récent au plus ancien par id, de sorte qu’un curseur fixe votre position de lecture même si de nouveaux formulaires sont créés entre les appels — vous ne verrez pas de doublons et vous ne manquerez rien de ce qui existait au moment où vous avez commencé à paginer.

Valeurs de status du formulaire

Le champ status de chaque réponse de métadonnées de formulaire est l’une des valeurs suivantes :

Le format de transmission utilise des tirets bas (in_progress, et non in-progress). Comparer aux chaînes ci-dessus telles quelles fonctionnera toujours.

Accès aux PII via l’API

Les endpoints de métadonnées de formulaire v1 (GET /workspaces/:workspaceId/forms et GET /workspaces/:workspaceId/forms/:formId) ne renvoient que des métadonnées opérationnelles : id, name, status, workspaceId, userId, preferredConsulate, createdAt, archivedAt. Ils n’exposent pas les réponses du demandeur — aucun nom, date de naissance, numéro de passeport, historique de voyage ni aucun autre champ du DS-160 n’est accessible via /v1.

Les PDF DS-160 complétés et les données complètes des champs ne sont accessibles que via le tableau de bord, sous le propriétaire audité du demandeur. Si votre intégration a besoin de lire les données saisies par le demandeur, faites-le via votre propre flux d’accueil client (votre CRM collecte les données d’abord, puis vous les transmettez à DS160.io) — ne supposez jamais que l’API vous les restituera.

Limites de débit

Chaque clé est limitée à 60 requêtes par minute. Chaque réponse comporte :

Si vous dépassez la limite, l’API renvoie 429 Too Many Requests avec un en-tête Retry-After. Si votre intégration a légitimement besoin d’un plafond plus élevé, contactez le support — nous pouvons relever la limite pour des clés spécifiques.

Idempotence et nouvelles tentatives

L’API v1 ne prend pas en charge un en-tête Idempotency-Key. Concrètement :

• POST /forms et POST /forms/:formId/clone ne sont pas idempotents et consomment un crédit de formulaire à chaque appel. Une nouvelle tentative naïve après un timeout réseau créera un formulaire en double et consommera un second crédit.
• POST /forms/:formId/client-links n’est pas idempotent non plus mais ne consomme pas de crédits — une tentative réémet simplement un second lien avec son propre jti et son propre expiresAt.
• Tous les endpoints GET peuvent être réessayés librement en toute sécurité.

Modèle de nouvelle tentative recommandé pour create/clone : si une POST /forms (ou /clone) expire ou renvoie un 5xx, ne réessayez pas aveuglément. Appelez plutôt GET /workspaces/:workspaceId/forms (les formulaires sont triés du plus récent au plus ancien) et vérifiez si un formulaire portant le name que vous avez fourni a été créé dans les dernières secondes. Si c’est le cas, considérez l’appel initial comme réussi et ignorez la nouvelle tentative. Sinon, l’écriture initiale n’a définitivement pas abouti et une nouvelle tentative est sûre.

Nous pourrions ajouter la prise en charge de Idempotency-Key dans une future version mineure ; les intégrations devraient le prévoir mais ne pas en dépendre aujourd’hui.

Révoquer une clé

Si une clé est divulguée, en fin de vie ou simplement inutilisée, révoquez-la depuis Paramètres du workspace → Équipe et accès → Clés d’API → Révoquer. La révocation prend effet immédiatement — la prochaine requête effectuée par la clé renvoie 401 Unauthorized. Les clés révoquées restent dans la liste à des fins d’audit mais ne peuvent pas être réactivées ; émettez-en une nouvelle si vous devez maintenir l’intégration en fonctionnement.

Bonnes pratiques

• Une clé par intégration. Plus facile à révoquer chirurgicalement lorsqu’un système est mis hors service, et la colonne Last used du tableau de bord vous indique quelles intégrations sont encore actives.
• Scopes minimaux. Une clé qui ne génère que des liens clients ne devrait pas avoir forms:clone. Des scopes plus restreints signifient un rayon d’impact plus faible en cas de fuite du secret.
• Stockez les secrets dans un coffre-fort. Ne les committez jamais dans le contrôle de version et ne les intégrez pas dans un bundle frontend — chaque onglet du navigateur les exposerait.
• Effectuez une rotation périodique. Émettez une nouvelle clé, basculez l’intégration dessus, puis révoquez l’ancienne. Le tableau de bord indique quand une clé a été utilisée pour la dernière fois afin que vous puissiez confirmer la bascule avant de révoquer.

Erreurs

Toutes les réponses non-2xx partagent la même structure JSON :

{ "error": "message lisible par un humain" }

La valeur de error est une chaîne. Pour un 400 Bad Request issu de la validation de schéma, c’est un tableau JSON sérialisé décrivant chaque contrainte violée ; pour tout le reste, c’est un message court que vous pouvez afficher ou journaliser directement.

Exemple de bout en bout

Un flux d’accueil complet — créer un formulaire, émettre un lien client, l’envoyer et interroger l’achèvement — avec curl. Les intégrations réelles utiliseront leur propre client HTTP ; la structure est la même dans n’importe quel langage.

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

Quelques notes sur cette recette :

• Cadence d’interrogation : toutes les 5 à 15 minutes est largement suffisant. Avec un plafond de 60 req/min, une seule clé peut confortablement interroger des milliers de formulaires en cours.
• Les webhooks ne sont pas encore disponibles. Si vous avez besoin de notifications push à l’achèvement, surveillez cette page ou contactez le support — c’est sur la feuille de route.
• L’étape 5 (télécharger le PDF complété) nécessite une session du tableau de bord aujourd’hui. L’API v1 n’expose volontairement pas les réponses du demandeur — voir Accès aux PII via l’API.

Versionnage et support

Stabilité. /v1 est la surface stable de l’API. Nous ajoutons de nouveaux champs optionnels, de nouveaux endpoints et de nouvelles valeurs d’enum au sein de /v1 sans incrémenter la version majeure, mais nous ne renommons, ne supprimons ni ne changeons le type d’aucun champ existant. Si nous devions un jour introduire un changement incompatible, il serait publié sous /v2 et /v1 continuerait de fonctionner pendant au moins 12 mois en parallèle.

Ajouts rétrocompatibles que vous devriez anticiper :

• De nouveaux champs de requête optionnels apparaîtront au fil du temps. Les requêtes existantes qui ne les envoient pas continuent de fonctionner.
• De nouveaux champs de réponse peuvent être ajoutés. Traitez les champs inconnus comme ignorables — n’échouez pas si un champ futur apparaît.
• De nouvelles valeurs d’enum pour status, defaultLanguage et disabledSections seront ajoutées. Ne plantez pas sur des valeurs inconnues ; journalisez-les et poursuivez.

Support :

• Limites de débit plus élevées, domaines personnalisés, accès anticipé aux webhooks et questions d’intégration : contactez votre gestionnaire de compte ou support@ds160.io.
• Signalements de bugs concernant l’API v1 : même adresse. Chaque réponse comporte un en-tête x-request-id — incluez-le dans votre signalement afin que nous puissions retrouver l’appel exact dans nos logs.