Credit Bureau Fallback API

Overview

You send three identity fields; you get back a credit report in the CRIF CLIK format the SaaS already consumes. Everything upstream of this endpoint — which bureau we buy from, how we authenticate to them, what product we purchase — is handled on our side and is not part of this contract.

Quick start

# minimal: the three required fields
curl -X POST https://pefindo.milikirumah.ai/api/v1/credit-report \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $CB_API_KEY" \
  -d '{
    "identity_number": "3529116903740002",
    "full_name": "TRI MURYATUN",
    "date_of_birth": "1982-12-17"
  }'

# what you get back (abridged)
{
  "CG_RES": {
    "Info": { "Status": "SS", "RequestTime": "...", "ResponseTime": "..." },
    "Response": {
      "Status": "SS",
      "RequestID": "1470453",
      "Detail": {
        "Status": "SS", "Process": "NAE", "Service": "CLIK",
        "Content": { "CB_NAE_ProductOutput": {
          "CBScore": { "CBSGlocal": { "ScoreData": {
            "@attributes": { "ScoreRaw": "624", "ScoreRange": "RRD1" } } } },
          "CreditReport": { "MatchedSubject": {...}, "ContractsHistory": {...} },
          "EnquiredData": {...}
        } }
      }
    },
    "_Coverage": { /* what this source could not fill */ }
  }
}

Every value is a string, exactly as in the incumbent's XML-derived JSON. int(x.DebitBalance) keeps working unchanged.

Authentication

Send the shared key on every request, in either header:

X-API-Key: <key>
Authorization: Bearer <key>

Keys look like cb_staging_… or cb_prod_… and are issued per consumer and per environment. Only a hash is stored server-side, so a lost key is replaced, never recovered.

• Keep it in your secret store, not in the repo or a ticket.
• Do not reuse a staging key in production — they are separate keys so we can revoke one without disrupting the other.
• Every request is logged against your key id, so we can tell you exactly what your integration called and when.

Ask in #platform for a key, or to have one revoked.

Test subjects

Fetch the catalogue at any time:

curl -H "X-API-Key: $CB_API_KEY"   https://pefindo.milikirumah.ai/api/v1/test-subjects

Call /api/v1/credit-report with identity_number, full_name and date_of_birth exactly as listed — a mismatched name or date lowers the similarity score, which is deliberate so you can exercise your min_similarity handling.

All 17 test subjects

Every identity below resolves against the bureau. Facilities is the total contract count, Open how many are still active, and History how many months of portfolio history the subject carries (blank means none — a common case worth handling).

Request

Required

All three are used for identity matching. A wrong name or date of birth lowers the match score and can turn a real subject into a not-found.

identity_numberrequired

KTP number. Exactly 16 digits. Rejected with 400 otherwise.

full_namerequired

Full name as printed on the KTP.

date_of_birthrequired

YYYY-MM-DD. Any other format is rejected with 400.

Recommended

provider_application_norecommended

Your application id. Returned in ApplicationCodes.ProviderApplicationNo and written to our request log, so a report can be traced back to the application that asked for it. Without it, that trace is guesswork.

min_similarityrecommended

0–100. If the best identity match scores below this, you get a not-found envelope instead of a possibly wrong person's credit file. Start at 80.

timeout_secondsrecommended

How long to wait before giving up with 503. Default 300. Set it to your failover budget — see Timeouts.

Optional — echoed back only

Copied into EnquiredData in the response, the way the incumbent echoes an enquiry back. They do not change the credit data returned. Send them if you want the response to carry your application context.

Output options

include_coveragedefault true

Adds CG_RES._Coverage describing what this source could not fill. It sits outside the CRIF nodes, so an existing parser ignores it. Set false to omit.

crif_strictdefault false

false renders every CRIF attribute, using "" where there is no value — so your parser never hits a missing key. true reproduces the incumbent's literal conventions instead: its key order, and absent attributes omitted rather than empty. Use true only if you compare or hash the raw JSON.

derive_quality_from_dpddefault true

Fills PastDueStausCode/Desc and Maximum.WorstStatusCode/Desc from each contract's own days-past-due using the standard OJK bands (0 → Current, 1–90 → Special Attention, 91–120 → Substandard, 121–180 → Doubtful, 180+ → Loss). The source reports DPD per contract but not collectibility per contract, so this is a derivation — set false to leave the fields out.

quality_profiledefault true

Populates CreditProfile[].QualityCode with the monthly collectibility (KOL) the source reports. It is portfolio-level — the worst grade across everything the subject held that month — attached to contracts open in that month, not that contract's own grade. _Coverage.quality_source spells this out. Set false to leave CreditProfile empty.

collapse_singletonsdefault false

With crif_strict, renders a one-element array as a bare object. Unverified against the incumbent — see the caveat.

Response

A CRIF CLIK CG_RES envelope. The node tree, key names, key order and string typing all match the incumbent's. Structurally it is a drop-in; the difference is content, covered next.

Score, and the one trap in it

Field coverage

Measured, not estimated: the mapping was compared field by field against a real response from the incumbent across 17 subjects and 4,163 facilities. Of the 258 fields the incumbent populates, this source fills 175 (68%).

Coverage is flat across subjects from 1 to 705 facilities, because the gaps are whole missing sections rather than sparse data. What matters is which sections:

In one line: everything needed to size and price an application is present. What is missing is trend and velocity.

Two conventions that keep this safe

1. An attribute with no value is omitted, not blank — exactly what the incumbent does. Check for presence (if (!attrs.DueDate)), not for an empty string. This matters: a blank date string parses to the Unix epoch and renders as 1 Jan 1970, and a blank numeric parses to NaN. Omitting avoids both.
2. Absent means unknown, not zero. The FootPrints counts are absent rather than "0", because "0" would assert there were no enquiries. Do not default them to zero in your scorecard.

If your parser genuinely needs every key present, send emit_empty_attributes: true and unavailable fields come back as "" instead. That is not how the incumbent behaves, so prefer presence checks.

Where codes differ

Collectibility 1–5 is the shared OJK/SLIK scale and maps exactly. ContractTypeCode and ProviderTypeCode use this source's code space, not the incumbent's — the descriptions are correct, the codes differ. If you branch on those codes rather than the descriptions, tell us and we will add a translation table.

CBContractCode is synthesised (prefixed PBK-) because this source carries no contract identifier. It is stable within one report but not across reports — do not use it as a durable key.

Status codes

The 502 / 503 split is deliberate and worth honouring: 503 is worth retrying, 502 is not.

{
  "error": {
    "code": "invalid_enquiry",
    "message": "identity_number must be exactly 16 digits for KTP",
    "field": "identity_number"
  }
}

Timeouts and retries

Report generation upstream is variable — typically a few seconds, but we have observed it exceed nine minutes during an upstream incident. Plan for that rather than assuming the happy path.

• Set timeout_seconds to your failover budget, not ours. A fallback that blocks a request for five minutes is not a fallback.
• On 503 the body carries an event_id. The report may still be building upstream, and it has already been paid for.
• Collect it later with GET /api/v1/report/{event_id} — 202 while still building, 200 with the full envelope once ready. This avoids being charged for a second enquiry.

# after a 503
curl -H "X-API-Key: $CB_API_KEY" \
  https://pefindo.milikirumah.ai/api/v1/report/08529317-1eed-4c62-b34b-d0774ba32b7a

Failover pattern

Because the envelope matches, failing over is a base-URL swap. The part worth thinking about is what you do with the reduced coverage.

1. Call the incumbent. On its failure, call this endpoint.
2. Record which source answered — _Coverage.source is "alternate-bureau" here. You will want this when explaining a decision later.
3. Guard features that read CreditProfile[] or FootPrints. An empty array is not a clean file; it is an absent signal. Skip the feature or fall back to a coarser rule rather than scoring the blank as zero.
4. Consider a stricter cut-off while on the fallback, since you are deciding with less information.

TypeScript client

// lib/creditBureau.ts
type Enquiry = {
  identity_number: string;   // 16 digits
  full_name: string;
  date_of_birth: string;     // YYYY-MM-DD
  provider_application_no?: string;
  min_similarity?: number;
  timeout_seconds?: number;
};

export class BureauUnavailable extends Error {
  constructor(msg: string, readonly eventId?: string) { super(msg); }
}

export async function fetchCreditReport(enquiry: Enquiry) {
  const res = await fetch(`${process.env.CB_FALLBACK_URL}/api/v1/credit-report`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": process.env.CB_API_KEY!,
    },
    body: JSON.stringify({ min_similarity: 80, timeout_seconds: 45, ...enquiry }),
  });

  if (res.status === 400) {
    const { error } = await res.json();
    throw new Error(`bad enquiry (${error.field}): ${error.message}`);
  }
  if (res.status === 503) {
    const { error } = await res.json();
    // retryable; event_id collects the report without paying again
    throw new BureauUnavailable(error.message, error.event_id);
  }
  if (!res.ok) throw new Error(`bureau error ${res.status}`);

  const body = await res.json();
  const cg = body.CG_RES;

  if (cg.Info.Status !== "SS") return { found: false as const };

  const out = cg.Response.Detail.Content.CB_NAE_ProductOutput;
  const score = out.CBScore.CBSGlocal.ScoreData?.["@attributes"];

  return {
    found: true as const,
    // blank ScoreRaw means "not scorable" -- never coerce it to 0
    score: score?.ScoreRaw ? Number(score.ScoreRaw) : null,
    riskGrade: score?.ScoreRange ?? null,
    contracts: out.CreditReport.ContractsHistory.Credit.GrantedCredit,
    totals: out.CreditReport.ContractsHistory.AggregatedData["@attributes"],
    // tells you which sections came back empty
    coverage: cg._Coverage,
    raw: body,
  };
}

Other endpoints

Liveness plus upstream reachability. 200 when healthy, 503 when the upstream connection is down — useful as a pre-flight before routing traffic here during an incident.

This request contract as JSON. Authoritative if it ever disagrees with this page.

Collect a report that timed out. 202 while still building, 200 with the envelope once ready.

Known caveat: single-element arrays