openapi: 3.1.0
info:
  title: LoanVault Debt Settlement API
  version: 2026-10
  description: 'Integration API for debt settlement companies connecting to the LoanVault API from NewLine.ai for Credologi.
    Two-stage flow: POST a pre-approval with estimated amounts, wait for the PreApproved stage, then PATCH the final amounts.


    Auth: OAuth 2.0 client credentials. Tokens last 3600 seconds; cache and reuse them.


    Support: jmarone@newline.ai'
  contact:
    name: Jason Marone
    email: jmarone@newline.ai
servers:
- url: https://stage-backend.newline.ai
  description: Sandbox
- url: https://backend.newline.ai
  description: Production
tags:
- name: Auth
- name: Debt settlement
- name: Webhooks
paths:
  /oauth/token:
    post:
      tags:
      - Auth
      summary: Get an access token
      description: 'Sandbox: https://stage-backend.newline.ai/oauth/token. Production uses a different host: https://auth.newline.ai/oauth/token.'
      security: []
      servers:
      - url: https://stage-backend.newline.ai
        description: Sandbox
      - url: https://auth.newline.ai
        description: Production
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenRequest'
      responses:
        '200':
          description: Token issued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
  /api/v1/loan/debt-settlement:
    post:
      tags:
      - Debt settlement
      summary: Submit pre-approval application (estimated amounts)
      security: &id001
      - bearerAuth: []
      parameters:
      - &id002
        name: _format
        in: query
        required: true
        schema:
          type: string
          enum:
          - json
        description: Always json.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DebtSettlementRequest'
            example:
              loan:
                externalId: DEBT-123456789
                type: individual
                borrower:
                  email: jane.sample@example.com
                  firstName: Jane
                  middleName: ''
                  lastName: Sample
                  suffixName: ''
                  dob: '1980-10-03'
                  ssn: 123-45-6789
                  phoneDay:
                    type: mobile
                    number: 910-555-0199
                  addressCurrent:
                    address: 100 Main St
                    city: Wilmington
                    state: NC
                    zipCode: '28403'
                customData:
                  company: Example Settlement Group
                  gcsAccountNumber: '145784154'
                  escrowAccountBalance: 275.36
                  paymentProcessing:
                    name: Example Pay
                    routingNumber: '000000000'
                    accountNumber: '000000000001'
                    dedicatedAccount: '145784154'
                  dscPaymentProcessing:
                    name: Example Bank
                    routingNumber: '000000000'
                    accountNumber: '000000000002'
                settlement:
                  fee: 1076.0
                  payment: 191.0
                  balance: 4036.0
                  programPaymentFrequency: Monthly
                  originalFico: 643
                  programStartDate: '2025-05-23'
                  lastNsfDate: '2025-08-23'
                  accounts:
                  - name: Example Card Co
                    accountNumber: '0000000000001234'
                    originalBalance: 4289.0
                    settledBalance: 0.0
                  - name: Example Savings Bank
                    accountNumber: '54588301'
                    originalBalance: 2847.0
                    settledBalance: 0.0
                  paymentsMade:
                  - date: '2025-11-17'
                    amount: 358.97
                  - date: '2025-12-17'
                    amount: 381.54
                  - date: '2026-01-17'
                    amount: 381.54
                  - date: '2026-02-17'
                    amount: 381.54
                  - date: '2026-03-17'
                    amount: 405.39
                  - date: '2026-04-17'
                    amount: 405.39
                  - date: '2026-05-17'
                    amount: 405.39
                  - date: '2026-06-17'
                    amount: 416.41
                  - date: '2026-07-17'
                    amount: 416.41
                  - date: '2026-08-17'
                    amount: 416.41
                  - date: '2026-09-17'
                    amount: 416.41
                  - date: '2026-10-17'
                    amount: 416.41
      responses:
        '200':
          description: Created. If the client has fewer than 6 payments in the last 6 months, stage is Ineligible.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoanResult'
              example:
                status: created
                data:
                  stage: Incomplete
                  loanNumber: 12002100003
                  externalId: DEBT-123456789
        4XX:
          description: Failure, e.g. account with this email already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
  /api/v1/loan/debt-settlement/{loanNumber}:
    patch:
      tags:
      - Debt settlement
      summary: Update with final settlement amounts
      description: 'Only works while the application is PreApproved. At any other stage it returns the error: loan: The loan
        application is not in the correct state to be updated. The borrower email cannot be changed.'
      security: *id001
      parameters:
      - name: loanNumber
        in: path
        required: true
        schema:
          type: string
      - *id002
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DebtSettlementRequest'
            example:
              loan:
                externalId: DEBT-123456789
                type: individual
                borrower:
                  email: jane.sample@example.com
                  firstName: Jane
                  middleName: ''
                  lastName: Sample
                  suffixName: ''
                  dob: '1980-10-03'
                  ssn: 123-45-6789
                  phoneDay:
                    type: mobile
                    number: 910-555-0199
                  addressCurrent:
                    address: 100 Main St
                    city: Wilmington
                    state: NC
                    zipCode: '28403'
                customData:
                  company: Example Settlement Group
                  gcsAccountNumber: '145784154'
                  escrowAccountBalance: 423.36
                  paymentProcessing:
                    name: Example Pay
                    routingNumber: '000000000'
                    accountNumber: '000000000001'
                    dedicatedAccount: '145784154'
                  dscPaymentProcessing:
                    name: Example Bank
                    routingNumber: '000000000'
                    accountNumber: '000000000002'
                settlement:
                  fee: 1076.0
                  payment: 191.0
                  balance: 4532.0
                  programPaymentFrequency: Monthly
                  originalFico: 643
                  programStartDate: '2025-05-23'
                  lastNsfDate: '2025-08-23'
                  accounts:
                  - name: Example Card Co
                    accountNumber: '0000000000001234'
                    originalBalance: 6289.0
                    settledBalance: 3189.0
                  - name: Example Savings Bank
                    accountNumber: '54588301'
                    originalBalance: 2847.0
                    settledBalance: 1343.0
                  paymentsMade:
                  - date: '2025-11-17'
                    amount: 358.97
                  - date: '2025-12-17'
                    amount: 381.54
                  - date: '2026-01-17'
                    amount: 381.54
                  - date: '2026-02-17'
                    amount: 381.54
                  - date: '2026-03-17'
                    amount: 405.39
                  - date: '2026-04-17'
                    amount: 405.39
                  - date: '2026-05-17'
                    amount: 405.39
                  - date: '2026-06-17'
                    amount: 416.41
                  - date: '2026-07-17'
                    amount: 416.41
                  - date: '2026-08-17'
                    amount: 416.41
                  - date: '2026-09-17'
                    amount: 416.41
                  - date: '2026-10-17'
                    amount: 416.41
      responses:
        '200':
          description: Modified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoanResult'
              example:
                status: modified
                data:
                  loanNumber: 12002100003
                  externalId: DEBT-123456789
        4XX:
          description: Failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
  /api/v1/loan/list:
    get:
      tags:
      - Debt settlement
      summary: Get application details and status
      description: For on-demand lookups of individual applications. Do not poll this endpoint for status. Use the ApplicationStageUpdated
        webhook to receive stage changes, and keep your own record of each application's stage. Calling this for all applications
        on a schedule creates unnecessary load.
      security: *id001
      parameters:
      - *id002
      - name: loanNumber
        in: query
        schema:
          type: string
      - name: externalId
        in: query
        schema:
          type: string
      responses:
        '200':
          description: List of applications for your API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Application'
  /api/webhook/register:
    post:
      tags:
      - Webhooks
      summary: Register a webhook
      security: *id001
      parameters:
      - *id002
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookRegister'
      responses:
        '200':
          description: Registered
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
              example:
                status: ok
                data:
                  id: 12
    get:
      tags:
      - Webhooks
      summary: View registered webhooks
      security: *id001
      parameters:
      - *id002
      responses:
        '200':
          description: Registered webhooks
          content:
            application/json:
              example:
                status: ok
                data:
                - id: 12
                  event: ApplicationStageUpdated
                  callbackUrl: https://www.myportal.com/api/application-updates
    delete:
      tags:
      - Webhooks
      summary: Un-register a webhook
      security: *id001
      parameters:
      - *id002
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
              required:
              - id
            example:
              id: 12
      responses:
        '200':
          description: Removed
          content:
            application/json:
              example:
                status: ok
webhooks:
  ApplicationStageUpdated:
    post:
      summary: Sent to your callbackUrl when an application's stage changes
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StageWebhook'
      responses:
        '200':
          description: Return any 2xx to acknowledge.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    TokenRequest:
      type: object
      properties:
        client_id:
          type: string
        client_secret:
          type: string
        grant_type:
          type: string
          enum:
          - client_credentials
      required:
      - client_id
      - client_secret
      - grant_type
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
        refresh_token:
          type: string
          description: 'Returned for completeness. You do not need it: when the access token is about to expire, request a
            new one with your client ID and secret.'
        expires_in:
          type: integer
          example: 3600
        token_type:
          type: string
          example: Bearer
    DebtSettlementRequest:
      type: object
      properties:
        loan:
          type: object
          properties:
            externalId:
              type: string
              description: Your own unique ID for this client/application.
            type:
              type: string
              enum:
              - individual
            borrower:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  description: Cannot be changed after creation.
                firstName:
                  type: string
                middleName:
                  type: string
                lastName:
                  type: string
                suffixName:
                  type: string
                  enum:
                  - JR
                  - SR
                  - I
                  - II
                  - III
                  - IV
                  - V
                  - VI
                  - VII
                  - VIII
                  - IX
                dob:
                  type: string
                  format: date
                ssn:
                  type: string
                  pattern: ^(\d{3}-\d{2}-\d{4}|\d{9})$
                phoneDay: &id003
                  type: object
                  properties:
                    type:
                      type: string
                      enum:
                      - home
                      - mobile
                      - work
                    number:
                      type: string
                phoneEvening: *id003
                addressCurrent:
                  type: object
                  properties:
                    address:
                      type: string
                    city:
                      type: string
                    state:
                      type: string
                    zipCode:
                      type: string
                      pattern: ^\d{5}$
                  required:
                  - address
                  - city
                  - state
                  - zipCode
              required:
              - email
              - firstName
              - lastName
              - dob
              - ssn
              - addressCurrent
            customData:
              type: object
              properties:
                company:
                  type: string
                  description: Your debt settlement company name.
                gcsAccountNumber:
                  type: string
                escrowAccountBalance:
                  type: number
                  description: Current balance in the client's escrow account.
                paymentProcessing:
                  type: object
                  properties:
                    name:
                      type: string
                    accountNumber:
                      type: string
                    routingNumber:
                      type: string
                    dedicatedAccount:
                      type: string
                  required:
                  - name
                  - accountNumber
                  - routingNumber
                  description: Payment processor ACH info; loan proceeds are sent here.
                dscPaymentProcessing:
                  type: object
                  properties:
                    name:
                      type: string
                    accountNumber:
                      type: string
                    routingNumber:
                      type: string
                  required:
                  - name
                  - accountNumber
                  - routingNumber
                  description: Client's recurring ACH draft account.
              required:
              - company
              - escrowAccountBalance
              - paymentProcessing
              - dscPaymentProcessing
            settlement:
              type: object
              properties:
                fee:
                  type: number
                  description: Total remaining settlement fees.
                payment:
                  type: number
                  description: Debt settlement program payment amount.
                balance:
                  type: number
                  description: Total remaining settled balances (excludes settlement or origination fees).
                programPaymentFrequency:
                  type: string
                  enum:
                  - Monthly
                  - Bi-Weekly
                  - Semi-Monthly
                  - Weekly
                originalFico:
                  type: number
                  description: FICO score when the client entered the program.
                programStartDate:
                  type: string
                  format: date
                lastNsfDate:
                  type: string
                  format: date
                accounts:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      accountNumber:
                        type: string
                      originalBalance:
                        type: number
                        description: Send a number, not a string.
                      settledBalance:
                        type: number
                        description: Send a number, not a string.
                    required:
                    - name
                    - accountNumber
                    - originalBalance
                    - settledBalance
                paymentsMade:
                  type: array
                  description: The client's payments from the last 12 months. We ask for 12 months to cover differences in
                    draft dates. The client needs at least 6 payments in the last 6 months to be eligible. May contain more
                    than 12 records if several payments were made in one month.
                  items:
                    type: object
                    properties:
                      date:
                        type: string
                        format: date
                      amount:
                        type: number
                    required:
                    - date
                    - amount
              required:
              - fee
              - payment
              - balance
              - programPaymentFrequency
              - originalFico
              - programStartDate
              - accounts
              - paymentsMade
          required:
          - type
          - borrower
          - customData
          - settlement
      required:
      - loan
    LoanResult:
      type: object
      properties:
        status:
          type: string
          enum:
          - created
          - modified
        data:
          type: object
          properties:
            stage:
              type: string
              description: Stage of the new application. A new application starts at Incomplete.
            loanNumber:
              oneOf:
              - type: integer
              - type: string
              description: A number in the submit response. Accept a number or a string and store it as text.
            url:
              type: string
              description: 'Link to the client''s application site. You do not need to send clients to it: LoanVault emails
                them the link for their current stage.'
            externalId:
              type: string
        warnings:
          type: object
          additionalProperties:
            type: string
          description: 'May be present. Check stage first: an ineligible client comes back with stage Ineligible.'
    Failure:
      type: object
      properties:
        status:
          type: string
          enum:
          - failed
        errors:
          type: object
          additionalProperties:
            type: string
          description: Keyed by field path.
    Stage:
      type: string
      enum:
      - Incomplete
      - Ineligible
      - ReviewDocuments
      - ReviewDocumentsFailed
      - Verified
      - OFACReview
      - AlertReview
      - ManualDecision
      - 3rdPartyFailure
      - Declined
      - Referral
      - PreApproved
      - Approved
      - ReviewFunding
      - OfferAccepted
      - Completed
      - Funded
      - Sold
      - FundingFailed
      - ComplianceReview
      - ComplianceFailed
      - CompliancePassed
      - Rejected
      - Withdrawn
      - WithdrawnApplicant
      - Suspended
      - Error
      description: PreApproved is the stage at which the final PATCH may be sent.
    Offer:
      type: object
      properties:
        amount:
          type: number
        netAmount:
          type: number
        term:
          type: integer
          description: Months.
        periodicPayment:
          type: number
        interestRate:
          type: number
        apr:
          type: number
        totalPayments:
          type: number
        originationFee:
          type: number
        otherFees:
          type: number
        dti:
          type: number
        amortization:
          type: integer
        paymentsPerYear:
          type: integer
        prepaidCharges:
          type: number
        financeCharges:
          type: number
        directAmount:
          type: number
        payoffAmount:
          type: number
    Offers:
      description: Empty array when there are no offers (until offers are generated, including applications declined or ineligible
        before pre-approval). Once offers are generated they stay in the payload for later stages, including Declined, Withdrawn
        and WithdrawnApplicant. It can still be an empty array at PreApproved if offers could not be generated (for example,
        no credit report was found). Otherwise, at PreApproved, an object with list (up to five offers, one per term). From
        OfferAccepted on, selected holds the offer the client chose (with extra fields such as amortization, financeCharges
        and payoffAmount) and list still holds all offers.
      oneOf:
      - type: array
        maxItems: 0
      - type: object
        properties:
          list:
            type: array
            items:
              $ref: '#/components/schemas/Offer'
          selected:
            $ref: '#/components/schemas/Offer'
    Application:
      type: object
      description: Full loan application object (also delivered as data in webhooks).
      properties:
        loanNumber:
          oneOf:
          - type: string
          - type: integer
          description: A number in webhook payloads, a string in some other responses. Accept either and store as text.
        externalId:
          type: string
        productType:
          type: string
          example: debt_settlement
        stage:
          $ref: '#/components/schemas/Stage'
        type:
          type: string
        state:
          type: string
        language:
          type: string
        purpose:
          type: string
        amount:
          type: number
        term:
          type: integer
        flags:
          type: array
          items:
            type: string
        created:
          type: string
          format: date-time
        offers:
          $ref: '#/components/schemas/Offers'
        customData:
          type: object
          additionalProperties: true
          description: 'Settlement details returned with the application: accounts, paymentsMade, originalFico, programStartDate,
            lastNsfDate, company, paymentProcessing, escrowAccountBalance, gcsAccountNumber (nullable), totalCreditors, initialAmount,
            maximumRequestedAmount.'
      additionalProperties: true
    WebhookRegister:
      type: object
      properties:
        event:
          type: string
          enum:
          - ApplicationStageUpdated
        callbackUrl:
          type: string
          format: uri
      required:
      - event
      - callbackUrl
    StageWebhook:
      type: object
      properties:
        event:
          type: string
          enum:
          - ApplicationStageUpdated
        source:
          type: string
        data:
          $ref: '#/components/schemas/Application'