# List tax returns

## ▶️ Usage

 With the List Tax Returns method, you can:

  1. List tax returns related to a specific link.id (using the link query parameter).
  2. Get the details of a specific tax-return.id (using the id query parameter).
  3. [Not Recommended] List all tax returns 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.

  ## 🔔 Multiple Schemas

  As a link can have both yearly and monthly tax returns, the response will include a mix of these two types of tax returns (and thus difference schemas).

Endpoint: GET /api/tax-returns/
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

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

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

  - `id` (string)
    Return information only for this resource id.
    Example: "24ccab1d-3a86-4136-a6eb-e04bf52b356f"

  - `id__in` (array)
    Return information for these resource ids.
    Example: ["6b3dea0f-be29-49d1-aabe-1a6d588642e6"]

  - `created_at` (string)
    Return items that were last updated in Belvo's database on this date (in YYYY-MM-DD format).
    Example: "2022-05-05"

  - `created_at__gt` (string)
    Return items that were last updated in Belvo's database after this date (in YYYY-MM-DD format).
    Example: "2022-05-05"

  - `created_at__gte` (string)
    Return items that were last updated in Belvo's database after or on this date (in YYYY-MM-DD format).
    Example: "2022-05-04"

  - `created_at__lt` (string)
    Return items that were last updated in Belvo's database before this date (in YYYY-MM-DD format).
    Example: "2022-04-01"

  - `created_at__lte` (string)
    Return items that were last updated in Belvo's database before or on this date (in YYYY-MM-DD format).
    Example: "2022-03-30"

  - `created_at__range` (array)
    Return accounts that were last updated in Belvo's database between two dates (in YYYY-MM-DD format). The first value indicates the start of the range and the second value indicates the end of the range.
    Example: ["2022-01-01","2022-12-31"]

  - `ejercicio` (integer)
    Return tax returns for exactly this year (YYYY).
    Example: 2017

  - `ejercicio__lt` (integer)
    Return tax returns for before this year (YYYY).
    Example: 2017

  - `ejercicio__lte` (integer)
    Return tax returns for this year and earlier (YYYY).
    Example: 2017

  - `ejercicio__gt` (integer)
    Return tax returns for after this year (YYYY).
    Example: 2017

  - `ejercicio__gte` (integer)
    Return tax returns for this year or later (YYYY).
    Example: 2017

  - `ejercicio__range` (array)
    Return tax returns for this range of years (YYYY). The first value indicates the start of the range and the second value indicates the end of the range.
    Example: [2015,2021]

  - `tipo_declaracion` (string)
    Return tax returns with this declaration type.
    Example: "Normal"

  - `tipo_declaracion__in` (array)
    Return tax returns with these declaration types.
    Example: ["Commercial"]

## 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) — one of:
    An array of:

  - Tax Return Personal (Yearly) objects
  - Tax Return Personal (Monthly) objects
  - Tax Return Business (Yearly) objects
  - Tax Return Business (Monthly) objects
  
  > 🚧 Multiple Schemas
  >
  > As a link can have both yearly and monthly tax returns, the response will include a mix of these two types of tax returns (and thus difference schemas).
    - Tax Return Personal (Yearly):
      - `id` (string)
        Belvo's unique identifier for the current item.
        Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d"
      - `link` (string,null)
        The link.id the data belongs to.
        Example: "30cb4806-6e00-48a4-91c9-ca55968576c8"
      - `collected_at` (string, required)
        The ISO-8601 timestamp when the data point was collected.
        Example: "2022-02-09T08:45:50.406032Z"
      - `created_at` (string)
        The ISO-8601 timestamp of when the data point was created in Belvo's database.
        Example: "2022-02-09T08:45:50.406032Z"
      - `informacion_general` (object,null, required)
        General information on the tax return (year, RFC, return type,
person/company name, and so on).
      - `sueldos_salarios` (object,null, required)
        Details regarding the income information together combined with withheld
taxes.
      - `servicios_profesionales` (object,null, required)
        Details regarding the income and tax information from professional
services provided.
      - `deducciones_personales` (object,null, required)
        List of all personal tax deductions.
      - `determinacion_impuesto` (object,null, required)
        Details regarding the final tax return.
      - `retenciones` (object,null, required)
        Details on the already withheld taxes.
      - `dividendos` (object,null, required)
        Details regarding dividends.
      - `datos_informativos` (object,null)
        Extra informative data on the tax return.
      - `pdf` (string,null, required)
        Tax return PDF as a binary.
        Example: "=PDF-STRING="
      - `receipt_pdf` (string,null, required)
        The acknowledgement receipt from the fiscal institution confirming that
they received the tax return.
        Example: "=PDF-STRING="
    - Tax Return Personal (Monthly):
      - `id` (string)
        Belvo's unique identifier for the current item.
        Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d"
      - `collected_at` (string, required)
        The ISO-8601 timestamp when the data point was collected.
        Example: "2022-02-09T08:45:50.406032Z"
      - `created_at` (string)
        The ISO-8601 timestamp of when the data point was created in Belvo's database.
        Example: "2022-02-09T08:45:50.406032Z"
      - `informacion_general` (object,null, required)
        General information regarding the tax return (year, RFC, return type,
person/company name, and so on).
      - `isr` (object,null, required)
        Information used to calculate the monthly provisional payments of the
income tax.
      - `iva` (object,null, required)
        Information used to calculate the monthly provisional payments of the VAT
tax.
      - `pdf` (string,null, required)
        Tax return PDF as a binary.
        Example: "=PDF-STRING="
      - `receipt_pdf` (string,null)
        The acknowledgement receipt from the fiscal institution confirming that
they received the tax return.
        Example: "=PDF-STRING="
      - `type` (string, required)
        The type of tax return. Can be either monthly or annual.
        Example: "monthly"
    - Tax Return Business (Yearly):
      - `id` (string, required)
        Belvo's unique identifier for the current item.
        Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d"
      - `collected_at` (string, required)
        The ISO-8601 timestamp when the data point was collected.
        Example: "2022-02-09T08:45:50.406032Z"
      - `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"
      - `informacion_general` (object,null, required)
        General information regarding the tax return (year, RFC, return type,
person/company name, and so on).
      - `datos_adicionales` (object,null, required)
        Additional data regarding the tax return.
      - `estado_resultados` (object,null, required)
        Detailed information about the legal entity's yearly profit and loss.

> Note: For tax returns submitted for the 2022 tax year and later, this field will return null as it is no longer a required field when submitting your tax return.
      - `estado_posicion_financiera_balance` (object,null, required)
        Details regarding balance sheet of the legal entity.

> Note: For tax returns submitted for the 2022 tax year and later, this field will return null as it is no longer a required field when submitting your tax return.
      - `conciliacion_entre_resultado_contable_fiscal` (object,null, required)
        Details regarding the accounting reconciliation.

> Note: For tax returns submitted for the 2022 tax year and later, this field will return null as it is no longer a required field when submitting your tax return.
      - `deducciones_autorizadas` (object,null, required)
        Details regarding the legal entity's deductions.
      - `cifras_cierre_ejercicio` (object,null, required)
        Details regarding key numbers at the end of the fiscal exercise.
      - `determinacion_del_impuesto_sobre_la_renta` (object,null, required)
        Details regarding the final tax return.
      - `dividendos_o_utilidades_distribuidos` (object,null, required)
        Details regarding distributed dividends.
      - `detalle_pago_r1_isr_personas_morales` (object,null, required)
        Details of the tax payment.
      - `ingressos` (object,null)
        > Note: Only applicable for tax return filed on or after 2022. For tax returns filed before 2022, this field will return null.

Details regarding the total amounts earned in the fiscal year.
      - `determinacion` (object,null)
        > Note: Only applicable for tax return filed on or after 2022. For tax returns filed before 2022, this field will return null.

Details regarding the tax due or tax credit.
      - `pdf` (string,null, required)
        Tax return PDF as a binary.
        Example: "=PDF-STRING="
      - `receipt_pdf` (string,null, required)
        The acknowledgement receipt from the fiscal institution confirming that
they received the tax return.
        Example: "=PDF-STRING="
    - Tax Return Business (Monthly):
      - `id` (string)
        Belvo's unique identifier for the current item.
        Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d"
      - `collected_at` (string, required)
        The ISO-8601 timestamp when the data point was collected.
        Example: "2022-02-09T08:45:50.406032Z"
      - `created_at` (string)
        The ISO-8601 timestamp of when the data point was created in Belvo's database.
        Example: "2022-02-09T08:45:50.406032Z"
      - `informacion_general` (object,null, required)
        General information regarding the tax return (year, RFC, return type,
person/company name, and so on).
      - `determinacion_isr` (object,null, required)
        Information used to calculate the provisional income tax for the period.
      - `detalle_pago_isr` (object,null, required)
        Information on the monthly provisional payments for the income tax.
      - `determinacion_iva` (object,null, required)
        Information used to calculate the provisional VAT tax for the period.
      - `detalle_pago_iva` (object,null, required)
        Information on the monthly provisional payments for the VAT tax.
      - `pdf` (string,null, required)
        Tax return PDF as a binary.
        Example: "=PDF-STRING="
      - `receipt_pdf` (string,null)
        The acknowledgement receipt from the fiscal institution confirming that
they received the tax return.
        Example: "=PDF-STRING="
      - `type` (string,null, required)
        The type of tax return. Can be either monthly or annual.
        Example: "monthly"

## 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 428 fields (application/json):

  - `code` (string)
    A unique error code (token_required) 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 token_required errors, the description is:
  
  - A MFA token is required by the institution to login.
    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: [a-f0-9]{32}). 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: [a-f0-9]{32}).
    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 false, 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 (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"