Formulários

Um formulário define o que o solicitante preenche e quais documentos e verificações a verificação coleta. Antes de criar uma solicitação KYC/KYB, liste os formulários da organização para exibir um seletor ao operador ou localizar o formulário certo pelo nome.

Esta é a mesma lista que o painel da Certivant exibe em Formulários — o endpoint REST a retorna somente para a organização da sua chave de API.

Todos os endpoints exigem uma chave de API. Consulte Autenticação.

Listar formulários

GET /api/v1/kyc/forms    Escopo: kyc:read

Retorna os formulários KYC e KYB da organização que fez a chamada. Por padrão, são retornados somente os formulários publicados (aqueles com os quais você pode de fato executar uma verificação).

Parâmetros de consulta

Exemplos:

# All published forms (KYC + KYB)
curl -H "Authorization: Bearer $CERTIVANT_API_KEY" \
  https://app.certivant.com/api/v1/kyc/forms

# Only published KYB (business) forms
curl -H "Authorization: Bearer $CERTIVANT_API_KEY" \
  "https://app.certivant.com/api/v1/kyc/forms?type=kyb"

# Everything, including drafts and archived
curl -H "Authorization: Bearer $CERTIVANT_API_KEY" \
  "https://app.certivant.com/api/v1/kyc/forms?status=all"

Resposta

{
  "data": [
    {
      "id": "cmr8prfoe000114msbv8bie12",
      "name": "KYC — Default Identity Verification",
      "description": "Standard KYC identity verification form. Requires 2 government-issued ID documents and a selfie.",
      "type": "kyc",
      "status": "published",
      "slug": "acme-kyc-9f2c1a",
      "publicSlug": "acme-kyc-9f2c1a",
      "embeddable": true,
      "aiAgentEnabled": false,
      "isDefault": true,
      "submissionCount": 32,
      "createdAt": "2026-06-14T10:22:13.022Z"
    }
  ]
}

Os resultados são ordenados com o formulário padrão de cada tipo da organização em primeiro lugar e, em seguida, em ordem alfabética pelo nome.

Carregar e usar um formulário

Liste os formulários, escolha um (pelo nome ou pela flag isDefault) e envie o solicitante para a URL hospedada do formulário — https://app.certivant.com/forms/{slug} — ou incorpore-o quando embeddable for true. Para conduzir o fluxo de servidor para servidor, ignore a URL hospedada e crie uma solicitação diretamente.

curl -H "Authorization: Bearer $CERTIVANT_API_KEY" \
  "https://app.certivant.com/api/v1/kyc/forms?type=kyc"
# Pick a form's "slug", then send applicants to complete it at:
#   https://app.certivant.com/forms/{slug}

const res = await fetch(
  "https://app.certivant.com/api/v1/kyc/forms?type=kyc",
  { headers: { Authorization: `Bearer ${process.env.CERTIVANT_API_KEY}` } },
);
const { data: forms } = await res.json();

// Show the operator a picker, or grab the org's default published KYC form:
const form = forms.find((f) => f.isDefault) ?? forms[0];

// Send the applicant to the hosted form to complete their verification
// (or embed it in an <iframe> when form.embeddable is true):
const hostedUrl = `https://app.certivant.com/forms/${form.slug}`;

import os, requests

BASE = "https://app.certivant.com"
headers = {"Authorization": f"Bearer {os.environ['CERTIVANT_API_KEY']}"}

forms = requests.get(f"{BASE}/api/v1/kyc/forms",
                     headers=headers, params={"type": "kyc"}).json()["data"]

# The org's default published KYC form (or present a picker):
form = next((f for f in forms if f["isDefault"]), forms[0])

# Hosted form URL the applicant opens to complete the verification:
hosted_url = f"{BASE}/forms/{form['slug']}"

Referência de campos

Erros

Próximo passo

Depois de escolher um formulário, crie uma solicitação. Para que o solicitante a conclua em um navegador, gere uma URL de sessão hospedada ou incorpore o formulário usando o seu slug. Em seguida, leia o resultado — verificações, pontuação de risco e decisão — com Obter uma única solicitação.