# Income (/data-api/api-reference/income)

Get income data derived from transaction analysis.



The Income endpoint provides income analysis derived from an end user's transaction history. This helps identify regular income sources and patterns.

Endpoints [#endpoints]

| Method | Endpoint     | Description                     |
| ------ | ------------ | ------------------------------- |
| `GET`  | `/v1/income` | Get income data for an end user |

The Income Model [#the-income-model]

| Attribute        | Type   | Description                                       |
| ---------------- | ------ | ------------------------------------------------- |
| `account_id`     | string | ID of the account the income was detected in      |
| `source`         | string | Identified income source (e.g., employer name)    |
| `frequency`      | string | Detected frequency (WEEKLY, FORTNIGHTLY, MONTHLY) |
| `average_amount` | number | Average income amount per period                  |
| `last_amount`    | number | Most recent income amount                         |
| `last_date`      | string | Date of most recent income                        |
| `confidence`     | number | Confidence score (0-1)                            |

Example Response [#example-response]

```json
{
  "account_id": "acc_123456789",
  "source": "ACME CORPORATION",
  "frequency": "FORTNIGHTLY",
  "average_amount": 3450.00,
  "last_amount": 3500.00,
  "last_date": "2023-01-15",
  "confidence": 0.95
}
```

Get Income Data [#get-income-data]

Retrieve income analysis for an end user.

```
GET https://api.fiskil.com/v1/income
```

Query Parameters [#query-parameters]

| Parameter     | Type   | Required | Description                   |
| ------------- | ------ | -------- | ----------------------------- |
| `end_user_id` | string | Yes      | The ID of the end user        |
| `account_id`  | string | No       | Filter by specific account ID |

Example Request [#example-request]

<Tabs items={['cURL', 'Node.js', 'Python']}>
  <Tab value="cURL">
    ```bash
    curl --request GET \
      --url 'https://api.fiskil.com/v1/income?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5' \
      --header 'Authorization: Bearer {access_token}' \
      --header 'accept: application/json; charset=UTF-8'
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    const response = await fetch(
      'https://api.fiskil.com/v1/income?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5',
      {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer {access_token}',
          'accept': 'application/json; charset=UTF-8'
        }
      }
    );

    const incomeData = await response.json();
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    response = requests.get(
        'https://api.fiskil.com/v1/income',
        params={'end_user_id': '482c0e2b-5866-46b1-b795-220b7bba45b5'},
        headers={
            'Authorization': 'Bearer {access_token}',
            'accept': 'application/json; charset=UTF-8'
        }
    )

    income_data = response.json()
    ```
  </Tab>
</Tabs>

Example Response [#example-response-1]

```json
{
  "data": [
    {
      "account_id": "acc_123456789",
      "source": "ACME CORPORATION",
      "frequency": "FORTNIGHTLY",
      "average_amount": 3450.00,
      "last_amount": 3500.00,
      "last_date": "2023-01-15",
      "confidence": 0.95
    },
    {
      "account_id": "acc_123456789",
      "source": "FREELANCE CLIENT",
      "frequency": "MONTHLY",
      "average_amount": 800.00,
      "last_amount": 1000.00,
      "last_date": "2023-01-10",
      "confidence": 0.72
    }
  ]
}
```

Income Frequencies [#income-frequencies]

| Frequency     | Description                     |
| ------------- | ------------------------------- |
| `WEEKLY`      | Income received weekly          |
| `FORTNIGHTLY` | Income received every two weeks |
| `MONTHLY`     | Income received monthly         |
| `IRREGULAR`   | Irregular or variable income    |

Confidence Score [#confidence-score]

The confidence score indicates how certain the algorithm is about the detected income pattern:

| Score Range | Interpretation                               |
| ----------- | -------------------------------------------- |
| 0.9 - 1.0   | High confidence (regular, consistent income) |
| 0.7 - 0.9   | Medium confidence (mostly regular income)    |
| 0.5 - 0.7   | Low confidence (irregular or recent pattern) |
| \< 0.5      | Very low confidence (may not be reliable)    |

Use Cases [#use-cases]

* **Loan Applications**: Verify income for lending decisions
* **Affordability Checks**: Assess ability to pay for services
* **Financial Planning**: Help users understand their income patterns
* **Subscription Pricing**: Offer pricing based on income levels

Related Endpoints [#related-endpoints]

* [Transactions](/data-api/api-reference/getBankingTransactions) - View the underlying transactions
* [Accounts](/data-api/api-reference/accounts) - Get account details