Prequalification

The prequalification endpoint is a powerful affordability calculator that goes far beyond traditional mortgage calculators. Unlike other affordability tools that are blind to pricing and guidelines, Pylon’s prequalification endpoint validates against all guidelines and pricing across all takeouts to determine maximum affordability within eligible products.

Why use prequalification?

All products at once

Returns maximum affordability across all products in a single call, rather than requiring separate calculations per product.

Guideline-aware

Validates against all encoded guidelines and pricing rules, ensuring accurate qualification estimates.

Minimal input

Requires only 8 pieces of information to get comprehensive affordability results.

Real-time pricing

Uses live rates and guidelines at the time of calculation, not static assumptions.

How it works

Prequalification is an asynchronous operation. When you create a prequalification request, it returns a job ID that you must poll to get the results.

Create prequalification

Submit a mutation with borrower information to create a prequalification job.

Receive job ID

The mutation returns a job ID that you’ll use to poll for results.

Poll for completion

Poll the prequalification query endpoint until the job status indicates completion.

Retrieve results

Once complete, fetch the results showing maximum affordability across all eligible products.

Creating a prequalification

To create a prequalification, you need 8 pieces of information:

mutation {
  preQualification {
    conventional(
      input: {
        monthlyIncome: 10000
        monthlyDebt: 2000
        qualifyingFicoScore: 750
        fipsCountyCode: "06037"
        propertyUsageType: PRIMARY_RESIDENCE
        neighborhoodHousingType: SINGLE_FAMILY
        isFirstTimeHomeBuyer: true
        isBorrowerSelfEmployed: false
      }
    ) {
      id
    }
  }
}

Required input fields

Field	Type	Description
`monthlyIncome`	`Float!`	Borrower’s total monthly income
`monthlyDebt`	`Float!`	Borrower’s total monthly debt payments
`fipsCountyCode`	`String!`	Five-digit FIPS county code for the property location
`propertyUsageType`	`PropertyUsageType!`	`PRIMARY_RESIDENCE`, `SECOND_HOME`, or `INVESTMENT`
`neighborhoodHousingType`	`NeighborhoodHousingType!`	Property type (e.g., `SINGLE_FAMILY`, `CONDOMINIUM`)
`isFirstTimeHomeBuyer`	`Boolean!`	Whether the borrower is a first-time homebuyer
`isBorrowerSelfEmployed`	`Boolean!`	Whether the borrower is self-employed

Optional input fields

Field	Type	Description
`qualifyingFicoScore`	`Int`	FICO score for qualification (if not provided, results may vary by score range)

Response

The mutation returns a job ID:

{
  "data": {
    "preQualification": {
      "conventional": {
        "id": "prequal_abc123xyz"
      }
    }
  }
}

Save the id from the response. You’ll use it to poll for results.

Polling for results

After creating a prequalification, poll the query endpoint to check the job status and retrieve results:

query {
  preQualification {
    conventional(id: "prequal_abc123xyz") {
      id
      status
      result {
        maxLoanAmount
        maxPurchasePrice
        maxMonthlyPayment
        products {
          product {
            name
            type
          }
          maxLoanAmount
          maxPurchasePrice
          maxMonthlyPayment
        }
      }
      error {
        message
        code
      }
    }
  }
}

Job status

The status field indicates the current state of the prequalification:

Status	Description	Action
`PENDING`	Job is queued and processing	Continue polling
`COMPLETED`	Calculation finished successfully	Read `result` field
`FAILED`	Calculation encountered an error	Read `error` field
`CANCELLED`	Job was cancelled	No results available

Polling strategy

Implement exponential backoff when polling to avoid excessive API calls:

async function pollPrequalification(
  id: string,
  maxAttempts: number = 30,
  initialDelayMs: number = 2000
): Promise<PrequalificationResult> {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const response = await fetchPrequalification(id);

    if (response.status === "COMPLETED") {
      return response.result;
    }

    if (response.status === "FAILED") {
      throw new Error(response.error?.message || "Prequalification failed");
    }

    // Exponential backoff: 2s, 4s, 8s, 16s, max 30s
    const delay = Math.min(initialDelayMs * Math.pow(2, attempt), 30000);

    await new Promise((resolve) => setTimeout(resolve, delay));
  }

  throw new Error("Prequalification polling timeout");
}

Polling intervals: Start with 2-5 second intervals and increase gradually. Most prequalifications complete within 10-30 seconds, but complex scenarios may take longer.

Understanding results

When the prequalification completes, the result field contains maximum affordability information:

{
  "data": {
    "preQualification": {
      "conventional": {
        "id": "prequal_abc123xyz",
        "status": "COMPLETED",
        "result": {
          "maxLoanAmount": 450000,
          "maxPurchasePrice": 562500,
          "maxMonthlyPayment": 3500,
          "products": [
            {
              "product": {
                "name": "Conventional 30-Year Fixed",
                "type": "CONVENTIONAL"
              },
              "maxLoanAmount": 450000,
              "maxPurchasePrice": 562500,
              "maxMonthlyPayment": 3500
            },
            {
              "product": {
                "name": "FHA 30-Year Fixed",
                "type": "FHA"
              },
              "maxLoanAmount": 420000,
              "maxPurchasePrice": 466667,
              "maxMonthlyPayment": 3200
            }
          ]
        }
      }
    }
  }
}

Result fields

Field	Description
`maxLoanAmount`	Maximum loan amount across all eligible products
`maxPurchasePrice`	Maximum purchase price (loan amount + down payment)
`maxMonthlyPayment`	Maximum monthly payment the borrower can afford
`products`	Array of results per product, showing maximums for each eligible product

The top-level maxLoanAmount, maxPurchasePrice, and maxMonthlyPayment represent the highest values across all products. Use the products array to show borrowers product-specific maximums.

Complete example

Here’s a complete TypeScript example that creates a prequalification and polls for results:

interface PrequalificationInput {
  monthlyIncome: number;
  monthlyDebt: number;
  qualifyingFicoScore?: number;
  fipsCountyCode: string;
  propertyUsageType: "PRIMARY_RESIDENCE" | "SECOND_HOME" | "INVESTMENT";
  neighborhoodHousingType: string;
  isFirstTimeHomeBuyer: boolean;
  isBorrowerSelfEmployed: boolean;
}

async function runPrequalification(
  input: PrequalificationInput,
  accessToken: string
): Promise<PrequalificationResult> {
  // Step 1: Create prequalification
  const createMutation = `
    mutation CreatePrequalification($input: ConventionalPreQualificationInput!) {
      preQualification {
        conventional(input: $input) {
          id
        }
      }
    }
  `;

  const createResponse = await fetch("https://pylon.mortgage/graphql", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${accessToken}`,
    },
    body: JSON.stringify({
      query: createMutation,
      variables: { input },
    }),
  });

  const { data: createData } = await createResponse.json();
  const prequalId = createData.preQualification.conventional.id;

  // Step 2: Poll for results
  const query = `
    query GetPrequalification($id: ID!) {
      preQualification {
        conventional(id: $id) {
          id
          status
          result {
            maxLoanAmount
            maxPurchasePrice
            maxMonthlyPayment
            products {
              product {
                name
                type
              }
              maxLoanAmount
              maxPurchasePrice
              maxMonthlyPayment
            }
          }
          error {
            message
            code
          }
        }
      }
    }
  `;

  // Poll with exponential backoff
  for (let attempt = 0; attempt < 30; attempt++) {
    const pollResponse = await fetch("https://pylon.mortgage/graphql", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${accessToken}`,
      },
      body: JSON.stringify({
        query,
        variables: { id: prequalId },
      }),
    });

    const { data: pollData } = await pollResponse.json();
    const prequal = pollData.preQualification.conventional;

    if (prequal.status === "COMPLETED") {
      return prequal.result;
    }

    if (prequal.status === "FAILED") {
      throw new Error(prequal.error?.message || "Prequalification failed");
    }

    // Wait before next poll (exponential backoff)
    const delay = Math.min(2000 * Math.pow(2, attempt), 30000);
    await new Promise((resolve) => setTimeout(resolve, delay));
  }

  throw new Error("Prequalification polling timeout");
}

Best practices

Handle errors gracefully: Check the error field when status is FAILED and provide meaningful messages to borrowers.
Set reasonable timeouts: Most prequalifications complete within 30 seconds, but set a maximum timeout (e.g., 2-3 minutes) to avoid indefinite polling.
Cache results: Prequalification results are valid for a period of time. Consider caching results with the input parameters as a key to avoid redundant calculations.
Show product breakdown: Display results per product so borrowers can see which products offer the highest affordability.
Explain limitations: Help borrowers understand that prequalification is an estimate and actual qualification may vary based on complete application details.
Use for lead qualification: Prequalification is perfect for initial borrower conversations to quickly assess affordability before creating a full loan application.

Error handling

Common error scenarios and how to handle them:

Error Code	Description	Resolution
`INVALID_INPUT`	One or more input fields are invalid	Validate inputs before submission
`GUIDELINE_VIOLATION`	Borrower doesn’t meet minimum guidelines	Explain qualification requirements to borrower
`RATE_UNAVAILABLE`	No rates available for the given parameters	Try adjusting inputs or explain market conditions
`TIMEOUT`	Calculation took too long	Retry the prequalification request

Pricing scenarios - Show detailed pricing options for specific loan amounts
Tracking loan updates - Learn how to poll for asynchronous job status
Marketing rates - Display competitive rates on your website

GET STARTED

EXAMPLES

ELEMENTS

CORE ENTITIES

Why use prequalification?

All products at once

Guideline-aware

Minimal input

Real-time pricing

How it works

Creating a prequalification

Required input fields

Optional input fields

Response

Polling for results

Job status

Polling strategy

Understanding results

Result fields

Complete example

Best practices

Error handling

GET STARTED

EXAMPLES

ELEMENTS

CORE ENTITIES

Documentation Index

​Why use prequalification?

All products at once

Guideline-aware

Minimal input

Real-time pricing

​How it works

​Creating a prequalification

​Required input fields

​Optional input fields

​Response

​Polling for results

​Job status

​Polling strategy

​Understanding results

​Result fields

​Complete example

​Best practices

​Error handling

​Related resources

Why use prequalification?

How it works

Creating a prequalification

Required input fields

Optional input fields

Response

Polling for results

Job status

Polling strategy

Understanding results

Result fields

Complete example

Best practices

Error handling

Related resources