> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argyle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mortgages Endpoint

> Let the Argyle API calculate payout statement YTD values for you.

This guide introduces the `/mortgages` endpoint with calculated YTD values for all monetary fields from your users' payout statements.

By utilizing this endpoint, you can increase the speed of implementation and reduce the complexity of your mortgage applications:

* Argyle provides an automated and structured way to collect employment and income data compliant with **Fannie Mae 1005** and **VA Form 26-8497** (VOE), as well as all of the income data and documentation necessary to compliantly verify income. Our `/mortgages` endpoint goes one step further, producing standard reusable calculations like YTD income, tenure, basic monthly pay calculations, and more.
* Reduce your team's manual effort and achieve a seamless re-verification process without borrower engagement by utilizing *continuous access* to the data provided by Argyle. You can subscribe to [webhooks](/api-guide/webhooks) to get the latest employment status of borrowers during the application process and gain access to a structured JSON output of W-2 and 1099 forms through our [`/payroll-documents`](/api-reference/payroll-documents) endpoint.

<Note>
  You can test your implementation of the `/mortgages` endpoint in Argyle's [Sandbox testing environment](/overview/sandbox-testing).
</Note>

## Endpoint attributes

<div className="argyle-divider" />

### Income

The `income` object contains:

* A `ytd` object, with all available monetary fields for the current year.
* When available, additional objects representing previous years with the same monetary fields.

```json theme={}
{
    "income": {
        "ytd": {
            "gross": "21231.02",
            "bonus": "1231.12",
            "commissions": "12312.01",
            "overtime": "123.12",
            "currency": "USD"
        },
        "2022": {
            "gross": "21231.02",
            "bonus": "1231.12",
            "commissions": "12312.01",
            "overtime": "123.12",
            "currency": "USD"
        },
        "2021": {
            "gross": "21231.02",
            "bonus": "1231.12",
            "commissions": "12312.01",
            "overtime": "123.12",
            "currency": "USD"
        }
    }
}
```

#### Definitions:

* `gross` — The amount of gross pay received in this calendar year.
* `bonus` — Additional amount added to the base pay.
* `commission` — A fee paid to a user for transacting a piece of business, like closing a sale or making a deal.
* `overtime` — The amount of pay that is generated during overtime work hours.
* `currency` — Currency of the payouts. The values of this field follow the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format, for example, `USD`.

<Note>
  Monetary fields in objects within `income` are only provided when the payout data is in a single currency.
</Note>

### Tenure

* The `tenure` object shows whether the user has spent two years in their currently active employment, and indicates the number of days in that tenure.
* The value for `tenure` can be `null` if no active employment is found for this account, or the employment data does not have any values for `hire_datetime`.

```json theme={}
{
   "tenure":{
      "twoyears": true,
      "length": 755
   }
}
```

#### Definitions:

* `twoyears` — Indicates whether the user has spent two years in currently active employment. Available only when `start_datetime` is present in the employment data.
* `length` — Indicates the number of days the user has been employed in their currently active employment. Available only when `start_datetime` is present in the employment data.

## Retrieving mortgage calculations

Use this request to return calculated YTD values for the account with the provided account ID:

GET `/v1/mortgages?account={id}`

The resulting `income` object contains YTD objects grouped by year. The `tenure` object contains the employment history required for a mortgage application.

```json theme={}
{
  results: [
        {
            "account": "470be45a-a5c7-40ec-9fb8-a6bf7306fd69",
            "income": {
                "ytd": {
                    "gross": "21231.02",
                    "bonus": "1231.12",
                    "commissions": "12312.01",
                    "overtime": "123.12",
                    "currency": "USD"
                },
                "2022": {
                    "gross": "21231.02",
                    "bonus": "1231.12",
                    "commissions": "12312.01",
                    "overtime": "123.12",
                    "currency": "USD"
                },
                "2021": {
                    "gross": "21231.02",
                    "bonus": "1231.12",
                    "commissions": "12312.01",
                    "overtime": "123.12",
                    "currency": "USD"
                }
            },
            "tenure": {
                "twoyears": false,
                "length": 123
            }
        }
    ]
}
```

If no results are found, then an empty `results` array is returned.

<Note>
  The `/mortgages` endpoint and its API attributes, calculations, and response payloads are subject to changes. The Argyle team is improving this solution and may introduce new API fields and fine-tune YTD calculations. Reach out to your respective Customer Success Manager or Account Executive for more details.
</Note>