openapi: 3.2.0
info:
  title: Integration Credit Risk API
  description: This API collection represents the integration APIs LendKey offers for 3rd party dependencies/integrations, and is for dev/qa use only. External connections are not prohibited following this document.
  termsOfService: http://www.lendkey.com
  license:
    name: Lendkey License
    url: http://www.lendkey.com
  version: 1.0.0
  contact:
    name: LendKey Product Operations Team
    url: http://www.lendkey.com
    email: HIL_product_team@lendkey.com
servers:
- url: https://proxy.kong.lkeyprod.com/integration/
  description: This is the production host for our API endpoints.
- url: https://proxy.kong.lkeystaging.com/integration/
  description: This is the staging host for our API endpoints. Please note that the ability to create a soft-pull is disabled in this environment. If credit pull testing in this environment is needed, please reach out to coordinate that.
- url: https://proxy.kong.eks-1.use-1.lkeyqa.com/integration/integration-api-spring-boot-main/
  description: This is the QA host for our API endpoints. Please use this for all development and testing purposes.
- url: '{protocol}://{env}-integration-api-spring-boot.ci.lkeyqa.com:{port}/{basePath}'
  description: The testing API server
  variables:
    protocol:
      enum:
      - http
      - https
      default: https
    env:
      default: staging
      description: 'This value is related to the environment you are running. ie: PR-1112, develop'
    port:
      enum:
      - '8443'
      - '443'
      default: '8443'
    basePath:
      description: 'Version path. ie: v1'
      default: ''
- url: http://localhost:{port}/{basePath}
  description: The local development server
  variables:
    protocol:
      enum:
      - http
      - https
      default: https
    env:
      default: develop
      description: 'this value is related to the environment you are running. ie: PR-1112, develop'
    port:
      default: '8080'
    basePath:
      description: 'Version path. ie: v1'
      default: ''
tags:
- name: Credit Risk
paths:
  /v1/credit/soft_pull:
    post:
      tags:
      - Credit Risk
      summary: Performs a soft credit pull
      description: Performs a soft credit pull for the given applicant, and returns their credit profile.
      requestBody:
        content:
          application/hal+json:
            schema:
              $ref: '#/components/schemas/softCreditRequest'
      responses:
        200:
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/softCreditResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        500:
          $ref: '#/components/responses/UnexpectedError'
      operationId: postV1CreditSoftPull
      x-operation-id-source: derived
  /v1/credit/combined_monthly_debt:
    post:
      tags:
      - Credit Risk
      summary: Calculates the combined monthly debt between two credit profiles
      description: Given two credit profile IDs, calculates the monthly debt between the two profiles.
      requestBody:
        content:
          application/hal+json:
            schema:
              $ref: '#/components/schemas/combinedMonthlyDebtRequest'
      responses:
        200:
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/combinedMonthlyDebtResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        500:
          $ref: '#/components/responses/UnexpectedError'
      operationId: postV1CreditCombinedMonthlyDebt
      x-operation-id-source: derived
  /v1/credit/resolve_attributes:
    post:
      tags:
      - Credit Risk
      summary: Resolves the values for all credit attributes passed
      description: Given a credit profile ID, calculates/resolves all the values for the attributes requested.
      requestBody:
        content:
          application/hal+json:
            schema:
              $ref: '#/components/schemas/resolveCreditAttributesRequest'
      responses:
        200:
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/resolvedAttributesResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        500:
          $ref: '#/components/responses/UnexpectedError'
      operationId: postV1CreditResolveAttributes
      x-operation-id-source: derived
  /v1/scoring/score:
    post:
      tags:
      - Credit Risk
      summary: Score a given set of attributes against a PMML model
      description: Calls the scoring engine to evaluate the given set of attributes against the given PMML model UUID.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/scoringRequest'
      responses:
        200:
          description: OK
          content:
            application/hal+json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/scoringResponsePass'
                - $ref: '#/components/schemas/scoringResponseFail'
        400:
          $ref: '#/components/responses/BadRequest'
        500:
          $ref: '#/components/responses/UnexpectedError'
      operationId: postV1ScoringScore
      x-operation-id-source: derived
components:
  schemas:
    combinedMonthlyDebtRequest:
      type: object
      properties:
        creditProfileA:
          type: integer
          description: The credit profile ID for the first credit profile to include in the calculation.
          example: 32423
        creditProfileB:
          description: The credit profile ID for the second credit profile to include in the calculation.
          example: 92343
    resolveCreditAttributesRequest:
      type: object
      properties:
        creditProfileId:
          type: integer
          description: The credit profile ID for the credit profile to resolve the attributes for.
        creditAttributes:
          type: array
          items:
            type: string
            description: The properties to resolve the values for.
      example:
        creditProfileId: 32423
        creditAttributes:
        - attribute_one_tbd
        - attribute_two_tbd
        - attribute_three_tbd
        - attribute_four_tbd
        - attribute_five_tbd
        - attribute_six_tbd
    softCreditResponse:
      type: object
      properties:
        id:
          type: integer
          example: 1234
    softCreditRequest:
      type: object
      required:
      - firstName
      - lastName
      - ssn
      - street
      - city
      - state
      - zipCode
      - creditBureauName
      - creditRiskModel
      - preamble
      - subCode
      properties:
        firstName:
          type: string
          description: The full first name should be entered when available. The minimum entry is the first name initial. Blanks and special characters (except dash) are not allowed. Compound names should contain a dash (e.g., Billy-Bob)
          example: John
        lastName:
          type: string
          description: The full applicant’s surname is required. If the surname contains two surnames, then split the surnames with a hyphen (e.g., Smith-Jones). The surname can also be input with an apostrophe (e.g., O’Brien), although apostrophe usage is limited to the letters D, L, and O.
          example: Doe
        ssn:
          type: string
          description: Full Social Security number should be entered. The social may be input with or without hyphens (e.g., 123456789 or 123-45-6789).
          example: 999-99-9999
        street:
          type: string
          description: Include the house number, directional, street name, street type, and street suffix data (Apt
          example: 9999 Carver Road Suite 400
        city:
          type: string
          example: Cincinnati
        state:
          type: string
          description: The 2-letter state abbreviation
          example: OH
        zipCode:
          type: string
          description: ZIP code designation. It may be 9 characters and may contain a hyphen to separate the first 5 digits from the last 4 digits. It is required on all current address data. Canadian zip codes (6 digits), Mexican and Canadian country codes are allowed.
          example: '45242'
        creditBureauName:
          type: string
          description: Only "Experian" is currently supported.
          example: Experian
        creditRiskModel:
          type: string
          description: FICOv3, FICOv8, and FICOv9 are supported. Which one to use is defined by the program.
          example: FICOv8
        preamble:
          type: string
          description: Varies by lender.
          example: TBD2
        subCode:
          type: string
          description: Varies by lender.
          example: 1928032
    resolvedAttributesResponse:
      type: object
      additionalProperties:
        anyOf:
        - type: string
        - type: boolean
        - type: integer
        - type: number
        - type: array
      example:
        attribute_one_tbd: some string value
        attribute_two_tbd: true
        attribute_three_tbd: 132
        attribute_four_tbd: 32000.12
        attribute_five_tbd: 0.00249
        attribute_six_tbd:
        - could be array of strings or numbers
    scoringResponsePass:
      type: object
      properties:
        id:
          type: string
          description: A reference UUID to retrieve this score result later if needed.
          example: 3fec06c7-2a21-4f83-b100-5425fc5e035e
        type:
          type: string
          description: The type of score that was evaluated
          example: insight
        attributes:
          type: object
          description: The scoring attributes to use
          properties:
            created:
              type: string
              description: Timestamp of when the scoring model was created.
              example: '2022-03-07T14:39:57Z'
            arguments:
              type: object
              additionalProperties:
                type: string
              description: The attributes to provide to the scoring model
              example:
                bor_score_max: 720
                cob_score_max: 820
                bor_trlines_mortg_delinq_ls24m_count: 0
                cob_trlines_mortg_delinq_ls24m_count: 0
                bor_pbrecrds_judgements_ls60m_count: 0
                cob_pbrecrds_judgements_ls60m_count: 0
                bor_pbrecrds_repossessions_ls60m_count: 0
                cob_pbrecrds_repossessions_ls60m_count: 0
                bor_pbrecrds_chargeoffs_ls60m_count: 0
                cob_pbrecrds_chargeoffs_ls60m_count: 0
                bor_pbrecrds_collections_cumulative: 0
                cob_pbrecrds_collections_cumulative: 0
                bor_trlines_foreclosures_count: 0
                cob_trlines_foreclosures_count: 0
                bor_person_bankruptcies_count: 0
                cob_person_bankruptcies_count: 0
                bor_yearly_income_gross: 72000.0
                cob_yearly_income_gross: 120000.0
                cosigner: true
                prescreen: true
                requested_amount: 24000.0
                stated_housing_expenses: 1200,
                bor_reported_housing_expenses: 1245.0
                cob_reported_housing_expenses: 814.0
                bor_monthly_debt_excluding_housing_and_education: 1782.23
                cob_monthly_debt_excluding_housing_and_education: 1689.51
                bor_monthly_education_debt: 0
                cob_monthly_education_debt: 256.32
                bcob_joint_monthly_debt: 764.9
                longest_qualified_term: 180
                rate_for_longest_qualified_term: 5.24
            results:
              type: object
              additionalProperties:
                type: string
              description: This is a dynamic KVM that contains the results of the scoring model.
              example:
                Reason Code 09: null
                Reason Code 12: null
                Reason Code 13: null
                Reason Code 14: null
                joint_dti_percentage: '39.24929967889547'
                Reason Code 15: null
                Reason Code 16: null
                Reason Code 17: null
                Reason Code 18: null
                Reason Code 19: null
                Reason Code 30: null
                Reason Code 31: null
                Reason Code 10: null
                Reason Code 32: null
                Reason Code 11: null
                Reason Code 33: null
                insightResult: pass
                overallScore: '0.0'
                Decision: pass
                Reason Code 01: null
                Reason Code 23: null
                Reason Code 02: null
                Reason Code 24: null
                Reason Code 03: null
                Reason Code 25: null
                Reason Code 04: null
                Reason Code 26: null
                Reason Code 05: null
                Reason Code 27: null
                Reason Code 06: null
                Reason Code 28: null
                Reason Code 07: null
                Reason Code 29: null
                Reason Code 08: null
                Reason Code 20: null
                Reason Code 21: null
                Reason Code 22: null
    combinedMonthlyDebtResponse:
      type: object
      properties:
        amount:
          type: integer
          description: The combined total monthly debt for the two given credit profiles.
          example: 2423
    scoringRequest:
      type: object
      properties:
        attributes:
          type: object
          description: The scoring attributes to use
          properties:
            modelId:
              type: string
              description: The scoring model UUID to use to score the given arguments against.
              example: 3f77a5a0-9662-4cd9-93e8-881ba87a204f
            arguments:
              type: object
              additionalProperties:
                type: string
              description: The attributes to provide to the scoring model
              example:
                bor_score_max: 720
                cob_score_max: 820
                bor_trlines_mortg_delinq_ls24m_count: 0
                cob_trlines_mortg_delinq_ls24m_count: 0
                bor_pbrecrds_judgements_ls60m_count: 0
                cob_pbrecrds_judgements_ls60m_count: 0
                bor_pbrecrds_repossessions_ls60m_count: 0
                cob_pbrecrds_repossessions_ls60m_count: 0
                bor_pbrecrds_chargeoffs_ls60m_count: 0
                cob_pbrecrds_chargeoffs_ls60m_count: 0
                bor_pbrecrds_collections_cumulative: 0
                cob_pbrecrds_collections_cumulative: 0
                bor_trlines_foreclosures_count: 0
                cob_trlines_foreclosures_count: 0
                bor_person_bankruptcies_count: 0
                cob_person_bankruptcies_count: 0
                bor_yearly_income_gross: 72000.0
                cob_yearly_income_gross: 120000.0
                cosigner: true
                prescreen: true
                requested_amount: 24000.0
                stated_housing_expenses: 1200,
                bor_reported_housing_expenses: 1245.0
                cob_reported_housing_expenses: 814.0
                bor_monthly_debt_excluding_housing_and_education: 1782.23
                cob_monthly_debt_excluding_housing_and_education: 1689.51
                bor_monthly_education_debt: 0
                cob_monthly_education_debt: 256.32
                bcob_joint_monthly_debt: 764.9
                longest_qualified_term: 180
                rate_for_longest_qualified_term: 5.24
    suberror:
      type: object
      properties:
        object:
          type: string
        field:
          type: string
        rejectedValue:
          type: string
        message:
          type: string
      example:
        object: Resource
        field: name
        rejectedValue: null
        message: must not be null
    error:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
        timestamp:
          type: string
        message:
          type: string
        debugMessage:
          type: string
        subErrors:
          type: array
          items:
            $ref: '#/components/schemas/suberror'
      example:
        id: null
        status: BAD_REQUEST
        timestamp: '2019-10-21 14:07:59'
        message: Validation error
        debugMessage: null
        subErrors:
        - object: Resource
          field: name
          rejectedValue: null
          message: must not be null
    scoringResponseFail:
      type: object
      properties:
        id:
          type: string
          description: A reference UUID to retrieve this score result later if needed.
          example: 3fec06c7-2a21-4f83-b100-5425fc5e035e
        type:
          type: string
          description: The type of score that was evaluated
          example: insight
        attributes:
          type: object
          description: The scoring attributes to use
          properties:
            modelId:
              type: string
              description: The scoring model UUID to use to score the given arguments against.
              example: da3965d9-8d89-4415-84b4-e34c869dfb96
            arguments:
              type: object
              additionalProperties:
                type: string
              description: The attributes to provide to the scoring model
              example:
                bor_dti: '0.1486'
                bor_mnthlyincome_gros": '5666.666666666667'
                bor_person_bkrupt_ls60m_count: '0'
                bor_score_max: '649'
                bor_trlines_ageold: '67'
                bor_trlines_crunion_default_count: '0'
                bor_trlines_delinq_ls24m_count: '0'
                bor_trlines_frclose_ls60m_count: '0'
                bor_trlines_negatives_ls24m_agg: '0.0'
                bor_trlines_nodeferstu_open_count: '6'
                bor_trlines_opendue": '0'
                bor_trlines_stu_default_count: '0'
                cob_dti: '0.0154'
                cob_mnthlyincome_gross: '13182.666666666666'
                cob_person_bkrupt_ls60m_count: '0'
                cob_score_max: '707'
                cob_trlines_ageold: '213'
                cob_trlines_crunion_default_count: '0'
                cob_trlines_delinq_ls24m_count: '0'
                cob_trlines_frclose_ls60m_count: '0'
                cob_trlines_negatives_ls24m_agg: '0.0'
                cob_trlines_nodeferstu_open_count: '1'
                cob_trlines_opendue: '0'
                cob_trlines_stu_default_count: '0'
                cosigner: 'true'
                prescreen: 'false'
            results:
              type: object
              additionalProperties:
                type: string
              description: This is a dynamic KVM that contains the results of the scoring model.
              example:
                Decision: fail
                insightResult: fail
                overallScore: '2.0'
                Reason Code 01: bor_credit_score
                Reason Code 02: cob_count_of_open_trades_except_deferred_student_loans
                Reason Code 03: null
                Reason Code 04: null
                Reason Code 05: null
                Reason Code 06: null
                Reason Code 07: null
                Reason Code 08: null
                Reason Code 09: null
                Reason Code 10: null
                Reason Code 11: null
                Reason Code 12: null
                Reason Code 13: null
                Reason Code 14: null
                Reason Code 15: null
                Reason Code 16: null
                Reason Code 17: null
                Reason Code 18: null
                Reason Code 19: null
                Reason Code 20: null
                Reason Code 21: null
                Reason Code 22: null
                Reason Code 23: null
                Reason Code 24: null
                Reason Code 25: null
                Reason Code 26: null
                Reason Code 27: null
                Reason Code 28: null
                Reason Code 29: null
                Reason Code 30: null
                Reason Code 31: null
                Reason Code 32: null
                Reason Code 33: null
  responses:
    UnexpectedError:
      description: An unexpected server error occurred.
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/error'
          example:
            id: b6c52a48-551a-42ef-b361-f642d25cfeb7
            status: INTERNAL_SERVER_ERROR
            timestamp: '2019-10-21 14:07:59'
            message: An internal issue occurred.  Please try again shortly.  If the issue persists, contact us with all of the data in this error message.
            debugMessage: null
    BadRequest:
      description: Invalid request, unable to process the request with the information provided.
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/error'
          example:
            id: b6c52a48-551a-42ef-b361-f642d25cfeb7
            status: BAD_REQUEST
            timestamp: '2019-10-21 14:07:59'
            message: Describes what was invalid about the request, if possible.
            debugMessage: null