> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.
# Crea sessione API: avvia verifica KYC o KYB
> POST /v3/session/ di Didit avvia una verifica KYC o KYB. Endpoint unificato, prezzi a consumo, inferenza in meno di 2s, $10 di credito al mese.
Prompt per creare una sessione
Copia il prompt negli appunti
\
\`Create a verification session via Didit's REST API.
Endpoint:
POST https://verification.didit.me/v3/session/
Authentication:
Use the x-api-key header with your Didit API key. The workflow's type (KYC or KYB) determines which kind of session is created — there is no separate endpoint for KYB.
Request body:
\- workflow_id (string, UUID, required) — Stable workflow UUID from /v3/workflows/. KYC workflows create User Verification sessions; KYB workflows create Business Verification sessions.
\- vendor_data (string, optional) — Your stable identifier for the entity (user or business). Strongly recommended: it binds the session to a User or Business entity and is used for duplicate detection across sessions.
\- callback (string, URL, optional): Where the hosted flow redirects the user when finished. Didit appends ?verificationSessionId={session_id}&status={status}. Falls back to the workflow default. When the application has allowed domains (allowed_domains on PATCH /v3/webhook/), an http or https callback must be on one of those origins (same scheme, host and port), otherwise creation fails with 400 on callback: "callback must be on one of the application's allowed domains: https://app.example.com". Custom URL schemes (app deep links such as myapp://) are always accepted. A workflow-default callback outside the allowed domains is not used for the redirect.
\- callback_method (string, optional, default "initiator") — One of "initiator", "completer", "both". Use "both" if the callback sometimes fails to fire.
\- metadata (object, optional) — Arbitrary JSON echoed back in responses and webhooks. Not shown to the user.
\- tags (array of strings, optional): Tags added to the session when it is created, by name, for example ["VIP", "ONBOARDING Q4"]. Up to 10, each up to 50 characters. Names are case-insensitive and stored in upper case; a name that does not exist yet in the application is created as a new tag. The tags show on the session in the console, where you can filter by them, and come back in the create response.
\- language (string, optional) — ISO 639-1 code for the verification UI (en, es, fr, de, pt, etc.). Defaults to browser detection.
\- contact_details (object, optional) — { email, send_notification_emails, email_lang, phone }. Pre-fills phone/email steps and (optionally) sends notification emails.
\- expected_details (object, optional) — Expected first_name, last_name, date_of_birth, nationality (ISO-3), id_country (ISO-3), expected_document_types (e.g. ["P","ID","DL","RP","SSC"]). Mismatches surface as decision warnings. For Business Verification (KYB) workflows, pass the business fields instead — company_name, registry_country, registration_number — to pre-fill the company registry search; registry_country is ISO 3166-1 alpha-2 and can include the state for state-level registries (e.g. "US-CA"), same format as the KYB Registry Search country_code. Person-level fields are ignored on KYB sessions.
\- portrait_image (string, base64, conditional) — Reference face for Biometric Authentication workflows (and graph workflows where Face Match runs before ID Verification). Max 2MB; JPEG, PNG, WebP, or TIFF. Optional when the vendor_data user already has a stored face: Didit reuses it automatically (approved liveness face, then ePassport chip photo, then ID document portrait, then a manually enrolled profile face). If omitted and no stored face exists, creation fails with 400. Ignored for other workflow types.
\- multi_account_segment (string, optional, max 64 chars) — Duplicate-detection realm inside your own organization. Duplicate face checks only compare this session against other sessions carrying the same segment, so an organization that runs separate account bases (personal vs business, or one per sub-client) does not see a person who legitimately holds one account in each reported as a duplicate. Omit it to use the single default realm — which is what every session uses today, so existing integrations are unaffected. Blocklist and allowlist matching ignore this field: a blocklisted face stays blocklisted in every segment.
\- sandbox_scenario (string, optional, sandbox applications only): Scenario slug from the sandbox catalog (GET /v1/sandbox/scenarios/). Expands the scenario's bundled magic values onto contact_details/expected_details so the session reproduces that outcome. Rejected with 400 on live applications. You can also arm or re-arm a scenario after create, as long as the session is still Not Started, via POST /v3/session/{session_id}/sandbox/arm/. See /integration/sandbox-testing.
\- user_state (string, optional, max 16 chars): Where the person lives, when you know it: an ISO 3166-2 code (US-IL) or a US state code or name (IL, Illinois). In Auto consent mode, Illinois, Texas or Colorado makes the flow ask for explicit biometric consent before the first face capture. 400 on an unrecognized value.
\- biometric_consent (object, optional): Consent you already collected: { given_at (ISO 8601, not in the future), text_version (max 64 chars) }. The flow does not ask again; the decision records it as given with trigger customer_collected.
\- sign (object, optional): { documents: [ { title, file_name, content_base64, fields } ], field_values: { : value } }. documents is for a workflow whose E-signature step takes documents from the session (signature_documents_source "session" or "both"). file_name ends in .pdf or .docx; content_base64 is the file in base64. Up to 20 documents and 50 MB in total; a PDF up to 20 MB and 100 pages, without a password, scripts or attachments; a Word file (.docx) up to 20 MB, converted to PDF while the request runs, at most 5 per session. fields is optional (up to 200 per document): signature, initials, full_name, date_signed, text, checkbox, email or data fields, each with a key unique in its document (^[a-z][a-z0-9_]{0,63}$), placed by page, x, y, width and height, or by anchor text ({ text, occurrence, offset_x, offset_y, width, height }). role defaults to the step's signer. field_values fills the fields whose prefill is "api.", on workflow and session documents alike: strings of 1 to 500 characters, booleans for checkboxes. 400 when the workflow has no E-signature step, takes workflow documents only and you sent documents, or needs session documents you didn't send; field_anchor_not_found, field_value_unknown, field_value_missing or field_value_invalid for fields and values. See /core-technology/electronic-signature/overview.
Idempotency:
Within one application, only one non-finished session can exist per (workflow_id, vendor_data). Calling create again with the same pair returns the existing session (and updates its callback + metadata, and adds any tags you send) instead of creating a duplicate. If you send sign again, its documents, fields and field values must be identical (same order, titles, file names, content, fields and values), or the call returns 400 { "sign": "signature_document_changed" }.
curl example:
curl -X POST https://verification.didit.me/v3/session/ \
-H "x-api-key: " \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "",
"vendor_data": "user-42",
"callback": "https://yourapp.com/callback",
"metadata": { "plan": "premium" }
}'
Response (201 Created) — keys you must handle:
\- session_id (UUID) — use this on every subsequent /v3/session/{session_id}/... call.
\- session_kind ("user" | "business") — discriminator, dispatch on this.
\- session_number (int) — human-friendly per-application sequence.
\- session_token (string) — short-lived, embedded in the hosted URL. Treat as secret.
\- url (string) — hosted verification URL. Redirect the end user here. (Field name is "url", NOT "verification_url".)
\- status (string) — newly created sessions return "Not Started".
\- workflow_id, workflow_version, vendor_data, metadata, callback — echoed back.
See /reference/data-models for the full schema.
Failure modes:
\- 400 — { "workflow_id": ["Invalid workflow_id."] } when the UUID is unknown.
\- 400 — { "vendor_data": ["This user or business has been blocked and cannot create new verification sessions."] } when blocklisted.
\- 400 — { "detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } when out of credits.
\- 400 — { "portrait_image": "No stored face image was found for this user. Send a portrait_image, or complete an approved verification with face liveness or an ID document for this vendor_data first." } on a Face Match workflow when portrait_image is omitted and the vendor_data user has no stored face.
\- 401 — invalid or missing API key.
\- 403 — { "detail": "You do not have permission to perform this action." } when the key lacks write:sessions.
\- 429 — rate limited (600 successful calls/minute per token/IP). Honour Retry-After.
Disclosure & consent:
This endpoint generates a URL — it does not record that you obtained user consent. Show your privacy notice and any biometric-specific consent in your own UX before redirecting to the hosted flow.
For people covered by Illinois, Texas or Colorado law, the hosted flow and native SDK 4.10.0 or later can ask for explicit biometric consent before the selfie; native SDKs below 4.10.0 cannot show that step. See /getting-started/biometric-consent.
Next step:
After the user finishes (status changes to Approved / Declined / In Review), call GET https://verification.didit.me/v3/session/{session_id}/decision/ for the full decision — see /sessions-api/retrieve-session.
For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`
\
Incolla in
## Supporto KYC e KYBUn unico endpoint crea sia sessioni di Verifica degli utenti sia sessioni di Verifica aziendale. Il **tipo di workflow** determina il tipo di sessione:- Passa un `workflow_id` di un **Workflow KYC** → viene creata una sessione di Verifica degli utenti (KYC). Risposta `session_kind: "user"`.
- Passa un `workflow_id` di un **workflow KYB** → viene creata una sessione di Verifica aziendale (KYB). Risposta `session_kind: "business"`.Configura i workflow nella console in *Workflows → Create workflow*. Al momento della creazione, un workflow è KYC oppure KYB; in seguito non puoi cambiarne il tipo.## Esempi> [tab] Verifica degli utenti (KYC)
>
> ```bash theme={null}
> curl -X POST https://verification.didit.me/v3/session/ \
> -H "x-api-key: YOUR_API_KEY" \
> -H "Content-Type: application/json" \
> -d '{
> "workflow_id": "YOUR_KYC_WORKFLOW_ID",
> "vendor_data": "user-42",
> "callback": "https://yourapp.com/callback"
> }'
> ```
>
> **Risposta (201 Created):**
>
> ```json theme={null}
> {
> "session_id": "4c5c7f3a-1f82-4f3b-8d8e-1a8d2d2f9b7a",
> "session_kind": "user",
> "session_number": 1024,
> "session_token": "...",
> "url": "https://verify.didit.me/session/...",
> "status": "Not Started",
> "workflow_id": "YOUR_KYC_WORKFLOW_ID",
> "vendor_data": "user-42"
> }
> ```> [tab] Verifica aziendale (KYB)
>
> ```bash theme={null}
> curl -X POST https://verification.didit.me/v3/session/ \
> -H "x-api-key: YOUR_API_KEY" \
> -H "Content-Type: application/json" \
> -d '{
> "workflow_id": "YOUR_KYB_WORKFLOW_ID",
> "vendor_data": "biz-acme-001",
> "callback": "https://yourapp.com/callback"
> }'
> ```
>
> **Risposta (201 Created):**
>
> ```json theme={null}
> {
> "session_id": "bs-01HJX1...",
> "session_kind": "business",
> "session_number": 89,
> "session_token": "...",
> "url": "https://verify.didit.me/session/...",
> "status": "Not Started",
> "workflow_id": "YOUR_KYB_WORKFLOW_ID",
> "vendor_data": "biz-acme-001"
> }
> ```## Documenti di firma elettronicaQuando il workflow include un passaggio di [Firma elettronica](https://docs.didit.me/it/core-technology/electronic-signature/overview.md) che usa i documenti della sessione (`signature_documents_source` impostato su `session` o `both`), invia i documenti in `sign.documents`. Ogni documento è il file in base64, quindi Didit non deve mai recuperarlo da un URL.```json theme={null}
{
"workflow_id": "YOUR_WORKFLOW_ID",
"vendor_data": "user-42",
"sign": {
"documents": [
{
"title": "Loan agreement",
"file_name": "loan-agreement.pdf",
"content_base64": "JVBERi0xLjcKJc...",
"fields": [
{ "key": "borrower_signature", "type": "signature", "label": "Borrower signature", "page": 3, "x": 0.1, "y": 0.78, "width": 0.32, "height": 0.06 },
{ "key": "date_signed", "type": "date_signed", "label": "Date", "page": 3, "x": 0.6, "y": 0.8, "width": 0.2, "height": 0.03, "date_format": "DD/MM/YYYY" },
{ "key": "loan_amount", "type": "data", "label": "Loan amount", "page": 1, "x": 0.34, "y": 0.31, "width": 0.3, "height": 0.03, "prefill": "api.loan_amount" },
{ "key": "initials", "type": "initials", "anchor": { "text": "[[initials]]", "occurrence": "all", "offset_x": 0, "offset_y": -0.005, "width": 0.12, "height": 0.04 } }
]
}
],
"field_values": { "loan_amount": "12,000 EUR" }
}
}
```| Campo | Regole |
| - | - |
| `title` | Mostrato al firmatario. Da 1 a 255 caratteri. Predefinito su `file_name`. |
| `file_name` | Obbligatorio. Termina con `.pdf` o `.docx`. Da 1 a 255 caratteri. |
| `content_base64` | Obbligatorio. Un PDF può avere fino a 20 MB e 100 pagine, senza password, script o file allegati. Un file Word può avere fino a 20 MB e viene convertito in PDF durante l'esecuzione della richiesta, in un massimo di 25 secondi; il PDF ha poi gli stessi limiti. Fino a 5 file Word per sessione. |
| `fields` | Facoltativo. Fino a 200 [campi](https://docs.didit.me/it/core-technology/electronic-signature/overview.md#campi-sul-documento) da posizionare sul documento, nella forma del campo senza `id`. Ogni campo richiede una `key` e un `type`, e una posizione (`page`, `x`, `y`, `width` e `height`) oppure una [`anchor`](#posiziona-i-campi-tramite-testo-di-ancoraggio). `role` ha come predefinito il firmatario dello step, mentre `required` e `label` derivano dal tipo di campo. Didit imposta `position` in base a dove si trova il campo. Pagine e posizioni si riferiscono al PDF, o al PDF convertito per un file Word. |Senza `fields`, il firmatario legge il documento e lo accetta.### Posiziona i campi tramite testo di ancoraggioInvece di una posizione, un campo può avere un `anchor`: un testo nel documento che indica dove va il campo. Le ancore sono adatte ai documenti che generi per ogni sessione, per esempio da un modello Word. Per i documenti del workflow, posiziona i campi nella console.| Proprietà `anchor` | Regole |
| - | - |
| `text` | Da 1 a 64 caratteri, cercati nel testo del documento. Per un file Word, nel PDF convertito. |
| `occurrence` | `first` (predefinito) posiziona un solo campo alla prima corrispondenza. `all` posiziona un campo per ogni corrispondenza, e le chiavi dopo la prima ricevono `_2`, `_3` e così via. |
| `offset_x`, `offset_y` | Frazioni della pagina. L'angolo in alto a sinistra del campo coincide con l'angolo in alto a sinistra del testo di ancoraggio più questi offset. |
| `width`, `height` | Dimensioni del campo, come frazioni della pagina. |Se il testo non è nel documento, la chiamata restituisce `400` con `field_anchor_not_found` e la chiave del campo. Didit non rimuove il testo di ancoraggio dal PDF, quindi scrivilo con lo stesso colore dello sfondo della pagina.### Valori dei campi`sign.field_values` imposta il valore di ogni campo il cui `prefill` è `api.`, sia nei documenti del workflow sia in quelli della sessione. È un oggetto con chiavi corrispondenti a questi nomi ``. I valori sono stringhe da 1 a 500 caratteri per i campi `text` e `data`, e booleani per un `checkbox`.```json theme={null}
{
"workflow_id": "YOUR_WORKFLOW_ID",
"vendor_data": "user-42",
"sign": {
"field_values": { "credit_limit": "3,000 EUR", "monthly_fee": "4.90 EUR" }
}
}
```| Errore (`400`) | Quando |
| - | - |
| `field_value_unknown` | Una chiave che nessun campo usa. |
| `field_value_missing` | Un campo obbligatorio il cui `api.` non ha un valore. |
| `field_value_invalid` | Un valore che non supera la [validazione](https://docs.didit.me/it/core-technology/electronic-signature/overview.md#validazione) del proprio campo. |### Errori e chiamate ripetuteUna sessione accetta fino a 20 documenti e 50 MB in totale. La chiamata restituisce `400` con un errore `sign` quando:- Il workflow non ha un passaggio di Firma elettronica.
- Hai inviato `sign.documents` e il passaggio accetta solo i documenti del workflow.
- Il passaggio accetta solo i documenti della sessione e non ne hai inviati, oppure non ha documenti del workflow e non ne hai inviati.
- Un documento è troppo grande, non è base64 valido o non è un file supportato.
- Un file Word viene rifiutato con `signature_document_not_supported`, oppure non può essere convertito e restituisce `signature_document_conversion_failed`; in entrambi i casi è riportato il `reason` elencato in [File supportati](https://docs.didit.me/it/core-technology/electronic-signature/overview.md#file-supportati).
- Un campo non è valido, la sua ancora non viene trovata (`field_anchor_not_found`), oppure un [valore del campo](#valori-dei-campi) viene rifiutato.Chiamare nuovamente l'endpoint di creazione per lo stesso `workflow_id` e `vendor_data` restituisce la sessione in attesa. Se questa chiamata invia `sign`, i suoi documenti, campi e valori dei campi devono essere identici ai primi (stesso ordine, titoli, nomi dei file, contenuto, campi e valori). Qualsiasi differenza restituisce `400` con `{"sign": "signature_document_changed"}`: usa un `vendor_data` diverso, oppure attendi che la sessione in attesa termini.## Test con scenari sandboxIn un'applicazione in modalità sandbox, passa `sandbox_scenario` per precaricare un esito deterministico (approvazione, un rifiuto specifico o uno scenario In revisione) senza toccare i provider reali né il tuo saldo:```json theme={null}
{
"workflow_id": "YOUR_SANDBOX_WORKFLOW_ID",
"sandbox_scenario": "decline_document_expired"
}
````sandbox_scenario` viene rifiutato con `400` nelle applicazioni in ambiente di produzione. Se al momento della creazione non conosci ancora l'esito, puoi impostarlo (o reimpostarlo) in seguito tramite `POST /v3/session/{session_id}/sandbox/arm/`, finché la sessione è ancora `Not Started`: il selettore dello scenario prima del flusso ospitato usa questo stesso endpoint. Consulta [Sandbox e dati di test](https://docs.didit.me/it/integration/sandbox-testing.md) per il catalogo completo degli scenari, il registro dei valori magici e la struttura di richiesta e risposta dell'endpoint arm.## `vendor_data` collega la sessione a un'entità- Per i workflow KYC: viene collegato a un'[entità utente](https://docs.didit.me/it/entities/users/overview.md). Se l'utente non esiste, viene creato automaticamente.
- Per i workflow KYB: viene collegato a un'[entità aziendale](https://docs.didit.me/it/entities/businesses/overview.md). Se è nuova, viene creata automaticamente.Per saperne di più, leggi [collegamento dei vendor data](https://docs.didit.me/it/entities/vendor-data-linking.md).## Consenso biometrico in Illinois, Texas e ColoradoIl flusso ospitato e l'SDK nativo 4.10.0 o successivo possono mostrare un passaggio esplicito di consenso biometrico prima della prima acquisizione del volto, a seconda della modalità di consenso dell'applicazione e della località della persona. Due campi facoltativi alimentano questa decisione:- `user_state`: dove vive la persona, quando lo conosci (`US-IL`, `IL` o `Illinois`). In modalità Auto, uno stato coperto fa sì che il flusso chieda il consenso.
- `biometric_consent`: un oggetto con `given_at` e `text_version`, per il consenso che hai già raccolto. Il flusso non lo richiede di nuovo.Gli SDK nativi precedenti alla 4.10.0 non possono mostrare questo passaggio: le loro sessioni funzionano come prima e la decisione riporta il consenso come non raccolto. Vedi [Consenso biometrico](https://docs.didit.me/it/getting-started/biometric-consent.md).## Importante: l'informativa viene fornita e il consenso viene raccolto ancora nel tuo prodotto`Create Session` genera un URL di verifica e un token di sessione. Di per sé **non** dimostra che hai mostrato all'utente le informative o ottenuto il consenso richiesto per il tuo specifico caso d'uso.Se avvii una sessione Didit dalla tua applicazione, dal tuo sito web, da un wrapper SDK o da un flusso white label, devi gestire lo strato legale nella tua UX prima che l'utente inizi l'acquisizione.## Checklist consigliata prima della verifica1. Comunica all'utente che **la tua azienda** richiede la verifica e che **Didit** è il fornitore di verifica / responsabile del trattamento che supporta il flusso.
2. Inserisci un link alla **tua informativa sulla privacy** e agli eventuali termini legali del titolare del trattamento applicabili al percorso.
3. Inserisci un link alla [Informativa sulla privacy per la verifica](https://didit.me/terms/verification-privacy-notice) di Didit e ai [Termini per l'utente finale per la verifica dell'identità](https://didit.me/terms/identity-verification).
4. Se il tuo workflow include l'acquisizione del documento o del selfie, il Rilevamento della vitalità o l'uso di dati biometrici, raccogli un **consenso esplicito e affermativo** ogni volta che la legge applicabile o la tua posizione legale lo richiedono.
5. Se usi un'interfaccia personalizzata, un dominio personalizzato o un percorso solo API, mostra queste informative nel tuo prodotto prima di inviare l'utente al flusso Didit.
6. Conserva una tua registrazione del testo dell'informativa o del consenso, del timestamp e dei metadati correlati, se il tuo team legale richiede una traccia di audit.> [!WARNING]
>
> I requisiti legali variano in base alla giurisdizione. Il branding white label non elimina il ruolo di Didit nel flusso di verifica. Prima del lancio, fai rivedere la tua implementazione da un legale se operi in giurisdizioni con norme specifiche sui dati biometrici.
## OpenAPI
````yaml it/openapi-25.json POST /v3/session/
openapi: 3.0.0
info:
version: 3.0.0
title: Didit Verification API
description: API di verifica dell'identità. Autenticati con l'intestazione x-api-key.
servers:
- url: https://verification.didit.me
security: []
tags: []
paths:
/v3/session/:
post:
tags:
- Sessions
summary: Crea una sessione di verifica
description: >-
Crea una sessione di Verifica degli utenti (KYC) o Verifica aziendale
(KYB) e ricevi un `url` di verifica ospitata insieme a un
`session_token` da reindirizzare o incorporare per il tuo utente finale.
Il parametro `workflow_id` seleziona quali passaggi di verifica eseguire
e se la sessione è KYC o KYB.
Chiama questo endpoint dal tuo backend (mai dal browser — la chiave API
è un segreto) ogni volta che un utente o un'azienda deve essere
verificata: alla registrazione, prima di un'azione sensibile o quando è
richiesta una nuova verifica. Prerequisiti: un workflow pubblicato
(creato nella pagina
[Workflows](https://docs.didit.me/it/console/workflows) della Console) e
una chiave API dell'applicazione con crediti disponibili. Le
applicazioni sandbox ignorano il controllo dei crediti.
**Idempotenza:** quando viene fornito `vendor_data` ed esiste già una
sessione non completata (`Not Started`, `In Progress`, `Resubmitted` o
`Awaiting User`) con lo stesso `vendor_data` nell'**ultima versione
attualmente pubblicata** del workflow (e tale sessione dispone già di un
URL di verifica ospitata), viene restituita la sessione esistente
(sempre `201`) invece di creare un duplicato — con i relativi `callback`
e `metadata` aggiornati ai nuovi valori forniti. Una sessione non
completata creata su una versione precedente del workflow (che nel
frattempo è stata ripubblicata) **non** viene riutilizzata; viene invece
creata una nuova sessione associata all'ultima versione pubblicata. Le
sessioni in `Approved`, `Declined`, `In Review`, `Expired`, `Abandoned`
o `Kyc Expired` non vengono mai riutilizzate.
**Effetti collaterali:** l'URL di verifica ospitata viene generato e
memorizzato; se `contact_details.send_notification_emails` è `true` e
viene fornita un'email, viene inviata un'email di invito alla verifica.
La sessione scade dopo il tempo di scadenza della sessione configurato
nel workflow. Per i workflow KYB, `contact_details.phone` ed
`expected_details` vengono ignorati.
operationId: post_v3_session_create
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- workflow_id
properties:
workflow_id:
type: string
format: uuid
description: >-
Identificatore stabile del workflow che definisce i passaggi
di verifica che la sessione eseguirà. I workflow vengono
creati e gestiti nella pagina
[Workflows](/it/console/workflows) della Console. Il valore
`workflow_id` seleziona inoltre implicitamente se la
sessione è KYC o KYB.
example: 11111111-2222-3333-4444-555555555555
x-readme-id: '0.0'
vendor_data:
type: string
description: >-
Un identificatore univoco per l'utente in fase di verifica,
come un UUID, un'email o un ID utente interno. Questo campo
è utilizzato per: (1) **Raggruppamento degli utenti** — le
sessioni con lo stesso vendor_data vengono collegate allo
stesso profilo utente nella scheda Utenti. (2) **Rilevamento
di duplicati cross-sessione** — durante il controllo di
volti, documenti, numeri di telefono, email, indirizzi IP o
fingerprint dei dispositivi duplicati, le sessioni con lo
stesso vendor_data vengono trattate come lo stesso utente ed
escluse dalle corrispondenze. Senza vendor_data, ogni
sessione viene considerata come un utente univoco e vengono
mostrati tutti i potenziali duplicati. Consigliamo vivamente
di fornire sempre un vendor_data per ridurre il rumore nel
rilevamento dei duplicati.
example: user-123
x-readme-id: '0.1'
multi_account_segment:
type: string
maxLength: 64
description: >-
Ambito opzionale per il rilevamento dei duplicati
all'interno della tua organizzazione. I controlli dei volti
duplicati confrontano questa sessione solo con altre
sessioni che presentano lo stesso segmento, in modo che basi
di account distinte (account personali e aziendali, o uno
per ciascun sub-cliente B2B) non segnalino una persona che
possiede legittimamente un account in ciascuna di esse.
Omettilo per utilizzare il singolo ambito predefinito, che è
quello utilizzato oggi da ogni sessione. La corrispondenza
con blocklist e allowlist ignora questo campo.
example: business-accounts
callback:
type: string
description: >-
URL a cui reindirizzare l'utente al termine della verifica.
Didit aggiunge automaticamente `verificationSessionId` e
`status` (Approved, Declined, In Review) come parametri di
query. Gli schemi URL personalizzati (es. `myapp://`) sono
supportati per i callback su dispositivi mobili. Se omesso,
viene utilizzato il `callback_url` predefinito del workflow.
Quando l'applicazione ha domini consentiti
(`allowed_domains` su `PATCH /v3/webhook/`), un callback
`http` o `https` deve appartenere a una di queste origini
(stesso schema, host e porta), altrimenti la richiesta non
va a buon fine con 400 su `callback`: `callback must be on
one of the application's allowed domains:
https://app.example.com`. Gli schemi URL personalizzati sono
sempre accettati.
example: https://example.com/verification/callback
x-readme-id: '0.2'
callback_method:
type: string
description: >-
Determina quale dispositivo deve gestire il reindirizzamento
all'URL di callback fornito. Usa `initiator` per
reindirizzare solo il dispositivo che ha avviato il flusso,
`completer` per il dispositivo che lo completa, oppure
`both` per consentire a entrambi i dispositivi di attivare
il callback. Se noti che il callback non si attiva in modo
affidabile, ti consigliamo di impostare questo valore su
`both`.
enum:
- initiator
- completer
- both
default: initiator
example: both
x-readme-id: '0.3'
metadata:
description: >-
JSON arbitrario memorizzato con la sessione e restituito
nella risposta e nei webhook. È accettato qualsiasi valore
JSON (oggetto, stringa, numero, array), ma è consigliato un
oggetto JSON di coppie chiave/valore. Non viene mostrato
all'utente finale. Utilizzalo per trasmettere i tuoi ID di
correlazione, varianti A/B o il contesto aziendale.
example:
user_type: premium
account_id: ABC123
x-readme-id: '0.4'
tags:
type: array
items:
type: string
maxLength: 50
maxItems: 10
description: >-
Tag aggiunti alla sessione al momento della creazione, per
nome. Fino a 10, ciascuno di massimo 50 caratteri. I nomi
non distinguono tra maiuscole e minuscole e vengono
memorizzati in maiuscolo. Un nome non ancora presente
nell'applicazione viene creato come nuovo tag. I tag
compaiono sulla sessione nella console, dove puoi filtrarli.
example:
- VIP
- ONBOARDING Q4
language:
type: string
description: >-
Codice lingua (ISO 639-1) per l'interfaccia della procedura
di verifica. Controlla la lingua mostrata all'utente finale
durante la verifica. Se non fornito, la lingua del browser
verrà rilevata e utilizzata automaticamente. Consulta tutte
le lingue supportate
[qui](/it/integration/supported-languages).
enum:
- en
- ar
- bg
- bn
- bs
- ca
- cnr
- cs
- da
- de
- el
- es
- et
- fa
- fi
- fr
- he
- hi
- hr
- hu
- hy
- id
- it
- ja
- ka
- kk
- ko
- ky
- lt
- lv
- mk
- mn
- ms
- nl
- 'no'
- pl
- pt-BR
- pt
- ro
- ru
- sk
- sl
- so
- sq
- sr
- sv
- th
- tr
- uk
- uz
- vi
- zh-CN
- zh-TW
- zh
example: en
x-readme-id: '0.5'
contact_details:
type: object
description: >-
Informazioni di contatto dell'utente che possono essere
utilizzate per le notifiche, la precompilazione dei moduli
di verifica e la verifica telefonica. Sono inclusi
l'indirizzo email, la lingua preferita per le comunicazioni
e il numero di telefono.
example:
email: john.doe@example.com
send_notification_emails: true
email_lang: en
phone: '+14155552671'
properties:
email:
type: string
format: email
description: >-
Indirizzo email dell'utente (ad es.
"john.doe@example.com") che verrà utilizzato durante il
passaggio di [Verifica
email](/it/core-technology/email-verification/overview).
Se non fornito, l'utente dovrà inserirlo durante il
flusso di verifica.
example: john.doe@example.com
x-readme-id: '1.0'
send_notification_emails:
type: boolean
default: false
description: >-
Se true e viene fornito un indirizzo email, Didit invia
l'email iniziale "Verifica la tua identità" in modo
asincrono quando viene creata la sessione di Verifica
degli utenti (KYC) o Verifica aziendale (KYB). Didit
invia inoltre le notifiche sullo stato della verifica
per le sessioni che richiedono una revisione manuale
all'indirizzo email fornito (es. da 'In Review' ad
'Approved' o 'Declined'). Questo aiuta gli utenti a
tornare alla tua applicazione una volta completata la
verifica. Se hai attivato il white label per la
sessione, l'email inviata sarà in white label.
example: true
x-readme-id: '1.1'
email_lang:
type: string
description: >-
Codice lingua (ISO 639-1) per le notifiche email.
Controlla la lingua di tutte le comunicazioni via email
(es. "en", "es", "fr"). Non è memorizzato alcun valore
predefinito: quando omesso, l'email di invito alla
verifica torna semplicemente all'inglese (`en`) al
momento dell'invio. L'enum sottostante è un'istantanea;
la fonte di verità aggiornata per i valori accettati è
la documentazione sulle [lingue
supportate](/it/integration/supported-languages):
consultala sempre prima di affidarti a uno specifico
codice.
enum:
- en
- ar
- bg
- bn
- bs
- ca
- cnr
- cs
- da
- de
- el
- es
- et
- fa
- fi
- fr
- he
- hi
- hr
- hu
- hy
- id
- it
- ja
- ka
- kk
- ko
- ky
- lt
- lv
- mk
- mn
- ms
- nl
- 'no'
- pl
- pt-BR
- pt
- ro
- ru
- sk
- sl
- so
- sq
- sr
- sv
- th
- tr
- uk
- uz
- vi
- zh-CN
- zh-TW
- zh
example: en
x-readme-id: '1.2'
phone:
type: string
description: >-
Numero di telefono in formato E.164 (ad es.
"+14155552671") che verrà utilizzato durante il
passaggio di [Verifica
telefonica](/it/core-technology/phone-verification/overview).
Se non fornito, l'utente deve inserirlo durante il
flusso di verifica. Ignorato per i workflow di Verifica
aziendale (KYB). **Importante:** questo numero di
telefono viene applicato solo se è un numero di telefono
E.164 valido. Se il numero fornito non è valido o non
può essere analizzato, verrà ignorato e l'utente potrà
inserire qualsiasi numero di telefono valido durante il
passaggio di Verifica telefonica.
example: '+14155552671'
x-readme-id: '1.3'
x-readme-id: '0.4'
expected_details:
type: object
description: >-
Dettagli dell'utente previsti utilizzati per la convalida
incrociata rispetto ai dati estratti dal documento
d'identità dell'utente, dalla Prova di residenza e da altri
passaggi di verifica. Le discrepanze vengono segnalate come
avvisi nella decisione; alcuni campi (ad es. `id_country`,
`expected_document_types`) modificano anche il flusso
visibile all'utente. Per i workflow di Verifica aziendale
(KYB) vengono utilizzati solo i campi aziendali
(`company_name`, `registry_country`, `registration_number`)
— che precompilano la ricerca nel registro delle imprese per
l'utente — e tutti i campi relativi alla persona vengono
ignorati.
example:
first_name: John
last_name: Doe
date_of_birth: '1990-05-15'
nationality: USA
id_country: USA
expected_document_types:
- P
- ID
properties:
first_name:
type: string
description: >-
Nome dell'utente. Ad esempio, `John`. La corrispondenza
utilizza un confronto fuzzy ed è possibile regolare il
livello di rigore configurando la soglia del punteggio
di corrispondenza del nome nella Console sia per i
workflow di Documento d'identità che per quelli di Prova
di residenza.
example: John
x-readme-id: '1.0'
last_name:
type: string
description: >-
Cognome dell'utente. Ad esempio, `Doe`. La
corrispondenza utilizza un confronto fuzzy ed è
possibile regolare il livello di rigore configurando la
soglia del punteggio di corrispondenza del nome nella
Console sia per i workflow di Documento d'identità che
per quelli di Prova di residenza.
example: Doe
x-readme-id: '1.1'
date_of_birth:
type: string
format: date
description: >-
Data di nascita dell'utente nel formato: YYYY-MM-DD. Ad
esempio, `1990-05-15`.
example: '1990-05-15'
x-readme-id: '1.2'
gender:
type: string
nullable: true
enum:
- M
- F
default: null
description: Genere dell'utente. Deve essere 'M', 'F' o null.
example: M
x-readme-id: '1.3'
nationality:
type: string
description: >-
Codice paese ISO 3166-1 alpha-3 che rappresenta il paese
di origine del richiedente. Ad esempio, `USA`. Consulta
l'[elenco completo dei codici paese
supportati](https://docs.didit.me/it/core-technology/id-verification/supported-documents-id-verification#documenti-supportati-per-paese).
example: USA
x-readme-id: '1.4'
country:
type: string
description: >-
Codice paese ISO 3166-1 alpha-3 utilizzato come fallback
per i controlli di mancata corrispondenza del paese sia
per la Verifica dell'identità sia per la Prova di
residenza. Obbligatorio se viene fornito `address` e non
sono impostati né `id_country` né `poa_country`.
example: USA
x-readme-id: 1.4.1
id_country:
type: string
description: >-
Codice paese ISO 3166-1 alpha-3 che rappresenta il paese
previsto del documento d'identità del richiedente, che
può differire dalla nazionalità. Ad esempio, `GBR`. Ha
la priorità su `country` per i controlli di mancata
corrispondenza del paese per la Verifica dell'identità.
Consulta l'[elenco completo dei codici paese
supportati](https://docs.didit.me/it/core-technology/id-verification/supported-documents-id-verification#documenti-supportati-per-paese).
example: GBR
x-readme-id: '1.5'
poa_country:
type: string
description: >-
Codice paese ISO 3166-1 alpha-3 che rappresenta il paese
previsto del documento di Prova di residenza. Ad
esempio, `USA`. Ha la priorità su `country` per i
controlli di mancata corrispondenza del paese del POA.
Consulta l'[elenco completo dei codici paese
supportati](https://docs.didit.me/it/core-technology/id-verification/supported-documents-id-verification#documenti-supportati-per-paese).
example: USA
x-readme-id: 1.5.1
address:
type: string
description: >-
L'indirizzo in un formato leggibile, includendo quante
più informazioni possibili. Ad esempio, `123 Main St,
San Francisco, CA 94105, USA`. Se fornito, devi
includere anche `country` o `poa_country`, altrimenti la
richiesta non va a buon fine con un errore `400`.
example: 123 Main St, San Francisco, CA 94105, USA
x-readme-id: '1.6'
identification_number:
type: string
description: >-
Il numero del documento, il codice personale o il codice
fiscale dell'utente. Ad esempio, `123456789`.
example: '123456789'
x-readme-id: '1.7'
ip_address:
type: string
description: >-
Indirizzo IP previsto per la sessione, in formato IPv4 o
IPv6. Se l'indirizzo IP effettivo differisce da questo
valore, verrà registrato un avviso. Ad esempio,
`192.168.1.100` o `2001:db8::1`.
example: 192.168.1.100
x-readme-id: '1.8'
expected_document_types:
type: array
description: >-
Limita i tipi di documento che l'utente può presentare
durante il passaggio di verifica dell'identità (OCR).
Quando viene impostato, la schermata di selezione del
documento mostra solo i tipi richiesti e il valore
restituito `documents_allowed` viene filtrato di
conseguenza. I valori non distinguono tra maiuscole e
minuscole e vengono deduplicati; i valori sconosciuti
vengono rifiutati con `400`. Codici consentiti: `P`
(passaporto), `ID` (carta d'identità), `DL` (patente di
guida), `RP` (permesso di soggiorno), `HIC` (tessera
sanitaria), `TC` (codice fiscale/tessera fiscale), `SSC`
(tessera di sicurezza sociale).
items:
type: string
enum:
- P
- ID
- DL
- RP
- HIC
- TC
- SSC
example:
- P
- ID
x-readme-id: '1.9'
company_name:
type: string
maxLength: 255
description: >-
Ragione sociale prevista dell'azienda oggetto di
verifica. Ad esempio, `Tesco PLC`. Precompila il campo
della ragione sociale nella ricerca nel registro nei
workflow di Verifica aziendale (KYB); quando viene
fornito anche `registration_number`, la ricerca nel
registro combina entrambi gli identificatori. Ignorato
per i workflow KYC.
example: Tesco PLC
x-readme-id: '1.10'
registry_country:
type: string
maxLength: 10
description: >-
Codice ISO 3166-1 alpha-2 del paese nel cui registro
delle imprese è registrata l'azienda. Ad esempio, `GB`.
Laddove i registri delle imprese operano a livello
statale o provinciale, aggiungi il codice di
suddivisione ISO 3166-2 come `XX-YY`: `US-CA` punta al
registro della California. Stesso formato di
`country_code` sull'[API di ricerca nel registro
KYB](https://docs.didit.me/it/standalone-apis/kyb-registry-search).
Pre-seleziona il paese del registro nei workflow di
Verifica aziendale (KYB); ignorato per i workflow KYC.
example: US-CA
x-readme-id: '1.11'
registration_number:
type: string
maxLength: 100
description: >-
Numero di registrazione previsto dell'azienda nel
registro delle imprese. Ad esempio, `00445790`.
Precompila il campo del numero di registrazione nella
ricerca nel registro nei workflow di Verifica aziendale
(KYB); quando viene fornito anche `company_name`, la
ricerca nel registro combina entrambi gli
identificatori. Ignorato per i workflow KYC.
example: '00445790'
x-readme-id: '1.12'
x-readme-id: '0.5'
portrait_image:
type: string
format: byte
description: >-
Immagine del volto dell'utente finale codificata in Base64
(max 2 MB; JPEG, PNG, WebP o TIFF). Utilizzata come immagine
di riferimento da confrontare con l'acquisizione della
vitalità quando il workflow è un workflow di `Biometric
Authentication` con Confronto facciale abilitato, o
qualsiasi workflow a grafo in cui il Confronto facciale
viene eseguito prima della Verifica dell'identità (OCR).
Opzionale quando l'utente specificato in `vendor_data` ha
già un'immagine del volto memorizzata: Didit la riutilizza
automaticamente, risolvendola in ordine di priorità: volto
da rilevamento della vitalità approvato, foto del chip
dell'ePassport, ritratto del documento d'identità, volto del
profilo registrato manualmente (vengono riutilizzati solo i
volti provenienti da sessioni approvate o i volti che hai
registrato personalmente). Se fornita, `portrait_image` ha
sempre la precedenza sul volto memorizzato. Se omessa e non
esiste alcun volto memorizzato (o non viene inviato
`vendor_data`), la creazione della sessione fallisce con
`400`. Ignorata per altri tipi di workflow.
example: >-
iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=
x-readme-id: '0.6'
sandbox_scenario:
type: string
description: >-
Slug dello scenario solo per la sandbox. Accettato solo
quando la chiave API appartiene a un'applicazione in
modalità sandbox; rifiutato nelle applicazioni di
produzione. Se impostato, il flusso di creazione inserisce i
valori magici associati allo scenario nei campi di input
della sessione (contact_details, expected_details),
consentendo ai provider simulati di riprodurre l'esito dello
scenario lungo l'effettiva pipeline del workflow. Consulta
il catalogo degli scenari con GET /v1/sandbox/scenarios/ o
in [Sandbox e dati di
test](/it/integration/sandbox-testing). Puoi anche preparare
(o ripreparare) uno scenario dopo la creazione tramite POST
/v3/session/{sessionId}/sandbox/arm/, a condizione che la
sessione sia ancora `Not Started`. Per le verifiche senza
documenti, usa `lookup_partial_match`, `lookup_no_match` o
`lookup_provider_error` per testare il budget di tentativi
configurato e il fallback. Per i wallet di identità, usa
`wallet_cancelled`, `wallet_timeout` o
`wallet_provider_error`; `approve` simula un wallet
verificato. Tutti i wallet del catalogo possono essere
testati in sandbox, inclusi gli schemi non disponibili nelle
applicazioni di produzione. I tentativi simulati non vengono
addebitati.
example: decline_document_expired
sign:
type: object
description: >-
Dati di input di Firma elettronica per questa sessione. I
`documents` sono i documenti da firmare, per un workflow il
cui passaggio di Firma elettronica riceve i documenti dalla
sessione (`signature_documents_source` `session` o `both`):
fino a 20 documenti e 50 MB in totale. `field_values`
compila i campi il cui `prefill` è `api.`, sia sui
documenti del workflow che su quelli della sessione. Creando
nuovamente una sessione per gli stessi `workflow_id` e
`vendor_data` viene restituita la sessione in sospeso; se
tale chiamata invia `sign`, i relativi documenti, campi e
valori devono essere identici a quelli iniziali, altrimenti
qualsiasi differenza restituisce `400` con `{"sign":
"signature_document_changed"}`. Consulta [Documenti di Firma
elettronica](/it/sessions-api/create-session#documenti-di-firma-elettronica).
properties:
documents:
type: array
minItems: 1
maxItems: 20
items:
$ref: '#/components/schemas/SessionSignDocument'
field_values:
type: object
description: >-
Valori indicizzati dalla `` di ciascuna origine di
precompilazione `api.`: stringhe da 1 a 500
caratteri per i campi `text` e `data`, booleani per una
`checkbox`. `400` con `field_value_unknown` per una
chiave non utilizzata da alcun campo,
`field_value_missing` per un campo obbligatorio privo
del relativo valore e `field_value_invalid` per un
valore che non supera la validazione del rispettivo
campo.
additionalProperties:
oneOf:
- type: string
minLength: 1
maxLength: 500
- type: boolean
example:
credit_limit: 3,000 EUR
user_state:
type: string
maxLength: 16
description: >-
Dove risiede la persona, se noto: un codice di suddivisione
ISO 3166-2 (`US-IL`, `ES-M`) o un codice o nome di uno stato
USA (`IL`, `Illinois`). Uno stato la cui legislazione
richiede un consenso biometrico esplicito (Illinois, Texas,
Colorado) fa sì che il flusso di verifica lo richieda prima
di acquisire il volto, con trigger `declared_state`. Un
valore non riconosciuto restituisce `400`. Consulta
[Consenso
biometrico](/it/getting-started/biometric-consent).
example: US-IL
biometric_consent:
type: object
description: >-
Consenso biometrico esplicito già raccolto dalla persona.
Soddisfa il requisito, quindi il flusso di verifica non lo
richiede nuovamente, e la decisione lo registra come
`status: "given"` con trigger `customer_collected`. Una
risposta già fornita dalla persona nel flusso non viene mai
sostituita. Consulta [Consenso
biometrico](/it/getting-started/biometric-consent).
required:
- given_at
- text_version
properties:
given_at:
type: string
format: date-time
description: >-
Quando la persona ha fornito il consenso biometrico
esplicito (ISO 8601). Non può essere nel futuro.
text_version:
type: string
maxLength: 64
description: >-
ID versione del testo del consenso accettato dalla
persona, nei tuoi registri.
example:
workflow_id: 11111111-2222-3333-4444-555555555555
vendor_data: user-123
callback: https://example.com/verification/callback
callback_method: both
metadata:
user_type: premium
account_id: ABC123
language: en
contact_details:
email: john.doe@example.com
send_notification_emails: true
email_lang: en
phone: '+14155552671'
expected_details:
first_name: John
last_name: Doe
date_of_birth: '1990-05-15'
id_country: USA
expected_document_types:
- P
- ID
examples:
Create KYC session:
summary: >-
Payload completo del percorso ideale per una sessione di
Verifica degli utenti (KYC)
description: >-
Chiamata di creazione realistica che utilizza tutti i campi
impostati comunemente: selezione del workflow, collegamento
del vendor, instradamento dei callback, metadati, impostazioni
locali, precompilazione dei contatti e dettagli attesi
dell'utente. Copia e incolla questo contenuto direttamente
nell'esempio cURL precedente.
value:
workflow_id: 11111111-2222-3333-4444-555555555555
vendor_data: user-123
callback: https://example.com/verification/callback
callback_method: both
metadata:
user_type: premium
account_id: ABC123
language: en
contact_details:
email: john.doe@example.com
send_notification_emails: true
email_lang: en
phone: '+14155552671'
expected_details:
first_name: John
last_name: Doe
date_of_birth: '1990-05-15'
nationality: USA
id_country: USA
expected_document_types:
- P
- ID
Create KYB session:
summary: >-
Payload per il percorso ottimale di una sessione di Verifica
aziendale (KYB)
description: >-
Stessa struttura della chiamata KYC: il `workflow_id` è ciò
che rende la sessione KYB. `vendor_data` fa generalmente
riferimento all'azienda nel tuo sistema e
`contact_details.email` è destinato al legale rappresentante
che completerà il flusso. `expected_details` accetta i campi
aziendali (`company_name`, `registry_country`,
`registration_number`), che precompilano la ricerca nel
registro delle imprese; i campi relativi alla persona e
`contact_details.phone` vengono ignorati per i workflow KYB.
value:
workflow_id: 33333333-4444-5555-6666-777777777777
vendor_data: company-acme-001
callback: https://example.com/kyb/callback
callback_method: both
metadata:
tier: enterprise
company_id: ACME-001
expected_details:
company_name: Tesco PLC
registry_country: GB
registration_number: '00445790'
language: en
contact_details:
email: legal-rep@acme.example.com
send_notification_emails: true
email_lang: en
responses:
'201':
description: >-
Sessione creata (o restituita, se esiste già una sessione non
completata con gli stessi `vendor_data` sull'ultima versione
pubblicata del workflow). La risposta è la sessione serializzata,
incluso l'`url` della pagina di verifica ospitata a cui
reindirizzare l'utente.
content:
application/json:
schema:
type: object
required:
- session_id
- session_number
- session_token
- url
- vendor_data
- metadata
- status
- workflow_id
- workflow_version
- callback
properties:
session_id:
type: string
format: uuid
description: >-
Identificativo univoco della sessione di verifica. Usa
questo id quando chiami `GET
/v3/session/{sessionId}/decision/`.
example: 11111111-2222-3333-4444-555555555555
session_number:
type: integer
description: >-
Numero sequenziale e di facile lettura assegnato alla
sessione all'interno della tua applicazione. Utile per
l'assistenza e le dashboard.
example: 43762
session_token:
type: string
description: >-
Token URL-safe di 12 caratteri che autorizza l'utente
finale ad accedere al flusso di verifica ospitato
all'indirizzo `url`. Valido fino alla scadenza della
sessione. Trattalo come un segreto: chiunque lo possieda
può aprire il flusso di verifica per questa sessione.
example: 3FaJ9wLqX2Mz
url:
type: string
format: uri
description: >-
URL di verifica ospitato a cui reindirizzare l'utente
finale. L'URL include il `session_token` e, se
configurato, utilizza il tuo dominio white label. Quando
la richiesta include `language`, l'URL contiene un
segmento di percorso per la lingua —
`https://verify.didit.me/{language}/session/{session_token}`
(ad es. `/es/session/...`); senza `language`, il segmento
viene omesso.
example: https://verify.didit.me/session/3FaJ9wLqX2Mz
vendor_data:
type: string
nullable: true
description: >-
Identificatore che hai passato nella richiesta per
collegare la sessione a un utente o a un'azienda nel tuo
sistema. Restituito esattamente come inviato. Null se non
fornito.
example: user-123
metadata:
description: >-
Payload JSON arbitrario memorizzato con la sessione al
momento della creazione. Viene restituito testualmente:
qualunque valore JSON inviato (oggetto, stringa, numero,
array) viene restituito così com'è, anche se è consigliato
un oggetto JSON. Non viene mostrato all'utente finale.
Sempre presente nelle risposte; `null` se non fornito al
momento della creazione.
example:
user_type: premium
account_id: ABC123
tags:
type: array
items:
type: string
description: I tag presenti sulla sessione, per nome.
example:
- VIP
- ONBOARDING Q4
status:
type: string
enum:
- Not Started
- In Progress
- Approved
- Declined
- In Review
- Expired
- Abandoned
- Kyc Expired
- Resubmitted
- Awaiting User
description: >-
Stato attuale della sessione. Le sessioni appena create
restituiscono `Not Started`. Se esisteva già una sessione
non conclusa per lo stesso `vendor_data` sull'ultima
versione pubblicata del workflow, lo stato restituito
riflette tale sessione esistente.
example: Not Started
callback:
type: string
format: uri
nullable: true
description: >-
URL di reindirizzamento finale a cui l'utente viene
inviato dopo aver completato il flusso. Didit aggiunge
`?verificationSessionId={session_id}&status={status}` a
questo URL. Utilizza come fallback l'URL di callback
configurato nel workflow se non fornito nella richiesta;
`null` quando nessuno dei due è impostato. Se
l'applicazione ha domini consentiti e questo URL è un URL
web esterno a essi (ad esempio un valore predefinito del
workflow impostato prima della modifica dell'elenco), il
flusso ospitato non vi reindirizza l'utente.
example: https://example.com/verification/callback
workflow_id:
type: string
format: uuid
description: >-
Identificatore stabile del workflow su cui viene eseguita
questa sessione. Corrisponde sempre all'identificatore di
gruppo stabile del workflow; anche se nella richiesta hai
fatto riferimento all'UUID di una versione specifica del
workflow (ricerca retrocompatibile), la risposta riporta
il `workflow_id` stabile. Usalo per correlare la sessione
con il workflow configurato nella Console.
example: 11111111-2222-3333-4444-555555555555
workflow_version:
type: integer
description: >-
Numero di versione della versione pubblicata del workflow
a cui la sessione è stata associata al momento della
creazione. Didit risolve `workflow_id` con l'ultima
versione pubblicata del workflow quando la sessione viene
creata, e la sessione continua a eseguire quella versione
anche se il workflow viene ripubblicato successivamente.
example: 3
examples:
KYC session:
summary: Sessione KYC creata
value:
session_id: 11111111-2222-3333-4444-555555555555
session_number: 43762
session_token: 3FaJ9wLqX2Mz
url: https://verify.didit.me/en/session/3FaJ9wLqX2Mz
vendor_data: user-123
metadata:
user_type: premium
account_id: ABC123
status: Not Started
workflow_id: 11111111-2222-3333-4444-555555555555
workflow_version: 3
callback: https://example.com/verification/callback
KYB session:
summary: Sessione KYB creata
value:
session_id: 22222222-3333-4444-5555-666666666666
session_number: 43763
session_token: Yk7pQ2vN8aBc
url: https://verify.didit.me/en/session/Yk7pQ2vN8aBc
vendor_data: company-acme-001
metadata:
tier: enterprise
status: Not Started
workflow_id: 33333333-4444-5555-6666-777777777777
workflow_version: 1
callback: https://example.com/kyb/callback
'400':
description: >-
Richiesta non valida: la convalida del payload non è riuscita
(`workflow_id` mancante o sconosciuto, `language` non valido,
`vendor_data` inserito nella blocklist, `portrait_image` non valido,
`address` senza `country`/`poa_country`, `sandbox_scenario` non
valido, documenti `sign`, campi o valori rifiutati dal passaggio di
Firma elettronica del workflow, come
`signature_document_not_supported`,
`signature_document_conversion_failed`, `field_anchor_not_found` o
`field_value_missing`, ecc.) oppure la tua organizzazione non
dispone di crediti sufficienti per avviare la sessione.
Il corpo è un oggetto avente come chiave il nome del campo
responsabile dell'errore (o `detail` per gli errori non legati ai
campi). I valori sono un **array di stringhe** per gli errori di
convalida dell'input (ad es. campo obbligatorio mancante, lingua non
valida, immagine del ritratto di dimensioni eccessive) e una
**stringa semplice** per gli errori rilevati durante la creazione
della sessione (`workflow_id` sconosciuto, `vendor_data` presente
nella blocklist, nessun volto di riferimento disponibile per un
workflow di Confronto facciale). Gestisci entrambi i formati.
content:
application/json:
schema:
type: object
additionalProperties: true
properties:
detail:
type: string
description: >-
Messaggio di errore di facile lettura per errori non
legati a singoli campi (ad es. crediti insufficienti). Gli
errori a livello di campo utilizzano invece il nome del
campo come chiave, con una stringa o un array di stringhe
come valore.
example: >-
You don't have enough credits to perform this request.
Please top up at https://business.didit.me
examples:
Missing workflow_id:
summary: Campo obbligatorio omesso (formato array di stringhe)
value:
workflow_id:
- This field is required.
Invalid workflow_id:
summary: workflow_id sconosciuto (formato stringa semplice)
value:
workflow_id: Invalid workflow_id.
Insufficient credits:
summary: L'organizzazione ha esaurito i crediti
value:
detail: >-
You don't have enough credits to perform this request.
Please top up at https://business.didit.me
Blocklisted vendor_data:
summary: vendor_data è in blocklist
value:
vendor_data: >-
This user or business has been blocked and cannot create
new verification sessions.
Portrait image too large:
summary: portrait_image non supera la validazione delle dimensioni
value:
portrait_image:
- Image size exceeds 2MB.
No stored face for vendor_data:
summary: >-
Workflow di Confronto facciale senza portrait_image e senza
volto memorizzato per l'utente vendor_data
value:
portrait_image: >-
No stored face image was found for this user. Send a
portrait_image, or complete an approved verification with
face liveness or an ID document for this vendor_data
first.
Portrait image required without vendor_data:
summary: >-
Workflow di Confronto facciale senza portrait_image e senza
vendor_data
value:
portrait_image: >-
A portrait image is required to perform face match for
this workflow. Send a portrait_image, or provide the
vendor_data of a user with a previously stored face image
to reuse it.
'403':
description: >-
Autenticazione o autorizzazione non riuscita. Una chiave errata,
revocata o scaduta restituisce `401`. L'endpoint restituisce `403`
quando l'intestazione `x-api-key` è mancante o la chiave API è
valida ma il client non dispone dell'autorizzazione per creare
sessioni in questa applicazione (ad esempio la chiave API appartiene
a un'organizzazione diversa). Questi errori condividono il corpo
`{"detail": "You do not have permission to perform this action."}`.
Verifica che l'intestazione `x-api-key` sia presente e appartenga
all'applicazione desiderata, recupera nuovamente la chiave API
dell'applicazione tramite l'[Auth API](/it/auth-api/get-credentials)
se necessario, e riprova.
**Applicazione eliminata:** per alcuni minuti dopo l'eliminazione di
un'applicazione, una richiesta effettuata con una delle sue chiavi
API può rispondere `{"detail": "This application was deleted.",
"code": "application_deleted"}`. Non riprovare: l'applicazione e le
sue chiavi API non esistono più. Trascorsi questi pochi minuti, la
chiave viene rifiutata come qualsiasi altra chiave non valida.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
example: You do not have permission to perform this action.
code:
type: string
description: >-
Motivo leggibile dalla macchina, presente solo per alcuni
errori. `application_deleted`: la chiave API appartiene a
un'applicazione che è stata eliminata.
example: application_deleted
required:
- detail
examples:
Missing or invalid API key:
summary: Nessuna intestazione `x-api-key` o chiave API non valida
value:
detail: You do not have permission to perform this action.
No permission:
summary: Il client non può creare sessioni
value:
detail: You do not have permission to perform this action.
Application deleted:
summary: Chiave API di un'applicazione eliminata
value:
detail: This application was deleted.
code: application_deleted
'429':
description: >-
Limite di frequenza superato — più di 600 richieste di creazione di
sessioni in una finestra di 60 secondi dalla stessa chiave API / IP.
Esamina `Retry-After` e attendi prima di riprovare.
**Nota:** il codice sorgente definisce anche un
`FREE_SESSION_RATE_LIMIT` di 10 chiamate/minuto insieme a
`PAID_SESSION_RATE_LIMIT=600` (`sessions/serializers/session.py`),
ma tale soglia del piano gratuito **non è applicata a questo
endpoint V3** — il middleware del limite di frequenza applica il
valore di 600/min `SESSION_CREATE_RATE_LIMIT` indipendentemente dal
piano. 600/min è l'unico limite che puoi raggiungere qui.
headers:
Retry-After:
description: >-
Secondi che il chiamante deve attendere prima di riprovare la
richiesta.
schema:
type: integer
minimum: 1
example: 42
X-RateLimit-Limit:
description: >-
Numero massimo di richieste consentite nella finestra temporale
corrente di 60 secondi per il limite superato (600 per
session-create). Assente nella variante della quota sandbox.
schema:
type: integer
example: 600
X-RateLimit-Remaining:
description: >-
Numero di richieste ancora consentite nell'intervallo corrente
per il limite superato. Assente nella variante della quota di
sandbox.
schema:
type: integer
minimum: 0
example: 0
X-RateLimit-Reset:
description: >-
Secondi dell'epoch UTC in cui si reimposta l'attuale finestra
del limite di frequenza. Assente nella variante della quota di
sandbox.
schema:
type: integer
minimum: 0
example: 1747497600
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: >-
Spiegazione di facile lettura del superamento del limite
di frequenza. Usa questo messaggio per distinguere quale
dei tre limiti è stato raggiunto.
example: >-
Session creation rate limit exceeded. You can make up to
600 requests per minute.
examples:
Session-create limit:
summary: Più di 600 richieste di creazione sessione al minuto
value:
detail: >-
Session creation rate limit exceeded. You can make up to
600 requests per minute.
Sandbox session quota:
summary: L'applicazione sandbox ha superato 500 sessioni in 24 ore
value:
detail: >-
Sandbox session quota exceeded (500 sessions per 24h).
Wait for the window to reset. Expected available in 3600
seconds.
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: cURL
source: |-
curl -X POST 'https://verification.didit.me/v3/session/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"workflow_id": "11111111-2222-3333-4444-555555555555",
"vendor_data": "user-123",
"callback": "https://example.com/verification/callback",
"callback_method": "both",
"metadata": {"user_type": "premium", "account_id": "ABC123"},
"language": "en",
"contact_details": {
"email": "john.doe@example.com",
"send_notification_emails": true,
"email_lang": "en",
"phone": "+14155552671"
},
"expected_details": {
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-05-15",
"id_country": "USA",
"expected_document_types": ["P", "ID"]
}
}'
- lang: python
label: Python
source: |-
from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.sessions.create(
workflow_id="11111111-2222-3333-4444-555555555555",
vendor_data="user-123",
callback="https://example.com/verification/callback",
callback_method="both",
metadata={"user_type": "premium", "account_id": "ABC123"},
language="en",
contact_details={
"email": "john.doe@example.com",
"send_notification_emails": True,
"email_lang": "en",
"phone": "+14155552671",
},
expected_details={
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-05-15",
"nationality": "USA",
"id_country": "USA",
"expected_document_types": ["P", "ID"],
},
)
print(result)
- lang: javascript
label: Node.js
source: |-
import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await didit.sessions.create({
workflow_id: "11111111-2222-3333-4444-555555555555",
vendor_data: "user-123",
callback: "https://example.com/verification/callback",
callback_method: "both",
metadata: { user_type: "premium", account_id: "ABC123" },
language: "en",
contact_details: {
email: "john.doe@example.com",
send_notification_emails: true,
email_lang: "en",
phone: "+14155552671",
},
expected_details: {
first_name: "John",
last_name: "Doe",
date_of_birth: "1990-05-15",
nationality: "USA",
id_country: "USA",
expected_document_types: ["P", "ID"],
},
});
console.log(result);
- lang: go
label: Go
source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Create(ctx, didit.SessionsCreateParams{\n\tWorkflowID: \"11111111-2222-3333-4444-555555555555\",\n\tVendorData: didit.String(\"user-123\"),\n\tCallback: didit.String(\"https://example.com/verification/callback\"),\n\tCallbackMethod: didit.Some(didit.SessionsCreateParamsCallbackMethod(\"both\")),\n\tMetadata: didit.Some[any](map[string]any{\"user_type\": \"premium\", \"account_id\": \"ABC123\"}),\n\tLanguage: didit.Some(didit.SessionsCreateParamsLanguage(\"en\")),\n\tContactDetails: didit.Some(didit.SessionsCreateParamsContactDetails{\n\t\tEmail: didit.String(\"john.doe@example.com\"),\n\t\tSendNotificationEmails: didit.Bool(true),\n\t\tEmailLang: didit.Some(didit.SessionsCreateParamsContactDetailsEmailLang(\"en\")),\n\t\tPhone: didit.String(\"+14155552671\"),\n\t}),\n\tExpectedDetails: didit.Some(didit.SessionsCreateParamsExpectedDetails{\n\t\tFirstName: didit.String(\"John\"),\n\t\tLastName: didit.String(\"Doe\"),\n\t\tDateOfBirth: didit.String(\"1990-05-15\"),\n\t\tNationality: didit.String(\"USA\"),\n\t\tIDCountry: didit.String(\"USA\"),\n\t\tExpectedDocumentTypes: didit.Some([]didit.SessionsCreateParamsExpectedDetailsExpectedDocumentTypes{\"P\", \"ID\"}),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
- lang: java
label: Java
source: |-
import java.time.LocalDate;
import java.util.List;
import java.util.Map;
import me.didit.Didit;
import me.didit.types.SessionsCreateParams;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result = client.sessions().create(SessionsCreateParams.builder()
.workflowId("11111111-2222-3333-4444-555555555555")
.vendorData("user-123")
.callback("https://example.com/verification/callback")
.callbackMethod(SessionsCreateParams.CallbackMethod.of("both"))
.metadata(Map.of("user_type", "premium", "account_id", "ABC123"))
.language(SessionsCreateParams.Language.of("en"))
.contactDetails(SessionsCreateParams.ContactDetails.builder()
.email("john.doe@example.com")
.sendNotificationEmails(true)
.emailLang(SessionsCreateParams.ContactDetails.EmailLang.of("en"))
.phone("+14155552671")
.build())
.expectedDetails(SessionsCreateParams.ExpectedDetails.builder()
.firstName("John")
.lastName("Doe")
.dateOfBirth(LocalDate.parse("1990-05-15"))
.nationality("USA")
.idCountry("USA")
.expectedDocumentTypes(List.of(SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of("P"), SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of("ID")))
.build())
.build());
System.out.println(result);
- lang: php
label: PHP
source: |-
sessions->create([
'workflow_id' => '11111111-2222-3333-4444-555555555555',
'vendor_data' => 'user-123',
'callback' => 'https://example.com/verification/callback',
'callback_method' => 'both',
'metadata' => ['user_type' => 'premium', 'account_id' => 'ABC123'],
'language' => 'en',
'contact_details' => [
'email' => 'john.doe@example.com',
'send_notification_emails' => true,
'email_lang' => 'en',
'phone' => '+14155552671',
],
'expected_details' => [
'first_name' => 'John',
'last_name' => 'Doe',
'date_of_birth' => '1990-05-15',
'nationality' => 'USA',
'id_country' => 'USA',
'expected_document_types' => ['P', 'ID'],
],
]);
print_r($result->toArray());
- lang: ruby
label: Ruby
source: |-
require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.sessions.create(
workflow_id: "11111111-2222-3333-4444-555555555555",
vendor_data: "user-123",
callback: "https://example.com/verification/callback",
callback_method: "both",
metadata: { user_type: "premium", account_id: "ABC123" },
language: "en",
contact_details: {
email: "john.doe@example.com",
send_notification_emails: true,
email_lang: "en",
phone: "+14155552671",
},
expected_details: {
first_name: "John",
last_name: "Doe",
date_of_birth: "1990-05-15",
nationality: "USA",
id_country: "USA",
expected_document_types: ["P", "ID"],
}
)
puts result.to_h
- lang: csharp
label: .NET
source: >-
using System;
using System.Collections.Generic;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await client.Sessions.CreateAsync(new
SessionsCreateParams
{
WorkflowId = "11111111-2222-3333-4444-555555555555",
VendorData = "user-123",
Callback = "https://example.com/verification/callback",
CallbackMethod = new SessionsCreateParamsCallbackMethod("both"),
Metadata = new Dictionary { ["user_type"] = "premium", ["account_id"] = "ABC123" },
Language = new SessionsCreateParamsLanguage("en"),
ContactDetails = new SessionsCreateParamsContactDetails
{
Email = "john.doe@example.com",
SendNotificationEmails = true,
EmailLang = new SessionsCreateParamsContactDetailsEmailLang("en"),
Phone = "+14155552671",
},
ExpectedDetails = new SessionsCreateParamsExpectedDetails
{
FirstName = "John",
LastName = "Doe",
DateOfBirth = "1990-05-15",
Nationality = "USA",
IdCountry = "USA",
ExpectedDocumentTypes = new SessionsCreateParamsExpectedDetailsExpectedDocumentTypes[] { "P", "ID" },
},
});
Console.WriteLine(JsonSerializer.Serialize(result));
components:
schemas:
SessionSignDocument:
type: object
required:
- file_name
- content_base64
properties:
title:
type: string
minLength: 1
maxLength: 255
description: Titolo mostrato al firmatario. Il valore predefinito è `file_name`.
file_name:
type: string
minLength: 1
maxLength: 255
description: Nome del file, che termina con `.pdf` o `.docx`.
content_base64:
type: string
format: byte
description: >-
Il file, codificato in base64. Un PDF può avere dimensioni fino a 20
MB e 100 pagine, senza password, script o file allegati. Un file
Word (`.docx`) può avere dimensioni fino a 20 MB e viene convertito
in PDF durante l'esecuzione della richiesta, in un massimo di 25
secondi; il PDF rispetta poi gli stessi limiti. Fino a 5 file Word
per sessione. Un file Word con macro, revisioni con rilevamento
delle modifiche, link a contenuti esterni o oggetti incorporati
viene rifiutato con `signature_document_not_supported`, mentre un
file che non può essere convertito restituisce
`signature_document_conversion_failed`, ciascuno con una `reason`.
fields:
type: array
description: >-
Campi opzionali da posizionare su questo documento, fino a 200. Le
pagine e le posizioni si riferiscono al PDF o al PDF convertito per
un file Word. Senza campi, il firmatario legge il documento e lo
accetta.
items:
$ref: '#/components/schemas/SignatureField'
maxItems: 200
SignatureField:
type: object
description: >-
Un campo da inserire su un documento di sessione: quale firmatario lo
compila, come e dove. Fornisci una posizione (`page`, `x`, `y`, `width`
e `height`) oppure un `anchor`. Le posizioni sono frazioni della pagina
così come visualizzata, a partire dall'angolo in alto a sinistra,
arrotondate a 4 decimali, e il campo deve rientrare nella pagina. Un
documento supporta fino a 200 campi e un firmatario fino a 500; ogni
ruolo con campi su un documento richiede un campo `signature` o
`initials`. Consulta [Campi sul
documento](/it/core-technology/electronic-signature/overview#campi-sul-documento).
required:
- key
- type
properties:
key:
type: string
pattern: ^[a-z][a-z0-9_]{0,63}$
description: >-
Definisce il nome del campo nei risultati e in `sign.field_values`.
Univoco all'interno del documento.
type:
type: string
enum:
- signature
- initials
- full_name
- date_signed
- text
- checkbox
- email
- data
description: >-
Cosa contiene il campo. Il firmatario applica la `signature` e le
`initials` adottate, inserisce `text`, spunta una `checkbox` e
digita una `email` se la sessione non dispone di un'email
verificata. Didit compila `full_name` (il nome verificato),
`date_signed` (la data della firma, nel fuso orario del firmatario),
`data` (da `prefill`) e una `email` verificata, mostrandoli in sola
lettura. Non esiste un tipo di selettore di date: usa `text`.
role:
type: string
enum:
- verified_person
- legal_representative
- key_people
description: >-
Chi compila il campo, con i valori di `signature_signer`. Un
passaggio compila e appone il timbro solo sui campi del proprio
firmatario. Il valore predefinito è il firmatario del passaggio.
page:
type: integer
minimum: 1
description: >-
Numero di pagina, da 1 al conteggio delle pagine del documento. Per
un documento Word, una pagina del PDF convertito.
x:
type: number
minimum: 0
maximum: 1
description: Bordo sinistro, espresso come frazione della larghezza della pagina.
'y':
type: number
minimum: 0
maximum: 1
description: Bordo superiore, espresso come frazione dell'altezza della pagina.
width:
type: number
minimum: 0.02
maximum: 1
description: >-
Larghezza, come frazione della larghezza della pagina. Una firma ha
una larghezza minima di `0.12`.
height:
type: number
minimum: 0.012
maximum: 1
description: >-
Altezza, come frazione dell'altezza della pagina. Una firma è alta
almeno `0.035`.
anchor:
$ref: '#/components/schemas/SignatureFieldAnchor'
required:
type: boolean
description: >-
`signature` and `initials` are required unless you set `false`.
`full_name`, `date_signed` and `data` are always required. The
signer can't finish a document until its required fields have a
value, and a required checkbox must be ticked.
label:
type: string
minLength: 1
maxLength: 80
description: >-
Mostrato al firmatario e nei risultati. Valore predefinito desunto
dal tipo.
placeholder:
type: string
nullable: true
maxLength: 80
description: Solo `text` ed `email`.
validation:
$ref: '#/components/schemas/SignatureFieldValidation'
prefill:
type: string
nullable: true
description: >-
Da dove proviene il valore: `identity.full_name`,
`identity.first_name`, `identity.last_name`,
`identity.date_of_birth` (`DD/MM/YYYY`), `identity.nationality`,
`identity.document_number`, `identity.document_type`,
`identity.issuing_country`, `identity.address`, `contact.email`,
`contact.phone`, `company.name`, `company.registration_number`,
`company.address`, `company.country` (KYB), `session.vendor_data`,
`metadata.` (una chiave dei `metadata` della sessione) o
`api.` (una chiave di `sign.field_values`). Obbligatorio per
`data`. `full_name` utilizza sempre `identity.full_name` ed `email`
utilizza `contact.email`. I valori dei campi `data`, `full_name` ed
`email` verificata vengono fissati quando il firmatario inizia ad
apporre la firma.
editable_when_prefilled:
type: boolean
default: false
description: >-
Solo `text` ed `email`: il firmatario può modificare un valore
precompilato.
checked_by_default:
type: boolean
default: false
description: 'Solo `checkbox`: la casella parte già selezionata.'
date_format:
type: string
enum:
- DD/MM/YYYY
- MM/DD/YYYY
- YYYY-MM-DD
- D MMMM YYYY
default: DD/MM/YYYY
description: Solo `date_signed`.
SignatureFieldAnchor:
type: object
description: >-
Posiziona un campo tramite una porzione di testo nel documento invece di
una posizione. Didit non rimuove il testo dal PDF, quindi scrivilo nello
stesso colore dello sfondo della pagina. Quando il testo non viene
trovato, la chiamata restituisce `400` con `field_anchor_not_found`.
Vedi [Posizionare i campi tramite testo di
ancoraggio](/it/sessions-api/create-session#posiziona-i-campi-tramite-testo-di-ancoraggio).
required:
- text
properties:
text:
type: string
minLength: 1
maxLength: 64
description: Testo cercato nel documento. Per i file Word, nel PDF convertito.
occurrence:
type: string
enum:
- first
- all
default: first
description: >-
`all` inserisce un campo per ogni corrispondenza; le chiavi
successive alla prima ricevono `_2`, `_3` e così via.
offset_x:
type: number
description: >-
Aggiunto al bordo sinistro del testo, come frazione della larghezza
della pagina.
offset_y:
type: number
description: >-
Aggiunto al bordo superiore del testo, come frazione dell'altezza
della pagina.
width:
type: number
minimum: 0.02
maximum: 1
description: Larghezza del campo, come frazione della larghezza della pagina.
height:
type: number
minimum: 0.012
maximum: 1
description: Altezza del campo, come frazione dell'altezza della pagina.
SignatureFieldValidation:
type: object
nullable: true
description: >-
Regole per il valore di un campo `text`. L'anteprima della console, il
flusso di firma e l'API applicano le stesse regole.
properties:
kind:
type: string
enum:
- any
- letters
- number
- email
- pattern
description: >-
`letters`: lettere in qualsiasi sistema di scrittura, spazi,
trattini e apostrofi. `number`: cifre con un separatore decimale
facoltativo. `pattern`: il valore deve corrispondere a `pattern`.
min_length:
type: integer
minimum: 0
maximum: 500
description: Da `0` fino a `max_length`.
max_length:
type: integer
minimum: 1
maximum: 500
default: 120
pattern:
type: string
nullable: true
minLength: 1
maxLength: 200
description: >-
Obbligatorio con `kind: "pattern"`. Un'espressione regolare a cui
deve corrispondere l'intero valore. Lookaround e backreference non
sono supportati.
message:
type: string
nullable: true
maxLength: 120
description: Mostrato al firmatario invece dell'errore predefinito.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
La chiave API della tua applicazione, da Developers -> API keys nella
Business Console. La chiave primaria ha accesso completo. Una chiave con
nome può avere un ambito definito: nessuno, lettura o scrittura per
risorsa, limitata ad alcuni workflow o a sessioni approvate, a un elenco
di indirizzi IP e a una data di scadenza. 401 indica che la chiave è
errata, revocata o scaduta; 403 indica che non è stata inviata alcuna
chiave, che la chiave non ha accesso a questa risorsa o azione, oppure
che la richiesta proviene da un indirizzo non incluso nel suo elenco IP;
404 su una route di sessione indica che la sessione non rientra nei
workflow o negli stati previsti dalla chiave. Una chiave senza accesso
ai media riceve gli URL di immagini, video e PDF come null, e una chiave
senza permessi di scrittura sulle sessioni riceve link e token di
sessione come null. Consulta https://docs.didit.me/console/api-keys.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.