Everything you need to integrate document verification: REST + JSON, signed webhooks, free sandbox, OpenAPI and SDK.
The Validento API verifies identity, documents and income inside your product — to onboard a client (KYC), hire someone from abroad, accept a tenant or buyer, or sign with a business partner. Send a person's documents (or a link so they upload them) and receive a score, a decision and the deviations found — by webhook or by polling.
| Base URL | https://api.validento.com |
|---|---|
| Format | JSON (UTF-8) · HTTPS · REST |
| Version | v1 · header Validento-Version: 2026-10-01 |
| Environments | vld_test_… sandbox (free, deterministic results) · vld_live_… production |
| Data | Analysed in the EU (Netherlands); results stored in the US (Supabase, Oregon). Documents are not stored after the analysis. |
Enterprise dashboard → Developers → API keys → “+ Sandbox key”. It is shown once: store it in your secrets manager.
curl https://api.validento.com/v1/me \
-H "Authorization: Bearer vld_test_YOUR_SANDBOX_KEY"import Validento from 'https://validento.com/sdk/validento.mjs';
const vd = new Validento(process.env.VALIDENTO_KEY);
console.log(await vd.me());import os, requests
r = requests.get("https://api.validento.com/v1/me", headers={"Authorization": f"Bearer {os.environ['VALIDENTO_KEY']}"})
print(r.json())$ch = curl_init("https://api.validento.com/v1/me");
curl_setopt_array($ch, [CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("VALIDENTO_KEY")], CURLOPT_RETURNTRANSFER => true]);
echo curl_exec($ch);
curl https://api.validento.com/v1/screenings \
-H "Authorization: Bearer vld_test_YOUR_SANDBOX_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"applicant": { "name": "Ana García", "email": "ana@example.com" },
"purpose": "client_onboarding",
"country": "ES",
"reference": "case-1042",
"consent_confirmed": true,
"case_details": { "source_of_funds": "salary", "employer": "Acme SL" },
"documents": [
{ "type": "payslip", "url": "https://files.yourapp.com/signed/payslip-sept.pdf" },
{ "type": "bank_statement", "media_type": "application/pdf", "data": "JVBERi0xLjQK..." }
],
"metadata": { "customer_id": "c_981" }
}'import Validento from './validento.mjs';
const vd = new Validento(process.env.VALIDENTO_KEY);
const screening = await vd.screenings.create({
applicant: { name: 'Ana García', email: 'ana@example.com' },
purpose: 'client_onboarding', country: 'ES', reference: 'case-1042',
consent_confirmed: true,
case_details: { source_of_funds: 'salary', employer: 'Acme SL' },
documents: [
{ type: 'payslip', url: 'https://files.yourapp.com/signed/payslip-sept.pdf' },
{ type: 'bank_statement', media_type: 'application/pdf', data: fs.readFileSync('statement.pdf').toString('base64') },
],
metadata: { customer_id: 'c_981' },
});
console.log(screening.id, screening.status); // "processing"import os, uuid, base64, requests
H = {"Authorization": f"Bearer {os.environ['VALIDENTO_KEY']}"}
r = requests.post("https://api.validento.com/v1/screenings",
headers={**H, "Idempotency-Key": str(uuid.uuid4())},
json={
"applicant": {"name": "Ana García", "email": "ana@example.com"},
"purpose": "client_onboarding", "country": "ES", "reference": "case-1042",
"consent_confirmed": True,
"case_details": {"source_of_funds": "salary", "employer": "Acme SL"},
"documents": [
{"type": "payslip", "url": "https://files.yourapp.com/signed/payslip-sept.pdf"},
{"type": "bank_statement", "media_type": "application/pdf",
"data": base64.b64encode(open("statement.pdf", "rb").read()).decode()},
],
"metadata": {"customer_id": "c_981"},
}, timeout=60)
r.raise_for_status()
print(r.json()["id"])<?php
function validento(string $method, string $path, ?array $body = null): array {
$ch = curl_init("https://api.validento.com" . $path);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => $method, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 60,
CURLOPT_HTTPHEADER => array_filter([
"Authorization: Bearer " . getenv("VALIDENTO_KEY"), "Content-Type: application/json",
$method === "POST" ? "Idempotency-Key: " . bin2hex(random_bytes(16)) : null,
]),
CURLOPT_POSTFIELDS => $body ? json_encode($body) : null,
]);
$res = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) >= 400) throw new RuntimeException($res["error"]["code"] ?? "error");
return $res;
}
$s = validento("POST", "/v1/screenings", [
"applicant" => ["name" => "Ana García"], "purpose" => "client_onboarding", "consent_confirmed" => true,
"case_details" => ["source_of_funds" => "salary", "employer" => "Acme SL"],
"documents" => [["type" => "payslip", "url" => "https://files.yourapp.com/signed/payslip-sept.pdf"]],
]);
echo $s["id"];
Register a webhook endpoint (dashboard or API) and receive screening.completed. Or poll GET /v1/screenings/{id} until status is no longer processing (usually 10–60 s; sandbox: instant).
When your integration works in sandbox, your account manager enables live. Swap the key for a vld_live_… one; the code stays the same.
Paste a sandbox key and call the API directly. The key stays in this tab (sessionStorage) and only travels to api.validento.com.
Send the key on every request as Authorization: Bearer vld_…. Only a hash is stored: if you lose it, create another. Keys are server-side: never in a browser or mobile app.
A key has full access (*) or is restricted: give each system only what it needs. write includes read. Without the scope: 403 missing_scope.
| Scope | Allows |
|---|---|
screenings:read | Read screenings and reports. |
screenings:write | Create and delete screenings (+ read). |
links:read | Read verification links. |
links:write | Create and cancel links (+ read). Ideal for the backend of your frontend. |
id_checks:read / id_checks:write | Read / create and cancel ID checks (ValiD). |
sanctions:read / sanctions:write | Read / create sanctions & PEP screenings. |
webhooks:read / webhooks:write | Manage endpoints; resend events. |
events:read | Read events (30 days). |
usage:read | Period usage and invoices. |
settings:read / settings:write | Settings: rules, branding, format, notifications. |
“Rotate” creates a new key and keeps the old one alive for the grace period you choose (0 h, 1 h, 24 h or 7 days). Deploy the new one, confirm in the request log that the old one is no longer used, and let it expire. Key exposed? Revoke it: it stops working within seconds.
Optional, per account: exact IPs or IPv4 CIDR ranges (203.0.113.0/24). Other IPs get 403 ip_not_allowed. Ask your account manager.
vld_test_ keys analyse nothing and charge nothing, and return deterministic results so you can test every path in your code. Test and live objects are fully separate (webhooks and events too).
sandbox_outcome | or in reference / name | Result |
|---|---|---|
approve (default) | — | score 86 · approve |
review | review | score 58 · review · 1 medium deviation |
decline | decline | score 28 · decline · 1 high deviation |
fail | fail | status failed · screening.failed |
Bodies in JSON (Content-Type: application/json). Dates in ISO 8601 UTC; amounts in cents (integers). Every response carries:
Validento-Request-Id | Include it when you contact support. |
Validento-Version | API version that answered. |
RateLimit-Limit / -Remaining / -Reset | Your per-minute quota. |
Idempotent-Replayed: true | Replayed response of an Idempotency-Key. |
Send Idempotency-Key: <uuid> on every POST. If the network fails and you retry with the same key within 24 h, you get the original response and no duplicate is created. The same key with another body returns 409 idempotency_conflict. The SDK does this for you.
Lists return { object:"list", data:[…], has_more }, newest first. Parameters: limit (1–100), starting_after=<id> (next page), ending_before=<id> (previous), created[gte] and created[lte] (unix seconds or ISO 8601).
curl -G https://api.validento.com/v1/screenings \
-H "Authorization: Bearer vld_test_YOUR_SANDBOX_KEY" \
-d limit=100 -d status=completed -d "created[gte]=1759276800" \
-d "metadata[customer_id]=c_981"for await (const s of vd.screenings.listAll({ status: 'completed', created: { gte: new Date('2026-10-01') }, metadata: { customer_id: 'c_981' } })) {
console.log(s.id, s.decision);
}params = {"limit": 100, "status": "completed"}
while True:
page = requests.get("https://api.validento.com/v1/screenings", headers=H, params=params).json()
for s in page["data"]:
print(s["id"], s["decision"])
if not page["has_more"]:
break
params["starting_after"] = page["data"][-1]["id"]$params = ["limit" => 100, "status" => "completed"];
do {
$page = json_decode(file_get_contents("https://api.validento.com/v1/screenings?" . http_build_query($params), false, $ctx), true);
foreach ($page["data"] as $s) echo $s["id"], " ", $s["decision"], "\n";
$params["starting_after"] = end($page["data"])["id"] ?? null;
} while ($page["has_more"]);
Store your own IDs in metadata (up to 20 keys of ≤ 40 characters, string values ≤ 500). It is returned as given, travels in webhooks and can be filtered with metadata[key]=value.
v1 does not break. We add fields, endpoints, events and enum values without notice: ignore what you don't know. An incompatible change gets a new dated version, with at least 12 months of transition and notice by email.
Errors use HTTP status codes and a stable body. Code against error.code (stable), not the message.
{
"error": {
"type": "invalid_request_error",
"code": "consent_required",
"message": "\"consent_confirmed\": true is required — confirm the applicant agreed to the check.",
"param": "consent_confirmed",
"doc_url": "https://validento.com/developers#error-consent_required",
"request_id": "req_Fq9MsetWX27BncBC"
}
}
Retry safely (same Idempotency-Key) on 429, 500 and network errors. Don't retry other 4xx without changing the request.
invalid_api_key 401 authentication_errorKey missing, mistyped, revoked or expired. → Check the Authorization: Bearer vld_… header.
missing_scope 403 permission_errorThe key is restricted and lacks this scope. → Use another key, or create one with the scope named in the message.
ip_not_allowed 403 permission_errorThe IP is not on your allowlist. → Add your server's egress IP in the dashboard.
live_not_enabled 403 permission_errorLive access is not enabled yet. → Keep using sandbox; your account manager enables live after the review.
account_suspended 403 permission_errorAccount suspended. → Contact your account manager.
service_not_enabled 403 permission_errorThe service is not in your agreement. → Ask your account manager.
insufficient_balance 402 billing_errorPrepaid balance too low. → Top up, or turn on auto top-up.
credit_limit_reached 402 billing_errorCredit limit reached. → Pay the open invoice or ask for a higher limit.
rate_limited 429 rate_limit_errorToo many requests. → Wait Retry-After seconds and retry.
invalid_json 400 invalid_request_errorThe body is not valid JSON. → Send Content-Type: application/json and a JSON object.
invalid_parameter 400 invalid_request_errorA parameter is invalid (see param). → Fix the field named in error.param.
invalid_purpose 400 invalid_request_errorUnknown purpose. → Use client_onboarding, employment, rental, purchase, business_partner or civil_matter.
invalid_metadata 400 invalid_request_errormetadata breaks the limits. → Max 20 keys of ≤ 40 chars, string values ≤ 500.
applicant_required 400 invalid_request_errorapplicant.name is missing.
consent_required 422 invalid_request_errorconsent_confirmed: true is missing. → Confirm the person agreed to the check.
documents_required 400 invalid_request_errorNo documents. → Send 1 to 20 documents.
too_many_documents 400 invalid_request_errorMore than 20 documents. → Split the case or combine pages into one PDF.
invalid_document 400 invalid_request_errorDocument without url or data+media_type.
unsupported_media_type 415 invalid_request_errorUnsupported format. → PDF, JPEG, PNG or WebP.
document_too_large 413 invalid_request_errorA document exceeds 10 MB. → Compress the image or lower the resolution.
documents_too_large 413 invalid_request_errorDocuments exceed 20 MB in total.
document_url_unreachable 422 invalid_request_errorWe could not download a URL (15 s). → Use a signed URL valid ≥ 10 min, or send base64.
invalid_settings 400 invalid_request_errorInvalid settings (see message).
invalid_url 400 invalid_request_errorThe URL must start with https://.
too_many_endpoints 409 invalid_request_errorAt most 10 endpoints.
link_not_pending 409 invalid_request_errorOnly a pending link can be canceled.
idempotency_conflict 409 idempotency_errorIdempotency-Key reused with another body. → Generate a new key per operation.
link_expired 410 invalid_request_errorLink expired or already used. → Create a new link.
not_found 404 invalid_request_errorNo such object (or it belongs to the other environment). → Test keys don't see live objects and vice versa.
method_not_allowed 405 invalid_request_errorMethod not allowed on this path.
server_error 500 api_errorOur fault. → Safe to retry (with the same Idempotency-Key).
| Requests per key | 120 / min live · 60 / min sandbox · raised on request |
| Documents per screening | 1–20 · ≤ 10 MB each · ≤ 20 MB in total |
| Formats | PDF, JPEG, PNG, WebP |
| Download of url | 15 s per document |
| Webhook endpoints | 10 per account · answer within 10 s |
| Events retrievable | 30 days |
| Screening retention | per your contract (default 365 days); deleted automatically afterwards |
Over the limit: 429 rate_limited with Retry-After. For bulk loads, spread requests or ask for a higher limit.
A screening = one person (or company) with 1 to 20 documents. It is asynchronous: created with status: "processing", ending in completed or failed. Only completed live screenings are billed.
/v1/screeningsscreenings:writeapplicant.name stringrequiredName of the person (or company).
applicant.email / phone / date_of_birth / id_number / company / address / country stringMore data helps the identity cross-check. date_of_birth as YYYY-MM-DD, country ISO alpha-2.
documents[] arrayrequired1–20 objects: { url } (https, we download it) or { data, media_type } (base64). Optional type as a hint: payslip, bank_statement, id, employment_contract, tax_return, rental_contract, purchase_agreement, registration_docs, annual_accounts…
consent_confirmed truerequiredYou confirm the person agreed to the check.
purpose enumclient_onboarding (KYC) · employment (hiring) · rental · purchase · business_partner · civil_matter. Changes what is weighed: identity and source of funds for onboarding, work history for a hire, income for a rental. Default: your setting.
country stringCountry of the documents (ISO alpha-2). Improves extraction.
case_details objectFacts the engine compares with the documents: employer, address, rent, price, declared source of funds… Each difference becomes a deviation. Flat, ≤ 30 snake_case keys. E.g. { "monthly_rent": 1200, "employer": "Acme SL" }
reference stringYour own ID (≤ 120). Filterable.
metadata objectSee metadata.
lang en | esLanguage of the summary and deviations.
sandbox_outcome enumSandbox only: approve, review, decline, fail.
curl https://api.validento.com/v1/screenings \
-H "Authorization: Bearer vld_test_YOUR_SANDBOX_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"applicant": { "name": "Ana García", "email": "ana@example.com" },
"purpose": "client_onboarding",
"country": "ES",
"reference": "case-1042",
"consent_confirmed": true,
"case_details": { "source_of_funds": "salary", "employer": "Acme SL" },
"documents": [
{ "type": "payslip", "url": "https://files.yourapp.com/signed/payslip-sept.pdf" },
{ "type": "bank_statement", "media_type": "application/pdf", "data": "JVBERi0xLjQK..." }
],
"metadata": { "customer_id": "c_981" }
}'import Validento from './validento.mjs';
const vd = new Validento(process.env.VALIDENTO_KEY);
const screening = await vd.screenings.create({
applicant: { name: 'Ana García', email: 'ana@example.com' },
purpose: 'client_onboarding', country: 'ES', reference: 'case-1042',
consent_confirmed: true,
case_details: { source_of_funds: 'salary', employer: 'Acme SL' },
documents: [
{ type: 'payslip', url: 'https://files.yourapp.com/signed/payslip-sept.pdf' },
{ type: 'bank_statement', media_type: 'application/pdf', data: fs.readFileSync('statement.pdf').toString('base64') },
],
metadata: { customer_id: 'c_981' },
});
console.log(screening.id, screening.status); // "processing"import os, uuid, base64, requests
H = {"Authorization": f"Bearer {os.environ['VALIDENTO_KEY']}"}
r = requests.post("https://api.validento.com/v1/screenings",
headers={**H, "Idempotency-Key": str(uuid.uuid4())},
json={
"applicant": {"name": "Ana García", "email": "ana@example.com"},
"purpose": "client_onboarding", "country": "ES", "reference": "case-1042",
"consent_confirmed": True,
"case_details": {"source_of_funds": "salary", "employer": "Acme SL"},
"documents": [
{"type": "payslip", "url": "https://files.yourapp.com/signed/payslip-sept.pdf"},
{"type": "bank_statement", "media_type": "application/pdf",
"data": base64.b64encode(open("statement.pdf", "rb").read()).decode()},
],
"metadata": {"customer_id": "c_981"},
}, timeout=60)
r.raise_for_status()
print(r.json()["id"])<?php
function validento(string $method, string $path, ?array $body = null): array {
$ch = curl_init("https://api.validento.com" . $path);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => $method, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 60,
CURLOPT_HTTPHEADER => array_filter([
"Authorization: Bearer " . getenv("VALIDENTO_KEY"), "Content-Type: application/json",
$method === "POST" ? "Idempotency-Key: " . bin2hex(random_bytes(16)) : null,
]),
CURLOPT_POSTFIELDS => $body ? json_encode($body) : null,
]);
$res = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) >= 400) throw new RuntimeException($res["error"]["code"] ?? "error");
return $res;
}
$s = validento("POST", "/v1/screenings", [
"applicant" => ["name" => "Ana García"], "purpose" => "client_onboarding", "consent_confirmed" => true,
"case_details" => ["source_of_funds" => "salary", "employer" => "Acme SL"],
"documents" => [["type" => "payslip", "url" => "https://files.yourapp.com/signed/payslip-sept.pdf"]],
]);
echo $s["id"];
Response 202 with the object in processing. Always use Idempotency-Key.
{
"id": "6c1f6a2e-4b1d-4f7e-9c55-2a8f0d7b3e11",
"object": "screening",
"environment": "live",
"status": "completed",
"channel": "api",
"reference": "case-1042",
"purpose": "client_onboarding",
"country": "ES",
"applicant": { "name": "Ana García", "email": "ana@example.com" },
"document_count": 3,
"decision": "approve",
"score": 82,
"result": {
"score": 82,
"decision": "approve",
"display_score": "82/100",
"summary": "Documents are consistent; net income matches the bank statements.",
"detected_document_type": "payslip",
"detected_country": "ES",
"documents_checked": 3,
"deviations": [
{ "field": "employer_name", "severity": "low", "note": "Abbreviated on one payslip" }
],
"fields": [ { "name": "net_monthly_income", "value": "3180.00" } ],
"income": { "monthly_amount": 3180, "currency": "EUR" },
"breakdown": { "document_integrity": 88, "financial_capacity": 79, "identity": 84 }
},
"case_details": { "employer": "Acme SL" },
"error": null,
"metadata": { "customer_id": "c_981" },
"link_id": null,
"created_at": "2026-10-04T09:12:03.120Z",
"completed_at": "2026-10-04T09:12:41.877Z"
}
score 0–100Always the same scale; your rules decide.
decision approve | review | declinePer your decision rules (default ≥ 70 / ≥ 45).
result.deviations[] arrayWhat doesn't add up: between documents, against case_details, or signs of tampering. severity low/medium/high.
result.fields[] arrayExtracted data (employer, net pay, partial IBAN, dates…).
result.income objectDetected monthly income and currency.
result.breakdown objectSub-scores 0–100: document integrity, financial capacity, identity.
result.display_score stringThe score on your scale (82/100, 8.2/10 or B).
error string | nullWhen failed: engine_unavailable or another reason. Not charged; you can retry.
result you receive is up to you in result_format./v1/screeningsscreenings:readFilters: reference, status, decision, purpose, channel (api/link/dashboard), link_id, metadata[key], created[gte|lte] + pagination.
/v1/screenings/{id}screenings:read/v1/screenings/{id}/report?lang=enscreenings:readPrintable HTML report in your branding. Turn it into a PDF with any browser or headless Chrome (Puppeteer: page.pdf()).
/v1/screenings/{id}screenings:writePermanent erase (GDPR): removes the screening and the person's data on its link; billed usage is kept without personal data. Emits screening.deleted.
Don't have the documents? Create a link: the person uploads them on a page with your branding (or inside your app) and you receive link.completed + screening.completed.
/v1/verification-linkslinks:writeapplicant.name stringrequiredName the person sees.
applicant.email stringRequired with send_email.
send_email booleanWe email the link in your branding (replies go to your support email).
locale es | enLanguage of the page and email.
documents_requested string[]List the person sees (≤ 20).
expires_in_days 1–30Default: your setting (7).
redirect_url https URLWhere to go when done.
purpose / country / reference / case_details / metadata / brand_name As for a screening; carried over to the resulting screening.
curl https://api.validento.com/v1/verification-links \
-H "Authorization: Bearer vld_test_YOUR_SANDBOX_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"applicant": { "name": "Ana García", "email": "ana@example.com" },
"purpose": "employment",
"reference": "case-1042",
"documents_requested": ["ID", "Last payslip", "Employment letter"],
"send_email": true,
"locale": "es"
}'const link = await vd.verificationLinks.create({
applicant: { name: 'Ana García', email: 'ana@example.com' },
purpose: 'employment', reference: 'case-1042',
documents_requested: ['ID', 'Last payslip', 'Employment letter'],
send_email: true, locale: 'es',
});
console.log(link.url, link.embed_url);link = requests.post("https://api.validento.com/v1/verification-links", headers={**H, "Idempotency-Key": str(uuid.uuid4())}, json={
"applicant": {"name": "Ana García", "email": "ana@example.com"},
"purpose": "employment", "reference": "case-1042",
"documents_requested": ["ID", "Last payslip", "Employment letter"],
"send_email": True, "locale": "es",
}).json()
print(link["url"])$link = validento("POST", "/v1/verification-links", [
"applicant" => ["name" => "Ana García", "email" => "ana@example.com"],
"purpose" => "employment", "reference" => "case-1042",
"send_email" => true, "locale" => "es",
]);
echo $link["url"];
url and embed_url carry a secret token and are only returned on create. Store them if you need them later.Create the link on your server and pass embed_url to the browser. No keys in the frontend.
<script src="https://validento.com/embed.js"></script>
<button id="verify">Verify my documents</button>
<script>
document.getElementById('verify').onclick = () => {
Validento.open({
url: EMBED_URL_FROM_YOUR_SERVER,
onReady: () => console.log('page loaded'),
onComplete: (e) => console.log('submitted', e.screening_id), // result follows by webhook
onClose: () => console.log('closed'),
closeDelay: 2500,
});
};
// Or inline: Validento.mount('#verify-box', { url: EMBED_URL, onComplete })
</script>
/v1/verification-linkslinks:readFilters: status (pending/completed/expired/canceled), reference, purpose + pagination.
/v1/verification-links/{id}links:read/v1/verification-links/{id}/cancellinks:writeSend a person a link: on their phone they photograph their document and do a short live face scan. We check the MRZ check digits (ICAO 9303), expiry, face match and liveness. No images are kept; you get the decision and a report with the figures.
/v1/id-checksid_checks:writeapplicant.name stringrequiredAs on the document (min. 3 characters).
applicant.email stringrequiredFor the email with the link.
purpose stringWhat it is for; the person sees it.
reference stringYour id (CRM, case); comes back on every event.
send_email booleanWe email the link in your name. Otherwise use url (only in this response).
locale es | enLanguage of the email and the page.
expires_in_days integer1–30, default 14.
metadata objectUp to 20 key/value pairs.
curl https://api.validento.com/v1/id-checks \
-H "Authorization: Bearer vld_test_YOUR_SANDBOX_KEY" \
-H "Content-Type: application/json" \
-d '{"applicant":{"name":"Ana García","email":"ana@example.com"},"purpose":"New client — file 1042","reference":"crm-1042","send_email":true,"locale":"es"}'const check = await vd.idChecks.create({
applicant: { name: 'Ana García', email: 'ana@example.com' },
purpose: 'New client — file 1042', reference: 'crm-1042', send_email: true, locale: 'es',
});
console.log(check.status, check.url); // "pending", https://validento.com/id/…r = requests.post("https://api.validento.com/v1/id-checks", headers={"Authorization": f"Bearer {key}"},
json={"applicant": {"name": "Ana García", "email": "ana@example.com"}, "reference": "crm-1042", "send_email": True})
print(r.json()["status"])$body = json_encode(["applicant" => ["name" => "Ana García", "email" => "ana@example.com"], "reference" => "crm-1042", "send_email" => true]);
| status | Meaning |
|---|---|
pending | Waiting for the person. |
retry | An attempt failed (photo, expiry, face); they may retry, up to 3 tries. |
in_review | A Validento specialist decides from the report — never an automatic reject over a bad photo. |
passed / rejected | Final decision (event id_check.completed). |
canceled / expired | Canceled, or not finished in time. |
/v1/id-checksid_checks:readFilters: status, reference, metadata[key] + pagination.
/v1/id-checks/{id}id_checks:read/v1/id-checks/{id}/cancelid_checks:write/v1/id-checks/{id}/simulateid_checks:writeSandbox: with a vld_test_… key, simulate with {"outcome":"passed"} (or retry, in_review, rejected) plays the outcome without a person and sends its webhook. Billing: one check of the month once the person submits their first try (live).
Screen a person or company against international sanctions lists (UN, EU, US OFAC, UK and many more), politically exposed persons (PEP) and criminal watchlists, with OpenSanctions data updated daily. The answer comes back at once.
/v1/sanctions-screeningssanctions:writesubject.name stringrequiredFull name of the person, or the company name.
subject.kind person | companyDefault person.
subject.birth_date stringYYYY or YYYY-MM-DD (person). Cuts false matches a lot.
subject.nationality stringISO 3166-1 alpha-2 (person).
subject.country stringISO 3166-1 alpha-2, jurisdiction (company).
subject.registration_number stringCompany registration number.
reference stringYour id; comes back on the object and every event.
customer stringYour customer id (Customers).
metadata objectUp to 20 key/value pairs.
curl https://api.validento.com/v1/sanctions-screenings \
-H "Authorization: Bearer vld_test_YOUR_SANDBOX_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: crm-1042-sanctions" \
-d '{"subject":{"kind":"person","name":"Ana García López","birth_date":"1986-03-14","nationality":"ES"},"reference":"crm-1042"}'const s = await vd.sanctionsScreenings.create({
subject: { kind: 'person', name: 'Ana García López', birth_date: '1986-03-14', nationality: 'ES' },
reference: 'crm-1042',
});
if (s.status === 'clear') proceed();
else if (s.status === 'in_review') hold(); // wait for sanctions_screening.reviewedr = requests.post("https://api.validento.com/v1/sanctions-screenings", headers={"Authorization": f"Bearer {key}"},
json={"subject": {"kind": "company", "name": "Acme Trading Ltd", "country": "GB"}, "reference": "supplier-77"})
print(r.json()["status"])$body = json_encode(["subject" => ["name" => "Ana García López", "birth_date" => "1986-03-14"], "reference" => "crm-1042"]);
| status | Meaning |
|---|---|
clear | No match above the threshold. |
in_review | A name matches a list entry. Not a finding: a Validento specialist compares date of birth, country and other details, usually within one working day. Meanwhile, don't take adverse decisions on this alone. |
no_match | Reviewed: not the same person or company (note in review.note). |
confirmed_match | Reviewed: the match is confirmed. Follow your own procedures (e.g. your compliance officer). |
failed | The lists could not be queried; not billed. Retry (the same Idempotency-Key never duplicates). |
result.hits lists the similar entries: caption, score (0–1), topics (e.g. sanction, role.pep, crime), datasets, countries, birth_dates and a public url. result.sanctioned and result.pep summarise the matches.
/v1/sanctions-screeningssanctions:readFilters: status, reference, customer, metadata[key] + pagination.
/v1/sanctions-screenings/{id}sanctions:readHow to integrate it
clear → continue. in_review → put the file on hold.sanctions_screening.reviewed webhook: data.status is no_match or confirmed_match.id in your KYC file as evidence (date, lists, decision).Billing: each live screening is one unit of your Enterprise usage (not billed when failed). Sandbox: with a vld_test_… key no lists are searched; a name containing "match" plays a possible match (in_review), any other name is clear. Scopes: sanctions:read / sanctions:write.
We send you a signed POST when something changes. Each environment has its own endpoints.
| Event | When |
|---|---|
screening.created | Screening created (status processing). |
screening.completed | Result available: score, decision, result. |
screening.failed | Could not be completed (not charged). |
screening.deleted | Erased (GDPR) via API or dashboard. |
link.created | Verification link created. |
link.completed | The person submitted documents; data.screening_id. |
link.canceled | Link canceled. |
link.expired | The link expired unused. |
id_check.created | ID check created (also from the dashboard). |
id_check.completed | Final decision: data.status passed or rejected (also after review). |
id_check.retry | An attempt failed; the person may retry (data.attempts_left). |
id_check.in_review | A specialist decides from the report. |
id_check.canceled | ID check canceled. |
sanctions_screening.completed | Sanctions screening done: data.status clear or in_review. |
sanctions_screening.reviewed | A specialist decided a possible match: data.status no_match or confirmed_match. |
sanctions_screening.failed | The lists could not be queried (not billed). |
ping | Test from the dashboard or the API. |
POST /your/webhook HTTP/1.1
Content-Type: application/json
Validento-Signature: t=1759569161,v1=5f2b0c8e…
Validento-Event: screening.completed
Validento-Event-Id: evt_8sK2pQ…
Validento-Delivery: 2b1c…
Validento-Version: 2026-10-01
{
"id": "evt_8sK2pQ…",
"object": "event",
"type": "screening.completed",
"environment": "live",
"api_version": "2026-10-01",
"created": 1759569161,
"data": { "id": "6c1f6a2e-…", "object": "screening", "status": "completed", "decision": "approve", "score": 82, "…": "…" }
}
v1 = hex HMAC-SHA256 of "{t}.{raw body}" with your whsec_… secret. Use the exact body received (don't re-serialise), compare in constant time and reject timestamps older than 5 minutes.
import express from 'express';
import crypto from 'node:crypto';
const app = express();
app.post('/webhooks/validento', express.raw({ type: 'application/json' }), (req, res) => {
const header = req.get('Validento-Signature') || '';
const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
const expected = crypto.createHmac('sha256', process.env.VALIDENTO_WHSEC)
.update(`${t}.${req.body}`).digest('hex');
const ok = v1 && v1.length === expected.length && crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
if (!ok || Math.abs(Date.now() / 1000 - Number(t)) > 300) return res.sendStatus(400);
const event = JSON.parse(req.body);
res.sendStatus(200); // answer fast, work after
queue.add(event); // dedupe on event.id
});
// Or with the SDK: const event = await Validento.webhooks.verify(rawBody, header, secret);import hmac, hashlib, time, json
from flask import Flask, request, abort
app = Flask(__name__)
@app.post("/webhooks/validento")
def validento_webhook():
raw = request.get_data() # bytes, exactly as received
parts = dict(p.split("=", 1) for p in request.headers.get("Validento-Signature", "").split(","))
expected = hmac.new(WHSEC.encode(), f"{parts.get('t')}.".encode() + raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, parts.get("v1", "")) or abs(time.time() - int(parts.get("t", 0))) > 300:
abort(400)
event = json.loads(raw)
enqueue(event) # dedupe on event["id"]
return "", 200<?php
$raw = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_VALIDENTO_SIGNATURE'] ?? ''), $sig);
$expected = hash_hmac('sha256', ($sig['t'] ?? '') . '.' . $raw, getenv('VALIDENTO_WHSEC'));
if (!hash_equals($expected, $sig['v1'] ?? '') || abs(time() - (int)($sig['t'] ?? 0)) > 300) {
http_response_code(400); exit;
}
$event = json_decode($raw, true);
http_response_code(200);
// process $event (dedupe on $event['id'])# Go
func verify(raw []byte, header, secret string) bool {
var t, v1 string
for _, p := range strings.Split(header, ",") {
kv := strings.SplitN(p, "=", 2)
if len(kv) == 2 && kv[0] == "t" { t = kv[1] }
if len(kv) == 2 && kv[0] == "v1" { v1 = kv[1] }
}
mac := hmac.New(sha256.New, []byte(secret))
mac.Write([]byte(t + "."))
mac.Write(raw)
ts, _ := strconv.ParseInt(t, 10, 64)
return hmac.Equal([]byte(hex.EncodeToString(mac.Sum(nil))), []byte(v1)) && math.Abs(float64(time.Now().Unix()-ts)) <= 300
}
event.id and, if state matters, fetch the object with GET.GET /v1/events and resend with POST /v1/events/{id}/resend./v1/webhook-endpointswebhooks:read/v1/webhook-endpointswebhooks:write/v1/webhook-endpoints/{id}webhooks:write/v1/webhook-endpoints/{id}webhooks:write/v1/webhook-endpoints/{id}/roll-secretwebhooks:write/v1/webhook-endpoints/{id}/testwebhooks:writecurl https://api.validento.com/v1/webhook-endpoints \
-H "Authorization: Bearer vld_test_YOUR_SANDBOX_KEY" -H "Content-Type: application/json" \
-d '{ "url": "https://api.yourapp.com/webhooks/validento", "events": ["screening.completed", "screening.failed", "link.completed"] }'
# → { "id": "…", "secret": "whsec_…" } (the secret is shown once)const ep = await vd.webhookEndpoints.create({ url: 'https://api.yourapp.com/webhooks/validento', events: ['screening.completed', 'screening.failed'] });
console.log(ep.secret); // store it now
console.log(await vd.webhookEndpoints.test(ep.id)); // { delivered: true, status: 200 }ep = requests.post("https://api.validento.com/v1/webhook-endpoints", headers=H, json={"url": "https://api.yourapp.com/webhooks/validento", "events": ["screening.completed"]}).json()
print(ep["secret"])$ep = validento("POST", "/v1/webhook-endpoints", ["url" => "https://api.yourapp.com/webhooks/validento", "events" => ["screening.completed"]]);
echo $ep["secret"];
Every event is kept for 30 days, with or without endpoints. Use them to reconcile, recover from outages, or build without webhooks.
/v1/events?type=screening.completed,link.completedevents:read/v1/events/{id}events:read/v1/events/{id}/resendwebhooks:writeresend delivers again to every subscribed endpoint, or to one with { "endpoint_id": "…" } (even if not subscribed).
// Catch up after downtime: everything since the last event you processed
for await (const ev of vd.events.listAll({ type: ['screening.completed', 'screening.failed'], created: { gte: lastSeenUnix } })) {
await handle(ev); // same handler as your webhook
}curl -G https://api.validento.com/v1/events -H "Authorization: Bearer vld_test_YOUR_SANDBOX_KEY" \
-d type=screening.completed -d "created[gte]=1759569000" -d limit=100
Your rules and branding, by API or in the dashboard (Business → Settings). They apply to live and sandbox. Send only what changes; null resets a field.
/v1/settingssettings:read/v1/settingssettings:writedecision.approve_min / review_min 1–100Decision thresholds (default 70 / 45).
branding.display_name / logo_url / primary_color / support_email / privacy_url stringYour brand on the upload page, emails and reports.
branding.hide_powered_by booleanHides “powered by Validento”.
link_defaults.* objectpurpose, country, expiry_days, documents_requested, redirect_url, email_applicant, language.
result_format.summary / deviations / fields / income / breakdown / applicant booleanWhich parts you receive by API and webhooks.
result_format.score_scale 100 | 10 | gradeFormat of display_score.
notifications.recipients / on_review / on_decline / on_failed / on_completed Emails to your team per live screening.
curl -X PATCH https://api.validento.com/v1/settings \
-H "Authorization: Bearer vld_test_YOUR_SANDBOX_KEY" -H "Content-Type: application/json" \
-d '{ "decision": { "approve_min": 75 }, "result_format": { "fields": false, "score_scale": "10" }, "branding": { "primary_color": "#6D28D9" } }'await vd.settings.update({ decision: { approve_min: 75 }, result_format: { fields: false, score_scale: '10' } });
/v1/usageusage:readCurrent period (20th to 19th), screenings, graduated amount, minimum, balance (prepaid) or credit limit (invoice).
/v1/invoicesusage:readMonthly invoices and statements with a link to the Stripe invoice and its PDF.
For software that verifies on behalf of its own customers — KYC and compliance platforms, ATS and recruiting agencies, insurers with brokers, practice-management software. Register each customer once and tag every screening, link, ID check and webhook endpoint with customer. Each customer gets its own branding, webhooks, usage and erasure.
/v1/customerscustomers:writeid stringrequiredYour own id for the customer (1–64; letters, digits, _ . -). It is what you pass later as customer.
name stringrequiredName (≤ 120).
brand_name / logo_url / primary_color / support_email stringThat customer's brand on the upload page, emails and report. Anything you leave out inherits your account branding.
metadata objectYour own data (≤ 20 keys).
curl https://api.validento.com/v1/customers \
-H "Authorization: Bearer vld_test_YOUR_SANDBOX_KEY" \
-H "Content-Type: application/json" \
-d '{"id":"acme","name":"Acme Lettings Ltd","brand_name":"Acme","primary_color":"#1D4ED8","support_email":"help@acme.example"}'await vd.request('POST', '/v1/customers', { id: 'acme', name: 'Acme Lettings Ltd', brand_name: 'Acme', primary_color: '#1D4ED8' });
// then, on every object for that customer:
const link = await vd.verificationLinks.create({
customer: 'acme', purpose: 'employment',
applicant: { name: 'Ana García', email: 'ana@example.com' }, send_email: true,
});
From then on, in every POST /v1/screenings, /v1/verification-links, /v1/id-checks and /v1/webhook-endpoints: "customer": "acme". An unknown customer returns unknown_customer. Objects return customer and lists filter with ?customer=acme.
| Branding | The upload page, the link email and the report carry the customer's brand (brand_name, logo, colour, support email). Without one, yours. |
|---|---|
| Webhooks | An endpoint created with customer receives only that customer's events (up to 200 such endpoints). Endpoints without a customer receive everything; the event carries data.customer. |
| Usage | GET /v1/customers/{id} returns usage: completed screenings this period and in total — to bill your customer. |
| Erasure | POST /v1/customers/{id}/erase deletes all of its screenings, links and ID checks (GDPR, irreversible). DELETE removes only the customer record. |
/v1/customerscustomers:read/v1/customers/{id}customers:read/v1/customers/{id}customers:write/v1/customers/{id}customers:write/v1/customers/{id}/erasecustomers:writecustomers:read and customers:write. You don't need a key per end customer: tag with customer and filter.Connect Validento to 7,000+ apps without code: when a screening finishes, update your CRM, post in Slack or save the result in a spreadsheet; when a new applicant comes in, send them a verification link.
| Triggers (instant) | Screening Completed · Screening Failed · Verification Link Completed · Verification Link Expired · ID Check Completed · Sanctions Screening Completed · Sanctions Screening Reviewed |
|---|---|
| Actions | Create Verification Link · Create ID Check · Screen for Sanctions & PEP |
| Search | Find Screening (by id or by your reference) |
| Connection | An API key (vld_test_… to test for free). |
The app is invite-only for now: ask us for the link at info@validento.com. Each active Zap creates a webhook endpoint for its event (max 10 per account).
In Zapier choose Webhooks by Zapier → Catch Hook and copy the URL.
Enterprise dashboard → Developers → Webhooks → paste the URL and pick the events. Press “Test” so Zapier sees a sample.
The object is under data: data.score, data.decision, data.reference, data.metadata.*.
Webhooks by Zapier → Custom Request: POST ${API}/v1/verification-links with the header Authorization: Bearer vld_….
Webhooks by Zapier needs a paid Zapier plan.
In Make (formerly Integromat) no app is needed: use the standard modules.
Module Webhooks → Custom webhook → copy the URL → register it in the dashboard (Developers → Webhooks) → “Test” so Make detects the structure.
Module HTTP → Make a request: URL ${API}/v1/…, header Authorization: Bearer vld_…, JSON body. Tick “Parse response”.
Add a filter on type (e.g. screening.completed) if the endpoint receives several events.
{
"applicant": { "name": "{{1.name}}", "email": "{{1.email}}" },
"purpose": "client_onboarding",
"reference": "{{1.deal_id}}",
"send_email": true,
"metadata": { "source": "make" }
}
Today CRMs connect through Zapier or Make (both have official Pipedrive, Salesforce and HubSpot apps). The key is the reference: put the deal or contact id from your CRM in reference (or metadata) when you create the link or screening; it comes back on every event.
| Pipedrive | Deal enters stage “Verify” → Create Verification Link (reference = deal id). Screening Completed → Pipedrive “Add note” / “Update deal” with score and decision. |
|---|---|
| Salesforce | New Lead/Opportunity → Create Verification Link. Screening Completed → “Update record” (custom fields: Validento Score, Decision, Report link). |
| HubSpot | Same: the contact or deal property is updated with the result. |
Native connectors (without Zapier/Make) on the Pipedrive Marketplace or Salesforce AppExchange: on the roadmap.
For HR teams, recruiting agencies and hiring platforms: verify the identity, documents and work history of a candidate from abroad before the offer. The reference is the candidate or job id in your ATS; the result comes back by webhook to that record.
| Flow | Candidate moves to “Verification” → POST /v1/verification-links with purpose: "employment", documents_requested (ID or passport, last payslip, employment letter, diploma) and send_email: true. The candidate uploads on a page with your brand. screening.completed → a note or field on the candidate. |
|---|---|
| Identity | Add POST /v1/id-checks (ValiD): the candidate verifies their document and face on their phone; no images kept. |
| Agencies | Verifying for several employers? Register each as a customer: their brand on the candidate's page, their webhooks and their usage. |
| Greenhouse · Lever · Workable · Teamtailor · Recruitee | Today through Zapier or Make (all have an official app): trigger “candidate stage changed” → Create Verification Link; Screening Completed → “Add note” or a custom field. |
{
"customer": "{{employer_id}}",
"purpose": "employment",
"applicant": { "name": "{{candidate.name}}", "email": "{{candidate.email}}" },
"documents_requested": ["ID or passport", "Last payslip", "Employment letter", "Diploma"],
"reference": "{{candidate.id}}",
"send_email": true,
"redirect_url": "https://careers.yourcompany.com/verified"
}
For customers who cannot send documents outside their own infrastructure: Validento's analysis containers, run by you. Yearly licence, the same answers as the API, updates as new images.
| verify-service | Document and income analysis. Runs in your Google Cloud project and uses your Vertex AI (your region, your data-processing terms). Validento never sees the documents. |
|---|---|
| idv-service (ValiD) | Identity: document, face and liveness. Fully offline: open models inside the image, no outbound call except the optional heartbeat. 2 vCPU, 4 GB, no GPU. |
| Licence | A signed token (Ed25519) in VALIDENTO_LICENSE + the public key in VALIDENTO_LICENSE_PUBKEY. Verified offline at startup; without a valid token the container does not start; after expiry it answers 403 license_inactive. Log warning from 30 days before. |
| Heartbeat | Optional, per licence: once a day the container sends { license_id, product, version, instance } — never documents, images or results. Lets Validento revoke a licence. Without heartbeat, no outbound call at all. |
| Images | europe-west4-docker.pkg.dev/validento-com/private/<service>:<tag> — private registry; your service account gets read access. Tags YYYY.MM; pin one in production. |
docker run -d -p 8080:8080 \
-e VALIDENTO_LICENSE="vdl1.…" -e VALIDENTO_LICENSE_PUBKEY="…" \
-e GOOGLE_CLOUD_PROJECT="your-gcp-project" -e GOOGLE_CLOUD_LOCATION="europe-west4" \
-e GOOGLE_APPLICATION_CREDENTIALS=/secrets/sa.json -v /path/sa.json:/secrets/sa.json:ro \
-e VERIFY_API_KEY="a-long-random-string" \
europe-west4-docker.pkg.dev/validento-com/private/verify-service:2026.10
curl -X POST http://localhost:8080/verify -H "apikey: a-long-random-string" -H "Content-Type: application/json" \
-d '{"purpose":"client_onboarding","country":"ES","lang":"en","files":[{"media_type":"application/pdf","data":"<base64>"}]}'
docker run -d -p 8081:8080 \
-e VALIDENTO_LICENSE="vdl1.…" -e VALIDENTO_LICENSE_PUBKEY="…" \
-e IDV_API_KEY="another-long-random-string" -e IDV_SESSION_SECRET="$(openssl rand -hex 32)" \
europe-west4-docker.pkg.dev/validento-com/private/idv-service:2026.10
# POST /v1/session → challenges; POST /v1/check (document, selfie, frames) → { decision, signals } — header x-api-key
POST /verify returns score, summary, detected_type, detected_country, fields[], deviations[], components, cross_check and detected income — the same information as result in the API, without the account layer (no webhooks, links or dashboard: your system does that). GET /health on both.
For companies that offer Validento verification to their own customers — practice-management software for law and accounting firms, KYC and onboarding platforms, applicant-tracking (ATS) and payroll systems, lenders and insurers, rental platforms and property software, B2B marketplaces. One Enterprise account, one API, your brand.
| Your brand | Logo, colours and name in the dashboard (Settings); each customer can have its own (brand_name, logo, colour, support email on its customer record). |
|---|---|
| Per end customer | Register each end customer in /v1/customers and pass customer on every call: branding, webhooks, usage and erasure per customer. Filter with GET /v1/screenings?customer=acme. |
| In your product | Link by email, embed in your site or app, or direct document upload by API. |
| Results | Signed webhooks and a branded report to pass on to your customer. |
| Billing | One monthly volume invoice to you; you bill your customers from the usage in GET /v1/customers/{id}. |
There are no sub-accounts with their own login for your end customers yet; they are separated by metadata. Talk to your account manager about channel terms.
One file, no dependencies, for Node 18+, Deno, Bun and edge runtimes. Retries with backoff (honours Retry-After), automatic Idempotency-Key, pagination with for await, typed errors and webhook verification. Types in validento.d.ts.
⬇ validento.mjs ⬇ validento.d.ts
import Validento, { ValidentoError } from './validento.mjs'; // Deno: 'https://validento.com/sdk/validento.mjs'
const vd = new Validento(process.env.VALIDENTO_KEY!, { maxRetries: 3, timeoutMs: 60_000 });
try {
const s = await vd.screenings.create({
applicant: { name: 'Ana García' }, consent_confirmed: true, purpose: 'purchase',
documents: [{ url: signedUrl, type: 'payslip' }],
case_details: { purchase_price: 320000 }, metadata: { customer_id: 'c_981' },
});
const done = await vd.screenings.waitFor(s.id); // polling helper; prefer webhooks in production
console.log(done.decision, done.result?.deviations);
} catch (err) {
if (err instanceof ValidentoError) console.error(err.status, err.code, err.param, err.requestId);
else throw err;
}
console.log(vd.lastResponse?.rateLimit);
Another language? Generate a client from the OpenAPI 3.1 spec (openapi-generator, oapi-codegen, NSwag…) or import it into Postman / Insomnia.
# Postman: Import → Link → https://api.validento.com/v1/openapi.json
npx @openapitools/openapi-generator-cli generate -i https://api.validento.com/v1/openapi.json -g python -o ./validento-python
npx @openapitools/openapi-generator-cli generate -i https://api.validento.com/v1/openapi.json -g go -o ./validento-go
DELETE /v1/screenings/{id}.consent_confirmed records the basis of your check.2026-10-09 — New Sanctions & PEP resource (OpenSanctions): POST /v1/sanctions-screenings, sanctions_screening.* events, sanctions:* scopes. No breaking changes.
2026-10-09 — Private deployment: verify-service and idv-service as licensed containers, run by the customer.
2026-10-08 — purpose accepts client_onboarding and employment. New Customers resource (multi-tenant): customer on screenings, links, ID checks and webhook endpoints; branding, usage and erasure per customer. No breaking changes.
Write to info@validento.com with the Validento-Request-Id and the approximate time. Enterprise clients: your account manager too. We answer in European business hours, usually the same day.
No account yet? See Enterprise or contact sales.