Most teams already have onboarding in place: a form, document and selfie checks, a rules engine, a manual queue. Oracul replaces none of these steps. It adds one more source of facts: does the person have a history online, and does it match what they stated. The key is to wire it in so the customer never waits.
Step 1. Start the scan in the background
Right after the application is submitted, your backend calls POST /v1/scans with the email, phone, username (if any), first and last name from the application, and the purpose of the check. The API answers at once with 202, the scan id and status queued. The customer carries on, the scan runs in parallel.
- More seeds mean a more accurate profile: the name filters out namesakes, email and phone give different angles.
- The purpose goes to the audit log with the request, which helps when a regulator asks.
- Recursion depth is set by the plan: 1 round on Free, 2 on Pro, 3 on Business and Enterprise.
Step 2. Receive the webhook
When the scan is done, Oracul POSTs to your webhook_url with a scan.completed event and a link to the result. The signature is HMAC-SHA256 in the X-Oracul-Signature header as t=…,v1=…. Check the signature with your secret and the timestamp t so you never accept a forgery or a replay. Webhooks go to https and public addresses only.
Step 3. Read the signals
GET /v1/scans/{id} returns the profile and a signals block: footprint age in days, the share of profiles with a matching name and the list of flags — no_footprint, young_footprint, name_mismatch, voip_phone, invalid_phone, breached_credentials. For details, GET /v1/scans/{id}/accounts pages through the accounts with sources and confidence.
Step 4. Let your rules decide
Oracul never says approve or decline. The decision stays in your engine, and the signals become one more input. For example:
- No flags and a footprint several years old: the normal path.
- young_footprint together with voip_phone: manual review before the first payout.
- name_mismatch: compare the document name with the profiles found in the console.
- breached_credentials: harden sign-in, the account with this email may have been taken over.
Where to put the decision point
Quick mode takes a few minutes; a full depth-2 scan takes 10–20 minutes. So it is easier to act on the signals not on the sign-up screen but at the step where risk appears: before the first payout, a card issue or a limit increase. By then the scan is usually done. If not, your rules decide whether to wait or let the application through the normal path.
Do not forget
- Plan limits: when they run out the API returns 429, so plan a retry or a fallback.
- Retention: results are deleted after 30 days. Keep what the decision needs on your side and erase the rest at once with DELETE /v1/scans/{id}.
- Quiet: the scan sends the person no emails or password resets, so the customer does not learn about the check from a notification.
- Legal basis: the basis for checking each customer is yours.
The free plan is enough to try the signals on your own cases: 5 scans a month, the console and the API.