{
  "openapi": "3.0.3",
  "info": {
    "title": "Nexus Test Credit Score API",
    "version": "1.0.0",
    "description": "Synthetic credit score endpoints used by internal applications to fabricate Experian-style payloads for staging and development environments."
  },
  "servers": [
    { "url": "https://nexus.example.com", "description": "Nexus base URL" },
    { "url": "http://localhost:3000", "description": "Local development" }
  ],
  "tags": [
    { "name": "Test Credit Scores", "description": "Endpoints for generating and decoding synthetic credit score data." }
  ],
  "paths": {
    "/api/v1/test-data/credit-scores": {
      "post": {
        "tags": ["Test Credit Scores"],
        "summary": "Generate synthetic credit score",
        "description": "Creates an Experian-style response using a synthetic SSN token. Persists an audit log and returns a replacement SSN.",
        "security": [{ "ApiKeyAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/TestCreditScoreCreateRequest" },
              "examples": {
                "CleanScore": {
                  "value": {
                    "ssn": "999820001",
                    "requesting_application": "nucleus",
                    "guarantor": {
                      "first_name": "Jane",
                      "last_name": "Doe",
                      "dob": "1988-07-11",
                      "address": {
                        "street": "123 Demo Way",
                        "city": "Springfield",
                        "state": "IL",
                        "postal_code": "62704"
                      }
                    }
                  }
                },
                "Alerts": {
                  "value": {
                    "ssn": "999750123",
                    "requesting_application": "proton",
                    "guarantor": {
                      "first_name": "John",
                      "last_name": "Ramos"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Synthetic credit score response",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/TestCreditScoreResponse" },
                "examples": {
                  "Success": {
                    "value": {
                      "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": "proton",
                      "alerts": [
                        { "code": "OFAC", "description": "OFAC record found" },
                        { "code": "BANKRUPTCY", "description": "Bankruptcy on record" },
                        { "code": "DELINQUENCIES", "description": "Account delinquencies found" }
                      ],
                      "reason_codes": ["OFAC_MATCH", "RECENT_BANKRUPTCY", "DELINQUENT_ACCOUNTS"],
                      "summary": {
                        "risk_tier": "very_good",
                        "alert_count": 3,
                        "has_adverse_action": true,
                        "score_bucket": "B"
                      },
                      "identifiers": {
                        "original_ssn": "999750123",
                        "replacement_ssn": "537-82-4916"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "422": { "$ref": "#/components/responses/ValidationError" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/api/v1/test-data/credit-scores/decode": {
      "get": {
        "tags": ["Test Credit Scores"],
        "summary": "Decode synthetic SSN",
        "description": "Returns the parsed score and alerts for a synthetic SSN token. Does not persist data.",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "ssn",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "pattern": "^999\\d{6}$" },
            "description": "Synthetic SSN in 999XXXYYY format"
          }
        ],
        "responses": {
          "200": {
            "description": "Decoded SSN details",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/TestCreditScoreDecodeResponse" },
                "examples": {
                  "Success": {
                    "value": {
                      "ssn": "999750123",
                      "score": 750,
                      "score_digits": "750",
                      "flags": ["1", "2", "3"],
                      "alerts": [
                        { "code": "OFAC", "description": "OFAC record found" },
                        { "code": "BANKRUPTCY", "description": "Bankruptcy on record" },
                        { "code": "DELINQUENCIES", "description": "Account delinquencies found" }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "422": { "$ref": "#/components/responses/ValidationError" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key"
      }
    },
    "schemas": {
      "TestCreditScoreCreateRequest": {
        "type": "object",
        "required": ["ssn"],
        "properties": {
          "ssn": {
            "type": "string",
            "pattern": "^999\\d{6}$",
            "description": "Synthetic SSN in 999XXXYYY format"
          },
          "requesting_application": {
            "type": "string",
            "description": "Name of the consuming application"
          },
          "guarantor": {
            "$ref": "#/components/schemas/GuarantorAttributes"
          }
        },
        "additionalProperties": false
      },
      "GuarantorAttributes": {
        "type": "object",
        "description": "Optional guarantor metadata to pass through the pipeline.",
        "properties": {
          "first_name": { "type": "string" },
          "last_name": { "type": "string" },
          "dob": { "type": "string", "format": "date" },
          "address": {
            "type": "object",
            "properties": {
              "street": { "type": "string" },
              "city": { "type": "string" },
              "state": { "type": "string", "minLength": 2, "maxLength": 2 },
              "postal_code": { "type": "string" }
            },
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      },
      "TestCreditScoreResponse": {
        "type": "object",
        "required": [
          "reference_id",
          "trace_id",
          "bureau",
          "score_model",
          "score",
          "score_digits",
          "requesting_application",
          "summary",
          "identifiers"
        ],
        "properties": {
          "reference_id": { "type": "string", "format": "uuid" },
          "trace_id": { "type": "string" },
          "bureau": { "type": "string", "enum": ["experian"] },
          "score_model": { "type": "string" },
          "score": { "type": "integer", "minimum": 300, "maximum": 850 },
          "score_digits": { "type": "string" },
          "requesting_application": { "type": "string" },
          "alerts": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Alert" },
            "description": "Alerts derived from the SSN flag digits"
          },
          "reason_codes": {
            "type": "array",
            "items": { "type": "string" }
          },
          "summary": { "$ref": "#/components/schemas/CreditSummary" },
          "identifiers": {
            "type": "object",
            "properties": {
              "original_ssn": { "type": "string" },
              "replacement_ssn": { "type": "string" }
            },
            "required": ["original_ssn", "replacement_ssn"]
          }
        }
      },
      "TestCreditScoreDecodeResponse": {
        "type": "object",
        "required": ["ssn", "score", "score_digits", "flags"],
        "properties": {
          "ssn": { "type": "string" },
          "score": { "type": "integer" },
          "score_digits": { "type": "string" },
          "flags": {
            "type": "array",
            "items": { "type": "string" }
          },
          "alerts": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Alert" }
          }
        }
      },
      "Alert": {
        "type": "object",
        "required": ["code", "description"],
        "properties": {
          "code": { "type": "string" },
          "description": { "type": "string" }
        }
      },
      "CreditSummary": {
        "type": "object",
        "required": ["risk_tier", "alert_count", "has_adverse_action", "score_bucket"],
        "properties": {
          "risk_tier": { "type": "string", "enum": ["excellent", "very_good", "good", "fair", "poor"] },
          "alert_count": { "type": "integer", "minimum": 0 },
          "has_adverse_action": { "type": "boolean" },
          "score_bucket": { "type": "string" }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" }
            }
          }
        }
      } 
    },
    "responses": {
      "BadRequest": {
        "description": "Malformed request",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
            "examples": {
              "BadRequest": {
                "value": {
                  "error": {
                    "code": "bad_request",
                    "message": "Request body must be valid JSON"
                  }
                }
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid API key",
        "headers": {
          "WWW-Authenticate": {
            "schema": { "type": "string" },
            "description": "Bearer realm description"
          }
        },
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
            "examples": {
              "Unauthorized": {
                "value": {
                  "error": {
                    "code": "unauthorized",
                    "message": "API key is invalid"
                  }
                }
              }
            }
          }
        }
      },
      "ValidationError": {
        "description": "Validation failure",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
            "examples": {
              "InvalidSSN": {
                "value": {
                  "error": {
                    "code": "invalid_ssn",
                    "message": "SSN must match 999XXXYYY format"
                  }
                }
              }
            }
          }
        }
      },
      "InternalError": {
        "description": "Unexpected server error",
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                { "$ref": "#/components/schemas/ErrorResponse" },
                {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "trace_id": { "type": "string" }
                      }
                    }
                  }
                }
              ]
            },
            "examples": {
              "Internal": {
                "value": {
                  "error": {
                    "code": "internal_error",
                    "message": "Unexpected error",
                    "trace_id": "5f836a1d-24a6-4d37-9cb0-1b8dd0186f4d"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}