Forms

List a tenant's KYC and KYB verification forms via the Certivant REST API — discover which form to run a verification against, filter by type, and read each form's slug, status, and embeddable flag.

A form defines what an applicant fills in and which documents + checks a verification collects. Before you create a KYC/KYB request, list the tenant's forms so you can show the operator a picker or resolve the right form by name.

This is the same list the Certivant dashboard renders under Forms — the REST endpoint returns it for your API key's organization only.

All endpoints require an API key. See Authentication.

List forms

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

Returns the calling organization's KYC and KYB forms. By default only published forms are returned (the ones you can actually run a verification against).

Query parameters

Parameter	Values	Default	Description
`type`	`kyc` · `kyb` (aliases `INDIVIDUAL` · `BUSINESS` accepted)	both	Restrict to individual (KYC) or business (KYB) forms.
`status`	`all`	`published`	Pass `all` to also include `draft` and `archived` forms.

Examples:

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

Response

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

Results are ordered with the tenant's default form for each type first, then alphabetically by name.

Load and use a form

List the forms, pick one (by name or the isDefault flag), then send the applicant to its hosted URL — https://app.certivant.com/forms/{slug} — or embed it when embeddable is true. To drive the flow server-to-server instead, skip the hosted URL and create a request directly.

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

Field reference

Field	Description
`id`	Form ID.
`name`	Human-readable form name (what the dashboard shows).
`type`	`kyc` (individual) or `kyb` (business).
`status`	`published` · `draft` · `archived`. Only `published` forms can back a live verification.
`slug` / `publicSlug`	URL-safe slug. `slug` mirrors `publicSlug`. Use it to build the hosted form URL — `https://app.certivant.com/forms/{slug}` — that applicants open to complete the verification. `null` for unpublished forms.
`embeddable`	`true` if the form may be embedded via `<iframe>` / `<script>` on your own site.
`aiAgentEnabled`	`true` if AI agents may submit this form via the REST API.
`isDefault`	`true` for the org's provisioned default KYC / KYB form.
`submissionCount`	Total submissions received through this form.
`createdAt`	ISO 8601 creation timestamp.

Errors

Status	When
`401`	Missing or invalid API key.
`403`	The key lacks the `kyc:read` scope.
`429`	Rate limit exceeded (120 requests / minute per tenant).

Next step

Once you've picked a form, create a request. To let the applicant complete it in a browser, generate a hosted session URL or embed the form using its slug. Then read the result — checks, risk score, and decision — with Get a single request.