Importing a MISMO file (Beta)

• Bringing in a loan from another system, such as a 1003 export from another loan origination system or an AUS submission file.
• Starting a re-application from an existing Pylon loan. Export the existing loan as a MISMO file, then import that file as a new loan. See Re-applying from an existing loan.

​

At a glance

​

Environments

// Point this at sandbox while developing, production when you go live.
const BASE_URL = "https://sandbox.pylon.mortgage";

​

Before you import: borrower consent

​

Making the request

curl -X POST "https://sandbox.pylon.mortgage/api/mismo-import" \
  -H "Authorization: Bearer $PYLON_ACCESS_TOKEN" \
  -F "mismo-file=@./loan-export.xml;type=application/xml"

import { openAsBlob } from "node:fs";

async function importMismoFile(path) {
  const formData = new FormData();
  formData.append(
    "mismo-file",
    await openAsBlob(path, { type: "application/xml" }),
    "loan-export.xml"
  );

  const response = await fetch(`${BASE_URL}/api/mismo-import`, {
    method: "POST",
    headers: { Authorization: `Bearer ${accessToken}` },
    body: formData,
    signal: AbortSignal.timeout(120_000),
  });

  // Error responses from a proxy or gateway may not be JSON
  const body = await response.json().catch(() => ({}));
  if (!response.ok) {
    throw new MismoImportError(response, body);
  }
  return body; // { loan_id, import_id, missing_fields }
}

class MismoImportError extends Error {
  constructor(response, body) {
    super(body.error ?? `MISMO import failed with HTTP ${response.status}`);
    this.status = response.status;
    this.code = body.code; // not present on every error, see "Errors"
    this.errorId = body.error_id;
    this.retryAfter = response.headers.get("Retry-After");
  }
}

import requests

def import_mismo_file(path: str) -> dict:
    with open(path, "rb") as f:
        response = requests.post(
            f"{BASE_URL}/api/mismo-import",
            headers={"Authorization": f"Bearer {access_token}"},
            files={"mismo-file": ("loan-export.xml", f, "application/xml")},
            timeout=120,
        )
    try:
        body = response.json()
    except ValueError:
        body = {}
    if not response.ok:
        raise RuntimeError(
            f"{response.status_code} {body.get('code')}: {body.get('error')}"
        )
    return body  # {"loan_id": ..., "import_id": ..., "missing_fields": [...]}

​

What the file must contain

• The root element is MESSAGE. A namespace prefix on it is fine. Any other root element is rejected as MISMO_UPLOAD_PARSE_FAILURE.
• A supported version. MISMO 3.4 and MISMO 3.6 are supported. The version is read from the MISMOReferenceModelIdentifier attribute on MESSAGE, or from MISMOLogicalDataDictionaryIdentifier when the first is absent. Identifiers such as 3.4.032420160128 or 3.6.0 are accepted. A file that declares another version, such as 3.5.021220160120, is rejected as MISMO_UPLOAD_UNSUPPORTED_VERSION. A file that declares no version, or a version identifier that isn’t in the usual major.minor form, is read as MISMO 3.4.
• A deal. The file needs a DEAL under DEAL_SETS/DEAL_SET/DEALS. Only the first deal in the file is imported. Any further deals are ignored without being reported, so send one deal per file.
• One subject loan. Inside the deal’s LOANS, the loan with LoanRoleType set to SubjectLoan is imported. If no loan carries that role, the first LOAN is used. A deal with more than one SubjectLoan is rejected, because the import can’t tell which loan you meant.
• UTF-8 encoding. The file is always read as UTF-8. A file saved in another encoding, such as Windows-1252, usually still imports, but accented or special characters in names and addresses turn into replacement characters (�). Convert the file to UTF-8 before you upload it.
• No complex DOCTYPE. A plain <!DOCTYPE MESSAGE> declaration is fine. A DOCTYPE with an external identifier or an internal subset is rejected, and so is extremely deep element nesting (413, MISMO_UPLOAD_EXCESSIVE_NESTING). Real MISMO exports don’t use either.
• 50 MB or smaller (52,428,800 bytes). Larger files are rejected with HTTP 413.

​

What gets imported

• Owned real estate arrives with no mortgage attached. Liabilities aren’t imported, so every owned property looks owned free and clear until you link its mortgage. When the file shows a lien on an owned property, the import report flags it as CRITICAL. After you pull credit, link each mortgage to its property with the attachOwnedPropertyLiability mutation. See Property-associated liabilities.
• Self-reported debts are not carried over. Debts a credit bureau may not report, such as an HOA lien, garnishments, delinquent taxes or a private personal loan, must be added by hand. Otherwise DTI is understated. See Managing self-reported liabilities.
• Addresses without a residency basis are left out. An address in a borrower’s history that doesn’t state whether the borrower owned, rented or lived rent-free is not imported, and it is listed in the report. Add it back on the borrower.
• Records that can’t be attached are skipped. For example, an asset or a rental income that isn’t linked to any borrower, a non-borrowing owner with no name, or a party in a role Pylon doesn’t track. Each one is listed in the report.
• A few MISMO 3.6 values can’t be imported yet. Each one is listed in the report with the element’s name from the file.
• Missing names and email addresses read as empty strings. When the file has no first name, last name or email address for a borrower, GraphQL returns "" for that field, not null.

​

Successful response

{
  "loan_id": "app_3vXq9TzK7mRbN2wLpYc8Hd",
  "import_id": "mimp_5Rk2WcQ8vNtLx3HbYp9JzA",
  "missing_fields": [
    {
      "entity": "SubjectProperty",
      "field": "address.county_fips",
      "ref": null,
      "severity": "RECOMMENDED",
      "value": null,
      "reason": "ABSENT",
      "message": null
    }
  ]
}

​

Reading the new loan

query ImportedLoan($loanId: ID!) {
  loan(id: $loanId) {
    id
    dealId
    currentStage
    borrowers(first: 20) {
      edges {
        node {
          id
          personalInformation {
            firstName
            lastName
            email
          }
        }
      }
    }
  }
}

​

The import report

query MismoImportReport($importId: ID!) {
  mismoImport(id: $importId) {
    id
    importedAt
    loan {
      id
    }
    nonAdoptions {
      __typename
      id
      reason
      severity
      source {
        entity
        label
        position
        rawValue
      }
      ... on MismoFieldNonAdoption {
        entity
        record {
          id
        }
        fields {
          column
          valueKind
          values {
            ... on IntakeInlineValues {
              values
            }
            ... on IntakeValuesRef {
              keyedOn
            }
          }
        }
      }
      ... on MismoUnrepresentableElement {
        element
        record {
          id
        }
      }
    }
  }
}

• MismoFieldNonAdoption: data that wasn’t imported for a record. When record is set, the record exists and one of its fields (fields) is empty or needs correcting. When record is null, the record was never created, and entity tells you what kind of record to create, for example a borrower’s income.
• MismoUnrepresentableElement: a MISMO 3.6 element that Pylon can’t store yet. element is the element’s name as it appears in the file. There’s nothing on the loan to fix, but the data from the file was lost.

​

Severity

​

Reason

​

Legacy missing fields

​

Common follow-ups after an import

• Every CRITICAL finding. Each one changes how DTI is calculated until it’s resolved.
• The subject property’s address and county. A loan can’t be priced without a complete subject property address, including its county.
• Each borrower’s email address. Borrowers without one can’t receive disclosures.
• Credit. No credit data is imported, so pull credit before you price the loan. Then link mortgages to owned properties.

​

Re-applying from an existing loan

mutation ExportLoan($loanId: ID!) {
  loan {
    export(input: { loanId: $loanId }) {
      downloadUrl
    }
  }
}

async function reapply(existingLoanId) {
  // 1. Export the existing loan
  const exportResult = await graphql(
    `mutation ExportLoan($loanId: ID!) {
      loan { export(input: { loanId: $loanId }) { downloadUrl } }
    }`,
    { loanId: existingLoanId }
  );
  // `graphql` is your GraphQL client call; it must throw when the response has `errors`
  const downloadUrl = exportResult.loan?.export?.downloadUrl;
  if (!downloadUrl) {
    throw new Error("Export returned no download URL");
  }

  // 2. Download the file (no Authorization header)
  const fileResponse = await fetch(downloadUrl);
  if (!fileResponse.ok) {
    throw new Error(`Download failed: ${fileResponse.status}`);
  }
  const file = new Blob([await fileResponse.arrayBuffer()], {
    type: "application/xml",
  });

  // 3. Confirm borrower authorization for the new application before this point

  // 4. Import it as a new loan
  const formData = new FormData();
  formData.append("mismo-file", file, "reapplication.xml");
  const importResponse = await fetch(`${BASE_URL}/api/mismo-import`, {
    method: "POST",
    headers: { Authorization: `Bearer ${accessToken}` },
    body: formData,
    signal: AbortSignal.timeout(120_000),
  });
  const body = await importResponse.json().catch(() => ({}));
  if (!importResponse.ok) {
    throw new Error(`${importResponse.status} ${body.code ?? ""}: ${body.error}`);
  }

  // 5. Review the report, then finish the new loan
  return { newLoanId: body.loan_id, importId: body.import_id };
}

• Credit. The credit report, scores and liabilities stay on the existing loan. Pull credit again on the new loan, and link mortgages to owned properties afterwards.
• Pricing, rate lock and disclosures. Price the new loan from scratch. A rate lock on the existing loan doesn’t transfer.
• Documents, tasks and conditions. Upload the documents the new loan needs. See Working with documents.
• The loan officer. Assign one on the new loan.
• Anything the import doesn’t read. The export contains data the import drops, such as the existing loan’s liabilities. Expect a CRITICAL finding for each owned property the export shows a mortgage on, until you link the mortgage on the new loan.

​

Errors

{
  "code": "MISMO_UPLOAD_UNSUPPORTED_VERSION",
  "error": "MISMO file declares reference model 3.5.021220160120; this endpoint imports MISMO 3.4 and 3.6",
  "error_id": "errx_7JpQ2nVb4KxRt9WmZc3LsA",
  "error_time": "2026-10-02T17:04:11.512Z"
}

​

Import error codes

​

Other errors

​

Retries and duplicates

• After 429, 500 or 503, retry with backoff. Honor Retry-After when it is present. Nothing was created by the failed request.
• After a 400 or 413, don’t retry until you’ve changed the file or the request. They fail the same way every time.
• After a timeout or dropped connection with no response, the import may still have completed. Before you retry, check whether the loan was already created, for example by listing your most recent deals. Otherwise you may end up with duplicates.
• Never retry after a success. A second call creates a second loan.

​

What beta means for your integration

• The contract may change, including in ways that aren’t backward compatible. This covers the response fields, the error codes and the import report. Check the changelog for updates.
• missing_fields will be removed. Build on import_id and the import report instead.
• New error codes and report values may be added. Handle an unknown code by its HTTP status: an unknown 4xx code means the file or request was rejected, and an unknown 5xx code means a failure on Pylon’s side. Handle an unknown reason or severity as “review this finding”.
• New fields may be added to responses. Ignore fields you don’t recognize instead of failing on them.
• Fewer findings over time. As more of the MISMO format is imported, files that produce findings today will produce fewer. Don’t hard-code a list of expected findings.
• Review imported loans. Check imported data before you rely on it for pricing or disclosures, especially for files from a source system you haven’t imported from before.

​

Related