API per sviluppatori

    Perché copiare i nomi manualmente tra sistemi quando una chiamata API fa tutto?

    Integri verifica aziendale, mappatura titolarità, controlli PEP, adverse media e segnali di sanzioni direttamente nei Suoi workflow esistenti.

    POST/api/v1/searchbash
    curl -X POST https://screenveritai.com/api/v1/search \
      -H 'X-API-Key: YOUR_API_KEY' \
      -H 'Content-Type: application/json' \
      -d '{
        "entity_name": "Acme Trading LLC",
        "entity_type": "company",
        "country": "AE",
        "search_type": "sanctions_check"
      }'
    # 202 Accepted
    # { "search_id": "SEARCH_ID", "status": "processing",
    #   "estimated_time_seconds": 15 }

    The request

    One POST call, then your poll loop.

    Entity name, type, country, screening type. The call returns 202 with a search_id and an ETA, and the agent works in the background — you poll for the result rather than hold the connection open.

    • entity_nameRequired, 1-500 characters. Alias-aware matching
    • entity_type"person", "company" or "any" (default "any")
    • countryOptional context field; does not filter Quick Check matching
    • search_type"sanctions_check", "adverse_media" or "full_search"

    The response

    Structured JSON. Findings, not a score.

    Core-jurisdiction fields and per-source arrays, plus criminal-watchlist and PEP/RCA findings. Review the available markdown, identifiers and source references; the response does not provide a numeric risk score.

    GET/api/v1/search/{search_id}200 OK
    {
      "id": "SEARCH_ID",
      "entity_name": "Acme Trading LLC",
      "entity_type": "company",
      "status": "completed",
      "search_type": "sanctions_check",
      "ofac_sanctions": "## OFAC Sanctions Findings\n\n**Status:** *Sanctioned*\n\n**Details:**\n- **Matched entity:** ACME TRADING LLC\n- **Authority:** US Treasury OFAC\n...",
      "eu_sanctions": "## EU Sanctions Findings\n\n**Status:** *No relevant listing found*\n...",
      "sanctions_sources": [
        { "source_id": "ofac_sanctions", "title": "OFAC Sanctions",
          "authority": "US Treasury OFAC", "hit_count": 1 },
        { "source_id": "eu_sanctions", "title": "EU Sanctions",
          "authority": "", "hit_count": 0 }
      ],
      "criminal_watchlists": null,
      "pep": null,
      "news_summary": null,
      "final_report": null,
      "created_at": "2026-09-04T09:20:03.771000+00:00",
      "completed_at": "2026-09-04T09:20:19.088000+00:00"
    }
    No relevant listing found / nullSanctioned / potential matchPer-source hit_countStatus and search_type
    • "ofac_sanctions"One markdown field per jurisdiction; read the *Status:* line
    • "sanctions_sources"source_id, title, authority, details, hit_count per source
    • "criminal_watchlists"Markdown when matched, null when nothing matched
    • "pep"Markdown when matched, null when nothing matched
    • "news_summary"Adverse-media report on adverse_media and full_search
    • "status"completed when done; error_* on failure

    API reference

    Three calls cover a screening integration: queue it, poll it, or hand over a file.

    POST/api/v1/searchQueue a screening run. Returns immediately with a search_id; the work happens in the background.202 Accepted
    Requestbash
    curl -X POST https://screenveritai.com/api/v1/search \
      -H 'X-API-Key: YOUR_API_KEY' \
      -H 'Content-Type: application/json' \
      -d '{"entity_name": "Acme Trading LLC", "entity_type": "company",
           "country": "AE", "search_type": "sanctions_check"}'
    Response202 Accepted
    { "search_id": "SEARCH_ID", "status": "processing",
      "message": "Search queued successfully. Poll the GET endpoint for results.",
      "estimated_time_seconds": 15 }
    GET/api/v1/search/{search_id}Poll for the result. Terminal status is completed; failures land in an error_* status.200 OK
    Requestbash
    curl https://screenveritai.com/api/v1/search/SEARCH_ID \
      -H 'X-API-Key: YOUR_API_KEY'
    Response200 OK
    { "id": "SEARCH_ID", "status": "completed", "search_type": "sanctions_check",
      "ofac_sanctions": "## OFAC Sanctions Findings ... *Sanctioned* ...",
      "eu_sanctions": "... *No relevant listing found* ...",
      "sanctions_sources": [{ "source_id": "ofac_sanctions", "hit_count": 1 }],
      "criminal_watchlists": null, "pep": null }
    POST/api/v1/batchUpload a CSV or XLSX with a name column — up to 100 rows and 2 MB. Poll the job, then export the CSV.202 Accepted
    Requestbash
    curl -X POST https://screenveritai.com/api/v1/batch \
      -H 'X-API-Key: YOUR_API_KEY' \
      -F 'file=@portfolio.csv'
    Response202 Accepted
    { "job_id": "JOB_ID", "total_rows": 100, "credits_charged": 100,
      "search_type": "sanctions_check", "status": "pending",
      "message": "Batch job created successfully. Poll the GET endpoint for status." }

    Integration patterns

    The API sits between data entry and decision — wherever you need a risk signal.

    • Customer onboarding

      1. Customer signup
      2. POST/api/v1/search
      3. Poll until completed
      4. Approve / hold
    • Payment processing

      1. Transaction init
      2. POST/api/v1/search
      3. Poll until completed
      4. Release / hold
    • CRM re-screen

      1. Record updated
      2. Your scheduler fires
      3. POST/api/v1/search
      4. Write result back

    Costruire in casa vs. integrare ScreenVeritAI

    Costruire in casa vs. integrare ScreenVeritAI
    AspettoCostruire in casaAPI ScreenVeritAI
    Tempo alla produzione6-12 mesi per reperire le liste, costruire il matching, gestire i casi limiteGiorni per integrare — pronta per la produzione dalla prima chiamata API
    Copertura liste di sanzioniAcquisizione manuale di ogni formato di lista; manutenzione continua dello schemaOgni fonte principale, mantenuta e aggiornata in modo continuo
    Precisione del matchingIl fuzzy matching personalizzato richiede competenze NLP e messa a punto costanteIA con fuzzy matching, traslitterazione, risoluzione degli alias, algoritmi fonetici
    PEP e adverse mediaFornitori separati, integrazioni separate, budget separatiDati PEP, adverse media e UBO nella stessa risposta API
    Manutenzione continuaUn team dedicato per aggiornamenti delle liste, modifiche allo schema, messa a punto dei falsi positiviCompletamente gestita — aggiornamenti, miglioramenti e infrastruttura a Suo carico zero
    Audit trailCostruisca da solo il Suo sistema di log, evidenze e conservazioneFascicoli di evidenza con data e ora e riferimenti alle fonti inclusi

    Quattro passaggi verso la conformità integrata

    1. Ottieni la Sua API key

      Crei una chiave con permessi definiti dalla Sua dashboard, a privilegio minimo: search:read, search:write, batch:read, batch:write.

    2. Integra l'endpoint

      Una chiamata POST nel Suo workflow di onboarding, pagamento o CRM — invii nome, tipo e paese dell'entità, ottenga un job ID in risposta.

    3. Elabora i risultati

      Effettui il polling dell'endpoint dei risultati per JSON strutturato — contesto aziendale, titolarità, PEP, adverse media, segnali di sanzioni e punteggi di rischio.

    4. Monitora e ricevi alert

      Configuri il monitoraggio continuo — l'API invia alert quando le liste di sanzioni si aggiornano o emergono nuovi adverse media.

    Iniziare in pochi minuti

    Un'unica chiamata API restituisce un risultato di screening completo.

    Sottoponi un'entità a screeningbash
    curl -X POST https://screenveritai.com/api/v1/search \
      -H 'X-API-Key: YOUR_API_KEY' \
      -H 'Content-Type: application/json' \
      -d '{"entity_name": "Acme Trading LLC", "country": "AE", "search_type": "sanctions_check"}'
    
    # 202 Accepted
    # { "search_id": "SEARCH_ID", "status": "processing", "estimated_time_seconds": 15 }
    Verifica il risultatobash
    curl https://screenveritai.com/api/v1/search/SEARCH_ID \
      -H 'X-API-Key: YOUR_API_KEY'
    
    # 200 OK
    # { "id": "SEARCH_ID", "status": "completed",
    #   "ofac_sanctions": "## OFAC Sanctions Findings ... *No relevant listing found* ...",
    #   "criminal_watchlists": null, "pep": null }

    Prestazioni dell'API

    • €0.39

      Quick Check per chiamata, nessun canone di piattaforma

    • 202

      Stato HTTP quando una ricerca è accettata; il risultato si ottiene con polling

    • EU

      Ospitato in Finlandia; i dati a riposo restano nell'UE

    FAQ sull'integrazione API

    Come autentico le richieste API?

    Autentichi le richieste API con una chiave segreta trasmessa nell'intestazione X-API-Key. Le chiavi vengono create dalla Sua dashboard con permessi definiti e a privilegio minimo.

    L'API è sincrona o asincrona?

    Asincrona. Invia una richiesta, ottiene un job ID, recupera i risultati tramite polling. La Sua pipeline non si blocca mai.

    Che formato di risposta restituisce l'API?

    JSON strutturato con campi per le principali giurisdizioni e array per fonte, oltre a risultati di liste di ricercati e PEP/RCA. Esamini markdown, identificatori e fonti disponibili. La risposta non fornisce un punteggio numerico di rischio.

    Quali rate limit si applicano?

    Assegnati in base al piano di abbonamento per ogni API key. Le intestazioni di risposta includono la quota residua e il timestamp di reset.

    Posso sottoporre a screening le entità in batch tramite l'API?

    Sì. L'endpoint batch accetta CSV o XLSX con un massimo di 100 righe per richiesta, con risultati recuperabili per riga o come esportazione completa.

    Come imposto il monitoraggio continuo tramite l'API?

    Configuri il monitoraggio dopo lo screening iniziale. Quando le liste si aggiornano o emergono nuovi adverse media, il monitoraggio segnala il cambiamento e La avvisa in-app.

    Quali dati di conformità sono inclusi in ogni risultato di screening?

    Corrispondenze di sanzioni su ogni principale fonte, stato PEP con collegamenti familiari, adverse media con citazioni multilingue, dati UBO, livello di rischio e fascicolo di evidenza con data e ora.

    Quanto tempo richiede uno screening?

    Controllo sanzioni standard: pochi secondi. Deep research con adverse media e mappatura della titolarità: meno di due minuti.

    Terminologia API

    API REST
    API web che usa metodi HTTP standard — compatibile con qualsiasi linguaggio o framework in grado di effettuare richieste HTTP.
    Elaborazione asincrona
    L'API accetta subito il job e lo elabora in background — recuperi i risultati tramite polling.
    API key
    Token segreto per autenticare le richieste API, con permessi definiti per un accesso a privilegio minimo.
    Rate limiting
    Limita le richieste API per finestra temporale in base al piano di abbonamento — quota residua e timestamp di reset nelle intestazioni di risposta.
    Risposta strutturata
    JSON leggibile da macchina con nomi e tipi di campo coerenti, che consente parsing automatico e logica decisionale.

    API REST per lo screening AML

    Integri sanzioni, PEP, liste di controllo penale, adverse media e screening KYB/UBO direttamente nei Suoi flussi di onboarding, monitoraggio e transazione. L'API è attiva: si autentichi con una API key e chiami lo stesso motore di screening usato dal portale.

    Gli endpoint sono generalmente disponibili con autenticazione tramite API key e rate limit per piano. Esplori ogni endpoint nella documentazione OpenAPI interattiva su /api/v1/docs.

    Avvio rapido

    1. 1. Crea una API key

      Crei una API key con permessi definiti dalla Sua dashboard, oppure ne generi una a livello di codice con il token bearer del Suo account per le richieste server-to-server.

      POST/api/v1/keyscurl
      curl -X POST https://screenveritai.com/api/v1/keys \
        -H "Authorization: Bearer <SUPABASE_JWT>" \
        -H "Content-Type: application/json" \
        -d '{"name":"server-key","permissions":["search:read","search:write"]}'
    2. 2. Esegui la prima ricerca

      Invii un'entità con l'intestazione X-API-Key. L'API restituisce un id di ricerca che recupera al termine dell'elaborazione.

      POST/api/v1/searchcurl
      curl -X POST https://screenveritai.com/api/v1/search \
        -H "X-API-Key: <YOUR_API_KEY>" \
        -H "Content-Type: application/json" \
        -d '{"entity_name":"Acme Ltd","entity_type":"company","search_type":"full_search"}'
    3. 3. Invia un batch

      Invii un file CSV/XLSX per sottoporre a screening molte entità in un unico job, poi recuperi le righe o le esportazioni al termine del batch.

      POST/api/v1/batchcurl
      curl -X POST https://screenveritai.com/api/v1/batch \
        -H "X-API-Key: <YOUR_API_KEY>" \
        -F "file=@entities.csv"

    Endpoint principali

    • POST/api/v1/search

      Crea una richiesta di screening per un'entità. Restituisce un id di ricerca e lo stato di elaborazione. Sono disponibili anche endpoint per account, copertura e stato del servizio sotto /api/v1.

      Auth: X-API-Key (search:write)

    • POST/api/v1/batch

      Invia file CSV/XLSX per screening ad alto volume, poi recupera righe o esportazioni al termine dei job.

      Auth: X-API-Key (batch:write)

    • POST/api/v1/keys

      Crea e gestisce credenziali API con permessi definiti, rate limit differenziati per piano e tracciamento dell'utilizzo.

      Auth: Bearer token (account)

    Crypto address checks. Source evidence at 0,39 €.

    Check an address against OFAC’s published digital-currency identifiers. Add native-USDC issuer-block status on Ethereum in the same request, at the same price.

    0,39 € per completed address check · prepaid PAYG only

    • POST/api/v1/crypto-address/checks
    • GET/api/v1/crypto-address/checks/{id}
    OFAC address match
    Exact address lookup under the requested OFAC currency label, such as ETH, XBT, TRX, USDT or USDC. Evidence includes the publication date, source URL, export hash and matching OFAC record.
    Ethereum USDC
    Set network to ethereum to check native-USDC issuer-block status at a finalized Ethereum mainnet block. The result includes the contract address, block number, block hash and contract response. Omit network for an OFAC-only check.
    Create a check
    POST requires X-API-Key with search:write, an Idempotency-Key of 16–128 ASCII letters, digits, underscores, dots, colons or hyphens, and address, currency and integer max_prepaid_cents fields. Set max_prepaid_cents to 39 to authorize the current price. A completed request returns HTTP 200 synchronously.
    Retrieve and retry
    GET requires search:read and returns your saved check without another charge. If a POST response is lost, reuse the same Idempotency-Key and payload. Keep that key while the outcome is uncertain; create a new key only for a deliberate new check.
    Billing
    Completed checks debit 0,39 € from your EUR prepaid balance. Minimum balance top-up: €5. Subscription allowances do not apply. Source failures are unpaid.

    A negative result means no published OFAC match or no native-USDC issuer block in the checked source. It does not establish wallet ownership or clear an address of all risk.

    This is an address-level source check. Transaction tracing, exposure scoring and continuous KYT monitoring are outside its scope. Crypto checks use this separate API; they are not available through name-screening batch uploads, portal history or PDF reports.

    Perché i team usano l'API

    • Un'unica integrazione per screening di sanzioni, PEP, liste di controllo penale, adverse media e KYB/UBO
    • Autenticazione con API key tramite l'intestazione X-API-Key, con chiavi a permessi definiti per un accesso a privilegio minimo
    • Rate limit per piano con registro degli utilizzi per governance e controllo dei costi
    • Endpoint di ricerca, batch, chiavi, account, copertura e stato del servizio sotto /api/v1
    • Documentazione OpenAPI interattiva su /api/v1/docs più uno schema OpenAPI leggibile da macchina
    • Output strutturato adatto a registri di audit, fascicoli di caso e decisioni a valle

    Integration playbooks

    FAQ sull'API

    Come autentico le richieste API?

    Le richieste di screening a /api/v1/search e /api/v1/batch si autenticano con una API key inviata nell'intestazione X-API-Key. Crei le chiavi dalla Sua dashboard, oppure a livello di codice tramite /api/v1/keys dopo essersi autenticato con il token bearer del Suo account.

    L'API è generalmente disponibile?

    Sì. L'API v1 è attiva e generalmente disponibile. Si autentichi con una API key, chiami gli endpoint di ricerca, batch e gestione chiavi, ed esplori tutto nella documentazione OpenAPI interattiva su /api/v1/docs.

    Posso definire i permessi delle API key?

    Sì. Le chiavi supportano permessi come search:read, search:write, batch:read e batch:write, così può applicare un accesso a privilegio minimo per ogni integrazione.

    Quali rate limit si applicano?

    I rate limit sono assegnati per livello API e applicati per ogni API key — il livello regola il throughput delle richieste, non la fatturazione. Le intestazioni di risposta includono il limite, la quota residua e i timestamp di reset, così può gestire correttamente i tentativi.

    Dove posso testare rapidamente gli endpoint?

    Utilizzi la documentazione interattiva su /api/v1/docs per test Swagger e /api/v1/redoc per la documentazione in stile riferimento. Lo schema OpenAPI viene servito su /api/v1/openapi.json.

    Avvii lo screening in pochi minuti.

    Scelga un piano e inizi oggi stesso lo screening.