Schemi ed enumerazioni

Tipi TypeScript canonici per ogni schema condiviso di Certivant — stati delle richieste, tipi di documento, tipi di controllo, forma del punteggio di rischio, campi del richiedente e dell'entità KYB, busta dei webhook e paginazione.

Questa pagina raccoglie le enumerazioni e le forme condivise che compaiono in più endpoint. Gli schemi completi per endpoint si trovano nel riferimento interattivo su /api/docs.

Prefissi degli ID

Tutti gli identificativi di Certivant sono stringhe con prefisso (in stile ULID dopo il prefisso). Il prefisso fa parte dell'identificativo — non lo rimuova.

Prefisso	Risorsa
`org_`	Organizzazione
`req_`	Richiesta KYC / KYB
`doc_`	Documento
`app_`	Richiedente
`kyb_`	Record dell'entità KYB
`check_`	Controllo di verifica
`kyk_`	Chiave API
`whsec_`	Segreto di firma del webhook

Questi ID sono stabili per sempre — non vengono mai riciclati e non cambiano dopo la creazione.

Tipi di richiesta

type RequestType = "INDIVIDUAL" | "BUSINESS";

INDIVIDUAL — KYC. Verifica una persona fisica.
BUSINESS — KYB. Verifica un'azienda, i suoi amministratori e i suoi titolari effettivi.

Stati della richiesta

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.

Il ciclo di vita procede solo in avanti: una volta che una richiesta è APPROVED, REJECTED o CANCELLED, non torna indietro. REJECTED può essere riportata a PENDING_UPLOAD tramite /resubmit, che crea un nuovo percorso attraverso la stessa macchina a stati sullo stesso record.

Tipi di documento

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

GOVERNMENT_ID è l'unico tipo che richiede un parametro side (front / back).

Stati dei documenti

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

pending — caricato, non ancora elaborato (visibile solo prima dell'invio della richiesta madre).
verified — ha superato i controlli di autenticità dopo l'invio.
failed — non ha superato almeno un controllo. I motivi compaiono nei record di controllo collegati.
corrupted — il file non può essere decodificato. Lo carichi di nuovo.

Tipi di controllo

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

Una richiesta di norma ha da 4 a 8 controlli, a seconda del set di documenti e delle impostazioni KYC della Sua organizzazione.

Decisioni

Il motore di rischio produce una delle tre decisioni, che corrispondono agli stati della richiesta:

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

Decisione del motore	Stato risultante
`approve`	`APPROVED`
`reject`	`REJECTED`
`escalate`	`ESCALATED` (attende la revisione umana)

Punteggio di rischio

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
};

Il punteggio è informativo. Il campo decision è ciò che guida effettivamente le transizioni di stato, e le soglie di punteggio per approvare, inoltrare o rifiutare sono configurabili per organizzazione nella dashboard in KYC → Impostazioni → Soglie.

Forma del richiedente

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>;
};

Tutti i campi sono facoltativi alla creazione. Ciò che manca può essere compilato dal richiedente tramite una sessione ospitata, oppure lasciato vuoto se i controlli sottostanti non lo richiedono (per esempio può eseguire uno screening solo sulle sanzioni con soltanto fullName e dateOfBirth).

Forma dell'entità KYB

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
};

Busta del webhook

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

Vedi Eventi webhook per la forma di data di ogni evento.

Paginazione

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
  };
};

Usi limit fino a 100 per ridurre i viaggi di andata e ritorno. Il valore predefinito è 20 se lo omette.

Codici di paese e di valuta

Paesi: ISO 3166-1 alpha-2 (US, GB, FR, JP). Le lettere minuscole sono accettate, ma nelle risposte vengono normalizzate in maiuscolo.
Numeri di telefono: E.164 con + iniziale (+14155551234).
Date: ISO 8601 (YYYY-MM-DD). Timestamp con fuso orario (2026-05-27T10:00:00.000Z).
Valute: codici a tre lettere ISO 4217 (USD, EUR, GBP).

Dove trovare altro

Il riferimento interattivo su /api/v1/docs (incorporato anche nella pagina Riferimento API) mostra ogni endpoint con costruttori di richieste dal vivo.
Il JSON OpenAPI 3.1 grezzo su /api/v1/openapi.json — lo importi in Postman, generi client, oppure lo dia in pasto al Suo generatore di codice preferito.

Entrambi sono pubblici: non serve alcun accesso né una chiave API, e descrivono solo gli endpoint /api/v1/kyc/** su cui costruisce. Gli schemi per endpoint, gli ambiti e le risposte di errore del documento OpenAPI sono la fonte autorevole; questa pagina raccoglie soltanto le forme che si ripetono tra gli endpoint.

Schemi ed enumerazioni

On this page