Skip to main content
Tasks are assignments that require action during the loan origination process. There are two types of tasks: borrower tasks (assigned to borrowers) and loan officer tasks (assigned to loan officers). Tasks guide users through exactly what’s needed for underwriting and loan processing.

​
Types of tasks

​
Borrower tasks

Borrower tasks are assignments that require borrowers to:
  • Upload documents (pay stubs, bank statements, tax returns, etc.)
  • Review and sign disclosures
  • Provide additional information or clarification

​
Loan officer tasks

Loan officer tasks are assignments that require loan officers to:
  • Upload documents on behalf of borrowers
  • Review and verify documents
  • Complete underwriting conditions
  • Handle disclosure-related tasks
Tasks are automatically created as the loan progresses through processing and underwriting. Each task includes:
  • Task type (document upload, disclosure review, etc.)
  • Status (not started, in progress, completed)
  • Description of what’s needed
  • Due date (if applicable)
  • Document links (for uploaded documents)

​
Retrieving tasks

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

​
Task types

Task TypeDescriptionAction Required
DOCUMENT_REQUIREDBorrower or loan officer must upload a documentUpload document via REST endpoint
DISCLOSURE_REVIEWBorrower must review and sign disclosuresDirect borrower to disclosure signing link

​
Commonly utilized documents

The following is a list of commonly utilized documents that may be requested as borrower tasks during the loan origination process. These documents are typically required to clarify discrepancies, verify information, or satisfy underwriting conditions.

​
How to use these document specifications

Each document page provides detailed specifications including required data fields, suggested questions, and validation rules. You have three options for handling these documents:
  1. Build your own forms - Use the required data fields and suggested questions from each document page to build custom forms that collect the necessary information
  2. Validate existing forms - Use the required data fields and validation rules to verify that your existing forms include all necessary fields and meet validation requirements
  3. Use pre-made templates - Use Pylon’s pre-made templates out of the box (templates will be provided separately)
Each document page includes:
  • Required data fields - All fields that must be collected, organized by section
  • Suggested questions - Questions you can use to collect each piece of data
  • Data validation rules - Rules to ensure data quality and completeness
  • Integration notes - Technical details for implementation

​
Commonly requested documents

DocumentDescription
Access LetterObtain acknowledgement from joint account co-owners granting permission for borrowers to utilize funds
Gift LetterValidate gift funds used for down payment or closing costs, including donor information and source of funds
Letter of Explanation - Address DiscrepancyResolve address inconsistencies between credit reports, applications, and other documentation
Letter of Explanation - Credit InquiryExplain credit inquiries to confirm no new undisclosed debt was incurred
Letter of Explanation - Employment GapExplain employment gaps to provide context and ensure stable income source
Letter of Explanation - Large DepositExplain large deposits that are unusual relative to the borrower’s income or significantly increase asset balance
Letter of Explanation - Recurring WithdrawalExplain recurring withdrawals to confirm they don’t represent undisclosed liabilities
Third-Party Validation - Rent-Free Living ArrangementVerify rent-free living arrangements when borrowers report no housing expenses
Verification of Rent or Mortgage (VOR/VOM)Verify rental or mortgage payment history and account status from landlord or creditor
Vesting InstructionsAscertain the borrower’s preferred method of taking title to the property

​
Uploading documents for borrower tasks

Borrower task documents are uploaded via a REST endpoint (not GraphQL): Endpoint: POST /api/loan-applications/{loanId}/borrower-tasks/{taskId}/documents Headers: 
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: multipart/form-data
Form field name: borrower-task-files Example: 
async function uploadBorrowerTaskDocument(loanId, taskId, files) {
  const formData = new FormData();
  files.forEach((file) => {
    formData.append("borrower-task-files", file);
  });

  const response = await fetch(
    `https://pylon.mortgage/api/loan-applications/${loanId}/borrower-tasks/${taskId}/documents`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${accessToken}`,
      },
      body: formData,
    }
  );

  if (!response.ok) {
    throw new Error(`Upload failed: ${response.statusText}`);
  }

  return response.json();
}

​
Uploading documents for loan officer tasks

Loan officer tasks may also require document uploads. The upload process is similar, but the endpoint and form field name may differ. Check the task’s documentUploadPath field for the specific upload endpoint.

​
Task status

After uploading a document, the task status updates automatically. Poll the tasks query to verify the upload was successful:
  • NOT_STARTED - Task has been created but no action taken
  • IN_PROGRESS - Document upload in progress
  • COMPLETED - Task is complete (document uploaded and verified)
  • CANCELLED - Task was cancelled

​
Polling for new tasks

Tasks are created automatically as the loan progresses. Poll tasks every 15-30 minutes to detect new tasks: 
async function pollForNewTasks(loanId, previousTaskIds) {
  const query = `
    query GetTasks($loanId: ID!) {
      loan(id: $loanId) {
        borrowers(first: 10) {
          edges {
            node {
              borrowerTasks {
                id
                title
                status
                type
              }
            }
          }
        }
        loanOfficerDocumentTasks {
          id
          title
          status
          type
        }
      }
    }
  `;

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

  const { data } = await response.json();
  const borrowerTasks = data.loan.borrowers.edges.flatMap(
    (edge) => edge.node.borrowerTasks
  );
  const allTasks = [...borrowerTasks, ...data.loan.loanOfficerDocumentTasks];
  const currentTaskIds = new Set(allTasks.map((t) => t.id));
  const newTasks = allTasks.filter((task) => !previousTaskIds.has(task.id));

  return { newTasks, currentTaskIds };
}

​
Task details

Each task includes a details field that provides context about the entity the task is associated with:
  • borrowerId - The borrower this task is for (if applicable)
  • borrowerName - Display name of the borrower
  • entityKind - The type of entity (e.g., “BORROWER”, “LOAN”)
  • entityDisplayName - Human-readable name of the entity

​
Best practices

  1. Poll regularly - Check for new tasks every 15-30 minutes
  2. Notify users - Alert borrowers and loan officers when new tasks are assigned
  3. Track completion - Monitor task status to ensure all required documents are uploaded
  4. Handle errors - Implement retry logic for failed uploads
  5. Validate files - Check file types and sizes before uploading
  6. Monitor both types - Track both borrower tasks and loan officer tasks to ensure nothing is missed