Nexus Test Credit Score Quickstart

Key Resources

Interactive API reference: /openapi/
Admin console: /admin/test-data/credit-scores (login required)
Decode tool: /admin/test-data/credit-scores/decode (no audit writes)
Raw OpenAPI JSON: /openapi/test_credit_score.json
Loan application overview: /docs/loan_applications/overview.md
Loan workflow OpenAPI: /openapi/loan_applications.json

Synthetic SSN Format (`999XXXYYY`)

Segment	Meaning	Notes
`999`	Synthetic prefix	Required; other prefixes return HTTP 422.
`XXX`	Score digits	Parsed as integer and clamped to FICO 300–850 range.
`YYY`	Alert dictionary	Use `001` for clean score, or combine digits below.

Alert digits:

Digit	Alert
1	OFAC record found
2	Bankruptcy on record
3	Account delinquencies found
4	Fraud alert found
5	Fraud shield flag
6	Mortgage delinquencies found
7	Foreclosure on record

Examples:

999820001 → score 820, no alerts.
999750123 → score 750, OFAC + bankruptcy + delinquency.
999680457 → score 680, fraud + fraud shield + foreclosure.

Create a Synthetic Score

Issue an API key from the admin console.
Send POST /api/v1/test-data/credit-scores with the synthetic SSN and optional guarantor metadata.
Persist only the replacement SSN returned in the response.

curl \ 
  -X POST http://localhost:3000/api/v1/test-data/credit-scores \ 
  -H "Authorization: Bearer ${NEXUS_API_KEY}" \ 
  -H "Content-Type: application/json" \ 
  -d '{
        "ssn": "999750123",
        "requesting_application": "nucleus",
        "guarantor": {
          "first_name": "Jane",
          "last_name": "Doe",
          "dob": "1988-07-11"
        }
      }'

The response mirrors Experian’s contract, including summary metrics, reason codes, and both SSNs:

{
  "reference_id": "9c1bde2f-7fe0-4a0d-9a8c-3b213ad0f7d5",
  "trace_id": "9c1bde2f-7fe0-4a0d-9a8c-3b213ad0f7d5",
  "bureau": "experian",
  "score_model": "Experian FICO",
  "score": 750,
  "score_digits": "750",
  "requesting_application": "nucleus",
  "alerts": [ ... ],
  "reason_codes": [ ... ],
  "summary": { ... },
  "identifiers": {
    "original_ssn": "999750123",
    "replacement_ssn": "537-82-4916"
  }
}

Loan Application Workflow Highlights

Applicants start or resume submissions at /loan_applications; the public form mirrors server-side validations and supports inline draft saves.
Draft saves return JSON with a resume_token and expiry window—ideal for embedding in emails or applicant portals.
Owner SSNs must follow the synthetic 999XXXYYY pattern and are automatically swapped for replacement identifiers before persistence.
Admins triage requests at /admin/loan-applications, update statuses with Turbo Streams, export filtered CSV/JSON, and review analytics via /admin/loan-applications/analytics.
See the loan application overview for configuration, auditing, and testing guidance.

Error Handling

Status	When it fires	Error code
401	Missing or invalid API key	`unauthorized`
422	Invalid SSN format or validation failure	`invalid_ssn`, `validation_error`
500	Unexpected server error	`internal_error` (includes `trace_id`)

Errors follow { "error": { "code", "message", ... } }. See the OpenAPI spec for full schema definitions.

Admin Tooling

Dashboard: Monitor volume, top applications, and alert distribution.
Audit log: Filter by application or date; inspect masked SSNs, scores, and trace IDs.
Decode tool: Test tokens without writing to the audit table.
API key management: Issue, rotate, and revoke keys (tokens hashed at rest).

Migration Checklist

Provision unique API keys for nucleus, fireball, proton, and zoltar.
Update each app to call Nexus when encountering 999XXXYYY SSNs.
Roll out behind environment flags and run parallel tests against legacy harnesses.
Share this quickstart and the interactive docs with QA/support.
Monitor adoption via the admin dashboard before decommissioning legacy harnesses.

Legacy Harness References

Older PCR and “Blue Book” SSN harnesses remain documented for historical context. New integrations should target Nexus exclusively to avoid contract drift.