Chaves de API e acesso programático

Se você já opera um CRM, um sistema de gestão de casos ou um portal interno, não precisa entrar no painel para criar cada formulário. As chaves de API permitem que o seu backend chame a API v1 da DS160.io diretamente: criar formulários, cloná-los e gerar links de admissão de clientes no seu próprio horário.

As chaves de API estão disponíveis em workspaces do tipo Business. Cada chave está vinculada a um único workspace e só pode operar dentro dele.

URL base da API

Todos os endpoints v1 têm como raiz:

https://ds160.io/api/v1

Estes documentos podem ser hospedados no domínio white-label da sua agência, mas as chamadas à API sempre vão para ds160.io. Todos os exemplos de código nesta página usam a URL completa para que você possa copiar e colar sem reescrever.

Referência de endpoints

/v1 é estável — as rotas e os nomes dos campos não mudarão sem uma versão maior /v2 (ver Versionamento e suporte). As rotas da tabela abaixo são mostradas relativas ao prefixo de workspace /workspaces/:workspaceId/; as estruturas completas das solicitações e respostas estão documentadas na seção de cada endpoint.

Todos os corpos e respostas são JSON. O scope forms:read concede acesso somente de leitura aos metadados de formulários; forms:write concede leitura e escrita, então uma chave que apenas escreve também tem leitura de graça.

1. Criar uma chave de API

Abra Configurações do Workspace → Equipe e acesso → Chaves de API e clique em Criar chave de API. Escolha um nome descritivo (recomendamos uma chave por integração, p. ex. Production CRM ou Staging webhook handler) e selecione os scopes que a integração precisa:

• forms:read — ler metadados de formulários (listar / obter)
• forms:write — criar formulários; também concede leitura
• forms:clone — duplicar um formulário existente
• client-links:write — gerar links de admissão de clientes

Apenas os Proprietários e Administradores do workspace podem gerar chaves.

Quando você clica em Criar chave, a plataforma exibe o segredo completo uma única vez. Copie-o imediatamente para o seu gerenciador de segredos: após fechar o modal, somente os últimos quatro caracteres serão exibidos novamente. Se você perder uma chave, revogue-a e gere uma nova.

2. Autenticar

Todos os endpoints v1 esperam um cabeçalho 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"]

O id do workspace aparece na URL de cada página do painel (/workspaces/<workspaceId>/...). O workspace da chave está vinculado no lado do servidor: chamar o endpoint de outro workspace com a chave errada retorna 403 Forbidden.

Dica: as abas de linguagem se sincronizam entre todos os trechos desta página. Escolha a sua linguagem uma vez e o resto da página acompanha.

3. Criar um formulário

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

Cada chamada consome um crédito de formulário do seu plano de faturamento (igual a criar um formulário pelo painel). Se o seu workspace ficar sem créditos, a chamada retorna 402 Payment Required: recarregue antes de tentar novamente.

O campo opcional name define um rótulo legível para o formulário (até 200 caracteres). Omita-o para obter um nome gerado automaticamente — de qualquer forma, você pode renomear o formulário pelo painel mais tarde.

4. Clonar um formulário existente

Se você tem um formulário modelo que reemite com frequência (digamos, o mesmo programa J-1 do mesmo empregador), clone-o em vez de começar do zero. Opcionalmente, passe disabledSections para omitir páginas específicas do formulário na cópia — qualquer item que você listar é substituído por campos vazios no novo formulário, de modo que o cliente o preencha do zero:

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

Clonar consome um crédito de formulário, assim como criar um novo.

Valores válidos de disabledSections

Passe um array vazio (ou omita o campo inteiramente) para copiar todas as páginas. Caso contrário, use qualquer combinação dos identificadores abaixo — qualquer outro valor retorna 400 Bad Request.

Apenas as seções relevantes para a categoria de visto do formulário estão realmente presentes; listar uma página que não existe no formulário de origem não tem efeito.

5. Gerar um link de admissão de cliente

Uma vez que um formulário exista, gere uma URL com token que o cliente pode usar para preenchê-lo:

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

Corpo da solicitação

Exemplo de resposta (200 OK)

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

Envie a url ao seu cliente. O token na URL é de uso único e expira em expiresAt — não há autenticação adicional necessária para que o cliente o preencha.

Revogar um link de admissão de cliente

Não existe um endpoint v1 para revogar links de cliente emitidos — revogue pelo painel (Workspace → Formulário → Compartilhamento → Revogar link). A revogação é imediata e permanente: a próxima solicitação que o link fizer retorna 401. Se houver suspeita de vazamento e ninguém estiver disponível para revogar pela UI, a alternativa mais segura é deixar o link expirar (limite expiresInDays adequadamente).

Valores válidos de defaultLanguage

defaultLanguage controla o idioma da interface de admissão do cliente quando o destinatário abre o link pela primeira vez. Use qualquer um dos códigos abaixo — qualquer outro valor retorna 400 Bad Request. Os códigos curtos (en, cn, …) são os identificadores de localização internos da DS160.io; a coluna BCP-47 mostra o que emitimos em <html lang>, hreflang e nas APIs Intl.*. Use o código curto nas solicitações à API; a forma BCP-47 é informativa.

Trate os links de cliente como senhas

A url é uma credencial portadora — qualquer pessoa que a possua pode preencher o formulário até que ele expire, sem segundo fator.

• Envie por um canal de confiança; não a publique em lugares onde possa vazar (chat público, páginas indexadas por buscadores, pacotes compartilhados).
• Oculte ?token= nos logs. O claim jti sozinho é seguro de registrar.
• Revogue diante de suspeita de vazamento — a revogação é imediata e permanente.
• expiresInDays é um compromisso: mais curto = janela de vazamento menor, mais longo = menos atrito para reemitir.

6. Listar ou obter formulários

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

Estes endpoints de leitura aceitam o scope forms:read (somente leitura) ou forms:write (que também concede leitura).

Paginação

GET /v1/workspaces/:workspaceId/forms é paginado. Passe os parâmetros de query ?limit= e ?cursor= para percorrer os resultados:

Cada resposta inclui um campo nextCursor. Quando não há mais páginas, nextCursor é null. Exemplo:

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

Avance enviando ?cursor=65f2a8a3…&limit=50 na próxima solicitação. Os formulários são ordenados do mais novo ao mais antigo por id, então um cursor fixa a sua posição de leitura mesmo que novos formulários sejam criados entre as chamadas — você não verá duplicatas nem perderá nada que existia no momento em que começou a paginar.

Valores de status do formulário

O campo status em cada resposta de metadados de formulário é um dos seguintes:

O formato de transmissão usa underscores (in_progress, não in-progress). Comparar com as strings acima como estão sempre funcionará.

Acesso a PII via a API

Os endpoints de metadados de formulários v1 (GET /workspaces/:workspaceId/forms e GET /workspaces/:workspaceId/forms/:formId) retornam apenas metadados operacionais: id, name, status, workspaceId, userId, preferredConsulate, createdAt, archivedAt. Eles não expõem as respostas do solicitante — nenhum nome, data de nascimento, número de passaporte, histórico de viagens ou qualquer outro campo do DS-160 é acessível através de /v1.

Os PDFs do DS-160 concluídos e os dados completos dos campos são acessíveis apenas através do painel, sob o proprietário auditado do solicitante. Se a sua integração precisar ler dados inseridos pelo solicitante, faça isso através do seu próprio fluxo de admissão de cliente (o seu CRM coleta os dados primeiro, você os envia para a DS160.io) — nunca presuma que a API os devolverá.

Limites de taxa

Cada chave está limitada a 60 solicitações por minuto. Cada resposta inclui:

Se você exceder o limite, a API retorna 429 Too Many Requests com um cabeçalho Retry-After. Se a sua integração legitimamente precisa de um teto mais alto, entre em contato com o suporte — podemos elevar o limite para chaves específicas.

Idempotência e novas tentativas

A API v1 não suporta um cabeçalho Idempotency-Key. Concretamente:

• POST /forms e POST /forms/:formId/clone não são idempotentes e consomem um crédito de formulário a cada chamada. Uma nova tentativa ingênua após um timeout de rede criará um formulário duplicado e queimará um segundo crédito.
• POST /forms/:formId/client-links também não é idempotente, mas não consome créditos — uma chamada repetida simplesmente cunha um segundo link com o seu próprio jti e expiresAt.
• Todos os endpoints GET são seguros para repetir livremente.

Padrão de nova tentativa recomendado para create/clone: se uma POST /forms (ou /clone) der timeout ou retornar um 5xx, não tente novamente às cegas. Em vez disso, chame GET /workspaces/:workspaceId/forms (os formulários são ordenados do mais novo ao mais antigo) e verifique se um formulário com o name que você forneceu foi criado nos últimos segundos. Se foi, trate a chamada original como bem-sucedida e pule a nova tentativa. Se não foi, a escrita original definitivamente não foi efetivada e uma nova tentativa é segura.

Podemos adicionar suporte a Idempotency-Key em um lançamento menor futuro; as integrações devem se planejar para isso, mas não depender disso hoje.

Revogar uma chave

Se uma chave for vazada, descontinuada ou simplesmente não usada, revogue-a em Configurações do Workspace → Equipe e acesso → Chaves de API → Revogar. A revogação entra em vigor imediatamente — a próxima solicitação que a chave fizer retorna 401 Unauthorized. Chaves revogadas permanecem na lista para fins de auditoria, mas não podem ser reativadas; gere uma nova se você precisar manter a integração funcionando.

Boas práticas

• Uma chave por integração. Mais fácil de revogar cirurgicamente quando um sistema é desativado, e a coluna Last used no painel indica quais integrações ainda estão ativas.
• Scopes mínimos. Uma chave que só gera links de cliente não deveria ter forms:clone. Scopes menores significam menor raio de impacto se o segredo vazar.
• Guarde os segredos em um cofre. Nunca os comite no controle de versão nem os incorpore em um bundle de frontend — cada aba do navegador os exporia.
• Rotacione periodicamente. Gere uma nova chave, migre a integração e então revogue a antiga. O painel mostra quando cada chave foi usada pela última vez para que você confirme a transição antes de revogar.

Erros

Todas as respostas não-2xx compartilham a mesma estrutura JSON:

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

O valor de error é uma string. Para 400 Bad Request por validação de esquema, é um array JSON serializado descrevendo cada restrição violada; para todo o resto, é uma mensagem curta que você pode exibir ou registrar diretamente.

Exemplo de ponta a ponta

Um fluxo de admissão completo — criar um formulário, cunhar um link de cliente, enviá-lo e consultar a conclusão — usando curl. Integrações reais usarão o seu próprio cliente HTTP; a estrutura é a mesma em qualquer linguagem.

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

Algumas notas sobre a receita:

• Cadência de polling: a cada 5–15 minutos é suficiente. Com um teto de 60 req/min, uma única chave pode consultar confortavelmente milhares de formulários em andamento.
• Os webhooks ainda não estão disponíveis. Se você precisa de notificações push na conclusão, acompanhe esta página ou entre em contato com o suporte — está no roadmap.
• O passo 5 (baixar o PDF concluído) requer uma sessão do painel hoje. A API v1 intencionalmente não expõe as respostas do solicitante — ver Acesso a PII via a API.

Versionamento e suporte

Estabilidade. /v1 é a superfície estável da API. Adicionamos novos campos opcionais, novos endpoints e novos valores de enum dentro de /v1 sem incrementar a versão maior, mas não renomeamos, removemos nem alteramos o tipo de nenhum campo existente. Se algum dia precisarmos de uma mudança incompatível, ela será lançada sob /v2 e /v1 continuará funcionando por pelo menos 12 meses ao lado dela.

Adições retrocompatíveis que você deve planejar:

• Novos campos opcionais nas solicitações aparecerão com o tempo. Solicitações existentes que não os enviarem continuarão funcionando.
• Novos campos podem ser adicionados nas respostas. Trate os campos desconhecidos como ignoráveis — não falhe se um campo futuro aparecer.
• Novos valores de enum para status, defaultLanguage e disabledSections serão adicionados. Não trave com valores desconhecidos; registre-os e prossiga.

Suporte:

• Limites de taxa mais altos, domínios personalizados, acesso antecipado a webhooks e perguntas sobre integração: entre em contato com o seu gerente de conta ou support@ds160.io.
• Relatos de bugs contra a API v1: o mesmo endereço. Cada resposta carrega um cabeçalho x-request-id — inclua-o no seu relato para que possamos encontrar a chamada exata em nossos logs.