Richieste KYB

KYB ("Know Your Business") verifica l'identità e la struttura di un'entità aziendale. Il ciclo di vita è lo stesso della KYC — creazione, caricamento dei documenti di supporto, invio, ricezione di una decisione — ma con un passaggio in più: si invia un payload dei dati dell'entità KYB che descrive l'azienda e i suoi principali.

Crei la richiesta con type: "BUSINESS", poi esegua una POST sull'endpoint /kyb per allegare i dati dell'entità.

L'estensione KYB

POST /api/v1/kyc/requests/:id/kyb    Ambito: kyc:write

Allega i dati dell'azienda, gli amministratori e i titolari effettivi (UBO) a una richiesta BUSINESS esistente.

Corpo della richiesta

{
  "companyName": "Acme Holdings Ltd",
  "registrationNo": "12345678",
  "countryOfIncorp": "GB",
  "companyType": "private_limited",
  "directors": [
    {
      "fullName": "Jane Doe",
      "dateOfBirth": "1975-06-22",
      "nationality": "GB",
      "appointedAt": "2018-01-15"
    }
  ],
  "ubos": [
    {
      "fullName": "Jane Doe",
      "dateOfBirth": "1975-06-22",
      "nationality": "GB",
      "ownershipPercentage": 100
    }
  ]
}

Ogni amministratore e ogni UBO riporta fullName, dateOfBirth, nationality e i campi specifici del ruolo (appointedAt per gli amministratori, ownershipPercentage per gli UBO).

Risposta (201)

{ "id": "req_...", "status": "PENDING_UPLOAD" }

La risposta avvia anche una ricerca nel registro in background — Certivant interroga il registro delle imprese competente (Companies House per il Regno Unito, OpenCorporates per molti altri paesi) e salva i risultati sulla richiesta. I risultati del registro sono consultabili in GET /kyb.

Ottieni i dati KYB

GET /api/v1/kyc/requests/:id/kyb    Ambito: kyc:read

Restituisce i dati dell'entità inviati insieme agli eventuali risultati della ricerca nel registro.

Risposta

{
  "id": "kyb_...",
  "requestId": "req_...",
  "companyName": "Acme Holdings Ltd",
  "registrationNo": "12345678",
  "countryOfIncorp": "GB",
  "companyType": "private_limited",
  "directors": [...],
  "ubos": [...],
  "registryLookup": {
    "status": "verified",
    "registryName": "Companies House",
    "registryUrl": "https://find-and-update.company-information.service.gov.uk/company/12345678",
    "registeredName": "Acme Holdings Ltd",
    "registeredAddress": "1 Example St, London",
    "status": "active",
    "incorporatedAt": "2018-01-15",
    "officerDelta": [],
    "raw": { ... }
  }
}

registryLookup.officerDelta elenca eventuali amministratori trovati nel registro ma non dichiarati nell'array directors — utile per individuare informazioni mancanti.

Documenti richiesti

Una richiesta BUSINESS richiede di norma un insieme di documenti diverso da quello di una persona fisica:

• CERTIFICATE_OF_INCORPORATION — prova che l'azienda esiste.
• PROOF_OF_ADDRESS — per la sede legale.
• GOVERNMENT_ID e SELFIE per ciascun UBO e amministratore (in alcune configurazioni vengono inseriti in sotto-richieste per singolo richiedente).
• COMPANY_OWNERSHIP_STRUCTURE — organigramma o libro dei soci.

L'elenco esatto compare in pendingDocTypes sulla richiesta dopo che è stata allegata l'entità KYB. Le impostazioni KYB della Sua organizzazione determinano ciò che è richiesto.

Sotto-richieste KYC per ogni amministratore

A seconda delle impostazioni della Sua organizzazione, Certivant può creare automaticamente sotto-richieste KYC individuali per ogni UBO e amministratore. Compaiono come richieste separate collegate alla richiesta BUSINESS madre tramite il campo parentRequestId. I documenti si caricano in ciascuna sotto-richiesta allo stesso modo in cui si caricano in una richiesta KYC autonoma — vedi Documenti.

graph LR
  Parent[BUSINESS request<br/>req_parent] --> Co[Company docs<br/>incorporation, address]
  Parent --> Ubo1[UBO 1 sub-request<br/>req_ubo1]
  Parent --> Ubo2[UBO 2 sub-request<br/>req_ubo2]
  Parent --> Dir1[Director sub-request<br/>req_dir1]
  Ubo1 --> Id1[GOVERNMENT_ID + SELFIE]
  Ubo2 --> Id2[GOVERNMENT_ID + SELFIE]
  Dir1 --> Id3[GOVERNMENT_ID + SELFIE]

La richiesta madre resta in PENDING_UPLOAD finché ogni sotto-richiesta non è almeno in PROCESSING, poi attraversa lo stesso ciclo di vita di una richiesta individuale — PROCESSING → APPROVED / REJECTED / ESCALATED.

Invio e decisione

Una volta caricati i documenti dell'azienda e inviate tutte le sotto-richieste, invii la richiesta madre:

curl -X POST https://app.certivant.com/api/v1/kyc/requests/req_parent/submit \
  -H "Authorization: Bearer ck_live_..."

Il motore di rischio aggrega i controlli aziendali della richiesta madre e l'esito di ogni sotto-richiesta in un'unica decisione. Gli eventi webhook vengono attivati per la richiesta madre — non è necessario tracciare separatamente ogni sotto-richiesta, a meno che non si desideri una vista di dettaglio.

Errori

• 400 BAD_REQUEST — la richiesta non è di tipo BUSINESS. Gli endpoint KYB funzionano solo sulle richieste business.
• 409 CONFLICT — i dati KYB sono già stati allegati. Per modificarli, contatti l'assistenza: i dati dell'entità fanno parte della traccia di audit e non possono essere modificati liberamente.

Correlati

• Richieste KYC — gli endpoint sottostanti della richiesta, stesso ciclo di vita.
• Documenti — caricamento della prova di costituzione e dei documenti per singolo amministratore.
• Webhook — si applicano gli stessi eventi kyc.request.*.