Developers
Four machine surfaces. Shapes, not mechanics.
FraudBrain exposes four surfaces to the systems that move applications: a tiers-only band feed, an agent-hold read, an enforcement verdict contract, and a short list of what an integration must carry so the graph can read it.
This page states each one's audience, its request, its answer and its failure shape. It states no weight, no threshold, no signal and no window; those stay where the Technology page says they stay.
Before anything else
Scores advise; people decide. FraudBrain never clears, declines, or terminates anyone.
Every surface below answers a question about a producer; none of them acts. A band is a reading, a hold is a human decision that already exists, a verdict is a shape the caller interprets under its own rules. The scoring description of record is the Technology page; nothing here restates it.
A caller key, by arrangement with InstaBrain
Every surface takes a key in the x-brain-key request header, and which key differs by surface: the band feed honours the platform key or a caller key, the hold read takes its own scoped key, and the verdict takes the application backend's own submission-guard key (no separate key is minted for it; the service maps that key to its tenant). Which key a caller holds is settled by arrangement: a key minted by FraudBrain for that caller, its digest armed on our side, or for the platform's own application backend the key it already presents to FraudBrain. The agent-hold read takes a key of its own that authorises nothing else. There is no self-service and no sign-up: the door is the access form, and a key follows a signed Order Form or a trial grant.
Nothing leaves that a key did not earn
An answer carries the fields the surface defines and no others: no score, no flag name, no narrative, no producer name, no note. Where a surface answers with producer identifiers, they are the platform's own ids and only the ones that surface defines (the hold read, for instance, names the held producers behind a licence number). Every example on this page uses the placeholder <caller key> and fixture identifiers that belong to nobody.
Fail closed on our side, fail open on yours
When a surface cannot read its own source it says so with an error status and no data, never a default. The systems that call it keep working: an application proceeds, a sign-up completes, a submission is answered later by the slower path. A silent gap is the one failure none of these surfaces is allowed.
Surface one
The tiers-only band feed. Counts of bands, nothing underneath.
Audience: platform operators holding an Order Form, by arrangement with InstaBrain. The feed answers one question for a list of producers: which alert band each one sits in right now. It is built for footnotes and dashboards that count bands, not for anything that reads a producer. It honours the platform key or a caller key minted for the operator; either goes in the x-brain-key header.
One POST, a list of producer ids
POST /fraudTierFeed
x-brain-key: <caller key>
content-type: application/json
{ "userIds": [900001, 900002, 900003] }
- At most 200 ids in one request. More, an empty list, a non-integer or a non-positive id is refused before anything is read.
- The ids are the caller's own producer identifiers as the platform knows them. The feed never maps a name, a licence number or a writing number.
A band per id that has one
{ "builtAt": "<instant>", "generation": null,
"tiers": { "900001": "HIGH", "900003": "LOW" } }
- The band vocabulary is three words: CRITICAL, HIGH, LOW. Never a number, never a new word.
- An id the current scoring cycle did not score is absent from the answer. Absent means unscored; it is never a default band and never null.
- When the scores the feed reads are missing, stale or malformed the answer is
503 { "error": "scores unreadable" }and no tiers. The feed writes nothing, ever.
Surface two
The agent-hold read. Is this producer on hold, and from which source.
Audience: the application at its start and at final submit, and the sign-up door of a producer portal. The read answers from a published hold list that is rebuilt on a fixed cycle and inside every human hold or release, so a decision is live for the next read within seconds. It takes its own scoped key, issued by arrangement with InstaBrain: the platform key is refused on this surface and this key authorises nothing else.
GET /agentHold?userId=900001
Answers { hold, sources, since, reviewDueAt, reasonCode, matchedBy, userId, matchedUserIds, listBuiltAt, listHash, listAgeSeconds, listAgeMinutes, consumerStaleSeconds, consumerStaleMinutes }. hold is true or false; reasonCode is one of enforcement, review_hold, outside_notice or null.
GET /agentHold?npn=12345678
The sign-up door's form of the question. A hit carries every held portal user behind the number in matchedUserIds, which can be empty when the hold rests on an outside notice with no portal user behind it (matchedBy says which: userId, notice or identifier); the door decides on identity, never on the bare number, because two people's numbers can coincide.
GET /agentHold
The published list with ETag set to its hash; a request carrying If-None-Match for the same hash is answered 304 with no body. Rate limited per calling address.
The sources an answer may name
- An enforcement state already recorded for the producer: terminated, suspended or restricted.
- A review hold placed by a named person, reversible, with a review date.
- An outside compliance or fraud notice that names the producer's licence number.
The source class travels. How a hold is decided, who placed it, the note behind it and the notice behind it never do.
The caller proceeds
- Unreachable, a timeout, a server error, or a list older than the staleness limit the answer itself carries (
listAgeSecondsaboveconsumerStaleSeconds): the application proceeds and we are the ones alerted. - Past a hard age the read itself refuses to answer
hold: truefrom stale facts and answers 503 with the list's age instead. - Every answer carries
Cache-Control: no-store; a hold is never served from a cache.
Surface three
The enforcement verdict contract. One word, named terms, your rules.
Audience: the carrier application backend, by arrangement with InstaBrain. At application start and at final submit the application asks the enforcement service for a verdict on the submission's producer identifiers. The service answers one word from a fixed vocabulary, names its mode, and names every term it did not evaluate on that request. Nothing in the answer is a score. The key on this call is the application backend's own submission-guard key, presented in x-brain-key and mapped to its tenant by the service; no separate caller key is minted for the verdict.
The caller's key and the identifiers the application keys on
POST /sparkVerdict
x-brain-key: <caller key>
{ "submissionId": "<the application's own id for this submit>",
"path": "start",
"agentId": 900002, "createdBy": 900002,
"opportunityUid": "<the application's record id>" }
- The key's digest sits in the service's ring for one tenant (for the platform's own application backend, the key that backend already presents); every producer identifier on the request is authorised under that tenant before anything is read for it.
- A retry of the same submission returns the stored answer and reads nothing new. The first answer is the answer.
ALLOW, CHALLENGE or REVIEW
{ "verdict": "ALLOW", "mode": "shadow",
"reasons": [], "notEvaluated": ["<term>", "..."],
"asOf": "<instant>", "requestId": "<id>" }
- The verdict is one of three words. REVIEW names the park kind, CHALLENGE a step-up, ALLOW that nothing here objects; what the caller does with each is the caller's own rule.
modenames the service's mode: inshadow, the only mode the service answers in today, FraudBrain holds nobody on a verdict and the answer is recorded beside the application's own flow. notEvaluatednames every term the service could not evaluate on this request, in the open, never silently.- A service error or a timeout is fail-open by contract: the application proceeds, and the hold read above is the slower path that still applies.
The terms, their weights and the timing of the sweep are not on this site (the band words themselves are the three above). The contract is the shape.
Surface four
What an integration must carry. So the graph can read it.
Audience: SDK and API partners who submit applications through a partner credential (the credential itself is issued by arrangement with InstaBrain). FraudBrain reads application rows; an application that arrives through a partner integration is read like any other, but only if the integration carries what the graph joins on. These are the requirements, each with what FraudBrain does with it, in one sentence.
The producer identifier on every application
The platform's own identifier of the writing producer, on every application the integration submits. FraudBrain reads it to score the producer and to answer the hold read.
The writing number as the carrier credits it
The number the carrier pays commission against, exactly as the carrier holds it. FraudBrain joins the post-sale ledger on it; a mismatch makes a producer invisible to the exposure side.
The applicant's contact fields as entered
The applicant's email, phone and address as the applicant gave them. FraudBrain reads them across the book as entered: a placeholder hides a pattern, and a value shared across applicants (one mailbox, one office number) becomes a pattern of its own. This is what the graph reads; the application's own field checks (a vendor verdict on the email address, a lookup on the phone number) are the application's and are not restated here.
The origin of the first step
The network address of the device that started the application, never the address of a relay or a proxy in front of it. FraudBrain reads where applications come from; a relay collapses every producer into one place.
The signing channel
How the applicant signed and where the signing request was delivered. FraudBrain reads whether the applicant was reached at all; a signature with no delivery record is a question, not an answer.
What the partner agrees to
A hold on a producer is honoured at the application door. A partner credential sits under published rate limits. Scores are advisory and every hold is a human decision; the partner is never asked to act on a score.
Keys, rotation and the door
Issuance is a process. Not a button.
A caller key follows a signed Order Form or a trial grant. FraudBrain mints the key, arms its digest on the surface it is for, and hands the value to one named person on the caller's side. Rotation replaces the digest and redeploys; the old value stops working the moment the new digest is armed. A key is never emailed to a list, never printed in a ticket, and never handed to a second caller; which keys a surface honours is written on that surface above (the band feed takes the platform key or a caller key, the hold read takes its own key, the verdict takes the application backend's submission-guard key). The only way in is the access form, read by a person.
Everything the surfaces leave out stays under the Security posture and is walked through under agreement during review. Bring your data people.