{"openapi":"3.1.0","info":{"title":"Validento API","version":"2026-10-01","description":"Document and income verification for platforms. Create a screening with documents (or send a hosted verification link), receive a score, decision and deviations — by webhook or by polling. Sandbox keys (vld_test_) are free and return deterministic results.","contact":{"name":"Validento developer support","email":"info@validento.com","url":"https://validento.com/developers"},"license":{"name":"Proprietary — Validento terms","url":"https://validento.com/terminos"},"termsOfService":"https://validento.com/terminos"},"servers":[{"url":"https://api.validento.com","description":"Production and sandbox (the key decides)"}],"security":[{"bearer":[]}],"tags":[{"name":"Screenings","description":"One person, up to 20 documents, an async result."},{"name":"Verification links","description":"A hosted, white-label upload page for the applicant (also embeddable)."},{"name":"Webhooks","description":"Endpoints that receive signed events."},{"name":"Events","description":"Every event of the last 30 days, for reconciliation and replay."},{"name":"Account","description":"Key info, usage, invoices and settings."}],"paths":{"/v1/me":{"get":{"tags":["Account"],"operationId":"getMe","summary":"The API key in use","description":"Environment, scopes, account status and limits. Useful as a health check.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyInfo"}}}},"401":{"$ref":"#/components/responses/E401"}}}},"/v1/screenings":{"post":{"tags":["Screenings"],"operationId":"createScreening","summary":"Create a screening","x-required-scope":"screenings:write","description":"Returns 202 with status \"processing\". The result arrives by the screening.completed / screening.failed webhook, or poll GET /v1/screenings/{id}. Live screenings are billable only when completed.","parameters":[{"name":"Idempotency-Key","in":"header","description":"Any unique string (≤ 255). Retrying with the same key within 24 h returns the first response; another body with the same key → 409.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreeningCreate"},"example":{"applicant":{"name":"Ana García","email":"ana@example.com"},"purpose":"rental","country":"ES","reference":"case-1042","consent_confirmed":true,"case_details":{"monthly_rent":1200,"property_address":"Calle Mayor 1, Madrid"},"documents":[{"type":"payslip","url":"https://files.example.com/p1.pdf"},{"type":"bank_statement","media_type":"application/pdf","data":"JVBERi0xLjQK…"}],"metadata":{"tenant_id":"t_981"}}}}},"responses":{"202":{"description":"Accepted — processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Screening"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"402":{"$ref":"#/components/responses/E402"},"403":{"$ref":"#/components/responses/E403"},"409":{"$ref":"#/components/responses/E409"},"413":{"$ref":"#/components/responses/E413"},"415":{"$ref":"#/components/responses/E415"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}},"get":{"tags":["Screenings"],"operationId":"listScreenings","summary":"List screenings","x-required-scope":"screenings:read","parameters":[{"name":"limit","in":"query","description":"1–100, default 20","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor: an object ID; returns older objects","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor: an object ID; returns newer objects","schema":{"type":"string"}},{"name":"created[gte]","in":"query","description":"Created at or after (unix seconds or ISO 8601)","schema":{"type":"string"}},{"name":"created[lte]","in":"query","description":"Created at or before (unix seconds or ISO 8601)","schema":{"type":"string"}},{"name":"reference","in":"query","schema":{"type":"string"}},{"name":"link_id","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"enum":["processing","completed","failed"]}},{"name":"decision","in":"query","schema":{"enum":["approve","review","decline"]}},{"name":"purpose","in":"query","schema":{"enum":["rental","purchase","business_partner","civil_matter"]}},{"name":"channel","in":"query","schema":{"enum":["api","link","dashboard"]}},{"name":"metadata[key]","in":"query","description":"Exact match on a metadata key, e.g. metadata[tenant_id]=t_981","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Screening"}},"has_more":{"type":"boolean"},"url":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}}},"/v1/screenings/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Object ID","schema":{"type":"string"}}],"get":{"tags":["Screenings"],"operationId":"getScreening","summary":"Retrieve a screening","x-required-scope":"screenings:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Screening"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}},"delete":{"tags":["Screenings"],"operationId":"deleteScreening","summary":"Erase a screening (GDPR)","x-required-scope":"screenings:write","description":"Deletes the screening and the applicant data on its link. Billed usage is kept (without personal data). Emits screening.deleted.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deleted"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/v1/screenings/{id}/report":{"get":{"tags":["Screenings"],"operationId":"getScreeningReport","summary":"Printable report (HTML) in your branding","x-required-scope":"screenings:read","parameters":[{"name":"id","in":"path","required":true,"description":"Object ID","schema":{"type":"string"}},{"name":"lang","in":"query","schema":{"enum":["en","es"]}}],"responses":{"200":{"description":"HTML document (print to PDF in any browser or headless Chrome)","content":{"text/html":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/v1/verification-links":{"post":{"tags":["Verification links"],"operationId":"createVerificationLink","summary":"Create a verification link","x-required-scope":"links:write","description":"The applicant uploads documents on a page with your branding (url) or inside your app (embed_url / embed.js). The url carries a secret token and is returned only here.","parameters":[{"name":"Idempotency-Key","in":"header","description":"Any unique string (≤ 255). Retrying with the same key within 24 h returns the first response; another body with the same key → 409.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationLinkCreate"},"example":{"applicant":{"name":"Ana García","email":"ana@example.com"},"purpose":"rental","reference":"case-1042","documents_requested":["ID","3 payslips"],"send_email":true,"locale":"es","expires_in_days":7}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationLink"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}},"get":{"tags":["Verification links"],"operationId":"listVerificationLinks","summary":"List verification links","x-required-scope":"links:read","parameters":[{"name":"limit","in":"query","description":"1–100, default 20","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor: an object ID; returns older objects","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor: an object ID; returns newer objects","schema":{"type":"string"}},{"name":"created[gte]","in":"query","description":"Created at or after (unix seconds or ISO 8601)","schema":{"type":"string"}},{"name":"created[lte]","in":"query","description":"Created at or before (unix seconds or ISO 8601)","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"enum":["pending","completed","expired","canceled"]}},{"name":"reference","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/VerificationLink"}},"has_more":{"type":"boolean"},"url":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"}}}},"/v1/verification-links/{id}":{"get":{"tags":["Verification links"],"operationId":"getVerificationLink","summary":"Retrieve a verification link","x-required-scope":"links:read","parameters":[{"name":"id","in":"path","required":true,"description":"Object ID","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationLink"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/v1/verification-links/{id}/cancel":{"post":{"tags":["Verification links"],"operationId":"cancelVerificationLink","summary":"Cancel a pending link","x-required-scope":"links:write","parameters":[{"name":"id","in":"path","required":true,"description":"Object ID","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationLink"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"}}}},"/v1/webhook-endpoints":{"get":{"tags":["Webhooks"],"operationId":"listWebhookEndpoints","summary":"List endpoints","x-required-scope":"webhooks:read","parameters":[{"name":"limit","in":"query","description":"1–100, default 20","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor: an object ID; returns older objects","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor: an object ID; returns newer objects","schema":{"type":"string"}},{"name":"created[gte]","in":"query","description":"Created at or after (unix seconds or ISO 8601)","schema":{"type":"string"}},{"name":"created[lte]","in":"query","description":"Created at or before (unix seconds or ISO 8601)","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}},"has_more":{"type":"boolean"},"url":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"}}},"post":{"tags":["Webhooks"],"operationId":"createWebhookEndpoint","summary":"Create an endpoint","x-required-scope":"webhooks:write","description":"The signing secret is returned once.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointWithSecret"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"409":{"$ref":"#/components/responses/E409"}}}},"/v1/webhook-endpoints/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Object ID","schema":{"type":"string"}}],"get":{"tags":["Webhooks"],"operationId":"getWebhookEndpoint","summary":"Retrieve an endpoint","x-required-scope":"webhooks:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}},"patch":{"tags":["Webhooks"],"operationId":"updateWebhookEndpoint","summary":"Update url, events or active","x-required-scope":"webhooks:write","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointUpdate"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}},"delete":{"tags":["Webhooks"],"operationId":"deleteWebhookEndpoint","summary":"Delete an endpoint","x-required-scope":"webhooks:write","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deleted"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/v1/webhook-endpoints/{id}/roll-secret":{"post":{"tags":["Webhooks"],"operationId":"rollWebhookSecret","summary":"Replace the signing secret","x-required-scope":"webhooks:write","parameters":[{"name":"id","in":"path","required":true,"description":"Object ID","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointWithSecret"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/v1/webhook-endpoints/{id}/test":{"post":{"tags":["Webhooks"],"operationId":"testWebhookEndpoint","summary":"Send a signed ping event now","x-required-scope":"webhooks:write","parameters":[{"name":"id","in":"path","required":true,"description":"Object ID","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"delivered":{"type":"boolean"},"status":{"type":["integer","null"]},"error":{"type":["string","null"]},"event":{"$ref":"#/components/schemas/Event"}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/v1/events":{"get":{"tags":["Events"],"operationId":"listEvents","summary":"List events (30 days)","x-required-scope":"events:read","parameters":[{"name":"limit","in":"query","description":"1–100, default 20","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor: an object ID; returns older objects","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor: an object ID; returns newer objects","schema":{"type":"string"}},{"name":"created[gte]","in":"query","description":"Created at or after (unix seconds or ISO 8601)","schema":{"type":"string"}},{"name":"created[lte]","in":"query","description":"Created at or before (unix seconds or ISO 8601)","schema":{"type":"string"}},{"name":"type","in":"query","description":"One type or a comma-separated list","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"has_more":{"type":"boolean"},"url":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"}}}},"/v1/events/{id}":{"get":{"tags":["Events"],"operationId":"getEvent","summary":"Retrieve an event","x-required-scope":"events:read","parameters":[{"name":"id","in":"path","required":true,"description":"evt_…","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/v1/events/{id}/resend":{"post":{"tags":["Events"],"operationId":"resendEvent","summary":"Deliver an event again","x-required-scope":"webhooks:write","description":"To every active endpoint subscribed to its type, or to one endpoint_id (also when not subscribed).","parameters":[{"name":"id","in":"path","required":true,"description":"evt_…","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"endpoint_id":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"resent_to":{"type":"integer"}}}]}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/v1/usage":{"get":{"tags":["Account"],"operationId":"getUsage","summary":"This billing period (20th → 19th)","x-required-scope":"usage:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"}}}},"/v1/invoices":{"get":{"tags":["Account"],"operationId":"listInvoices","summary":"Monthly invoices and statements","x-required-scope":"usage:read","parameters":[{"name":"limit","in":"query","description":"1–100, default 20","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor: an object ID; returns older objects","schema":{"type":"string"}},{"name":"ending_before","in":"query","description":"Cursor: an object ID; returns newer objects","schema":{"type":"string"}},{"name":"created[gte]","in":"query","description":"Created at or after (unix seconds or ISO 8601)","schema":{"type":"string"}},{"name":"created[lte]","in":"query","description":"Created at or before (unix seconds or ISO 8601)","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}},"has_more":{"type":"boolean"},"url":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"}}}},"/v1/settings":{"get":{"tags":["Account"],"operationId":"getSettings","summary":"Decision rules, branding, link defaults, result format, notifications","x-required-scope":"settings:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Settings"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"}}},"patch":{"tags":["Account"],"operationId":"updateSettings","summary":"Update settings (partial)","x-required-scope":"settings:write","description":"Send only the sections and fields to change; null resets a field. Applies to live and sandbox.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Settings"},"example":{"decision":{"approve_min":75},"result_format":{"fields":false,"score_scale":"10"}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Settings"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"}}}}},"webhooks":{"screening.created":{"post":{"operationId":"webhook_screening_created","summary":"screening.created","description":"POST to your endpoint. Verify Validento-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, \"<t>.<raw body>\")>. Answer 2xx within 10 s; failures are retried after 1, 5, 30, 120, 360, 720 and 1440 minutes. Deduplicate on the event id.","parameters":[{"name":"Validento-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"Validento-Event","in":"header","schema":{"type":"string"}},{"name":"Validento-Event-Id","in":"header","schema":{"type":"string"}},{"name":"Validento-Delivery","in":"header","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Received"}}}},"screening.completed":{"post":{"operationId":"webhook_screening_completed","summary":"screening.completed","description":"POST to your endpoint. Verify Validento-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, \"<t>.<raw body>\")>. Answer 2xx within 10 s; failures are retried after 1, 5, 30, 120, 360, 720 and 1440 minutes. Deduplicate on the event id.","parameters":[{"name":"Validento-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"Validento-Event","in":"header","schema":{"type":"string"}},{"name":"Validento-Event-Id","in":"header","schema":{"type":"string"}},{"name":"Validento-Delivery","in":"header","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Received"}}}},"screening.failed":{"post":{"operationId":"webhook_screening_failed","summary":"screening.failed","description":"POST to your endpoint. Verify Validento-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, \"<t>.<raw body>\")>. Answer 2xx within 10 s; failures are retried after 1, 5, 30, 120, 360, 720 and 1440 minutes. Deduplicate on the event id.","parameters":[{"name":"Validento-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"Validento-Event","in":"header","schema":{"type":"string"}},{"name":"Validento-Event-Id","in":"header","schema":{"type":"string"}},{"name":"Validento-Delivery","in":"header","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Received"}}}},"screening.deleted":{"post":{"operationId":"webhook_screening_deleted","summary":"screening.deleted","description":"POST to your endpoint. Verify Validento-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, \"<t>.<raw body>\")>. Answer 2xx within 10 s; failures are retried after 1, 5, 30, 120, 360, 720 and 1440 minutes. Deduplicate on the event id.","parameters":[{"name":"Validento-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"Validento-Event","in":"header","schema":{"type":"string"}},{"name":"Validento-Event-Id","in":"header","schema":{"type":"string"}},{"name":"Validento-Delivery","in":"header","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Received"}}}},"link.created":{"post":{"operationId":"webhook_link_created","summary":"link.created","description":"POST to your endpoint. Verify Validento-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, \"<t>.<raw body>\")>. Answer 2xx within 10 s; failures are retried after 1, 5, 30, 120, 360, 720 and 1440 minutes. Deduplicate on the event id.","parameters":[{"name":"Validento-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"Validento-Event","in":"header","schema":{"type":"string"}},{"name":"Validento-Event-Id","in":"header","schema":{"type":"string"}},{"name":"Validento-Delivery","in":"header","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Received"}}}},"link.completed":{"post":{"operationId":"webhook_link_completed","summary":"link.completed","description":"POST to your endpoint. Verify Validento-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, \"<t>.<raw body>\")>. Answer 2xx within 10 s; failures are retried after 1, 5, 30, 120, 360, 720 and 1440 minutes. Deduplicate on the event id.","parameters":[{"name":"Validento-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"Validento-Event","in":"header","schema":{"type":"string"}},{"name":"Validento-Event-Id","in":"header","schema":{"type":"string"}},{"name":"Validento-Delivery","in":"header","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Received"}}}},"link.canceled":{"post":{"operationId":"webhook_link_canceled","summary":"link.canceled","description":"POST to your endpoint. Verify Validento-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, \"<t>.<raw body>\")>. Answer 2xx within 10 s; failures are retried after 1, 5, 30, 120, 360, 720 and 1440 minutes. Deduplicate on the event id.","parameters":[{"name":"Validento-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"Validento-Event","in":"header","schema":{"type":"string"}},{"name":"Validento-Event-Id","in":"header","schema":{"type":"string"}},{"name":"Validento-Delivery","in":"header","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Received"}}}},"link.expired":{"post":{"operationId":"webhook_link_expired","summary":"link.expired","description":"POST to your endpoint. Verify Validento-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, \"<t>.<raw body>\")>. Answer 2xx within 10 s; failures are retried after 1, 5, 30, 120, 360, 720 and 1440 minutes. Deduplicate on the event id.","parameters":[{"name":"Validento-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"Validento-Event","in":"header","schema":{"type":"string"}},{"name":"Validento-Event-Id","in":"header","schema":{"type":"string"}},{"name":"Validento-Delivery","in":"header","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Received"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"vld_live_… (production) or vld_test_… (sandbox: free, deterministic results, nothing analysed)."}},"responses":{"E400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E402":{"description":"Balance or credit limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E403":{"description":"Missing scope, IP or permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E409":{"description":"Conflict (idempotency, state, limits)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E413":{"description":"Documents too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E415":{"description":"Unsupported media type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E422":{"description":"Consent or document URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E429":{"description":"Rate limited — see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["type","code","message","request_id"],"properties":{"type":{"enum":["invalid_request_error","authentication_error","permission_error","billing_error","rate_limit_error","idempotency_error","api_error"]},"code":{"type":"string","examples":["consent_required"]},"message":{"type":"string"},"param":{"type":"string"},"doc_url":{"type":"string"},"request_id":{"type":"string"}}}}},"Deleted":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string"},"deleted":{"const":true}}},"Metadata":{"type":"object","description":"Up to 20 keys (≤ 40 chars, [A-Za-z0-9_.-]) with string values (≤ 500 chars). Returned as given; filter with metadata[key].","additionalProperties":{"type":"string"}},"CaseDetails":{"type":"object","description":"Facts the engine compares with the documents (rent, price, address, employer…); each difference becomes a deviation. Flat, up to 30 keys (snake_case), string or number values.","additionalProperties":{"type":["string","number"]},"examples":[{"monthly_rent":1200,"property_address":"Calle Mayor 1, Madrid","employer":"Acme SL"}]},"Applicant":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":160},"email":{"type":"string"},"phone":{"type":"string"},"date_of_birth":{"type":"string","format":"date"},"id_number":{"type":"string"},"company":{"type":"string"},"address":{"type":"string"},"country":{"type":"string","description":"ISO 3166-1 alpha-2"}}},"Document":{"type":"object","description":"Either url (https, we download it) or data (base64) + media_type. PDF, JPEG, PNG or WebP; ≤ 10 MB each, ≤ 20 MB per screening. Documents are not stored after the analysis.","properties":{"type":{"type":"string","description":"Optional hint: payslip, bank_statement, id, employment_contract, tax_return, rental_contract, …"},"url":{"type":"string","format":"uri"},"data":{"type":"string","contentEncoding":"base64"},"media_type":{"enum":["application/pdf","image/jpeg","image/png","image/webp"]}}},"ScreeningCreate":{"type":"object","required":["applicant","documents","consent_confirmed"],"properties":{"applicant":{"$ref":"#/components/schemas/Applicant"},"documents":{"type":"array","minItems":1,"maxItems":20,"items":{"$ref":"#/components/schemas/Document"}},"consent_confirmed":{"const":true,"description":"You confirm the applicant agreed to this check."},"purpose":{"enum":["rental","purchase","business_partner","civil_matter"],"default":"rental (or your settings default)"},"country":{"type":"string","description":"Country of the documents (ISO alpha-2)"},"reference":{"type":"string","maxLength":120,"description":"Your own ID; filterable"},"case_details":{"$ref":"#/components/schemas/CaseDetails"},"metadata":{"$ref":"#/components/schemas/Metadata"},"lang":{"enum":["en","es"],"description":"Language of the summary and deviations"},"sandbox_outcome":{"enum":["approve","review","decline","fail"],"description":"Sandbox only: force the outcome"}}},"Screening":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"const":"screening"},"environment":{"enum":["live","test"]},"status":{"enum":["processing","completed","failed"]},"channel":{"enum":["api","link","dashboard"]},"reference":{"type":["string","null"]},"purpose":{"enum":["rental","purchase","business_partner","civil_matter"]},"country":{"type":["string","null"]},"applicant":{"$ref":"#/components/schemas/Applicant"},"document_count":{"type":"integer"},"decision":{"enum":["approve","review","decline",null]},"score":{"type":["integer","null"],"minimum":0,"maximum":100},"result":{"oneOf":[{"$ref":"#/components/schemas/Result"},{"type":"null"}]},"case_details":{"$ref":"#/components/schemas/CaseDetails"},"error":{"type":["string","null"]},"metadata":{"$ref":"#/components/schemas/Metadata"},"link_id":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"}}},"Result":{"type":"object","description":"Which parts are included follows your result_format settings.","properties":{"score":{"type":"integer"},"decision":{"enum":["approve","review","decline"]},"display_score":{"type":"string","examples":["82/100","8.2/10","B"]},"summary":{"type":"string"},"detected_document_type":{"type":["string","null"]},"detected_country":{"type":["string","null"]},"documents_checked":{"type":"integer"},"deviations":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"severity":{"enum":["low","medium","high"]},"note":{"type":"string"}}}},"fields":{"type":"array","items":{"type":"object","additionalProperties":true}},"income":{"type":"object","properties":{"monthly_amount":{"type":["number","null"]},"currency":{"type":["string","null"]}}},"breakdown":{"type":["object","null"],"properties":{"document_integrity":{"type":"integer"},"financial_capacity":{"type":"integer"},"identity":{"type":"integer"}}},"sandbox":{"type":"boolean"}}},"VerificationLinkCreate":{"type":"object","required":["applicant"],"properties":{"applicant":{"$ref":"#/components/schemas/Applicant"},"purpose":{"enum":["rental","purchase","business_partner","civil_matter"]},"country":{"type":"string"},"reference":{"type":"string"},"documents_requested":{"type":"array","maxItems":20,"items":{"type":"string"}},"expires_in_days":{"type":"integer","minimum":1,"maximum":30},"redirect_url":{"type":"string","format":"uri"},"brand_name":{"type":"string","maxLength":80},"locale":{"enum":["es","en"]},"send_email":{"type":"boolean","description":"Email the link to applicant.email in your branding"},"case_details":{"$ref":"#/components/schemas/CaseDetails"},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"VerificationLink":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"verification_link"},"environment":{"enum":["live","test"]},"status":{"enum":["pending","completed","expired","canceled"]},"reference":{"type":["string","null"]},"purpose":{"enum":["rental","purchase","business_partner","civil_matter"]},"country":{"type":["string","null"]},"applicant":{"$ref":"#/components/schemas/Applicant"},"documents_requested":{"type":"array","items":{"type":"string"}},"locale":{"type":["string","null"]},"case_details":{"$ref":"#/components/schemas/CaseDetails"},"redirect_url":{"type":["string","null"]},"url":{"type":["string","null"],"description":"Only on create"},"embed_url":{"type":["string","null"],"description":"Only on create"},"email_sent":{"type":"boolean"},"screening_id":{"type":["string","null"]},"expires_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"]},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"WebhookEndpointCreate":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"enum":["screening.created","screening.completed","screening.failed","screening.deleted","link.created","link.completed","link.canceled","link.expired"]}},"active":{"type":"boolean"}}},"WebhookEndpointUpdate":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"enum":["screening.created","screening.completed","screening.failed","screening.deleted","link.created","link.completed","link.canceled","link.expired"]}},"active":{"type":"boolean"}}},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"webhook_endpoint"},"environment":{"enum":["live","test"]},"url":{"type":"string"},"events":{"type":"array","items":{"enum":["screening.created","screening.completed","screening.failed","screening.deleted","link.created","link.completed","link.canceled","link.expired"]}},"active":{"type":"boolean"},"secret_hint":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"WebhookEndpointWithSecret":{"allOf":[{"$ref":"#/components/schemas/WebhookEndpoint"},{"type":"object","properties":{"secret":{"type":"string","description":"whsec_… — shown once"}}}]},"Event":{"type":"object","properties":{"id":{"type":"string","examples":["evt_8sK2…"]},"object":{"const":"event"},"type":{"enum":["screening.created","screening.completed","screening.failed","screening.deleted","link.created","link.completed","link.canceled","link.expired","ping"]},"environment":{"enum":["live","test"]},"api_version":{"type":"string"},"created":{"type":"integer","description":"Unix seconds"},"data":{"description":"The object as it was at that moment (screening, verification_link, …)","type":"object"}}},"Usage":{"type":"object","properties":{"object":{"const":"usage"},"period_start":{"type":"string","format":"date"},"period_end":{"type":"string","format":"date"},"invoice_date":{"type":"string","format":"date"},"screenings":{"type":"integer"},"amount":{"type":"integer","description":"Cents, graduated"},"minimum":{"type":"integer"},"currency":{"enum":["eur","usd"]},"tiers":{"type":"array","items":{"type":"object","properties":{"up_to":{"type":["integer","null"]},"cents":{"type":"integer"}}}},"billing_mode":{"enum":["prepaid","invoice"]},"balance":{"type":["integer","null"]},"credit_limit":{"type":["integer","null"]}}},"Invoice":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"invoice"},"period_start":{"type":"string"},"period_end":{"type":"string"},"screenings":{"type":"integer"},"volume":{"type":"integer"},"fixed":{"type":"integer"},"minimum_topup":{"type":"integer"},"onboarding":{"type":"integer"},"total":{"type":"integer"},"currency":{"type":"string"},"billing_mode":{"type":"string"},"status":{"enum":["draft","open","paid","void","uncollectible","settled_from_balance"]},"hosted_url":{"type":["string","null"]},"pdf_url":{"type":["string","null"]},"due_date":{"type":["string","null"]},"created_at":{"type":"string"}}},"ApiKeyInfo":{"type":"object","properties":{"object":{"const":"api_key"},"id":{"type":"string"},"name":{"type":"string"},"environment":{"enum":["live","test"]},"prefix":{"type":"string"},"scopes":{"type":"array","items":{"enum":["*","screenings:read","screenings:write","links:read","links:write","usage:read","settings:read","settings:write","webhooks:read","webhooks:write","events:read"]}},"expires_at":{"type":["string","null"]},"account":{"type":"object"},"api_version":{"type":"string"},"rate_limit_per_minute":{"type":"integer"},"available_scopes":{"type":"array","items":{"type":"string"}},"events":{"type":"array","items":{"type":"string"}}}},"Settings":{"type":"object","properties":{"decision":{"type":"object","properties":{"approve_min":{"type":"integer","minimum":1,"maximum":100,"default":70},"review_min":{"type":"integer","minimum":1,"maximum":100,"default":45}}},"branding":{"type":"object","properties":{"display_name":{"type":["string","null"]},"logo_url":{"type":["string","null"]},"primary_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}$"},"support_email":{"type":["string","null"]},"privacy_url":{"type":["string","null"]},"hide_powered_by":{"type":"boolean"}}},"link_defaults":{"type":"object","properties":{"purpose":{"enum":["rental","purchase","business_partner","civil_matter"]},"country":{"type":["string","null"]},"expiry_days":{"type":"integer","minimum":1,"maximum":30},"documents_requested":{"type":"array","items":{"type":"string"}},"redirect_url":{"type":["string","null"]},"email_applicant":{"type":"boolean"},"language":{"enum":["auto","es","en"]}}},"result_format":{"type":"object","properties":{"summary":{"type":"boolean"},"deviations":{"type":"boolean"},"fields":{"type":"boolean"},"income":{"type":"boolean"},"breakdown":{"type":"boolean"},"applicant":{"type":"boolean"},"score_scale":{"enum":["100","10","grade"]}}},"notifications":{"type":"object","properties":{"recipients":{"type":"array","maxItems":10,"items":{"type":"string","format":"email"}},"on_completed":{"type":"boolean"},"on_review":{"type":"boolean"},"on_decline":{"type":"boolean"},"on_failed":{"type":"boolean"}}}}}}}}