LendKey Credit Risk API

openapi: 3.0.3
info:
  title: LendKey E-Sign API (via Kong Gateway) Application Contracts Credit Risk API
  version: 0.1
  description: "# LendKey E-Sign API - Kong Gateway Documentation\n\n## Overview\n\nThe LendKey E-Sign API provides endpoints for creating and managing electronic signature contracts using DocuSign.\nThis API is accessed through Kong Gateway, which handles authentication via OAuth2.\n\n## Authentication\n\nAll requests to this API require OAuth2 authentication through Kong Gateway.\n\n### Step 1: Get OAuth2 Token\n\nBefore calling any endpoint, you must obtain an access token:\n\n**Production Environment:**\n```bash\ncurl -X POST https://api.lendkey.com/esign/oauth2/token \\\n  -d \"grant_type=client_credentials\" \\\n  -d \"client_id=YOUR_CLIENT_ID\" \\\n  -d \"client_secret=YOUR_CLIENT_SECRET\"\n```\n\n**Response:**\n```json\n{\n  \"access_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n  \"token_type\": \"bearer\",\n  \"expires_in\": 7200\n}\n```\n\n### Step 2: Use Token in API Calls\n\nInclude the access token in the `Authorization` header:\n```\nAuthorization: Bearer YOUR_ACCESS_TOKEN\n```\n\n**Token Lifetime:** 2 hours (7200 seconds)\n\n## Base URLs (Kong Gateway)\n\n| Environment | Kong Base URL | Backend Kubernetes Service |\n|------------|---------------|---------------------------|\n| **Production** | `https://api.lendkey.com/esign` | `main-esign-kotlin.ci.lkeyprod.com` |\n\n## How Kong Routes Requests\n\nWhen you call Kong:\n```\nhttps://api.lendkey.com/esign/applications\n```\n\nKong:\n1. Validates your OAuth2 token\n2. Strips the `/esign` prefix\n3. Forwards to: `http://main-esign-kotlin.ci.lkeyprod.com/applications`\n\nYou don't need to manage any backend authentication - Kong handles everything!\n\n## Getting Started\n\n1. **Get Credentials:** Contact your Kong admin or use the Kong Developer Portal\n2. **Get Token:** Use the OAuth2 token endpoint for your environment\n3. **Call API:** Use the token in the Authorization header\n4. **Refresh:** Get a new token every 2 hours\n"
  contact:
    name: LendKey Platform Team
    url: https://lendkey.com
servers:
- url: https://api.lendkey.com/esign
  description: Production Environment
security:
- oauth2: []
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'
  /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'
  /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'
  /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'
components:
  schemas:
    combinedMonthlyDebtResponse:
      type: object
      properties:
        amount:
          type: integer
          description: The combined total monthly debt for the two given credit profiles.
          example: 2423
    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
    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
    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
    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
    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
    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
    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
    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
    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
    softCreditResponse:
      type: object
      properties:
        id:
          type: integer
          example: 1234
  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
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth2 client credentials flow via Kong Gateway
      flows:
        clientCredentials:
          tokenUrl: /oauth2/token
          scopes: {}