# Complete an incomes request

Used to resume an Income retrieve session that was paused because an MFA
token was required by the institution.


Endpoint: PATCH /api/incomes/
Version: 1.222.0
Security: basicAuth

## Query parameters:

  - `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.

## Request fields (application/json):

  - `session` (string, required)
    The session you want to resume. You need to use the  value
that is provided in the 428 Token Required response that you receive
after you make your POST request.
    Example: "6e7b283c6efa449c9c028a16b5c249fa"

  - `token` (string)
    The MFA token generated by the institution which is required to continue a session.
    Example: "1234ab"

  - `link` (string, required)
    The  you want to resume. Must be the same  as the
one you receive in the 428 Token Required response that contains the
 ID.
    Example: "683005d6-f45c-4adb-b289-f1a12f50f80c"

  - `save_data` (boolean)
    Indicates whether or not to persist the data in Belvo. By default, this is set to  and we return a 201 Created response.

When set to , the data won't be persisted and we return a 200 OK response.
    Example: true

## Response 200 fields (application/json):

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

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

  - `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"

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

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

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

We return one of the following enum values:

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

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

We return one of the following enum values:

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

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

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

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

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

  - `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"

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

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

  - `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.

 For transactions with =, this value returns .
    Example: 1

  - `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.

 For transactions with =, this value returns .
    Example: 1

  - `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.

 For transactions with =, this value returns .

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

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

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

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

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

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

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

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

We return one of the following enum values:

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

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

  -
    Enum: "BANK"

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

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

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

  - `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]

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

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

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

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

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

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

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

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

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

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

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

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

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

## Response 201 fields (application/json):

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

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

  - `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"

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

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

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

We return one of the following enum values:

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

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

We return one of the following enum values:

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

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

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

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

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

  - `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"

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

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

  - `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.

 For transactions with =, this value returns .
    Example: 1

  - `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.

 For transactions with =, this value returns .
    Example: 1

  - `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.

 For transactions with =, this value returns .

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

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

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

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

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

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

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

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

We return one of the following enum values:

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

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

  -
    Enum: "BANK"

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

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

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

  - `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]

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

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

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

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

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

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

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

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

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

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

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

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

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

## Response 408 fields (application/json):

  - `code` (string)
    A unique error code () 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  errors, the description is:
  
  - .
    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: ). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 428 fields (application/json):

  - `code` (string)
    A unique error code () that allows you to classify and handle the error programmatically.
ℹ️ Check our DevPortal for more information on how to handle 428 token_required errors.
    Example: "token_required"

  - `message` (string)
    A short description of the error. 
For  errors, the description is:
  
  - .
    Example: "A MFA token is required by the institution to login"

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

  - `session` (string)
    A 32-character unique ID of the login session (matching a regex pattern of: ).
    Example: "2675b703b9d4451f8d4861a3eee54449"

  - `expiry` (integer)
    Session duration time in seconds.
    Example: 9600

  - `link` (string)
    Unique identifier created by Belvo, used to reference the current
Link.
    Example: "30cb4806-6e00-48a4-91c9-ca55968576c8"

  - `token_generation_data` (object)
    Details on how to generate the token.

  - `token_generation_data.instructions` (string)
    Instructions for token generation.
    Example: "Use this code to generate the token"

  - `token_generation_data.type` (string)
    Type of the data to generate the token (QR code, numeric
challenge).
    Example: "numeric"

  - `token_generation_data.value` (string)
    Value to use to generate the token.
    Example: "12345"

  - `token_generation_data.expects_user_input` (boolean)
    Indicates whether the user needs to provide input in order to complete the authentication.
When set to , your user may need to:
- confirm the login on another device
- scan a QR code
You will still need to make a PATCH call to complete the request.
    Example: true

## Response 500 fields (application/json):

  - `code` (string)
    A unique error code () 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  errors, the description is:
  
  - .
    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: ). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"