# List tax statuses

## ▶️ Usage

With the List Tax Statuses method, you can:

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

## 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 tax status 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.collected_at` (string, required)
    The ISO-8601 timestamp when the data point was collected.
    Example: "2022-02-09T08:45:50.406032Z"

  - `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.place_and_date_of_issuance` (string,null, required)
    The place and date of that the tax status was issued.
    Example: "TLALPAN , CIUDAD DE MEXICO A 19 DE MARZO DE 2020"

  - `results.official_name` (string,null, required)
    The name of the person or business.
    Example: "John Doe"

  - `results.id_cif` (string,null, required)
    The taxpayer's Cédula de Identificación Fiscal (CIF) ID.
    Example: "12345678901"

  - `results.tax_payer_information` (object,null, required)
    Details regarding the taxpayer.

  - `results.tax_payer_information.rfc` (string,null, required)
    The tax payers's identification number (For Mexico, this is the RFC).
    Example: "BEMP12345G58"

  - `results.tax_payer_information.curp` (string,null)
    The tax payers's Clave Única de Registro de Población (CURP) number.

  - `results.tax_payer_information.name` (string,null)
    The tax payers's first name.
    Example: "JOHN"

  - `results.tax_payer_information.first_last_name` (string,null)
    The tax payers's first last name.
    Example: "DOE"

  - `results.tax_payer_information.second_last_name` (string,null)
    The tax payers's second last name.
    Example: "SCHMOE"

  - `results.tax_payer_information.start_operations_date` (string,null, required)
    Date when the tax payer commenced taxable commercial activities, in YYYY-MM-DD format.

  - `results.tax_payer_information.status_padron` (string,null, required)
    Status of the taxpayer in the Federal Register of Taxpayers (RFC). Can be ACTIVO or INACTIVO.

  - `results.tax_payer_information.last_status_change_date` (string,null, required)
    Date when status_padron was most recently updated, in YYYY-MM-DD format.

  - `results.tax_payer_information.commercial_name` (string,null)
    The name of the business designated for consumers and the general public.

Note: Only applicable for businesses.
    Example: "Jar Jar Transport"

  - `results.tax_payer_information.social_name` (string,null)
    The unique and exclusive name within the national territory that companies
receive for legal or administrative purposes.

Note: Only applicable for businesses.
    Example: "John Doe SA DE CV"

  - `results.tax_payer_information.email` (string,null)
    Contact email address for the tax payer.
    Example: "john_doe@gmail.com"

  - `results.tax_payer_information.phone` (string,null)
    Contact phone number for the tax payer.
    Example: "1234567890"

  - `results.address` (object,null, required)
    The tax payer's address details.

  - `results.address.postal_code` (string,null, required)
    The postcode of the address.
    Example: "21255"

  - `results.address.street_type` (string,null)
    The street type.
    Example: "CALLE"

  - `results.address.street` (string,null)
    The tax payers street.
    Example: "LA MALINCHE"

  - `results.address.exterior_number` (string,null)
    The street number.
    Example: "432"

  - `results.address.interior_number` (string,null)
    Additional address information.
    Example: "PLANTA BAJA"

  - `results.address.suburb` (string,null)
    The suburb of the tax payer.
    Example: "BUENAVENTURA"

  - `results.address.locality` (string,null)
    The locality of the address.
    Example: "none"

  - `results.address.municipality` (string,null)
    The municipality of the address.
    Example: "CDMX DC"

  - `results.address.state` (string,null)
    The state that the address is in.
    Example: "Federal"

  - `results.address.between_street` (array,null)
    Additional information about where the street is located.

  - `results.address.between_street.street_one` (string,null)
    The first street that street is located between.
    Example: "CALLE PRINCIPE"

  - `results.address.between_street.street_two` (string,null)
    The second street that street is located between.
    Example: "CALLE NUEVA ROMA"

  - `results.economic_activity` (array,null, required)
    A list of economic activity objects.

  - `results.economic_activity.economic_activity` (string,null)
    The description of the economic activity.
    Example: "Asalariado"

  - `results.economic_activity.initial_date` (string,null)
    The start date of the economic activity, in YYYY-MM-DD format.
    Example: "2020-12-06"

  - `results.economic_activity.end_date` (string,null)
    The end date of the economic activity, in YYYY-MM-DD format.

  - `results.economic_activity.order` (string,null)
    The order of the economic activity.
    Example: "2"

  - `results.economic_activity.percentage` (string,null)
    The percentage of the economic activity.
    Example: "1"

  - `results.regimes` (array,null, required)
    A list of regimen objects.

  - `results.regimes.end_date` (string,null, required)
    The end date of the regimen, in YYYY-MM-DD format.

  - `results.regimes.initial_date` (string,null, required)
    The start date of the regimen, in YYYY-MM-DD format.
    Example: "2020-12-06"

  - `results.regimes.regimen` (string,null, required)
    The description of the regimen.
    Example: "Régimen de Ingresos por Dividendos (socios y accionistas)"

  - `results.obligations` (array,null, required)
    Details regarding a business's obligations.

ℹ️ For non-business accounts, this field will return empty.

  - `results.obligations.obligation` (string,null)
    The description of the obligation.
    Example: "Declaración informativa de IVA con la anual de ISR"

  - `results.obligations.expiration` (string,null)
    The deadline to fulfill the obligation, as imposed by the tax authority.
    Example: "Conjuntamente con la declaración anual del ejercicio."

  - `results.obligations.initial_date` (string,null)
    The date when obligation started, in YYYY-MM-DD format.
    Example: "2020-12-06"

  - `results.obligations.end_date` (string,null)
    The date when obligation ended, in YYYY-MM-DD format.

  - `results.digital_stamp` (string,null, required)
    The validation certificate of the document.
    Example: "||2020/04/26|GHTF980303F7|CONSTANCIA DE SITUACIÓN\nFISCAL|2044441088666600000034||\n"

  - `results.digital_stamp_chain` (string,null, required)
    A data chain containing the basic structure of a fiscal digital check. For Mexico, this is the Comprobante Fiscal Digital por Internet (CFDI).
    Example: "EtenSA9t1adG7bn+Jj23kj43JK+XbMPxdOppwabhXD+pXseSqYowWWDna0mpUk3264lkj2345j23faNZB852dCDt9KAjow=\n"

  - `results.pdf` (string,null, required)
    Tax status PDF as a binary string.
    Example: "=PDF-STRING="

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