Schemas und Aufzählungen

Kanonische TypeScript-Typen für jedes gemeinsame Certivant-Schema — Anfragestatus, Dokumenttypen, Prüfarten, Aufbau des Risiko-Scores, Felder für Antragsteller und Unternehmen (KYB), Webhook-Envelope und Paginierung.

Diese Seite sammelt die Aufzählungen und gemeinsamen Strukturen, die in mehreren Endpunkten vorkommen. Die vollständigen Schemas je Endpunkt finden Sie in der interaktiven Referenz unter /api/docs.

ID-Präfixe

Alle Certivant-Kennungen sind präfixierte Zeichenketten (nach dem Präfix im ULID-Stil). Das Präfix gehört zur Kennung — entfernen Sie es nicht.

Präfix	Ressource
`org_`	Organisation
`req_`	KYC-/KYB-Anfrage
`doc_`	Dokument
`app_`	Antragsteller
`kyb_`	KYB-Entitätsdatensatz
`check_`	Verifizierungsprüfung
`kyk_`	API-Schlüssel
`whsec_`	Signaturgeheimnis des Webhooks

Diese IDs sind dauerhaft stabil — sie werden nie wiederverwendet und ändern sich nach der Erstellung nie.

Anfragetypen

type RequestType = "INDIVIDUAL" | "BUSINESS";

INDIVIDUAL — KYC. Verifiziert eine natürliche Person.
BUSINESS — KYB. Verifiziert ein Unternehmen, seine Geschäftsführer und seine wirtschaftlich Berechtigten.

Anfragestatus

type RequestStatus =
  | "PENDING_UPLOAD"  // Awaiting documents
  | "PROCESSING"      // Submitted, automated checks running
  | "APPROVED"        // Cleared. Done.
  | "REJECTED"        // Failed. May be resubmitted.
  | "ESCALATED"       // Borderline. Awaiting human decision.
  | "CANCELLED";      // Withdrawn before completion.

Der Lebenszyklus verläuft streng vorwärts — sobald eine Anfrage APPROVED, REJECTED oder CANCELLED ist, springt sie nicht mehr zurück. REJECTED kann über /resubmit auf PENDING_UPLOAD zurückgesetzt werden; dabei entsteht auf demselben Datensatz ein neuer Pfad durch dieselbe Zustandsmaschine.

Dokumenttypen

type DocumentType =
  | "GOVERNMENT_ID"
  | "PASSPORT"
  | "SELFIE"
  | "PROOF_OF_ADDRESS"
  | "CERTIFICATE_OF_INCORPORATION"
  | "COMPANY_OWNERSHIP_STRUCTURE"
  | "BANK_STATEMENT"
  | "OTHER";

GOVERNMENT_ID ist der einzige Typ, der einen Parameter side benötigt (front / back).

Dokumentstatus

type DocumentStatus = "pending" | "verified" | "failed" | "corrupted";

pending — hochgeladen, noch nicht verarbeitet (wird nur vor der Einreichung der übergeordneten Anfrage gesehen).
verified — hat nach der Einreichung die Echtheitsprüfungen bestanden.
failed — hat mindestens eine Prüfung nicht bestanden. Die Gründe stehen in den verknüpften Prüfdatensätzen.
corrupted — die Datei konnte nicht dekodiert werden. Erneut hochladen.

Prüfarten

type CheckType =
  | "document_authenticity"
  | "ocr"
  | "face_match"
  | "liveness"
  | "sanctions_screening"
  | "pep_screening"
  | "adverse_media"
  | "proof_of_address"
  | "phone_verification"
  | "email_verification"
  | "registry_lookup";

type CheckResult = "pass" | "fail" | "review";

Eine Anfrage umfasst je nach Dokumentenset und den KYC-Einstellungen Ihrer Organisation typischerweise 4–8 Prüfungen.

Entscheidungen

Die Risiko-Engine liefert eine von drei Entscheidungen, die auf Anfragestatus abgebildet werden:

type RiskDecision = "approve" | "reject" | "escalate";

Entscheidung der Engine	Resultierender Status
`approve`	`APPROVED`
`reject`	`REJECTED`
`escalate`	`ESCALATED` (wartet auf manuelle Prüfung)

Risiko-Score

type RiskScore = {
  score: number;         // 0–100. Higher = lower risk
  decision: RiskDecision;
  factors: RiskFactor[];
  factorVerdicts?: { factor: string; verdict: "pass" | "fail" | "review" }[];
  disqualifiers?: string[];   // Hard blockers, e.g. "document_expired"
  reviewTriggers?: string[];  // Reasons for escalation
  reason?: string;       // Free-text summary for humans
};

type RiskFactor = {
  name: string;          // e.g. "face_match", "liveness"
  weight: number;        // 0–1, contribution to overall score
  score: number;         // 0–1, this factor's standalone score
};

Der Score dient zur Information. Das Feld decision steuert tatsächlich die Statuswechsel; die Score-Schwellen für Genehmigen, Eskalieren und Ablehnen lassen sich je Organisation im Dashboard unter KYC → Einstellungen → Schwellenwerte konfigurieren.

Aufbau des Antragstellers

type Applicant = {
  externalRef?: string;
  fullName?: string;
  dateOfBirth?: string;     // ISO 8601 date (YYYY-MM-DD)
  nationality?: string;     // ISO 3166-1 alpha-2 (2 chars)
  email?: string;
  phone?: string;           // E.164 format with leading +
  emailVerified?: boolean;
  phoneVerified?: boolean;
  metadata?: Record<string, unknown>;
};

Beim Erstellen sind alle Felder optional. Was fehlt, kann der Antragsteller über eine gehostete Sitzung ergänzen, oder es bleibt leer, sofern die zugrunde liegenden Prüfungen es nicht benötigen (Sie können z. B. eine reine Sanktionsprüfung nur mit fullName und dateOfBirth durchführen).

Aufbau der KYB-Entität

type KybEntity = {
  companyName: string;
  registrationNo?: string;
  countryOfIncorp?: string; // ISO 3166-1 alpha-2
  companyType?: string;     // "private_limited" | "llc" | "partnership" | "sole_trader" | …
  directors?: Director[];
  ubos?: Ubo[];
};

type Director = {
  fullName: string;
  dateOfBirth?: string;
  nationality?: string;
  appointedAt?: string;     // ISO 8601 date
};

type Ubo = {
  fullName: string;
  dateOfBirth?: string;
  nationality?: string;
  ownershipPercentage?: number;  // 0–100
};

Webhook-Envelope

type WebhookPayload = {
  event: KycWebhookEventType;
  requestId: string;
  organizationId: string;
  externalRef?: string;
  subTenantName?: string;        // Partner mode: end-customer display name
  subTenantExternalId?: string;  // Partner mode: your end-customer id
  status: RequestStatus;
  timestamp: string;        // ISO 8601
  data?: Record<string, unknown>;  // Event-specific
};

type KycWebhookEventType =
  | "kyc.request.created"
  | "kyc.request.processing"
  | "kyc.request.approved"
  | "kyc.request.rejected"
  | "kyc.request.escalated"
  | "kyc.request.cancelled"
  | "kyc.document.uploaded"
  | "kyc.check.completed";

Die data-Struktur je Ereignis finden Sie unter Webhook-Ereignisse.

Paginierung

type PaginatedResponse<T> = {
  data: T[];
  pagination: {
    total: number;   // Total matching rows across all pages
    page: number;    // Current page, 1-indexed
    limit: number;   // Page size
    pages: number;   // Total page count
  };
};

Verwenden Sie limit bis zu 100, um Round-Trips zu minimieren. Ohne Angabe beträgt der Standard 20.

Länder- und Währungscodes

Länder: ISO 3166-1 alpha-2 (US, GB, FR, JP). Kleinbuchstaben werden akzeptiert, in Antworten jedoch in Großbuchstaben normalisiert.
Telefonnummern: E.164 mit führendem + (+14155551234).
Datumsangaben: ISO 8601 (YYYY-MM-DD). Zeitstempel mit Zeitzone (2026-05-27T10:00:00.000Z).
Währungen: dreistellige ISO-4217-Codes (USD, EUR, GBP).

Weitere Informationen

Die interaktive Referenz unter /api/v1/docs (ebenfalls auf der Seite API-Referenz eingebettet) zeigt jeden Endpunkt mit Live-Anfrage-Erstellern.
Das rohe OpenAPI-3.1-JSON unter /api/v1/openapi.json — importieren Sie es in Postman, generieren Sie Clients oder übergeben Sie es Ihrem bevorzugten Code-Generator.

Beide sind öffentlich: Es sind weder Anmeldung noch API-Schlüssel nötig, und sie beschreiben nur die Endpunkte /api/v1/kyc/**, für die Sie entwickeln. Die Schemas, Berechtigungsbereiche und Fehlerantworten je Endpunkt im OpenAPI-Dokument sind die maßgebliche Quelle; diese Seite sammelt lediglich die Strukturen, die sich über mehrere Endpunkte wiederholen.

Schemas und Aufzählungen

On this page