- Chile first, country-agnostic design: today subjects are Chilean (
country: "CL", RUT asdoc_id); new countries plug in without contract changes. - Live freshness: every report queries the data sources at purchase time and declares, per source, whether the data is
live,cachedorunavailable. No silent stale data. - Compliance built in: the declared
purposeis mandatory (Chilean data protection law), every score carries its reason codes, and every report includes a public verification code.
Qscore is a paid product gated by the
risk service flag of your account and billed per report (risk_report_person / risk_report_company standalone fees). If the generation fails after the charge, the fee is refunded automatically and the report ends failed with its error_code. The exception is your own report: a verified account holder generates their self report for free — see “Your own report (self)” below.How it works
Generation is synchronous: thePOST fetches the bureau records, computes the score, renders the PDF and returns the ready report in a single response. A source that is down does not fail a paid report — it is generated with the persisted data and the source is declared cached (or unavailable if it contributed nothing) in the sources section.
Your own report (self)
If you hold a verified account (approved KYC/KYB), you can generate and download your own Qscore report directly. This is your right of access to your personal data (ARCO / Chilean Law 21.719), not a purchase:- Free: no fee is charged, ever.
- No score penalty: self reports are excluded from the inquiry count of your score — checking your own report never hurts it.
- Anti-oracle by design: the subject identity comes from the
tax_idverified in your KYC/KYB. The request does not accept adoc_id— asking for someone else’s report through these endpoints is impossible. - Frequency limit: one new report every 30 days. If you already have a
readyreport within the window, thePOSTreturns it withidempotency_hit: true(HTTP 200) instead of generating another.
Generate (or reuse) your report
POST /v1/qscore/my-report — the body is optional: {"lang": "en"|"es"|"zh"} (default en). Generation is synchronous: the response carries the finished report. No idempotency_key is needed — idempotency is deterministic per account, subject and day (a double submit on the same day returns the already-created report).
Generate your own report
201 Created (new report generated)
200 OK with the same report and "idempotency_hit": true. If the generation fails, the response is 201 with status: "failed" and its error_code / error_message (nothing was charged — the self report is free).
Read your latest report
GET /v1/qscore/my-report returns your most recent self report (any status) without generating a new one — 404 not_found if you never generated one.
Download the PDF
GET /v1/qscore/my-report/pdf downloads the PDF of your latest self report (Content-Disposition: attachment; filename="qscore_self_<id>.pdf"). If the report is not ready yet, it answers 404 pdf_not_ready.
The PDF carries the same public verification code as any Qscore report — anyone holding it can check its authenticity at GET /verify/qscore/{code} (see “Public verification” below).
Self-report errors
The commercial endpoint
POST /v1/qscore/reports rejects purpose: "self_access" with 400 invalid_purpose — self access only goes through /v1/qscore/my-report. The risk_report_ready webhook of a self report carries an extra "purpose": "self_access" field in its payload.1. Buy a report
POST /v1/qscore/reports creates and generates the full report. idempotency_key is mandatory (the report charges a fee: a retry with the same key returns the original report with idempotency_hit: true and never double-charges).
- Person
- Company
Create person report
201 Created (report ready)
error_code: "generation_failed" persisted on the report. Re-running with the same idempotency_key returns the original report (or its failure) — it never charges twice.
2. The score (model v1)
The score runsqscore-v1: base 600, range 1–999, adjusted by adverse facts (open delinquencies, protests, bankruptcies, recent queries) and positive signals (active tradelines, credit history depth, company activity, alternative data).
Every report carries its
reason_codes — the explainability layer of the score:
Industry peer benchmark (company reports only)
Company reports may include thepeer_benchmark block: the score’s position within its segment — same country and same industry (ISIC classification, from the tax registry).
Benchmark rules:
- Company reports only — person reports never include it (the block is omitted).
- The industry comes from the tax registry and is stamped on the subject (the latest known value wins).
- The comparable population is the latest score of each company in the same country and industry, excluding the evaluated subject.
- Published only with at least 5 comparable companies — below that, the block is omitted from the report (statistical context is never invented).
percentilereads as “better than N% of the segment”;median_scoreis the segment median.
3. Query and history
List reports
GET /v1/qscore/reports lists the reports purchased by your account. from and to (dates YYYY-MM-DD, organization timezone, both inclusive) are mandatory; filters subject_id and status (pending, ready, failed) are optional; pagination with page / page_size (default 50, max 200).
List reports
200 OK
Report detail
GET /v1/qscore/reports/{report_id} returns the report; when ready it includes the full report object (same shape as the creation response).
Download the PDF
GET /v1/qscore/reports/{report_id}/pdf downloads the branded PDF (application/pdf, filename qscore_<report_id>.pdf). Until the report is ready it answers 404 pdf_not_ready. The PDF is a private document: download it authenticated — it is never attached to emails nor exposed on public URLs.
Subject file and current score (without buying a new report)
GET /v1/qscore/subjects/{doc_id}?country=CL returns the subject file (identity + latest score) for a document you already reported on:
200 OK (subject file)
GET /v1/qscore/subjects/{doc_id}/score?country=CL returns just the current score (404 no_score if the subject has none yet):
200 OK (current score)
4. Report statuses
5. Errors
See the full catalogue in Errors.
6. Webhooks
Subscribe to the Qscore events in your webhook settings. All three are account-audience events, signed like every other webhook.risk_report_ready — a report finished generating
risk_report_ready — a report finished generating
risk_report_ready
"purpose": "self_access" field; commercial reports omit it.risk_score_changed — the subject's score moved
risk_score_changed — the subject's score moved
Fired when a new report computes a score different from the subject’s previous one.
risk_score_changed
risk_monitoring_alert — a monitored subject changed
risk_monitoring_alert — a monitored subject changed
Fired for every active monitoring subscription when the subject’s score drops below your
monitor_since_score floor, new bureau records appear, or records are removed. The first evaluation after subscribing only seeds the baseline and never alerts.risk_monitoring_alert
7. Public verification
Every report PDF prints a verification code and URL. Anyone holding the code can check the report’s authenticity — without PII — atGET /verify/qscore/{code} (no auth):
200 OK (valid report)
404 with {"valid": false, ...}. The endpoint is rate-limited per IP and reveals nothing beyond validity, band and date.
8. ARCO disputes
Data subjects can exercise their ARCO rights (access, rectification, cancellation, opposition). Your account opens a dispute against a specific record of a subject:Open a dispute
201 Created
open → under_review → resolved_corrected | resolved_rejected (final). List them with GET /v1/qscore/subjects/{doc_id}/disputes?country=CL&status=open (paginated) and read one with GET /v1/qscore/disputes/{dispute_id}. Resolution is handled by your org admin from the admin panel.
9. Monitoring
Once you own aready report on a subject, subscribe to continuous monitoring and receive a risk_monitoring_alert webhook every time something relevant changes: the score drops below your threshold, new bureau records appear, or records are removed. Monitoring is free — the only requirement is the purchased report (the same policy as the score endpoint: nobody watches a third party without paying to know them first).
Subscribe (or update thresholds)
200 OK
monitor_since_score(optional, 1–999): alert when the score falls below this threshold (score_drop_belowtrigger).only_material(defaultfalse): whentrue, only material changes fire the alert.- The worker re-evaluates every monitored subject every ~5 minutes. The first pass only seeds the baseline — it never alerts on data you already saw in the report you paid for.
GET /v1/qscore/subjects/{doc_id}/monitoring, list every monitored subject of the account with GET /v1/qscore/monitoring?active=true&page=1&page_size=50 (paginated: items, page, page_size, total), and deactivate with DELETE:
Deactivate monitoring
200 OK
DELETE deactivates (active: false) — the subscription history is never deleted, and a new PUT reactivates it with fresh thresholds.
The alert payload (risk_monitoring_alert) carries the triggers (score_drop_below, new_records, records_removed), the current and previous score, the band and the new records — full example in webhooks.
10. Batch scoring (portfolios)
To score a whole portfolio instead of one subject at a time, submit a batch withPOST /v1/qscore/batches: up to 5,000 subjects (JSON or CSV), one shared country and purpose, and an estimated fee computed up front. The API answers 202 Accepted immediately and a background worker generates the individual reports one by one — each item is a standard Qscore report with its own PDF, fee and automatic refund if its generation fails.
- Terminal fan-out: when the batch finishes you receive exactly one
risk_batch_completedwebhook and one summary email (never one per subject). - Follow-up: list and inspect batches, page through their items and download the consolidated CSV at
GET /v1/qscore/batches/{id}/results.csv.
FAQ
Is the score recomputed on every report?
Is the score recomputed on every report?
Yes. Every purchase fetches the sources live and recomputes the score with the current
qscore-v1 model. If a source is down, the report is generated with persisted data and the source is declared cached/unavailable in the sources section — never silently.What happens if the report fails after charging me?
What happens if the report fails after charging me?
The fee is refunded automatically in the same flow and the report ends
failed with its error_code. Your idempotency_key replays to that failed report; to try again, use a new key.Why is purpose mandatory?
Why is purpose mandatory?
Chilean data protection law requires a declared, legitimate purpose to query a person’s or company’s credit data. It is stored with the report and printed in it (auditability for the data subject).
Can I check someone's score without paying a report?
Can I check someone's score without paying a report?
Yes — if you already purchased a report on that subject,
GET /v1/qscore/subjects/{doc_id}/score returns the latest computed score at no extra cost. The first report on a subject is always a paid full report.Is the PDF sent by email?
Is the PDF sent by email?
No. The “report ready” email carries no attachment on purpose (third-party data minimization). The PDF only downloads authenticated from the API.
Which countries are supported?
Which countries are supported?
Chile today (
country: "CL", RUT as doc_id). The contract is country-agnostic: new countries will work with the same endpoints once their sources are plugged in.How often is a monitored subject checked?
How often is a monitored subject checked?
Every ~5 minutes. The
risk_monitoring_alert webhook only fires when something changed against the baseline (or only on material changes with only_material: true) — you never get paged for a no-op.