# Loan Obligations
> A Loan Obligation represents a bill on a loan: an amount of principal, interest, and fees the borrower must pay by a due date.

[Events](https://increase.com/documentation/webhooks.md) will be generated for this resource. The possible event categories are: `loan_obligation.created`.

## The Loan Obligation object
### Example
```json
{
  "account_id": "account_in71c4amph0vgo2qllky",
  "created_at": "2020-01-31T23:59:59Z",
  "due_at": "2020-01-31T23:59:59Z",
  "due_fees": 100,
  "due_interest": 100,
  "due_principal": 100,
  "file_id": "file_makxrc67oh9l6sg7w9yc",
  "id": "loan_obligation_p6zk4mqoelj8bs7b8jmh",
  "idempotency_key": null,
  "past_due_at": "2020-01-31T23:59:59Z",
  "type": "loan_obligation"
}
```
### Attributes
- `account_id` (string)
  The identifier of the loan Account the Loan Obligation is billed against.

- `created_at` (string)
  The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time at which the Loan Obligation was created.

- `due_at` (string)
  The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time at which the Loan Obligation is due.

- `due_fees` (integer)
  The amount of fees due in the minor unit of the currency. For dollars, this is cents.

- `due_interest` (integer)
  The amount of interest due in the minor unit of the currency. For dollars, this is cents.

- `due_principal` (integer)
  The amount of principal due in the minor unit of the currency. For dollars, this is cents.

- `file_id` (string)
  The identifier of the File containing a PDF of the Loan Obligation.

- `id` (string)
  The Loan Obligation identifier.

- `idempotency_key` (string, nullable)
  The idempotency key you chose for this object. This value is unique across Increase and is used to ensure that a request is only processed once. Learn more about [idempotency](https://increase.com/documentation/idempotency-keys).

- `past_due_at` (string)
  The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time after which the Loan Obligation is past due if it is unpaid.

- `type` (string)
  A constant representing the object's type. For this resource it will always be `loan_obligation`.

## List Loan Obligations
GET /loan_obligations

### Example
```curl
curl \
  --url "${INCREASE_URL}/loan_obligations" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```

### Query Parameters
- `cursor` (string, optional)
  Return the page of entries after this one.

- `limit` (integer, optional)
  Limit the size of the list that is returned. The default (and maximum) is 100 objects.
  Default: `100`

- `account_id` (string, optional)
  Filter Loan Obligations to those billed against the specified loan Account.

- `idempotency_key` (string, optional)
  Filter records to the one with the specified `idempotency_key` you chose for that object. This value is unique across Increase and is used to ensure that a request is only processed once. Learn more about [idempotency](https://increase.com/documentation/idempotency-keys).

- `due_at.after` (string, optional)
  Return results after this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.

- `due_at.before` (string, optional)
  Return results before this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.

- `due_at.on_or_after` (string, optional)
  Return results on or after this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.

- `due_at.on_or_before` (string, optional)
  Return results on or before this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.

- `past_due_at.after` (string, optional)
  Return results after this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.

- `past_due_at.before` (string, optional)
  Return results before this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.

- `past_due_at.on_or_after` (string, optional)
  Return results on or after this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.

- `past_due_at.on_or_before` (string, optional)
  Return results on or before this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.

### Returns a Loan Obligation List object:
```json
{
  "data": [
    {
      "account_id": "account_in71c4amph0vgo2qllky",
      "created_at": "2020-01-31T23:59:59Z",
      "due_at": "2020-01-31T23:59:59Z",
      "due_fees": 100,
      "due_interest": 100,
      "due_principal": 100,
      "file_id": "file_makxrc67oh9l6sg7w9yc",
      "id": "loan_obligation_p6zk4mqoelj8bs7b8jmh",
      "idempotency_key": null,
      "past_due_at": "2020-01-31T23:59:59Z",
      "type": "loan_obligation"
    }
  ],
  "next_cursor": "v57w5d"
}
```

## Retrieve a Loan Obligation
GET /loan_obligations/{loan_obligation_id}

### Example
```curl
curl \
  --url "${INCREASE_URL}/loan_obligations/loan_obligation_p6zk4mqoelj8bs7b8jmh" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `loan_obligation_id` (string, required)
  The identifier of the Loan Obligation.

## Retrieve the balances of a Loan Obligation
GET /loan_obligations/{loan_obligation_id}/balances

### Example
```curl
curl \
  --url "${INCREASE_URL}/loan_obligations/loan_obligation_p6zk4mqoelj8bs7b8jmh/balances" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `loan_obligation_id` (string, required)
  The identifier of the Loan Obligation to look up the balances of.

### Query Parameters
- `at_time` (string, optional)
  The moment to query the balances at. If not set, returns the current balances.

### Returns a Loan Obligation Balance Lookup object:
```json
{
  "due_fees": 100,
  "due_interest": 100,
  "due_principal": 100,
  "loan_obligation_id": "loan_obligation_p6zk4mqoelj8bs7b8jmh",
  "paid_fees": 100,
  "paid_interest": 100,
  "paid_principal": 100,
  "type": "loan_obligation_balance_lookup"
}
```

## Sandbox: Create a Loan Obligation
POST /simulations/loan_obligations
> Simulates a Loan Obligation being created for a loan Account, billing everything the Account owes. In production, Loan Obligations are created at the end of each cycle of the Account's obligation schedule.
### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/simulations/loan_obligations" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "account_id": "account_in71c4amph0vgo2qllky"
  }'
```

### Body Parameters
- `account_id` (string, required)
  The identifier of the loan Account the Loan Obligation should be billed against.