Getting Started

​Getting Started

Follow this guide to make your first Scrub API call in under five minutes.

​Integration journey

1
Create an account
Sign up at detect.usescrub.io and verify your email to activate your organisation account.
2
Authenticate
Log in for a dashboard session, or create an API key in Token Management for server-to-server calls.
3
Configure webhooks
In Settings → Controls, set your webhook URL and signing secret to receive report.ready and report.failed events.
4
Detect documents
Call POST /api/v1/detect/file with Bearer auth to screen uploaded images for AI / manipulation signals.
5
Run financial reports
Call POST /api/v1/report, embed link_url on your frontend for bank connection, then receive the scored report via webhook or poll.

​Quickstart — detect an uploaded document

1. Authenticate — log in for a JWT, or use an API key from Token Management. See Authentication.

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "you@company.ng",
  "password": "your_password"
}
http

2. Upload a file for detection

POST /api/v1/detect/file
Authorization: Bearer <access_token_or_api_key>
Content-Type: multipart/form-data

file=@document.png
http

3. Expected response shape

{
  "success": true,
  "cached": false,
  "detection_data": {},
  "image_hash": "sha256:..."
}
json

​Quickstart — start a financial report

Create a case, embed the bank-connection link on your frontend, then receive the scored report via webhook (or poll for status).

​1. Configure your webhook (once)

In the dashboard under Settings → Controls, set a webhook URL and copy the signing secret. Scrub will POST signed events to that URL when the report is ready or fails. See Webhooks for signature verification and retries.

​2. Create a report case

POST /api/v1/report
Authorization: Bearer <access_token_or_api_key>
Content-Type: application/json

{
  "full_name": "Adebola James",
  "contact_email": "adebola@example.com",
  "reference_id": "loan_app_9981",
  "country_codes": ["US"]
}
http

202 response

{
  "case_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PENDING_CONNECTION",
  "message": "Embed link_url in an iframe on your platform to open Plaid Link. Report will be delivered via webhook upon completion.",
  "link_url": "https://app.example.com/plaid/link?session=opaque-token"
}
json

​3. Open bank connection on your frontend

link_url is for your frontend, not a backend call. Embed it in an iframe or redirect the applicant to it so they can connect their bank.

​4. Case statuses

StatusMeaning
PENDING_CONNECTIONConsent link issued; waiting for the applicant to connect a bank
CONNECTEDBank connected; report generation queued
PROCESSINGPulling provider data and scoring
REPORT_READYReport ready — payload available via poll and report.ready webhook
FAILEDGeneration failed (or marked failed after provider/item errors)
EXPIREDConsent link expired before the applicant connected

Terminal statuses: REPORT_READY, FAILED, EXPIRED.

​5. Receive the result via webhook

After the applicant connects, Scrub generates the report asynchronously and POSTs to your webhook URL:

EventWhen
report.readyStatus is REPORT_READY — body includes score and report summary
report.failedStatus is FAILED or EXPIRED

report.ready example

{
  "event": "report.ready",
  "case_id": "550e8400-e29b-41d4-a716-446655440000",
  "reference_id": "loan_app_9981",
  "status": "REPORT_READY",
  "report": {
    "score": 72,
    "income_monthly_usd": 4200,
    "income_monthly_local": 4200,
    "affordability_ceiling_local": 1260,
    "dti_ratio": 0.31
  },
  "report_pdf_url": "https://api.example.com/reports/..."
}
json

Return 2xx within 15 seconds. Failed deliveries retry with backoff. Full details: Webhooks.

​6. Or poll for status

GET /api/v1/report/{case_id}
Authorization: Bearer <access_token_or_api_key>
http

When status is REPORT_READY, the response includes score and report payload. webhook_delivered_at is set after a successful webhook delivery.

​Next steps

IntroductionAuthentication