For developers

API documentation

Everything you need to integrate document verification: REST + JSON, signed webhooks, free sandbox, OpenAPI and SDK.

Introduction

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 URLhttps://api.validento.com
FormatJSON (UTF-8) · HTTPS · REST
Versionv1 · header Validento-Version: 2026-10-01
Environmentsvld_test_… sandbox (free, deterministic results) · vld_live_… production
DataAnalysed in the EU (Netherlands); results stored in the US (Supabase, Oregon). Documents are not stored after the analysis.

Quickstart

  1. Create a sandbox key

    Enterprise dashboard → Developers → API keys → “+ Sandbox key”. It is shown once: store it in your secrets manager.

  2. Check the key
    curl https://api.validento.com/v1/me \
      -H "Authorization: Bearer vld_test_YOUR_SANDBOX_KEY"
  3. Create a screening
    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" }
      }'
  4. Receive the result

    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).

  5. Go live

    When your integration works in sandbox, your account manager enables live. Swap the key for a vld_live_… one; the code stays the same.

Try it

Paste a sandbox key and call the API directly. The key stays in this tab (sessionStorage) and only travels to api.validento.com.

Authentication & keys

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.

Scopes

A key has full access (*) or is restricted: give each system only what it needs. write includes read. Without the scope: 403 missing_scope.

ScopeAllows
screenings:readRead screenings and reports.
screenings:writeCreate and delete screenings (+ read).
links:readRead verification links.
links:writeCreate and cancel links (+ read). Ideal for the backend of your frontend.
id_checks:read / id_checks:writeRead / create and cancel ID checks (ValiD).
sanctions:read / sanctions:writeRead / create sanctions & PEP screenings.
webhooks:read / webhooks:writeManage endpoints; resend events.
events:readRead events (30 days).
usage:readPeriod usage and invoices.
settings:read / settings:writeSettings: rules, branding, format, notifications.

Zero-downtime rotation

“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.

IP allowlist

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.

Sandbox

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_outcomeor in reference / nameResult
approve (default)—score 86 · approve
reviewreviewscore 58 · review · 1 medium deviation
declinedeclinescore 28 · decline · 1 high deviation
failfailstatus failed · screening.failed
The decision follows your decision rules, in sandbox too: if you raise “approve from” to 90, the sandbox 86 becomes review.

Requests & responses

Bodies in JSON (Content-Type: application/json). Dates in ISO 8601 UTC; amounts in cents (integers). Every response carries:

Validento-Request-IdInclude it when you contact support.
Validento-VersionAPI version that answered.
RateLimit-Limit / -Remaining / -ResetYour per-minute quota.
Idempotent-Replayed: trueReplayed response of an Idempotency-Key.

Idempotency

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.

Pagination

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"

Metadata

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.

Versioning & changes

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

Errors use HTTP status codes and a stable body. Code against error.code (stable), not the message.

JSON
{
  "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_error

Key missing, mistyped, revoked or expired. → Check the Authorization: Bearer vld_… header.

missing_scope 403 permission_error

The 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_error

The IP is not on your allowlist. → Add your server's egress IP in the dashboard.

live_not_enabled 403 permission_error

Live access is not enabled yet. → Keep using sandbox; your account manager enables live after the review.

account_suspended 403 permission_error

Account suspended. → Contact your account manager.

service_not_enabled 403 permission_error

The service is not in your agreement. → Ask your account manager.

insufficient_balance 402 billing_error

Prepaid balance too low. → Top up, or turn on auto top-up.

credit_limit_reached 402 billing_error

Credit limit reached. → Pay the open invoice or ask for a higher limit.

rate_limited 429 rate_limit_error

Too many requests. → Wait Retry-After seconds and retry.

invalid_json 400 invalid_request_error

The body is not valid JSON. → Send Content-Type: application/json and a JSON object.

invalid_parameter 400 invalid_request_error

A parameter is invalid (see param). → Fix the field named in error.param.

invalid_purpose 400 invalid_request_error

Unknown purpose. → Use client_onboarding, employment, rental, purchase, business_partner or civil_matter.

invalid_metadata 400 invalid_request_error

metadata breaks the limits. → Max 20 keys of ≤ 40 chars, string values ≤ 500.

applicant_required 400 invalid_request_error

applicant.name is missing.

documents_required 400 invalid_request_error

No documents. → Send 1 to 20 documents.

too_many_documents 400 invalid_request_error

More than 20 documents. → Split the case or combine pages into one PDF.

invalid_document 400 invalid_request_error

Document without url or data+media_type.

unsupported_media_type 415 invalid_request_error

Unsupported format. → PDF, JPEG, PNG or WebP.

document_too_large 413 invalid_request_error

A document exceeds 10 MB. → Compress the image or lower the resolution.

documents_too_large 413 invalid_request_error

Documents exceed 20 MB in total.

document_url_unreachable 422 invalid_request_error

We could not download a URL (15 s). → Use a signed URL valid ≥ 10 min, or send base64.

invalid_settings 400 invalid_request_error

Invalid settings (see message).

invalid_url 400 invalid_request_error

The URL must start with https://.

too_many_endpoints 409 invalid_request_error

At most 10 endpoints.

idempotency_conflict 409 idempotency_error

Idempotency-Key reused with another body. → Generate a new key per operation.

not_found 404 invalid_request_error

No 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_error

Method not allowed on this path.

server_error 500 api_error

Our fault. → Safe to retry (with the same Idempotency-Key).

Limits

Requests per key120 / min live · 60 / min sandbox · raised on request
Documents per screening1–20 · ≤ 10 MB each · ≤ 20 MB in total
FormatsPDF, JPEG, PNG, WebP
Download of url15 s per document
Webhook endpoints10 per account · answer within 10 s
Events retrievable30 days
Screening retentionper 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.

Screenings

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.

Create a screening

POST/v1/screeningsscreenings:write
applicant.name stringrequired

Name of the person (or company).

applicant.email / phone / date_of_birth / id_number / company / address / country string

More data helps the identity cross-check. date_of_birth as YYYY-MM-DD, country ISO alpha-2.

documents[] arrayrequired

1–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 truerequired

You confirm the person agreed to the check.

purpose enum

client_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 string

Country of the documents (ISO alpha-2). Improves extraction.

case_details object

Facts 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 string

Your own ID (≤ 120). Filterable.

metadata object

See metadata.

lang en | es

Language of the summary and deviations.

sandbox_outcome enum

Sandbox 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" }
  }'

Response 202 with the object in processing. Always use Idempotency-Key.

The screening object

JSON
{
  "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–100

Always the same scale; your rules decide.

decision approve | review | decline

Per your decision rules (default ≥ 70 / ≥ 45).

result.deviations[] array

What doesn't add up: between documents, against case_details, or signs of tampering. severity low/medium/high.

result.fields[] array

Extracted data (employer, net pay, partial IBAN, dates…).

result.income object

Detected monthly income and currency.

result.breakdown object

Sub-scores 0–100: document integrity, financial capacity, identity.

result.display_score string

The score on your scale (82/100, 8.2/10 or B).

error string | null

When failed: engine_unavailable or another reason. Not charged; you can retry.

Which parts of result you receive is up to you in result_format.

List & filter

GET/v1/screeningsscreenings:read

Filters: reference, status, decision, purpose, channel (api/link/dashboard), link_id, metadata[key], created[gte|lte] + pagination.

Retrieve, report & erase

GET/v1/screenings/{id}screenings:read
GET/v1/screenings/{id}/report?lang=enscreenings:read

Printable HTML report in your branding. Turn it into a PDF with any browser or headless Chrome (Puppeteer: page.pdf()).

DELETE/v1/screenings/{id}screenings:write

Permanent erase (GDPR): removes the screening and the person's data on its link; billed usage is kept without personal data. Emits screening.deleted.

ID checks (ValiD)

Send 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.

POST/v1/id-checksid_checks:write
applicant.name stringrequired

As on the document (min. 3 characters).

applicant.email stringrequired

For the email with the link.

purpose string

What it is for; the person sees it.

reference string

Your id (CRM, case); comes back on every event.

send_email boolean

We email the link in your name. Otherwise use url (only in this response).

locale es | en

Language of the email and the page.

expires_in_days integer

1–30, default 14.

metadata object

Up 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"}'
statusMeaning
pendingWaiting for the person.
retryAn attempt failed (photo, expiry, face); they may retry, up to 3 tries.
in_reviewA Validento specialist decides from the report — never an automatic reject over a bad photo.
passed / rejectedFinal decision (event id_check.completed).
canceled / expiredCanceled, or not finished in time.
GET/v1/id-checksid_checks:read

Filters: status, reference, metadata[key] + pagination.

GET/v1/id-checks/{id}id_checks:read
POST/v1/id-checks/{id}/cancelid_checks:write
POST/v1/id-checks/{id}/simulateid_checks:write

Sandbox: 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).

Sanctions & PEP screening

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.

POST/v1/sanctions-screeningssanctions:write
subject.name stringrequired

Full name of the person, or the company name.

subject.kind person | company

Default person.

subject.birth_date string

YYYY or YYYY-MM-DD (person). Cuts false matches a lot.

subject.nationality string

ISO 3166-1 alpha-2 (person).

subject.country string

ISO 3166-1 alpha-2, jurisdiction (company).

subject.registration_number string

Company registration number.

reference string

Your id; comes back on the object and every event.

customer string

Your customer id (Customers).

metadata object

Up 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"}'
statusMeaning
clearNo match above the threshold.
in_reviewA 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_matchReviewed: not the same person or company (note in review.note).
confirmed_matchReviewed: the match is confirmed. Follow your own procedures (e.g. your compliance officer).
failedThe 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.

GET/v1/sanctions-screeningssanctions:read

Filters: status, reference, customer, metadata[key] + pagination.

GET/v1/sanctions-screenings/{id}sanctions:read

How to integrate it

  1. Call it at onboarding (and, if you need to, again periodically: the lists change daily).
  2. clear → continue. in_review → put the file on hold.
  3. Listen for the sanctions_screening.reviewed webhook: data.status is no_match or confirmed_match.
  4. Keep the 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.

Webhooks

We send you a signed POST when something changes. Each environment has its own endpoints.

EventWhen
screening.createdScreening created (status processing).
screening.completedResult available: score, decision, result.
screening.failedCould not be completed (not charged).
screening.deletedErased (GDPR) via API or dashboard.
link.createdVerification link created.
link.completedThe person submitted documents; data.screening_id.
link.canceledLink canceled.
link.expiredThe link expired unused.
id_check.createdID check created (also from the dashboard).
id_check.completedFinal decision: data.status passed or rejected (also after review).
id_check.retryAn attempt failed; the person may retry (data.attempts_left).
id_check.in_reviewA specialist decides from the report.
id_check.canceledID check canceled.
sanctions_screening.completedSanctions screening done: data.status clear or in_review.
sanctions_screening.reviewedA specialist decided a possible match: data.status no_match or confirmed_match.
sanctions_screening.failedThe lists could not be queried (not billed).
pingTest from the dashboard or the API.
HTTP
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, "…": "…" }
}

Verify the signature

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.

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

Delivery & retries

  • Answer 2xx within 10 s; process afterwards (queue).
  • Otherwise: retries after 1, 5, 30, 120, 360, 720 and 1440 minutes (~1 day).
  • “At least once” and no guaranteed order: dedupe on event.id and, if state matters, fetch the object with GET.
  • Your endpoint was down? Catch up with GET /v1/events and resend with POST /v1/events/{id}/resend.
  • Every delivery and attempt shows in the dashboard (Developers → Webhooks), with a resend button.

Manage endpoints by API

GET/v1/webhook-endpointswebhooks:read
POST/v1/webhook-endpointswebhooks:write
PATCH/v1/webhook-endpoints/{id}webhooks:write
DELETE/v1/webhook-endpoints/{id}webhooks:write
POST/v1/webhook-endpoints/{id}/roll-secretwebhooks:write
POST/v1/webhook-endpoints/{id}/testwebhooks:write
curl 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)

Events

Every event is kept for 30 days, with or without endpoints. Use them to reconcile, recover from outages, or build without webhooks.

GET/v1/events?type=screening.completed,link.completedevents:read
GET/v1/events/{id}events:read
POST/v1/events/{id}/resendwebhooks:write

resend delivers again to every subscribed endpoint, or to one with { "endpoint_id": "…" } (even if not subscribed).

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

Settings

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.

GET/v1/settingssettings:read
PATCH/v1/settingssettings:write
decision.approve_min / review_min 1–100

Decision thresholds (default 70 / 45).

branding.display_name / logo_url / primary_color / support_email / privacy_url string

Your brand on the upload page, emails and reports.

branding.hide_powered_by boolean

Hides “powered by Validento”.

link_defaults.* object

purpose, country, expiry_days, documents_requested, redirect_url, email_applicant, language.

result_format.summary / deviations / fields / income / breakdown / applicant boolean

Which parts you receive by API and webhooks.

result_format.score_scale 100 | 10 | grade

Format 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" } }'

Usage & invoices

GET/v1/usageusage:read

Current period (20th to 19th), screenings, graduated amount, minimum, balance (prepaid) or credit limit (invoice).

GET/v1/invoicesusage:read

Monthly invoices and statements with a link to the Stripe invoice and its PDF.

Your customers (multi-tenant)

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.

POST/v1/customerscustomers:write
id stringrequired

Your own id for the customer (1–64; letters, digits, _ . -). It is what you pass later as customer.

name stringrequired

Name (≤ 120).

brand_name / logo_url / primary_color / support_email string

That customer's brand on the upload page, emails and report. Anything you leave out inherits your account branding.

metadata object

Your 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"}'

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.

BrandingThe upload page, the link email and the report carry the customer's brand (brand_name, logo, colour, support email). Without one, yours.
WebhooksAn 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.
UsageGET /v1/customers/{id} returns usage: completed screenings this period and in total — to bill your customer.
ErasurePOST /v1/customers/{id}/erase deletes all of its screenings, links and ID checks (GDPR, irreversible). DELETE removes only the customer record.
GET/v1/customerscustomers:read
GET/v1/customers/{id}customers:read
PATCH/v1/customers/{id}customers:write
DELETE/v1/customers/{id}customers:write
POST/v1/customers/{id}/erasecustomers:write
Scoped keys: customers:read and customers:write. You don't need a key per end customer: tag with customer and filter.

Zapier

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.

Validento app for Zapier

Triggers (instant)Screening Completed · Screening Failed · Verification Link Completed · Verification Link Expired · ID Check Completed · Sanctions Screening Completed · Sanctions Screening Reviewed
ActionsCreate Verification Link · Create ID Check · Screen for Sanctions & PEP
SearchFind Screening (by id or by your reference)
ConnectionAn 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).

Without the app: Webhooks by Zapier

  1. Trigger

    In Zapier choose Webhooks by Zapier → Catch Hook and copy the URL.

  2. Endpoint

    Enterprise dashboard → Developers → Webhooks → paste the URL and pick the events. Press “Test” so Zapier sees a sample.

  3. Fields

    The object is under data: data.score, data.decision, data.reference, data.metadata.*.

  4. Actions towards Validento

    Webhooks by Zapier → Custom Request: POST ${API}/v1/verification-links with the header Authorization: Bearer vld_….

Webhooks by Zapier needs a paid Zapier plan.

Make

In Make (formerly Integromat) no app is needed: use the standard modules.

  1. Receive results

    Module Webhooks → Custom webhook → copy the URL → register it in the dashboard (Developers → Webhooks) → “Test” so Make detects the structure.

  2. Call the API

    Module HTTP → Make a request: URL ${API}/v1/…, header Authorization: Bearer vld_…, JSON body. Tick “Parse response”.

  3. Filter

    Add a filter on type (e.g. screening.completed) if the endpoint receives several events.

“Make a request” body → POST /v1/verification-links
{
  "applicant": { "name": "{{1.name}}", "email": "{{1.email}}" },
  "purpose": "client_onboarding",
  "reference": "{{1.deal_id}}",
  "send_email": true,
  "metadata": { "source": "make" }
}

CRMs: Pipedrive, Salesforce, HubSpot

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.

PipedriveDeal enters stage “Verify” → Create Verification Link (reference = deal id). Screening Completed → Pipedrive “Add note” / “Update deal” with score and decision.
SalesforceNew Lead/Opportunity → Create Verification Link. Screening Completed → “Update record” (custom fields: Validento Score, Decision, Report link).
HubSpotSame: 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.

ATS & recruiting

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.

FlowCandidate 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.
IdentityAdd POST /v1/id-checks (ValiD): the candidate verifies their document and face on their phone; no images kept.
AgenciesVerifying for several employers? Register each as a customer: their brand on the candidate's page, their webhooks and their usage.
Greenhouse · Lever · Workable · Teamtailor · RecruiteeToday through Zapier or Make (all have an official app): trigger “candidate stage changed” → Create Verification Link; Screening Completed → “Add note” or a custom field.
Body → POST /v1/verification-links
{
  "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"
}

Private deployment (on-premise)

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-serviceDocument 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.
LicenceA 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.
HeartbeatOptional, 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.
Imageseurope-west4-docker.pkg.dev/validento-com/private/<service>:<tag> — private registry; your service account gets read access. Tags YYYY.MM; pin one in production.
verify-service
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>"}]}'
idv-service (ValiD)
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.

Pricing: a yearly licence plus a per-check price, tailored, with a support and confidentiality agreement. Talk to sales: Enterprise. Full guide and docker-compose in the delivery package.

Channel partners

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 brandLogo, 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 customerRegister 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 productLink by email, embed in your site or app, or direct document upload by API.
ResultsSigned webhooks and a branded report to pass on to your customer.
BillingOne 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.

SDK JavaScript

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

TypeScript
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.

Shell
# 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

Security & data

  • TLS 1.2+ everywhere. Keys stored as SHA-256 hashes; webhook secrets are never shown again.
  • Analysis in the EU (Netherlands); the result is stored in the US (Supabase, Oregon) under the EU–US Data Privacy Framework. Documents are analysed and not stored.
  • Retention per contract (default 365 days), automatic deletion afterwards; immediate erase with DELETE /v1/screenings/{id}.
  • You are the controller; Validento is the processor (DPA available). consent_confirmed records the basis of your check.
  • Per-key scopes, IP allowlist, rotation with grace, a log of every request (dashboard → Request log).
  • The result supports a decision; it is not legal advice nor a final automated decision: keep a human review for “review” and “decline”.

Changelog

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.

2026-10-07
  • ValiD in the API: /v1/id-checks, id_check.* events and sandbox simulation.
  • Integration guides: Zapier (invite-only app), Make, CRMs and channel partners.
2026-10-01
  • Scoped keys, Events API (30 days, resend), webhook endpoints by API, cancel and list links.
  • Up to 20 documents (20 MB), case_details, settings and result format, branded report, GDPR erase.
  • RateLimit-*, Validento-Version, Idempotent-Replayed headers; errors with param and doc_url; OpenAPI 3.1; JavaScript SDK.

Support

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.