# List incomes

## ▶️ Usage

With the List Incomes method, you can:

1. List incomes related to a specific link.id (using the link query parameter).
2. Get the details of a specific income.id (using the id query parameter).
3. [Not Recommended] List all incomes related to your Belvo account (without using any query parameters).

## 📖 Pagination

This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.

## 🔦 Filtering Responses

Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.

Endpoint: GET /api/incomes/
Version: 1.223.0
Security: basicAuth

## Query parameters:

  - `link` (string)
    The link.id you want to filter by.

ℹ️ We highly recommend adding the link.id filter in order to improve your performance.
    Example: "8848bd0c-9c7e-4f53-a732-ec896b11d4c4"

  - `page_size` (integer)
    Indicates how many results to return per page. By default we return 100 results per page.

ℹ️ The minimum number of results returned per page is 1 and the maximum is 1000. If you enter a value greater than 1000, our API will default to the maximum value (1000).
    Example: 100

  - `page` (integer)
    A page number within the paginated result set.
    Example: 1

  - `link__in` (array)
    Return results only for these link.ids.
    Example: ["5722d0ba-69d7-42dc-8ff5-33767b83c5d6"]

  - `omit` (string)
    Omit certain fields from being returned in the response. For more information, see our Filtering responses DevPortal article.

  - `fields` (string)
    Return only the specified fields in the response. For more information, see our Filtering responses DevPortal article.

  - `account` (string)
    The account.id you want to filter by.

ℹ️ We highly recommend adding either the link.id or the account.id filters in order to improve your performance.
    Example: "8848bd0c-9c7e-4f53-a732-ec896b11d4c4"

  - `account__in` (array)
    Return results only for these account.ids.
    Example: ["85b77707-90ef-46fd-9059-5a757f24247a"]

## Response 200 fields (application/json):

  - `count` (integer)
    The total number of results in your Belvo account.
    Example: 130

  - `next` (string,null)
    The URL to next page of results. Each page consists of up to 100 items. If there are not enough results for an additional page, the value is null.

In our documentation example, we use {endpoint} as a placeholder value. In production, this value will be replaced by the actual endpoint you are currently using (for example, accounts or owners).
    Example: "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2"

  - `previous` (string,null)
    The URL to the previous page of results. If there is no previous page, the
value is null.

  - `results` (array)
    Array of income objects.

  - `results.id` (string, required)
    Belvo's unique identifier for the current item.
    Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d"

  - `results.link` (string,null, required)
    The link.id the data belongs to.
    Example: "30cb4806-6e00-48a4-91c9-ca55968576c8"

  - `results.created_at` (string, required)
    The ISO-8601 timestamp of when the data point was created in Belvo's database.
    Example: "2022-02-09T08:45:50.406032Z"

  - `results.income_streams` (array, required)
    An array of enriched income stream objects.

  - `results.income_streams.account_id` (string, required)
    Unique ID for the bank account to be verified for income streams.
    Example: "EBACA-89077589"

  - `results.income_streams.income_type` (string, required)
    The type of income used in the calculations.

We return one of the following enum values:

  - SALARY
  - GOVERNMENT
  - INTEREST
  - RENT
  - RETIREMENT
  - FREELANCE
  - ALTERNATIVE_INCOME
  - TRANSFER
  - DEPOSIT
  - UNKNOWN
    Enum: "SALARY", "GOVERNMENT", "INTEREST", "RENT", "RETIREMENT", "FREELANCE", "ALTERNATIVE_INCOME", "TRANSFER", "DEPOSIT", "UNKNOWN"

  - `results.income_streams.frequency` (string, required)
    How often the income is received.

We return one of the following enum values:

  - MONTHLY - For transactions that occur once per month.
  - FORTNIGHTLY - For transactions that occur once every two weeks.
  - WEEKLY - For transactions that occur once per week.
  - IRREGULAR - For transactions that do not occur on a defined frequency pattern.
  - SINGLE - For transactions that occur only once and do not repeat.
    Enum: "MONTHLY", "FORTNIGHTLY", "WEEKLY", "IRREGULAR", "SINGLE"

  - `results.income_streams.monthly_average` (number, required)
    The average amount of income received from the source over periods_with_income.
    Example: 2500

  - `results.income_streams.monthly_median` (number)
    The median amount of income received from the source over within a natural month.
    Example: 2200

  - `results.income_streams.average_income_amount` (number, required)
    The average income transaction amount from the source.
    Example: 2500

  - `results.income_streams.last_income_amount` (number, required)
    The amount of the most recent income received from the source.
    Example: 2500

  - `results.income_streams.currency` (string, required)
    The three-letter currency code of the income. For example:

  • 🇧🇷 BRL (Brazilian Real)
  • 🇨🇴 COP (Colombian Peso)
  • 🇲🇽 MXN (Mexican Peso)
    Example: "BRL"

  - `results.income_streams.last_income_description` (string, required)
    The description of the most recent income from the stream.
    Example: "Salário"

  - `results.income_streams.last_income_date` (string, required)
    The date when the most recent income from the stream was received, in YYYY-MM-DD format.
    Example: "2023-02-09"

  - `results.income_streams.stability` (number,null, required)
    The stability of the income based on its amount, with a range from 0 to 1, where 1 represents perfect stability.

Note: For transactions with frequency=SINGLE, this value returns null.
    Example: 1

  - `results.income_streams.regularity` (number,null, required)
    The regularity of the income based in its frequency, with a range from 0 to 1, where 1 represents perfect regularity.

Note: For transactions with frequency=SINGLE, this value returns null.
    Example: 1

  - `results.income_streams.trend` (number,null, required)
    The income trend during a period of time calculated between last income and first income received, where:
  - a negative float means that the income trend is decreasing during the time period.
  - a positive float means that the income trend is increasing during the time period.

Note: For transactions with frequency=SINGLE, this value returns null.

  - `results.income_streams.lookback_periods` (integer, required)
    Number of period units (based on rolling months) used to generate insights and calculations.

Note: A rolling month is a period of 30 days. For example, 2023-01-15 to 2023-02-15.
    Example: 9

  - `results.income_streams.full_periods` (integer, required)
    Number of period units (based on rolling months) with data to perform calculations.

Note: A rolling month is a period of 30 days. For example, 2023-01-15 to 2023-02-15.
    Example: 9

  - `results.income_streams.periods_with_income` (integer, required)
    Number of period units (based on rolling months) with at least one income available.

Note: A rolling month is a period of 30 days. For example, 2023-01-15 to 2023-02-15.
    Example: 9

  - `results.income_streams.number_of_incomes` (integer, required)
    Number of income transactions over the lookback_periods.
    Example: 9

  - `results.income_streams.confidence` (string, required)
    Belvo's level of confidence for future incomes.

We return one of the following enum values:

  - HIGH
  - MEDIUM
  - LOW
    Enum: "HIGH", "MEDIUM", "LOW"

  - `results.income_source_type` (string, required)
    The type of source we generate income insights from.
We return one of the following enum values:

  - BANK
    Enum: "BANK"

  - `results.first_transaction_date` (string,null, required)
    The date when the first transaction occurred, in YYYY-MM-DD format.
    Example: "2022-06-09"

  - `results.last_transaction_date` (string, required)
    The date when when the last transaction occurred, in YYYY-MM-DD format.
    Example: "2023-02-09"

  - `results.best_working_day_to_charge` (integer, required)
    The best working day of the month to charge the user.
    Example: 22

  - `results.good_working_days_to_charge` (array, required)
    Additional working days that have been identified as good days to charge the user.
    Example: [17,7,2]

  - `results.number_of_income_streams` (integer, required)
    Number of total income streams analized.
    Example: 1

  - `results.monthly_average` (number, required)
    Average amount of income received per month across all the accounts for the specific user.
    Example: 2500

  - `results.monthly_average_regular` (number, required)
    Average amount of regular income (with a frequency of MONTHLY, FORTNIGHTLY, or WEEKLY) received per month for the specific user.
    Example: 2500

  - `results.monthly_average_irregular` (number, required)
    Average amount of irregular income (with a frequency of SINGLE or IRREGULAR) received per month for the specific user.

  - `results.monthly_average_low_confidence` (number, required)
    Average amount of income received per month for the specific user with LOW confidence.

  - `results.monthly_average_medium_confidence` (number, required)
    Average amount of income received per month for the specific user with MEDIUM confidence.

  - `results.monthly_average_high_confidence` (number, required)
    Average amount of income received per month for the specific user with HIGH confidence.
    Example: 2500

  - `results.total_income_amount` (number, required)
    Total amount of all income received for the specific user.
    Example: 22500

  - `results.total_regular_income_amount` (number, required)
    Total amount of regular income (with a frequency of MONTHLY, FORTNIGHTLY, WEEKLY) for the specific user.
    Example: 22500

  - `results.total_irregular_income_amount` (number)
    Total amount of irregular income (with a frequency of SINGLE or IRREGULAR) for the specific user.

  - `results.total_low_confidence` (number, required)
    Total amount of income for the specific user with LOW confidence.

  - `results.total_medium_confidence` (number, required)
    Total amount of income for the specific user with MEDIUM confidence.

  - `results.total_high_confidence` (number, required)
    Total amount of income for the specific user with HIGH confidence.
    Example: 22500

## Response 403 fields (application/json):

  - `code` (string)
    A unique error code (access_to_resource_denied) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 403 access_to_resource_denied.
    Example: "access_to_resource_denied"

  - `message` (string)
    A short description of the error. 


For access_to_resource_denied errors, the description is:
  
  - You don't have access to this resource..
    Example: "You don't have access to this resource."

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 404 fields (application/json):

  - `code` (string)
    A unique error code (not_found) that allows you to classify and handle the error programmatically.
    Example: "not_found"

  - `message` (string)
    A short description of the error.


For not_found errors, the description is:

  - Not found
    Example: "Not found"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 408 fields (application/json):

  - `code` (string)
    A unique error code (request_timeout) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 408 request_timeout errors.
    Example: "request_timeout"

  - `message` (string)
    A short description of the error. 


For request_timeout errors, the description is:
  
  - The request timed out, you can retry asking for less data by changing your query parameters.
    Example: "The request timed out, you can retry asking for less data by changing your query parameters"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 500 fields (application/json):

  - `code` (string)
    A unique error code (unexpected_error) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 500 unexpected_error errors.
    Example: "unexpected_error"

  - `message` (string)
    A short description of the error. 


For unexpected_error errors, the description is:
  
  - Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution.
    Example: "Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"