Tracking loan updates

To monitor loan changes, you’ll need to poll the GraphQL API at a cadence appropriate for your use case.

Quick reference

Example entities	Recommended interval	Detection method
Loan stage	15-30 min	Compare `currentStage`
Tasks	15-30 min	Track task IDs and `status`
Documents	30-60 min	Track `uploadedAt` timestamps
Borrower info	Daily	Compare field values
Credit pull (active)	30 sec - 2 min	Poll until `status` is complete

How it works

Write a focused query

Request only the fields you need. Don’t fetch the entire loan when you only need the stage.

Store the previous state

Cache the values you’re monitoring (e.g., currentStage, task IDs).

Poll at your chosen interval

Fetch the data and compare against your cached state.

Emit events on change

When a difference is detected, trigger your business logic.

Implementation example

This TypeScript example polls for loan stage changes every 30 minutes and emits an event when a stage changes.

Quick Start
GraphQL Query
Full Implementation

const poller = new LoanStagePoller({
  apiEndpoint: "https://api.pylon.mortgage/graphql",
  accessToken: "your-access-token",
  loanIds: ["loan-id-1", "loan-id-2"],
  pollingIntervalMs: 30 * 60 * 1000, // 30 minutes
});

poller.on("stageChange", (event) => {
  console.log(`Loan ${event.friendlyId}: ${event.previousStage} → ${event.currentStage}`);
  // Update your database, notify users, trigger workflows, etc.
});

poller.on("error", ({ loanId, error }) => {
  console.error(`Error polling loan ${loanId}:`, error);
});

poller.start();

query GetLoanStage($id: ID!) {
  loan(id: $id) {
    id
    friendlyId
    currentStage
    stages {
      name
      timestamp
    }
  }
}

import { EventEmitter } from "events";

// ─────────────────────────────────────────────────────────────
// Types
// ─────────────────────────────────────────────────────────────

interface LoanStage {
  name: string;
  timestamp: string;
}

interface LoanStageResponse {
  data: {
    loan: {
      id: string;
      friendlyId: string;
      currentStage: string;
      stages: LoanStage[];
    } | null;
  };
}

interface StageChangeEvent {
  loanId: string;
  friendlyId: string;
  previousStage: string;
  currentStage: string;
  timestamp: string;
}

interface PollerConfig {
  apiEndpoint: string;
  accessToken: string;
  loanIds: string[];
  pollingIntervalMs?: number;
}

// ─────────────────────────────────────────────────────────────
// Query
// ─────────────────────────────────────────────────────────────

const LOAN_STAGE_QUERY = `
  query GetLoanStage($id: ID!) {
    loan(id: $id) {
      id
      friendlyId
      currentStage
      stages {
        name
        timestamp
      }
    }
  }
`;

// ─────────────────────────────────────────────────────────────
// Poller Class
// ─────────────────────────────────────────────────────────────

class LoanStagePoller extends EventEmitter {
  private apiEndpoint: string;
  private accessToken: string;
  private loanIds: string[];
  private pollingIntervalMs: number;
  private previousStages = new Map<string, string>();
  private intervalId: NodeJS.Timeout | null = null;

  constructor(config: PollerConfig) {
    super();
    this.apiEndpoint = config.apiEndpoint;
    this.accessToken = config.accessToken;
    this.loanIds = config.loanIds;
    this.pollingIntervalMs = config.pollingIntervalMs ?? 30 * 60 * 1000;
  }

  async start(): Promise<void> {
    await this.poll();
    this.intervalId = setInterval(() => this.poll(), this.pollingIntervalMs);
    this.emit("started", { loanIds: this.loanIds, intervalMs: this.pollingIntervalMs });
  }

  stop(): void {
    if (this.intervalId) {
      clearInterval(this.intervalId);
      this.intervalId = null;
      this.emit("stopped");
    }
  }

  addLoan(loanId: string): void {
    if (!this.loanIds.includes(loanId)) this.loanIds.push(loanId);
  }

  removeLoan(loanId: string): void {
    this.loanIds = this.loanIds.filter((id) => id !== loanId);
    this.previousStages.delete(loanId);
  }

  private async poll(): Promise<void> {
    for (const loanId of this.loanIds) {
      try {
        const loan = await this.fetchLoan(loanId);
        if (!loan) {
          this.emit("error", { loanId, error: new Error("Loan not found") });
          continue;
        }

        const previous = this.previousStages.get(loanId);
        const current = loan.currentStage;

        if (previous !== undefined && previous !== current) {
          const latest = loan.stages[loan.stages.length - 1];
          this.emit("stageChange", {
            loanId: loan.id,
            friendlyId: loan.friendlyId,
            previousStage: previous,
            currentStage: current,
            timestamp: latest?.timestamp ?? new Date().toISOString(),
          } as StageChangeEvent);
        }

        this.previousStages.set(loanId, current);
      } catch (error) {
        this.emit("error", { loanId, error });
      }
    }
  }

  private async fetchLoan(loanId: string): Promise<LoanStageResponse["data"]["loan"]> {
    const res = await fetch(this.apiEndpoint, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${this.accessToken}`,
      },
      body: JSON.stringify({ query: LOAN_STAGE_QUERY, variables: { id: loanId } }),
    });

    if (!res.ok) throw new Error(`API error: ${res.status}`);
    const json: LoanStageResponse = await res.json();
    return json.data.loan;
  }
}

export { LoanStagePoller, StageChangeEvent, PollerConfig };

Starter queries

Use these comprehensive queries as starting points. Trim them down to only the fields you need for your specific polling use case.

Full loan

Full loan data including stages, pricing, rate lock, and associated entities.

query GetLoan($id: ID!) {
  loan(id: $id) {
    id
    friendlyId
    loanNumber
    loanPurpose
    loanTermYears
    noteRatePercent
    maxLoanAmount
    maxPurchasePrice
    purchasePrice
    ltv
    outOfPocketMax
    totalAssetsAvailable
    earnestMoneyDeposit
    sellerCredit
    refinanceCashOutProceeds
    closingDate
    latestPreApprovalRunTime
    currentStage
    dealId
    isClosed
    isFrozen
    isFirstTimeHomebuyer
    pylonApproved
    useOwnTitleCompany
    allowedStates

    assignedLoanOfficer {
      id
      email
      firstName
      lastName
    }
    borrowerPreferences {
      closingCosts
      downPaymentAmount
      monthlyPayment
      rate
    }
    borrowers(first: 5) {
      edges {
        node {
          id
          dependentAges
          emailVerified
          externalUserId
          isFirstTimeHomeBuyer
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
    changeRequests {
      id
      status
    }
    concessions {
      id
      amount
      approvedAt
      reason
    }
    contacts {
      id
      email
      companyName
      firstName
    }
    documents {
      id
      name
      category
      uploadedAt
    }
    fees {
      id
      feeActualTotalAmount
      feeDescription
    }
    preapprovalProduct {
      id
      type
      description
    }
    productPricingRate {
      id
      apr
      closingCosts
    }
    productStructure {
      id
      apr
      closingCosts
    }
    rateLock {
      status
      expirationTime
      lockedTime
      period
    }
    stages {
      name
      timestamp
    }
    subjectProperty {
      id
      avmEstimatedValue
      hoaDues
      homeInsuranceMonthlyAmount
      subjectPropertyIntent {
        id
        neighborhoodHousingType
      }
    }
  }
}

Borrower personal information

Identity and contact details.

query GetBorrowerPersonalInfo($id: ID!) {
  borrower(id: $id) {
    id
    dependentAges
    personalInformation {
      firstName
      middleName
      lastName
      email
      dateOfBirth
      citizenshipResidencyType
      taxIdentifierNumber
      taxIdentifierNumberType
      phoneNumbers {
        id
        number
        type
      }
      currentAddress {
        id
        address {
          line
          line2
          city
          state
          zipCode
        }
      }
    }
    mailingAddress {
      line
      line2
      city
      state
      zipCode
    }
  }
}

Borrower financials (assets, income, properties)

Complete financial profile for underwriting.

query GetBorrowerFinancials($id: ID!) {
  borrower(id: $id) {
    assets {
      id
      amount
      borrowerIds
      ... on CheckingAccountAsset {
        accountIdentifier
        institutionName
      }
      ... on SavingsAccountAsset {
        accountIdentifier
        institutionName
      }
      ... on RetirementFundAsset {
        accountIdentifier
        institutionName
      }
      ... on GiftAsset {
        source
        donorName
        dateOfTransfer
      }
    }
    incomes(first: 25) {
      edges {
        node {
          id
          statedMonthlyAmount
          ... on StandardEmploymentIncome {
            employment {
              position
              startDate
              isCurrentEmployment
              ... on StandardEmployment {
                employer {
                  name
                }
              }
            }
          }
          ... on SelfEmploymentIncome {
            employment {
              position
              ... on SelfEmployment {
                business {
                  name
                }
              }
            }
          }
        }
      }
      pageInfo {
        hasNextPage
      }
    }
    ownedProperties(first: 25) {
      edges {
        node {
          id
          address {
            line
            city
            state
            zipCode
          }
          intendedDisposition
          currentUsageType
          rentalIncome {
            statedMonthlyAmount
          }
          liabilities {
            id
            balance
          }
        }
      }
      pageInfo {
        hasNextPage
      }
    }
  }
}

Borrower liabilities

Debts and obligations for DTI calculation.

query GetBorrowerLiabilities($id: ID!, $after: String) {
  borrower(id: $id) {
    liabilities(first: 25, after: $after) {
      edges {
        node {
          id
          accountIdentifier
          balance
          creditorName
          type
          monthlyPayment
          intent
          exclusionReason
        }
      }
      pageInfo {
        endCursor
        hasNextPage
      }
    }
  }
}

Tasks

Borrower and loan officer tasks for workflow management.

query GetTasks($loanId: ID!) {
  loan(id: $loanId) {
    id
    borrowers(first: 10) {
      edges {
        node {
          id
          personalInformation {
            firstName
            lastName
          }
          tasks: borrowerTasks {
            id
            title
            status
            type
            priority
            dueDate
            completedAt
            createdOn
            borrowerFacingDescription
            documentLinks {
              id
              title
              url
            }
            details {
              borrowerId
              borrowerName
              entityKind
            }
          }
        }
      }
    }
    loanOfficerTasks: loanOfficerDocumentTasks {
      id
      title
      status
      type
      priority
      dueDate
      completedAt
      createdOn
      description
      documentLinks {
        id
        title
        url
      }
      details {
        borrowerId
        borrowerName
        entityKind
      }
    }
  }
}

Best practices

Use focused queries

Don’t fetch the entire loan object when you only need currentStage. Smaller queries are faster, reduce bandwidth, and make change detection simpler.

Implement exponential backoff

If requests fail, wait progressively longer before retrying. This prevents overwhelming the API during outages and gives transient issues time to resolve.

const backoff = (attempt: number) => Math.min(1000 * 2 ** attempt, 30000);

// Attempt 1: 2 seconds
// Attempt 2: 4 seconds
// Attempt 3: 8 seconds
// ...capped at 30 seconds

Store state efficiently

Only cache what you need for comparison. For stage monitoring, store a Map<loanId, stage> rather than full loan objects. This keeps memory usage low and simplifies the comparison logic.

Stagger requests for many loans

If monitoring hundreds of loans, don’t fire all requests simultaneously. Spread them over the polling interval to avoid rate limits and reduce peak load.

Use pagination cursors for lists

For lists like tasks or documents, track cursors to efficiently detect new items rather than comparing entire arrays. Store the last cursor and fetch only items after it.

// Store the cursor from your last successful poll
let lastCursor: string | null = null;

// On next poll, fetch only new items
const query = `
  query GetTasks($loanId: ID!, $after: String) {
    loan(id: $loanId) {
      borrowers(first: 10) {
        edges {
          node {
            tasks: borrowerTasks(after: $after) {
              id
              status
            }
          }
        }
        pageInfo { endCursor }
      }
    }
  }
`;

Log polling activity

Keep logs of your polling activity for debugging. Include timestamps, loan IDs, and any detected changes. This helps diagnose issues when changes aren’t being detected as expected.

console.log(
  JSON.stringify({
    timestamp: new Date().toISOString(),
    loanId,
    previousStage,
    currentStage,
    changed: previousStage !== currentStage,
  })
);

Rate limiting

Polling too aggressively can result in rate limiting. Start with conservative intervals and adjust based on your needs.

If you’re monitoring many loans:

Stagger requests rather than firing them simultaneously
Use longer intervals for less time-sensitive data
Implement circuit breakers to pause polling if you hit rate limits
Log all poll activity for debugging

GET STARTED

EXAMPLES

ELEMENTS

CORE ENTITIES

Quick reference

How it works

Implementation example

Starter queries

Best practices

Use focused queries

Implement exponential backoff

Store state efficiently

Stagger requests for many loans

Log polling activity

Rate limiting

GET STARTED

EXAMPLES

ELEMENTS

CORE ENTITIES

​Quick reference

​How it works

​Implementation example

​Starter queries

​Best practices

​Use focused queries

​Implement exponential backoff

​Store state efficiently

​Stagger requests for many loans

​Use pagination cursors for lists

​Log polling activity

​Rate limiting

Quick reference

How it works

Implementation example

Starter queries

Best practices

Use focused queries

Implement exponential backoff

Store state efficiently

Stagger requests for many loans

Use pagination cursors for lists

Log polling activity

Rate limiting