Query structured spec data via REST or MCP. Get exactly what your agent needs.
https://sandbox.belvo.com
https://development.belvo.com
/api/links/{id}
Update the credentials of a specific link. If the successfully updated link is a recurrent one, we automatically trigger an update of the link. If we find fresh data, you'll [receive historical update](https://developers.belvo.com/docs/webhooks) webhooks. <div style="background-color:#f4f6f8; border-left: 6px solid #4CAF50;padding: 12px;margin-left: 25px; border-radius: 4px; margin-right: 25px"> <strong>Note: </strong> We recommend using our <a href="https://developers.belvo.com/docs/connect-widget" target="_blank">Connect Widget</a> to handle updating <code>invalid</code> or <code>token_required</code> links. </div>
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| id | path | required | string | The `link.id` you want to update. |
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LinksPutRequest"
}
}
},
"required": true
}
PUT /api/links/{id}
400InvalidCredentialsStorageError
{
"type": "object",
"title": "Invalid Credentials Storage",
"properties": {
"code": {
"type": "string",
"example": "login_error",
"description": "A unique error code (`invalid_credentials_storage`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle <a href=\"https://developers.belvo.com/docs/belvo-api-errors#400-invalid_credentials_storage\" target=\"_blank\">400 invalid_credentials_storage errors</a>.\n"
},
"message": {
"type": "string",
"example": "Recurrent links must store the credentials",
"description": "A short description of the error. \n\n\nFor `invalid_credentials_storage` errors, the description can be one of the following:\n\n - `Recurrent links must store the credentials`\n \n"
},
"request_id": {
"type": "string",
"example": "9e7b283c6efa449c9c028a16b5c249fb",
"pattern": "[a-f0-9]{32}",
"description": "A 32-character unique ID of the request (matching a regex pattern of: `[a-f0-9]{32}`). Provide this ID when contacting the Belvo\nsupport team to accelerate investigations.\n"
}
},
"description": "This error occurs when you attempted to create a **recurrent** link where you set `credentials_storage` to either `nostore` or to a date range between `1d` to `365d`.\n"
}
400InvalidFetchHistorical
{
"type": "object",
"title": "Invalid Fetch Resources",
"properties": {
"code": {
"type": "string",
"example": "invalid_fetch_resources",
"description": "A unique error code (`invalid_fetch_resources`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle <a href=\"https://developers.belvo.com/docs/belvo-api-errors#400-invalid_fetch_resources\" target=\"_blank\">400 invalid_fetch_resources errors</a>.\n"
},
"message": {
"type": "string",
"example": "Single links without stored credentials must fetch resources",
"description": "A short description of the error. \n\n\nFor `invalid_fetch_resources` errors, the description can be one of the following:\n\n - `Single links without stored credentials must fetch resources`\n \n"
},
"request_id": {
"type": "string",
"example": "9e7b283c6efa449c9c028a16b5c249fb",
"pattern": "[a-f0-9]{32}",
"description": "A 32-character unique ID of the request (matching a regex pattern of: `[a-f0-9]{32}`). Provide this ID when contacting the Belvo\nsupport team to accelerate investigations.\n"
}
},
"description": "This error occurs when you attempted to create a link where you set `credentials_storage` to `nostore` and did not send any resources in the `fetch_resources`. For links where we don't store credentials, you must send through an array of resources in `fetch_resources`.\n"
}
400InvalidResourcesError
{
"type": "object",
"title": "Invalid Resources",
"properties": {
"code": {
"type": "string",
"example": "invalid",
"description": "A unique error code (`invalid`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle <a href=\"https://developers.belvo.com/docs/belvo-api-errors#400-invalid\" target=\"_blank\">400 invalid_period errors</a>.\n"
},
"field": {
"type": "string",
"example": "resources",
"description": "The request parameter that is causing the error. For invalid resources, this will be set to `resources`.\n"
},
"message": {
"type": "string",
"example": "The institution only supports the following resources: EMPLOYMENT_RECORDS, OWNERS",
"description": "A short description of the error. \n\n\nFor `invalid` errors relating to `fetch_resources`, the description is:\n \n - `The institution only supports the following resources: (comma-separated list of supported resources)`.\n"
},
"request_id": {
"type": "string",
"example": "9e7b283c6efa449c9c028a16b5c249fb",
"pattern": "[a-f0-9]{32}",
"description": "A 32-character unique ID of the request (matching a regex pattern of: `[a-f0-9]{32}`). Provide this ID when contacting the Belvo\nsupport team to accelerate investigations.\n"
}
},
"description": "This error occurs when you attempted to create a link where you added resources in `fetch_resources` that are unsupported by the institution.\n"
}
401_consent_without_accounts_error
{
"type": "object",
"title": "Consent Without Accounts",
"properties": {
"code": {
"type": "string",
"example": "consent_without_accounts",
"description": "A unique error code (`consent_without_accounts`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle <a href=\"https://developers.belvo.com/docs/belvo-api-errors#401-consent_without_accounts\" target=\"_blank\">401 consent_without_accounts errors</a>.\n"
},
"message": {
"type": "string",
"example": "The institution only supports the following resources: EMPLOYMENT_RECORDS, OWNERS",
"description": "A short description of the error. \n\n\nFor `invalid` errors relating to `fetch_resources`, the description is:\n \n - `The institution only supports the following resources: (comma-separated list of supported resources)`.\n"
},
"request_id": {
"type": "string",
"example": "9e7b283c6efa449c9c028a16b5c249fb",
"pattern": "[a-f0-9]{32}",
"description": "A 32-character unique ID of the request (matching a regex pattern of: `[a-f0-9]{32}`). Provide this ID when contacting the Belvo\nsupport team to accelerate investigations.\n"
}
},
"description": "This error occurs when your user has removed accounts associated with the consent they provided. For example, when your user first generated their consent, they had a checking and a loan account at the institution but has closed those accounts since then.\n"
}
AccessToResourceDenied
{
"type": "object",
"title": "Access to Belvo API denied",
"properties": {
"code": {
"type": "string",
"example": "access_to_resource_denied",
"description": "A unique error code (`access_to_resource_denied`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle <a href=\"https://developers.belvo.com/docs/belvo-api-errors#403-access_to_resource_denied\" target=\"_blank\">403 access_to_resource_denied</a>.\n"
},
"message": {
"type": "string",
"example": "You don't have access to this resource.",
"description": "A short description of the error. \n\n\nFor `access_to_resource_denied` errors, the description is:\n \n - `You don't have access to this resource.`.\n"
},
"request_id": {
"type": "string",
"example": "9e7b283c6efa449c9c028a16b5c249fb",
"pattern": "[a-f0-9]{32}",
"description": "A 32-character unique ID of the request (matching a regex pattern of: `[a-f0-9]{32}`). Provide this ID when contacting the Belvo\nsupport team to accelerate investigations.\n"
}
},
"description": "This error occurs when you try to access Belvo's resource without the correct permissions.\n"
}
Account
{
"type": "object",
"title": "Accounts Standard (Multi-Region)",
"nullable": true,
"required": [
"name",
"number",
"type",
"category",
"public_identification_name",
"public_identification_value",
"currency",
"balance",
"balance_type",
"credit_data",
"loan_data",
"collected_at",
"last_accessed_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "0d3ffb69-f83b-456e-ad8e-208d0998d71d",
"description": "The unique identifier created by Belvo used to reference the current\naccount.\n"
},
"link": {
"type": "string",
"example": "30cb4806-6e00-48a4-91c9-ca55968576c8",
"nullable": true,
"description": "The `link.id` the account belongs to."
},
"name": {
"type": "string",
"example": "Cuenta Perfiles- M.N. - MXN-666",
"nullable": true,
"description": "The account name, as given by the institution."
},
"type": {
"type": "string",
"example": "Cuentas de efectivo",
"nullable": true,
"description": "The account type, as designated by the institution."
},
"number": {
"type": "string",
"example": "4057068115181",
"nullable": true,
"description": "The account number, as designated by the institution."
},
"balance": {
"$ref": "#/components/schemas/AccountsBalance"
},
"category": {
"$ref": "#/components/schemas/EnumAccountCategory"
},
"currency": {
"type": "string",
"example": "MXN",
"nullable": true,
"description": "The currency of the account. For example:\n- 🇧🇷 BRL (Brazilian Real)\n- 🇨🇴 COP (Colombian Peso)\n- 🇲🇽 MXN (Mexican Peso)\n\n Please note that other currencies other than in the list above may be returned."
},
"loan_data": {
"$ref": "#/components/schemas/AccountsLoanData"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-02-09T08:45:50.406032Z",
"description": "The ISO-8601 timestamp of when the data point was last updated in Belvo's database.\n"
},
"funds_data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AccountsFundsData"
},
"nullable": true,
"description": "One or more funds that contribute to the the pension account."
},
"credit_data": {
"$ref": "#/components/schemas/AccountsCreditData"
},
"institution": {
"$ref": "#/components/schemas/InstitutionAccount"
},
"balance_type": {
"type": "string",
"example": "ASSET",
"nullable": true,
"description": "Indicates whether this account is either an `ASSET` or a `LIABILITY`. You can consider the balance of an `ASSET` as being positive, while the balance of a `LIABILITY` as negative.\n"
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2019-09-27T13:01:41.941Z",
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"bank_product_id": {
"type": "string",
"example": null,
"nullable": true,
"deprecated": true,
"description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our [Deprecated fields](https://developers.belvo.com/reference/using-the-api-reference#%EF%B8%8F-deprecated-fields) explanation.*\n\n*The institution's product ID for the account type.*\n"
},
"last_accessed_at": {
"type": "string",
"format": "date-time",
"example": "2021-03-09T10:28:40.000Z",
"nullable": true,
"description": "The ISO-8601 timestamp of Belvo's most recent successful access to the institution for the given link.\n"
},
"internal_identification": {
"type": "string",
"example": null,
"nullable": true,
"deprecated": true,
"description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our [Deprecated fields](https://developers.belvo.com/reference/using-the-api-reference#%EF%B8%8F-deprecated-fields) explanation.*\n\n*The institution's internal identification for the account.*\n"
},
"public_identification_name": {
"type": "string",
"example": "CLABE",
"nullable": true,
"description": "The public name for the type of identification. For example: `\"CLABE\"`.\n\nℹ️ For 🇧🇷 Brazilian savings and checking accounts, this field will be `AGENCY/ACCOUNT`.\n"
},
"public_identification_value": {
"type": "string",
"example": "150194683119900273",
"nullable": true,
"description": "The value for the `public_identification_name`.\n\nℹ️ For 🇧🇷 Brazilian savings and checking accounts, this field will be the agency and bank account number, separated by a slash.\nFor example: `0444/45722-0`.\n"
}
},
"description": "Details regarding the account.\n\n**Note**: For our recurring expenses resource, this account relates to the account that was analyzed to generate the recurring expenses report.\n"
}
AccountBalanceOpenFinanceBrazil
{
"type": "object",
"required": [
"current"
],
"properties": {
"blocked": {
"type": "number",
"format": "float",
"example": 60.32,
"pattern": "^\\d{1,15}\\.\\d{2,4}$",
"description": "The amount that is currently blocked due to pending transactions.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `balances` field is available.\n"
},
"current": {
"type": "number",
"format": "float",
"example": 5874.13,
"pattern": "^\\d{1,15}\\.\\d{2,4}$",
"nullable": true,
"description": "The current balance is calculated differently according to the type of account.\n\n\n- **💰 Checking and saving accounts**:\n\n\nThe user's account balance at the `collected_at` timestamp.\n\n- **💳 Credit cards**:\n\n\nThe amount the user has spent in the current card billing period (see `credit_data.cutting_date` for information on when the current billing period finishes).\n\n- **🏡 Loan accounts**:\n\n\nThe amount remaining to pay on the users's loan.\n"
},
"available": {
"type": "number",
"format": "float",
"example": 5621.12,
"pattern": "^\\d{1,15}\\.\\d{2,4}$",
"nullable": true,
"description": "The balance that the account owner can use.\n\n- **💰 Checking and saving accounts**:\n\n\nThe available balance may be different to the `current` balance due to pending transactions.\n\n- **💳 Credit cards**:\n\n\nThe credit amount the user still has available for the current period. The amount is calculated as `credit_data.credit_limit` minus `balance.current`.\n\n- **🏡 Loan accounts**:\n\n\nThe present value required to pay off the loan, as provided by the institution.\n\n\n**Note:** If the institution does not provide this value, we return `null`.\n"
},
"automatically_invested": {
"type": "number",
"format": "float",
"example": 131.5,
"pattern": "^\\d{1,15}\\.\\d{2,4}$",
"description": "The amount that is automatically invested (as agreed upon with the institution).\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `balances` field is available.\n"
}
},
"description": "Details regarding the current and available balances for the account.\n"
}
AccountCreditDataCardsOpenFinanceBrazil
{
"type": "object",
"required": [
"is_multiple",
"identification_number"
],
"properties": {
"is_multiple": {
"type": "boolean",
"example": false,
"description": "Boolean to indicate if this account has multiple credit cards.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"identification_number": {
"type": "string",
"example": "4453",
"pattern": "^[a-zA-Z0-9][a-zA-Z0-9-]{0,99}$",
"maxLength": 100,
"minLength": 1,
"description": "The credit card number.\n\n**Note:** Often, this is just the last four digit of the credit card.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
}
},
"description": "Details regarding all the cards associated with the account."
}
AccountCreditDataLimitsOpenFinanceBrazil
{
"type": "object",
"required": [
"identification_number",
"credit_limit",
"used_amount",
"available_amount",
"is_limit_flexible",
"type",
"consolidation_type",
"line_name",
"line_name_additional_info"
],
"properties": {
"type": {
"$ref": "#/components/schemas/EnumCreditCardLimitType"
},
"line_name": {
"type": "string",
"example": "CREDITO_A_VISTA",
"nullable": true,
"description": "The credit limit line name.\n"
},
"used_amount": {
"type": "number",
"format": "float",
"example": 400.04,
"pattern": "^\\d{1,15}\\.\\d{2,4}$",
"nullable": true,
"description": "The amount used.\n"
},
"credit_limit": {
"type": "number",
"format": "float",
"example": 1000.04,
"pattern": "^\\d{1,15}\\.\\d{2,4}$",
"nullable": true,
"description": "The limit of the credit card.\n"
},
"available_amount": {
"type": "number",
"format": "float",
"example": 600,
"pattern": "^\\d{1,15}\\.\\d{2,4}$",
"description": "The amount still available.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"is_limit_flexible": {
"type": "boolean",
"example": false,
"description": "Boolean to indicate if the `credit_limit` is flexible.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"consolidation_type": {
"type": "string",
"example": "INDIVIDUAL",
"description": "Indicates whether or not the credit limit is consolidated or individual.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"identification_number": {
"type": "string",
"example": "4453",
"pattern": "^[a-zA-Z0-9][a-zA-Z0-9-]{0,99}$",
"nullable": true,
"maxLength": 100,
"minLength": 1,
"description": "The credit card number.\n\n**Note:** Often, this is just the last four digit of the credit card.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"line_name_additional_info": {
"type": "string",
"example": "Informações adicionais e complementares",
"pattern": "[\\w\\W\\s]*",
"nullable": true,
"maxLength": 100,
"description": "Additional information about the line name.\n"
}
},
"description": "Detailed information regarding the credit limits for the credit cards.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
}
AccountCreditDataOpenFinanceBrazil
{
"type": "object",
"nullable": true,
"required": [
"collected_at",
"credit_limit"
],
"properties": {
"cards": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AccountCreditDataCardsOpenFinanceBrazil"
},
"minItems": 1,
"description": "Details regarding the cards associated with the account."
},
"limits": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AccountCreditDataLimitsOpenFinanceBrazil"
}
},
"network": {
"$ref": "#/components/schemas/EnumAccountCreditCardNetwork"
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2019-09-27T13:01:41.941Z",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"credit_limit": {
"type": "number",
"format": "float",
"example": 192000.9,
"pattern": "^\\d{1,15}\\.\\d{2,4}$",
"nullable": true,
"maxLength": 20,
"description": "The upper credit limit of the card.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"cutting_date": {
"type": "string",
"format": "date",
"example": "2019-12-11",
"pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$",
"nullable": true,
"maxLength": 10,
"description": "The date when the credit card's bill is due."
},
"interest_rate": {
"type": "number",
"format": "float",
"example": null,
"nullable": true,
"description": "**Note:** This field is not applicable for OF Brazil and will return null.\n"
},
"minimum_payment": {
"type": "number",
"format": "float",
"example": 2400.3,
"pattern": "^\\d{1,15}\\.\\d{2,4}$",
"nullable": true,
"maxLength": 20,
"description": "The minimum amount that the account owner needs to pay in the current credit period.\n"
},
"monthly_payment": {
"type": "number",
"example": null,
"nullable": true,
"deprecated": true,
"description": "**Note:** This field is not applicable for OF Brazil and will return null.\n"
},
"last_payment_date": {
"type": "string",
"example": null,
"nullable": true,
"deprecated": true,
"description": "**Note:** This field is not applicable for OF Brazil and will return null.\n"
},
"next_payment_date": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note:** This field is not applicable for OF Brazil and will return null.\n"
},
"no_interest_payment": {
"type": "number",
"format": "float",
"example": null,
"nullable": true,
"description": "**Note:** This field is not applicable for OF Brazil and will return null.\n"
},
"network_additional_info": {
"type": "string",
"example": "It's an orange card.",
"pattern": "[\\w\\W\\s]*",
"nullable": true,
"maxLength": 100,
"description": "Additional information about the credit card network.\n"
}
},
"description": "Details regarding the credit cards associated with this account."
}
AccountLoanDataBalloonPaymentsOpenFinanceBrazil
{
"type": "object",
"nullable": true,
"required": [
"due_date",
"currency",
"amount"
],
"properties": {
"amount": {
"type": "number",
"format": "float",
"example": 45391.89,
"pattern": "^\\d{1,15}\\.\\d{2,4}$",
"nullable": true,
"description": "The total amount of the balloon payment.\n"
},
"currency": {
"type": "string",
"example": "BRL",
"pattern": "^[A-Z]{3}$",
"nullable": true,
"maxLength": 3,
"description": "The three-letter currency code (ISO-4217).\n"
},
"due_date": {
"type": "string",
"format": "date",
"example": "2021-09-06",
"pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$",
"nullable": true,
"maxLength": 10,
"description": "The date that the balloon payment is to be paid, in `YYYY-MM-DD` format.\n"
}
},
"description": "Detailed information regarding any balloon payments for the loan, if applicable."
}
AccountLoanDataCollateralsOpenFinanceBrazil
{
"type": "object",
"nullable": true,
"required": [
"type",
"subtype",
"currency",
"amount"
],
"properties": {
"type": {
"type": "string",
"example": "OPERACOES_GARANTIDAS_PELO_GOVERNO",
"description": "The type of collateral, as defined by the institution.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `collaterals` field is available.\n"
},
"amount": {
"type": "number",
"format": "float",
"example": 45391.89,
"pattern": "^\\d{1,15}\\.\\d{2,4}$",
"description": "The total amount of the bill.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `collaterals` field is available.\n"
},
"subtype": {
"type": "string",
"example": "CCR_CONVENIO_CREDITOS_RECIPROCOS",
"description": "The subtype of the collateral, as defined by the institution.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `collaterals` field is available.\n"
},
"currency": {
"type": "string",
"example": "BRL",
"pattern": "^[A-Z]{3}$",
"maxLength": 3,
"description": "The three-letter currency code (ISO-4217).\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `collaterals` field is available.\n"
}
},
"description": "Details regarding any loan collaterals that the individual or business supplied."
}
AccountLoanDataContractedChargesOpenFinanceBrazil
{
"type": "object",
"nullable": true,
"properties": {
"info": {
"type": "string",
"example": "Late fee",
"pattern": "^[\\w\\W\\s]{0,140}$",
"nullable": true,
"maxLength": 140,
"description": "Additional information regarding the contracted charge.\n"
},
"rate": {
"type": "number",
"format": "float",
"example": 0.062,
"pattern": "^[01]\\.\\d{6}$",
"nullable": true,
"description": "The percentage rate of the charge, calculated based on the amount of the loan.\n"
},
"type": {
"$ref": "#/components/schemas/EnumAccountLoanDataContractedChargeType"
}
},
"description": "Details regarding any contracted charges.\n"
}
AccountLoanDataFeesOpenFinanceBrazil
{
"type": "object",
"nullable": true,
"required": [
"type",
"value",
"name",
"code",
"fee_charge_type",
"fee_charge",
"rate"
],
"properties": {
"code": {
"type": "string",
"example": "CADASTRO",
"pattern": "^[\\w\\W\\s]{0,140}$",
"maxLength": 140,
"description": "The fee code.\n\n > **Non-nullable:** A value must be returned by Brazil's open finance network if the `fees` field is available.\n"
},
"name": {
"type": "string",
"example": "Renovação de cadastro",
"pattern": "^[\\w\\W\\s]{0,140}$",
"maxLength": 140,
"description": "The fee name.\n\n > **Non-nullable:** A value must be returned by Brazil's open finance network if the `fees` field is available.\n"
},
"rate": {
"type": "number",
"format": "float",
"example": 0.062,
"pattern": "^[01]\\.\\d{6}$",
"nullable": true,
"description": "The percentage rate of the fee. Required when `fee_charge` is set to `PERCENTAGE`.\n"
},
"type": {
"$ref": "#/components/schemas/EnumAccountLoanDataFeeType"
},
"value": {
"type": "number",
"format": "float",
"example": 5.6,
"pattern": "^\\d{1,15}\\.\\d{2,4}$",
"nullable": true,
"description": "The total value of the fee. Same currency as the loan.\n"
},
"fee_charge": {
"$ref": "#/components/schemas/EnumAccountLoanDataFeeCharge"
},
"fee_charge_type": {
"$ref": "#/components/schemas/EnumAccountLoanDataFeeChargeType"
}
},
"description": "Breakdown of the fees applied to the loan."
}
AccountLoanDataInterestRateDataOpenFinanceBrazil
{
"type": "object",
"nullable": true,
"required": [
"tax_type",
"rate_type",
"calculation_base",
"reference_index_type",
"reference_index_subtype",
"reference_index_info",
"pre_fixed_rate",
"post_fixed_rate",
"additional_info"
],
"properties": {
"type": {
"$ref": "#/components/schemas/EnumAccountLoanDataInterestRateType"
},
"tax_type": {
"$ref": "#/components/schemas/EnumAccountLoanDataInterestRateDataTaxType"
},
"rate_type": {
"$ref": "#/components/schemas/EnumAccountLoanDataInterestRateDataRateType"
},
"pre_fixed_rate": {
"type": "number",
"format": "float",
"example": 0.062,
"pattern": "^[01]\\.\\d{6}$",
"description": "The pre-fixed percentage rate of the interest rate.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"additional_info": {
"type": "string",
"example": "Additional information",
"pattern": "[\\w\\W\\s]*",
"nullable": true,
"maxLength": 1200,
"description": "Additional information regarding the interest rate.\n"
},
"post_fixed_rate": {
"type": "number",
"format": "float",
"example": 0.062,
"pattern": "^[01]\\.\\d{6}$",
"description": "The post-fixed percentage rate of the interest rate.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"calculation_base": {
"type": "string",
"example": "30/360",
"pattern": "^[0-9]{2}\\/[0-9]{3}$",
"description": "The base calculation for the interest rate.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"reference_index_info": {
"type": "string",
"example": "Additional information",
"pattern": "^[\\w\\W\\s]{0,140}$",
"nullable": true,
"maxLength": 140,
"description": "Additional information regarding the reference index rate.\n"
},
"reference_index_type": {
"$ref": "#/components/schemas/EnumAccountLoanDataInterestRateDataReferenceIndexType"
},
"reference_index_subtype": {
"type": "string",
"example": "TR_TBF",
"nullable": true,
"description": "The subtype of the reference index rate.\n"
}
},
"description": "Detailed information regarding the interest rate."
}
AccountLoanDataInterestRateOpenFinanceBrazil
{
"type": "object",
"required": [
"name",
"type",
"value",
"interest_rate_data"
],
"properties": {
"name": {
"type": "string",
"example": "NOMINAL",
"nullable": true,
"description": "The name of the type of interest rate applied to the loan.\n\n**Note:** For OFDA Brazil, we recommend you use the `interest_date_data.tax_type` parameter.\n"
},
"type": {
"$ref": "#/components/schemas/EnumAccountLoanDataInterestRateType"
},
"value": {
"type": "number",
"format": "float",
"example": 7.85,
"nullable": true,
"description": "The interest rate (in percent or currency value).\n\n**Note:** For OFDA Brazil, we recommend you use the `interest_date_data.pre_fixed_rate` and `interest_date_data.post_fixed_rate`parameter.\n"
},
"interest_rate_data": {
"$ref": "#/components/schemas/AccountLoanDataInterestRateDataOpenFinanceBrazil"
}
},
"description": "Breakdown of the interest applied to the loan. With OF Brazil, we highly recommend using the `interest_rate_data` object for in-depth information.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
}
AccountLoanDataOpenFinanceBrazil
{
"type": "object",
"nullable": true,
"required": [
"collected_at",
"loan_code",
"contract_amount",
"total_effectove_cost",
"loan_type",
"outstanding_balance",
"interest_rates",
"fees",
"collaterals",
"balloon_payments",
"installments_contract_term_frequency",
"installment_frequency",
"installment_frequency_info",
"first_installment_due_date",
"number_of_installments_total",
"number_of_installments_outstanding",
"number_of_installments_paid",
"number_of_installments_past_due",
"disbursement_dates",
"settlement_date",
"contract_start_date",
"contract_end_date",
"contract_remaining_frequency",
"contract_remaining_total",
"amortization_schedule",
"amortization_schedule_info",
"consignee_id",
"contract_number",
"monthly_payment",
"principal",
"payment_day",
"outstanding_principal",
"credit_limit",
"last_period_balance",
"interest_rate",
"limit_day",
"cutting_day",
"cutting_date",
"last_payment_date",
"no_interest_payment"
],
"properties": {
"fees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AccountLoanDataFeesOpenFinanceBrazil"
},
"nullable": true,
"description": "Breakdown of the fees applied to the loan.\n"
},
"limit_day": {
"type": "string",
"example": null,
"nullable": true,
"deprecated": true,
"description": "**Note:** This field is not applicable for OF Brazil and will return null.\n"
},
"loan_code": {
"type": "string",
"example": "92792126019929279212650822221989319252576",
"pattern": "^\\d{22,67}$",
"maxLength": 67,
"minLength": 22,
"description": "The country-specific standardized contract number.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"loan_type": {
"type": "string",
"example": "HOME_EQUITY",
"description": "The type of the loan, according to the institution.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"principal": {
"type": "number",
"format": "float",
"example": null,
"nullable": true,
"description": "**Note:** This field is not applicable for OF Brazil and will return null.\n"
},
"collaterals": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AccountLoanDataCollateralsOpenFinanceBrazil"
},
"nullable": true,
"description": "Details regarding any loan collaterals that the individual or business supplied.\n"
},
"cutting_day": {
"type": "string",
"example": null,
"nullable": true,
"deprecated": true,
"description": "**Note:** This field is not applicable for OF Brazil and will return null.\n"
},
"payment_day": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note:** This field is not applicable for OF Brazil and will return null.\n"
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2022-02-09T08:45:50.406032Z",
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"consignee_id": {
"type": "string",
"example": "60500998000135",
"pattern": "^\\d{14}$",
"nullable": true,
"maxLength": 14,
"description": "The ID of the consignee of the loan.\n"
},
"credit_limit": {
"type": "number",
"example": null,
"nullable": true,
"deprecated": true,
"description": "**Note:** This field is not applicable for OF Brazil and will return null.\n"
},
"cutting_date": {
"type": "string",
"example": null,
"nullable": true,
"deprecated": true,
"description": "**Note:** This field is not applicable for OF Brazil and will return null.\n"
},
"interest_rate": {
"type": "number",
"example": null,
"nullable": true,
"deprecated": true,
"description": "**Note:** This field is not applicable for OF Brazil and will return null.\n"
},
"interest_rates": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AccountLoanDataInterestRateOpenFinanceBrazil"
},
"description": "Breakdown of the interest applied to the loan. With OF Brazil, we highly recommend using the information in `interest_rate_data` for in-depth information.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"contract_amount": {
"type": "number",
"format": "float",
"example": 202000,
"pattern": "^\\d{1,15}\\.\\d{2,4}$",
"nullable": true,
"description": "The initial total loan amount when the contract was signed, calculated by the institution. This amount includes the principal + interest + taxes + fees.\n"
},
"contract_number": {
"type": "string",
"example": "1324926521496",
"pattern": "^\\d{1,100}$",
"nullable": true,
"maxLength": 100,
"minLength": 1,
"description": "The contract number of the loan, as given by the institution.\n"
},
"monthly_payment": {
"type": "number",
"format": "float",
"example": null,
"nullable": true,
"description": "**Note:** This field is not applicable for OF Brazil and will return null.\n"
},
"settlement_date": {
"type": "string",
"example": "2021-09-23",
"pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$",
"nullable": true,
"maxLength": 10,
"description": "The date that the loan was settled, in `YYYY-MM-DD` format.\n"
},
"balloon_payments": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AccountLoanDataBalloonPaymentsOpenFinanceBrazil"
},
"nullable": true,
"description": "Detailed information regarding any balloon payments for the loan, if applicable.\n"
},
"contract_end_date": {
"type": "string",
"format": "date",
"example": "2027-10-01",
"pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$",
"nullable": true,
"maxLength": 10,
"description": "The date when the loan is expected to be completed, in `YYYY-MM-DD` format.\n"
},
"last_payment_date": {
"type": "string",
"example": null,
"nullable": true,
"deprecated": true,
"description": "**Note:** This field is not applicable for OF Brazil and will return null.\n"
},
"contracted_charges": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AccountLoanDataContractedChargesOpenFinanceBrazil"
},
"nullable": true,
"description": ""
},
"disbursement_dates": {
"type": "array",
"items": {
"type": "string",
"example": "2021-09-23",
"pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$",
"nullable": true,
"maxLength": 10,
"description": "The date that the loan was disbursed, in `YYYY-MM-DD` format.\n"
},
"minItems": 1,
"nullable": true,
"description": "An array of dates when the loan was disbursed.\n"
},
"contract_start_date": {
"type": "string",
"format": "date",
"example": "2020-03-01",
"pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$",
"maxLength": 10,
"description": "The date when the loan contract was signed, in `YYYY-MM-DD` format.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"last_period_balance": {
"type": "number",
"example": null,
"nullable": true,
"deprecated": true,
"description": "**Note:** This field is not applicable for OF Brazil and will return null.\n"
},
"no_interest_payment": {
"type": "number",
"example": null,
"nullable": true,
"deprecated": true,
"description": "**Note:** This field is not applicable for OF Brazil and will return null.\n"
},
"outstanding_balance": {
"type": "number",
"format": "float",
"example": 182000,
"pattern": "^\\d{1,15}\\.\\d{2,4}$",
"nullable": true,
"maxLength": 20,
"minLength": 4,
"description": "The amount remaining to pay in total, including interest.\n"
},
"total_effective_cost": {
"type": "number",
"format": "float",
"example": 209000,
"pattern": "^\\d{1,15}\\.\\d{2,4}$",
"nullable": true,
"description": "The initial total effective cost of the loan.\n"
},
"amortization_schedule": {
"type": "string",
"example": "SEM_SISTEMA_AMORTIZACAO",
"description": "The loan amortization schedule.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"installment_frequency": {
"$ref": "#/components/schemas/EnumAccountLoanDataInstallmentFrequency"
},
"outstanding_principal": {
"type": "number",
"format": "float",
"example": null,
"nullable": true,
"description": "**Note:** This field is not applicable for OF Brazil and will return null.\n"
},
"contract_remaining_total": {
"type": "integer",
"format": "int32",
"example": 20,
"maximum": 999999999,
"nullable": true,
"description": "The total number of installments remaining on the loan.\n"
},
"amortization_schedule_info": {
"type": "string",
"example": "No need for a schedule.",
"pattern": "[\\w\\W\\s]*",
"nullable": true,
"maxLength": 200,
"description": "Additional information regarding the `amortization_schedule`.\n"
},
"first_installment_due_date": {
"type": "string",
"format": "date",
"example": "2020-03-01",
"pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$",
"nullable": true,
"maxLength": 10,
"description": "The date when the first installment of the loan is to be paid, in `YYYY-MM-DD` format.\n"
},
"installment_frequency_info": {
"type": "string",
"example": "Both the term and requency are the same.",
"pattern": "^[\\w\\W\\s]{0,99}$$",
"nullable": true,
"maxLength": 100,
"description": "Additional information regarding the `installment_frequency`.\n"
},
"number_of_installments_paid": {
"type": "integer",
"format": "int32",
"example": 32,
"maximum": 999999999,
"nullable": true,
"description": "The number of installments already paid.\n"
},
"contract_remaining_frequency": {
"$ref": "#/components/schemas/EnumAccountLoanDataContractRemainingFrequency"
},
"number_of_installments_total": {
"type": "integer",
"format": "int32",
"example": 60,
"maximum": 999999999,
"nullable": true,
"description": "The total number of installments required to pay the loan.\n"
},
"number_of_installments_past_due": {
"type": "integer",
"format": "int32",
"example": 2,
"maximum": 999,
"nullable": true,
"description": "The number of installments that are overdue.\n"
},
"number_of_installments_outstanding": {
"type": "integer",
"format": "int32",
"example": 48,
"maximum": 999999999,
"nullable": true,
"description": "The number of installments left to pay.\n"
},
"installments_contract_term_frequency": {
"$ref": "#/components/schemas/EnumAccountsLoanDataContractInstallmentFrequency"
}
},
"description": "The loan options associated with this account."
}
AccountOpenFinanceBrazil
{
"type": "object",
"title": "Accounts (OFDA Brazil)",
"nullable": true,
"required": [
"id",
"link",
"institution",
"collected_at",
"created_at",
"last_accessed_at",
"category",
"balance_type",
"type",
"subtype",
"name",
"number",
"agency",
"check_digit",
"balance",
"currency",
"public_identification_name",
"public_identification_value",
"internal_identification",
"credit_data",
"loan_data",
"funds_data"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "0d3ffb69-f83b-456e-ad8e-208d0998d71d",
"description": "The unique identifier created by Belvo for the current\naccount.\n"
},
"link": {
"type": "string",
"example": "30cb4806-6e00-48a4-91c9-ca55968576c8",
"nullable": true,
"description": "The `link.id` the account belongs to."
},
"name": {
"type": "string",
"example": "Cuenta Perfiles- M.N. - MXN-666",
"nullable": true,
"description": "The account name, as given by the institution."
},
"type": {
"type": "string",
"example": "STANDARD_NACIONAL",
"description": "The account type, as designated by the institution.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"agency": {
"type": "string",
"example": "6272",
"pattern": "^\\d{1,4}$",
"nullable": true,
"maxLength": 4,
"description": "The branch code where the product was opened.\n"
},
"number": {
"type": "string",
"example": "4057068115181",
"nullable": true,
"description": "The account number, as designated by the institution.\n"
},
"balance": {
"$ref": "#/components/schemas/AccountBalanceOpenFinanceBrazil"
},
"subtype": {
"type": "string",
"example": "FINANCIAMENTO_HABITACIONAL_SFH",
"description": "The account subtype, as designated by the institution.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"category": {
"$ref": "#/components/schemas/EnumAccountCategoryOpenFinance"
},
"currency": {
"type": "string",
"example": "BRL",
"pattern": "^[A-Z]{3}$",
"maxLength": 3,
"description": "The three-letter currency code (ISO-4217).\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `balances` field is available.\n"
},
"loan_data": {
"$ref": "#/components/schemas/AccountLoanDataOpenFinanceBrazil"
},
"overdraft": {
"$ref": "#/components/schemas/AccountOverdraftOpenFinanceBrazil"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-02-09T08:45:50.406032Z",
"description": "The ISO-8601 timestamp of when the data point was created in Belvo's database.\n"
},
"funds_data": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note:** This field is not applicable for OF Brazil and will return null.\n"
},
"check_digit": {
"type": "string",
"example": "7",
"pattern": "[\\w\\W\\s]*",
"nullable": true,
"maxLength": 2,
"description": "The check digit of the product's number, if applicable.\n"
},
"credit_data": {
"$ref": "#/components/schemas/AccountCreditDataOpenFinanceBrazil"
},
"institution": {
"$ref": "#/components/schemas/InstitutionAccount"
},
"balance_type": {
"type": "string",
"example": "ASSET",
"nullable": true,
"description": "Indicates whether this account is either an `ASSET` or a `LIABILITY`. You can consider the balance of an `ASSET` as being positive, while the balance of a `LIABILITY` as negative.\n"
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2019-09-27T13:01:41.941Z",
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"last_accessed_at": {
"type": "string",
"format": "date-time",
"example": "2021-03-09T10:28:40.000Z",
"nullable": true,
"description": "The ISO-8601 timestamp of Belvo's most recent successful access to the institution for the given link.\n"
},
"internal_identification": {
"type": "string",
"example": "92792126019929279212650822221989319252576",
"pattern": "^[a-zA-Z0-9][a-zA-Z0-9-]{0,99}$",
"maxLength": 100,
"description": "The institution's internal identification for the account.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `balances` field is available.\n"
},
"public_identification_name": {
"type": "string",
"example": "AGENCY/ACCOUNT",
"nullable": true,
"description": "The public name for the type of identification. For 🇧🇷 Brazilian savings and checking accounts, this field will be `AGENCY/ACCOUNT`.\n"
},
"public_identification_value": {
"type": "string",
"example": "0444/45722-0",
"nullable": true,
"description": "The value for the `public_identification_name`.\n\nFor 🇧🇷 OFDA Brazilian savings and checking accounts, this field will be the agency and bank account number, separated by a slash. For example: `0444/45722-0`.\n\nFor 🇧🇷 OFDA Brazilian credit card accounts, we will return a string of concatenated credit card numbers associated with the account. For example: \"8763,9076,5522\"\n"
}
},
"description": "Details regarding the account.\n"
}
AccountOverdraftOpenFinanceBrazil
{
"type": "object",
"nullable": true,
"required": [
"arranged",
"used",
"unarranged"
],
"properties": {
"used": {
"type": "number",
"format": "float",
"example": 1000.5,
"pattern": "^\\d{1,15}\\.\\d{2,4}$",
"description": "The overdraft value used.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `overdraft` field is available.\n"
},
"arranged": {
"type": "number",
"format": "float",
"example": 5000.5,
"pattern": "^\\d{1,15}\\.\\d{2,4}$",
"description": "The agreed upon overdraft limit between the account holder and the institution.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `overdraft` field is available.\n"
},
"unarranged": {
"type": "number",
"format": "float",
"example": 300.1,
"pattern": "^\\d{1,15}\\.\\d{2,4}$",
"description": "The overdraft used that was not arranged between the account holder and the institution.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `overdraft` field is available.\n"
}
}
}
AccountsBalance
{
"type": "object",
"required": [
"current"
],
"properties": {
"current": {
"type": "number",
"format": "float",
"example": 5874.13,
"nullable": true,
"description": "The current balance is calculated differently according to the type of account.\n\n\n- **💰 Checking and saving accounts**:\n\n\nThe user's account balance at the `collected_at` timestamp.\n\n- **💳 Credit cards**:\n\n\nThe amount the user has spent in the current card billing period (see `credit_data.cutting_date` for information on when the current billing period finishes).\n\n- **🏡 Loan accounts**:\n\n\nThe amount remaining to pay on the users's loan.\n"
},
"available": {
"type": "number",
"format": "float",
"example": 5621.12,
"nullable": true,
"description": "The balance that the account owner can use.\n\n- **💰 Checking and saving accounts**:\n\n\nThe available balance may be different to the `current` balance due to pending transactions.\n\n- **💳 Credit cards**:\n\n\nThe credit amount the user still has available for the current period. The `available` balance may be different to the `current` balance due to pending transactions or future instalments.\n\n- **🏡 Loan accounts**:\n\n\nThe present value required to pay off the loan, as provided by the institution.\n\n\n**Note:** If the institution does not provide this value, we return `null`.\n"
}
},
"description": "Details regarding the current and available balances for the account.\n"
}
AccountsCreateLinkAccounts201Response
{
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/Account"
},
{
"$ref": "#/components/schemas/AccountOpenFinanceBrazil"
}
]
}
}
AccountsCreateLinkAccounts400Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
}
]
}
}
AccountsCreateLinkAccounts401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
AccountsCreateLinkAccounts408Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RequestTimeoutError"
},
"title": "Request Timeout",
"description": "Belvo has a limit regarding the time it takes to log in, retrieve account data, and log out. A timeout occurs when there is a very high amount of data and everything could not be obtained within the allotted time.\n \n"
}
AccountsCreateLinkAccounts428Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenRequiredResponse"
}
}
AccountsCreateLinkAccounts500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
AccountsCreateLinkAccountsResponse
{
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/Account"
},
{
"$ref": "#/components/schemas/AccountOpenFinanceBrazil"
}
]
}
}
AccountsCreditData
{
"type": "object",
"nullable": true,
"required": [
"credit_limit",
"cutting_date",
"next_payment_date",
"minimum_payment",
"no_interest_payment",
"interest_rate",
"collected_at"
],
"properties": {
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2019-09-27T13:01:41.941Z",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"credit_limit": {
"type": "number",
"format": "float",
"example": 192000,
"nullable": true,
"description": "The maximum amount of credit the owner can receive."
},
"cutting_date": {
"type": "string",
"example": "2019-12-11",
"nullable": true,
"description": "The closing date of the credit period, in `YYYY-MM-DD` format."
},
"interest_rate": {
"type": "number",
"format": "float",
"example": 4,
"nullable": true,
"description": "The annualized interest rate of the credit."
},
"minimum_payment": {
"type": "number",
"format": "float",
"example": 2400.3,
"nullable": true,
"description": "The minimum amount to be paid on the `next_payment_date`."
},
"monthly_payment": {
"type": "number",
"example": null,
"nullable": true,
"deprecated": true,
"description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our [Deprecated fields](https://developers.belvo.com/reference/using-the-api-reference#%EF%B8%8F-deprecated-fields) explanation.*\n\n*The recurrent monthly payment, if applicable.*\n"
},
"last_payment_date": {
"type": "string",
"example": null,
"nullable": true,
"deprecated": true,
"description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our [Deprecated fields](https://developers.belvo.com/reference/using-the-api-reference#%EF%B8%8F-deprecated-fields) explanation.*\n\n\n*The date when the last credit payment was made, in `YYYY-MM-DD` format.*\n"
},
"next_payment_date": {
"type": "string",
"example": "2019-12-13",
"description": "The due date for the next payment , in `YYYY-MM-DD` format."
},
"last_period_balance": {
"type": "string",
"example": null,
"nullable": true,
"deprecated": true,
"description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our [Deprecated fields](https://developers.belvo.com/reference/using-the-api-reference#%EF%B8%8F-deprecated-fields) explanation.*\n\n\n*The balance remaining after the `last_payment_date`.*\n"
},
"no_interest_payment": {
"type": "number",
"format": "float",
"example": 2690.83,
"nullable": true,
"description": "The minimum amount required to pay to avoid generating interest."
}
},
"description": "The credit options associated with this account."
}
AccountsDeleteSpecificAccount404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
AccountsDeleteSpecificAccountResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
AccountsFundsData
{
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "FIX X",
"nullable": true,
"description": "The pension fund name."
},
"type": {
"type": "string",
"example": "CNPJ",
"nullable": true,
"description": "Type of pension fund."
},
"balance": {
"type": "number",
"format": "float",
"example": 88427.94,
"nullable": true,
"description": "The amount in the fund."
},
"percentage": {
"type": "number",
"format": "float",
"example": 100,
"nullable": true,
"description": "How much this fund, as a percentage, contributes to the pension\naccount's total.\n"
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2020-04-23T21:32:55.336854+00:00",
"description": "The ISO-8601 timestamp when the data point was collected."
},
"public_identifications": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AccountsFundsDataPublicIdentifications"
},
"nullable": true,
"description": "The fund's public IDs."
}
}
}
AccountsFundsDataPublicIdentifications
{
"type": "object",
"required": [
"name",
"value"
],
"properties": {
"name": {
"type": "string",
"example": "CNPJ",
"description": "The type of identification number for the fund."
},
"value": {
"type": "string",
"example": "05.954.445/0221-68",
"nullable": true,
"description": "The fund's identification number."
}
}
}
AccountsGetDetails401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
AccountsGetDetails404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
AccountsGetDetailsResponse
{
"oneOf": [
{
"$ref": "#/components/schemas/Account"
},
{
"$ref": "#/components/schemas/AccountOpenFinanceBrazil"
}
]
}
AccountsListAll401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
AccountsListAllResponse
{
"oneOf": [
{
"$ref": "#/components/schemas/AccountsPaginatedResponse"
},
{
"$ref": "#/components/schemas/AccountsPaginatedResponseOpenFinanceBrazil"
}
]
}
AccountsLoanData
{
"type": "object",
"nullable": true,
"required": [
"principal",
"monthly_payment",
"outstanding_balance",
"interest_rates",
"collected_at"
],
"properties": {
"fees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AccountsLoanDataFees"
},
"nullable": true,
"description": "Breakdown of the fees applied to the loan."
},
"limit_day": {
"type": "string",
"example": null,
"nullable": true,
"deprecated": true,
"description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our [Deprecated fields](https://developers.belvo.com/reference/using-the-api-reference#%EF%B8%8F-deprecated-fields) explanation.*\n\nPlease see `payment_day` instead.\n"
},
"loan_type": {
"type": "string",
"example": "Consignado",
"nullable": true,
"description": "The type of the loan, according to the institution."
},
"principal": {
"type": "number",
"format": "float",
"example": 192000,
"nullable": true,
"description": "Total amount of the loan (the amount the user receives)."
},
"cutting_day": {
"type": "string",
"example": null,
"nullable": true,
"deprecated": true,
"description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our [Deprecated fields](https://developers.belvo.com/reference/using-the-api-reference#%EF%B8%8F-deprecated-fields) explanation.*\n\nThe closing day of the month for the loan.\n"
},
"payment_day": {
"type": "string",
"example": "27",
"nullable": true,
"description": "The day of the month by which the owner needs to pay the loan (`DD`)."
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2022-02-09T08:45:50.406032Z",
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"credit_limit": {
"type": "number",
"example": null,
"nullable": true,
"deprecated": true,
"description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our [Deprecated fields](https://developers.belvo.com/reference/using-the-api-reference#%EF%B8%8F-deprecated-fields) explanation.*\n\nPlease see `principal` instead.\n"
},
"cutting_date": {
"type": "string",
"example": null,
"nullable": true,
"deprecated": true,
"description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our [Deprecated fields](https://developers.belvo.com/reference/using-the-api-reference#%EF%B8%8F-deprecated-fields) explanation.*\n\nThe closing date of the loan period, in `YYYY-MM-DD` format.\n"
},
"interest_rate": {
"type": "number",
"example": null,
"nullable": true,
"deprecated": true,
"description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our [Deprecated fields](https://developers.belvo.com/reference/using-the-api-reference#%EF%B8%8F-deprecated-fields) explanation.*\n\nPlease see the `interest_rates` object instead.\n"
},
"interest_rates": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AccountsLoanDataInterestRate"
},
"nullable": true,
"description": "Breakdown of the interest applied to the loan."
},
"contract_amount": {
"type": "number",
"format": "float",
"example": 202000,
"nullable": true,
"description": "The initial total loan amount, calculated by the institution, when the contract was signed. This amount includes the principal + interest + taxes + fees."
},
"contract_number": {
"type": "string",
"example": "890ASLDJF87SD00",
"nullable": true,
"description": "The contract number of the loan, as given by the institution."
},
"monthly_payment": {
"type": "number",
"format": "float",
"example": 1000,
"nullable": true,
"description": "The recurrent monthly payment, if applicable."
},
"contract_end_date": {
"type": "string",
"format": "date",
"example": "2027-10-01",
"description": "The date when the loan is expected to be completed, in `YYYY-MM-DD` format."
},
"last_payment_date": {
"type": "string",
"nullable": true,
"deprecated": true,
"description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our [Deprecated fields](https://developers.belvo.com/reference/using-the-api-reference#%EF%B8%8F-deprecated-fields) explanation.*\n\nThe date when the last loan payment was made, in `YYYY-MM-DD` format.\n"
},
"next_payment_date": {
"type": "string",
"example": null,
"nullable": true,
"deprecated": true,
"description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our [Deprecated fields](https://developers.belvo.com/reference/using-the-api-reference#%EF%B8%8F-deprecated-fields) explanation.*\n\nPlease use `payment_day` instead, in `YYYY-MM-DD` format.\n"
},
"contract_start_date": {
"type": "string",
"example": "2020-03-01",
"nullable": true,
"description": "The date when the loan contract was signed , in `YYYY-MM-DD` format."
},
"last_period_balance": {
"type": "number",
"example": null,
"nullable": true,
"deprecated": true,
"description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our [Deprecated fields](https://developers.belvo.com/reference/using-the-api-reference#%EF%B8%8F-deprecated-fields) explanation.*\n\nPlease see `outstanding_balance` instead.\n"
},
"no_interest_payment": {
"type": "number",
"example": null,
"nullable": true,
"deprecated": true,
"description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our [Deprecated fields](https://developers.belvo.com/reference/using-the-api-reference#%EF%B8%8F-deprecated-fields) explanation.*\n\nThe minimum amount required to pay to avoid generating interest.\n"
},
"outstanding_balance": {
"type": "number",
"format": "float",
"example": 182000,
"nullable": true,
"description": "The amount remaining to pay in total, including interest."
},
"outstanding_principal": {
"type": "number",
"format": "float",
"example": 142023,
"nullable": true,
"description": "Outstanding loan amount, that is, how much remains to pay on the principal (not including interest).\n"
},
"number_of_installments_total": {
"type": "integer",
"format": "int32",
"example": 60,
"nullable": true,
"description": "The total number of installments required to pay the loan."
},
"number_of_installments_outstanding": {
"type": "integer",
"format": "int32",
"example": 48,
"nullable": true,
"description": "The number of installments left to pay."
}
},
"description": "The loan options associated with this account."
}
AccountsLoanDataFees
{
"type": "object",
"nullable": true,
"required": [
"type",
"value"
],
"properties": {
"type": {
"$ref": "#/components/schemas/EnumLoanDataFeeType"
},
"value": {
"type": "number",
"format": "float",
"example": 5.6,
"description": "The total value of the fee. Same currency of the Loan.\n"
}
},
"description": "Breakdown of the fees applied to the loan."
}
AccountsLoanDataInterestRate
{
"type": "object",
"required": [
"name",
"type",
"value"
],
"properties": {
"name": {
"type": "string",
"example": "jurosEfetivo",
"nullable": true,
"description": "The name of the type of interest rate applied to the loan."
},
"type": {
"$ref": "#/components/schemas/EnumLoanDataInterestRateType"
},
"value": {
"type": "number",
"format": "float",
"example": 7.85,
"nullable": true,
"description": "The interest rate (in percent or currency value)."
}
},
"description": "Breakdown of the interest applied to the loan."
}
AccountsPaginatedResponse
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/common_pagination_properties"
},
{
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Account"
},
"description": "An array of Account objects."
}
}
}
],
"title": "Accounts Standard (Multi-Region)"
}
AccountsPaginatedResponseOpenFinanceBrazil
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/common_pagination_properties"
},
{
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AccountOpenFinanceBrazil"
},
"description": "An array of account objects."
}
}
}
],
"title": "Accounts (OFDA Brazil)"
}
AccountsResumeRetrieveSession201Response
{
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/Account"
},
{
"$ref": "#/components/schemas/AccountOpenFinanceBrazil"
}
]
}
}
AccountsResumeRetrieveSession400Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
}
]
}
}
AccountsResumeRetrieveSession401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
AccountsResumeRetrieveSession408Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RequestTimeoutError"
},
"title": "Request Timeout",
"description": "Belvo has a limit regarding the time it takes to log in, retrieve account data, and log out. A timeout occurs when there is a very high amount of data and everything could not be obtained within the allotted time.\n \n"
}
AccountsResumeRetrieveSession428Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenRequiredResponse"
}
}
AccountsResumeRetrieveSession500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
AccountsResumeRetrieveSessionResponse
{
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/Account"
},
{
"$ref": "#/components/schemas/AccountOpenFinanceBrazil"
}
]
}
}
AnnualCostsAndDeductionsStatementBusiness
{
"type": "object",
"required": [
"costs",
"administration_expenses",
"distribution_and_sales_expenses",
"financial_expenses",
"total_costs_and_deductible_expenses"
],
"properties": {
"costs": {
"type": "number",
"format": "float",
"example": 1881843000,
"description": "Total costs for the company to operate."
},
"financial_expenses": {
"type": "number",
"format": "float",
"example": 0,
"description": "Total value of any fees incurred by the company to operate (such as bank fees)."
},
"administration_expenses": {
"type": "number",
"format": "float",
"example": 3266000,
"description": "Total costs of the company related to training, company offsites, or similar."
},
"distribution_and_sales_expenses": {
"type": "number",
"format": "float",
"example": 0,
"description": "Total costs the company incurred in order to distribute or sell their product."
},
"total_costs_and_deductible_expenses": {
"type": "number",
"format": "float",
"example": 191449000,
"description": "Total value of all costs and dedictible expenses."
}
},
"description": "Object containing the reported annual costs and applicable deductions."
}
AnnualIncomeStatementBusiness
{
"type": "object",
"required": [
"gross_income_from_ordinary_activities",
"dividends",
"other_income",
"total_gross_income",
"returns_rebates_and_discounts_on_sales",
"total_net_income"
],
"properties": {
"dividends": {
"type": "number",
"format": "float",
"example": 0,
"description": "Total income that the company generated from dividends."
},
"other_income": {
"type": "number",
"format": "float",
"example": 0,
"description": "Total income that the company generated from activities not associated with their main economic activity."
},
"total_net_income": {
"type": "number",
"format": "float",
"example": 210043000,
"description": "Total net income of the company, taking into account `returns_rebates_and_discounts_on_sales`."
},
"total_gross_income": {
"type": "number",
"format": "float",
"example": 210043000,
"description": "Total gross income the company generated."
},
"gross_income_from_ordinary_activities": {
"type": "number",
"format": "float",
"example": 210043000,
"description": "Total gross income that the company generated from their main economic activity."
},
"returns_rebates_and_discounts_on_sales": {
"type": "number",
"format": "float",
"example": 0,
"description": "Total value of cancelled orders, corrected invoices, or similar, that can be discounted from the `total_gross_income`."
}
},
"description": "Object containing the reported annual incomes, deductions, and final balances of the tax payer."
}
AnnualIncomeStatementIndividual
{
"type": "object",
"required": [
"gross_income",
"non_taxable_income",
"net_income",
"annual_totals"
],
"properties": {
"net_income": {
"$ref": "#/components/schemas/NetIncomeIndividual"
},
"gross_income": {
"$ref": "#/components/schemas/GrossIncomeIndividual"
},
"annual_totals": {
"$ref": "#/components/schemas/AnnualTotalsIndividual"
},
"non_taxable_income": {
"$ref": "#/components/schemas/NonTaxableIncomeIndividual"
}
},
"description": "Object containing the reported annual incomes, deductions, and final balances of the tax payer."
}
AnnualTotalsIndividual
{
"type": "object",
"required": [
"total_exempt_income",
"total_applicable_deductions",
"total_exemptions_and_deductions",
"total_ordinary_net_income"
],
"properties": {
"total_exempt_income": {
"type": "number",
"format": "float",
"example": 115004000,
"description": "Total income that is not taxable, according to the institution."
},
"total_ordinary_net_income": {
"type": "number",
"format": "float",
"example": 0,
"description": "Sum total of the taxpayer's income (gross income - exemptions - deductions)."
},
"total_applicable_deductions": {
"type": "number",
"format": "float",
"example": 0,
"description": "Total deductions that the taxpayer can apply to their income, according to the institution."
},
"total_exemptions_and_deductions": {
"type": "number",
"format": "float",
"example": 0,
"description": "Sum total of all exempt and deductions that can be applied to the taxpayer's income."
}
},
"description": "Object containing the tax payers total exempt, deducted, and ordinary net incomes."
}
AsynchronousAccepted202
{
"type": "object",
"properties": {
"request_id": {
"type": "string",
"example": "b5d0106ac9cc43d5b36199fe831f6bbe",
"description": "The unique ID for this request. We recommend you store this value to later identify which webhook event relates to an asynchronous request."
}
}
}
Balance
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "076c66e5-90f5-4e01-99c7-50e32f65ae42",
"description": "Belvo's unique ID for the balance request."
},
"account": {
"$ref": "#/components/schemas/Account"
},
"balance": {
"type": "number",
"format": "float",
"example": 50000,
"description": "The funds available in the account by the end of the `value_date`."
},
"statement": {
"type": "string",
"example": null,
"nullable": true,
"deprecated": true,
"description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our [Deprecated fields](https://developers.belvo.com/reference/using-the-api-reference#%EF%B8%8F-deprecated-fields) explanation.*\n\n*The ID of the banking statement used to extract the `balance`.*\n"
},
"value_date": {
"type": "string",
"format": "date",
"example": "2019-10-23",
"description": "The date when the `balance` was available, in `YYYY-MM-DD` format."
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": null,
"nullable": true,
"deprecated": true,
"description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our [Deprecated fields](https://developers.belvo.com/reference/using-the-api-reference#%EF%B8%8F-deprecated-fields) explanation.*\n\n*The ISO-8601 timestamp when the data point was collected.*\n"
},
"current_balance": {
"type": "number",
"example": null,
"nullable": true,
"deprecated": true,
"description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our [Deprecated fields](https://developers.belvo.com/reference/using-the-api-reference#%EF%B8%8F-deprecated-fields) explanation.*\n\nPlease use the `balance` field instead.\n"
}
}
}
BalancesDeleteBalance404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
BalancesDeleteBalanceResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
BalancesGetAllResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
BalancesGetDetails404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
BalancesGetDetailsResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
BalancesGetLinkBalances201Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Balance"
}
}
BalancesGetLinkBalances400Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
}
]
}
}
BalancesGetLinkBalances401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
BalancesGetLinkBalances408Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RequestTimeoutError"
},
"title": "Request Timeout",
"description": "Belvo has a limit regarding the time it takes to log in, retrieve account data, and log out. A timeout occurs when there is a very high amount of data and everything could not be obtained within the allotted time.\n \n"
}
BalancesGetLinkBalances428Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenRequiredResponse"
}
}
BalancesGetLinkBalances500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
BalancesGetLinkBalancesResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Balance"
}
}
BalancesPaginatedResponse
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/common_pagination_properties"
},
{
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Balance"
},
"description": "Array of balance objects."
}
}
}
]
}
BalancesRequest
{
"type": "object",
"required": [
"link",
"date_from",
"date_to"
],
"properties": {
"link": {
"type": "string",
"format": "uuid",
"example": "2ccd5e15-194a-4a19-a45a-e7223c7e6717",
"description": "The `link.id` that you want to get information for."
},
"token": {
"type": "string",
"example": "1234ab",
"description": "The OTP token generated by the bank."
},
"account": {
"type": "string",
"format": "uuid",
"example": "d4617561-1c01-4b2f-83b6-a594f7b3bc57",
"description": "If provided, only balances matching this `account.id` are\nreturned.\n"
},
"date_to": {
"type": "string",
"example": "2021-02-15",
"pattern": "[0-9]{4}-[0-9]{2}-[0-9]{2}",
"description": "Date that you want to stop receiving balances, in `YYYY-MM-DD` format.\n\n\n⚠️ The value of `date_to` cannot be greater than today's date (in other words, no future dates).\n"
},
"date_from": {
"type": "string",
"example": "2021-01-18",
"pattern": "[0-9]{4}-[0-9]{2}-[0-9]{2}",
"description": "Date from which you want to start receiving balances, in `YYYY-MM-DD` format.\n\n\n⚠️ The value of `date_from` cannot be greater than `date_to`.\n"
},
"save_data": {
"type": "boolean",
"default": true,
"description": "Indicates whether or not to persist the data in Belvo. By default, this is set to `true` and we return a 201 Created response.\n\nWhen set to `false`, the data won't be persisted and we return a 200 OK response.\n"
}
}
}
BalancesResumeSession201Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Balance"
}
}
BalancesResumeSession400Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
}
]
}
}
BalancesResumeSession401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
BalancesResumeSession408Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RequestTimeoutError"
},
"title": "Request Timeout",
"description": "Belvo has a limit regarding the time it takes to log in, retrieve account data, and log out. A timeout occurs when there is a very high amount of data and everything could not be obtained within the allotted time.\n \n"
}
BalancesResumeSession428Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenRequiredResponse"
}
}
BalancesResumeSession500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
BalancesResumeSessionResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Balance"
}
}
Categorization
{
"type": "object",
"properties": {
"transactions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CategorizationBody"
},
"description": "An array of enriched transaction objects."
}
}
}
CategorizationBody
{
"type": "object",
"required": [
"transaction_id",
"account_holder_type",
"account_holder_id",
"account_id",
"account_category",
"value_date",
"description",
"type",
"amount",
"currency",
"institution",
"category",
"merchant"
],
"properties": {
"mcc": {
"type": "integer",
"format": "int32",
"example": 2345,
"nullable": true,
"description": "The four-digit ISO 18245 Merchant Category Code (MCC).\n"
},
"type": {
"$ref": "#/components/schemas/EnumCategorizationTransactionType"
},
"amount": {
"type": "number",
"format": "float",
"example": 650.89,
"maximum": 9999999999.99,
"minimum": 0,
"description": "The transaction amount.\n"
},
"category": {
"$ref": "#/components/schemas/EnumCategorizationTransactionCategory"
},
"currency": {
"type": "string",
"example": "BRL",
"description": "The currency of the account, in ISO-4217 format. For example:\n- 🇧🇷 BRL (Brazilian Real)\n- 🇨🇴 COP (Colombian Peso)\n- 🇲🇽 MXN (Mexican Peso)"
},
"merchant": {
"$ref": "#/components/schemas/CategorizationMerchantData"
},
"account_id": {
"type": "string",
"example": "EREB-89077589",
"description": "The unique ID for the account where the transaction occurred in your system.\n"
},
"value_date": {
"type": "string",
"format": "date",
"example": "2022-11-18",
"description": "The date when the transaction occurred, in `YYYY-MM-DD` format.\n"
},
"description": {
"type": "string",
"example": "APPL3STORE",
"description": "The description of the transaction.\n"
},
"institution": {
"type": "string",
"example": "Erebor Brazil",
"description": "The institution where the account is registered.\n\n\n>**Note:** This is the name that you use in your system to identify an institution.\n \n"
},
"subcategory": {
"$ref": "#/components/schemas/EnumCategorizationTransactionSubcategory"
},
"transaction_id": {
"type": "string",
"example": "3CWE4927CF15355",
"description": "The unique ID for the transaction in your system."
},
"account_category": {
"$ref": "#/components/schemas/EnumCategorizationAccountCategory"
},
"account_holder_id": {
"type": "string",
"example": "7890098789087",
"description": "The unique ID for the account holder in your system.\n"
},
"account_holder_type": {
"$ref": "#/components/schemas/EnumCategorizationAccountHolderType"
}
}
}
CategorizationBodyRequest
{
"type": "object",
"required": [
"transaction_id",
"account_holder_type",
"account_holder_id",
"account_id",
"account_category",
"value_date",
"description",
"type",
"amount",
"currency",
"institution"
],
"properties": {
"mcc": {
"type": "integer",
"format": "int32",
"example": 2345,
"nullable": true,
"description": "The four-digit ISO 18245 Merchant Category Code (MCC).\n"
},
"type": {
"$ref": "#/components/schemas/EnumCategorizationTransactionType"
},
"amount": {
"type": "number",
"format": "float",
"example": 650.89,
"maximum": 9999999999.99,
"minimum": 0,
"description": "The transaction amount.\n"
},
"currency": {
"type": "string",
"example": "BRL",
"description": "The currency of the account, in ISO-4217 format. For example:\n- 🇧🇷 BRL (Brazilian Real)\n- 🇨🇴 COP (Colombian Peso)\n- 🇲🇽 MXN (Mexican Peso)\n"
},
"account_id": {
"type": "string",
"example": "EREB-89077589",
"description": "Your unique ID for the account where the transaction occurred.\n"
},
"value_date": {
"type": "string",
"format": "date",
"example": "2022-11-18",
"description": "The date when the transaction occurred, in `YYYY-MM-DD` format.\n"
},
"description": {
"type": "string",
"example": "APPL3STORE",
"description": "The description of the transaction.\n"
},
"institution": {
"type": "string",
"example": "Erebor Retail Brasil",
"description": "The institution where the account is registered.\n\n\n>**Note:** This is the name that you use in your system to identify an institution.\n"
},
"transaction_id": {
"type": "string",
"example": "3CWE4927CF15355",
"description": "Your unique ID for the transaction."
},
"account_category": {
"$ref": "#/components/schemas/EnumCategorizationAccountCategory"
},
"account_holder_id": {
"type": "string",
"example": "7890098789087",
"description": "Your unique ID for the account holder.\n"
},
"account_holder_type": {
"$ref": "#/components/schemas/EnumCategorizationAccountHolderType"
}
}
}
CategorizationCategorizeTransactions401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
CategorizationCategorizeTransactions403Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/AccessToResourceDenied"
},
"description": "This error occurs when you try to access Belvo's resource without the correct permissions.\n"
}
CategorizationCategorizeTransactions500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
CategorizationCategorizeTransactionsResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
}
]
}
}
CategorizationMerchantData
{
"type": "object",
"nullable": true,
"properties": {
"logo": {
"type": "string",
"example": "https://www.apple.com/ac/structured-data/images/open_graph_logo.png?202110180743",
"nullable": true,
"description": "The URL to the merchant's logo."
},
"website": {
"type": "string",
"example": "https://www.apple.com/br/",
"nullable": true,
"description": "The URL to the merchant's website."
},
"merchant_name": {
"type": "string",
"example": "Apple, Inc",
"description": "The name of the merchant."
}
},
"description": "Additional data regarding the merchant involved in the transaction.\n"
}
CategorizationRequest
{
"type": "object",
"required": [
"language",
"transactions"
],
"properties": {
"language": {
"type": "string",
"example": "pt",
"description": "Two-letter ISO 639-1 code for the language of the transaction.\n"
},
"transactions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CategorizationBodyRequest"
},
"description": "An array of transaction objects that you want categorized.\n\n\n**Note:** Each object corresponds to one, unique transaction and you can send through up to 10,000 transactions per request.\n"
}
}
}
ChangeAccessMode
{
"type": "object",
"required": [
"access_mode"
],
"properties": {
"access_mode": {
"$ref": "#/components/schemas/EnumLinkAccessModeRequest"
}
}
}
CreditScore
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "a4e0d6f8-aa0b-45e4-9cd2-38cc741a64ad",
"description": "The unique ID for the credit score analysis.\n"
},
"score": {
"type": "integer",
"format": "int32",
"example": 400,
"description": "The credit score of the user.\n"
},
"date_to": {
"type": "string",
"format": "date",
"example": "2023-06-01",
"description": "The date that the credit score analysis ends, in `YYYY-MM-DD` format.\n"
},
"user_id": {
"type": "string",
"example": "AGH7890098789087",
"description": "Your unique ID for the user.\n"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2023-06-01T12:00:00.000Z",
"description": "The ISO-8601 timestamp when the credit score analysis was created.\n"
},
"reason_codes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CreditScoreReasonCode"
},
"minItems": 1,
"description": "An array of codes that explain the reason behind the credit score."
}
},
"description": "Credit Score response"
}
CreditScoreDeleteSpecificScore404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
CreditScoreDeleteSpecificScoreResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
CreditScoreEyodGetUserCreditScore400Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
}
]
}
}
CreditScoreEyodGetUserCreditScore401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
CreditScoreEyodGetUserCreditScore403Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/AccessToResourceDenied"
},
"description": "This error occurs when you try to access Belvo's resource without the correct permissions.\n"
}
CreditScoreEyodGetUserCreditScore500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
CreditScoreEyodGetUserCreditScoreRequest
{
"type": "array",
"items": {
"$ref": "#/components/schemas/EyodCreditScoreRequest"
}
}
CreditScoreEyodGetUserCreditScoreResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/CreditScore"
}
}
CreditScoreGetByLink401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
CreditScoreGetByLink408Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RequestTimeoutError"
},
"title": "Request Timeout",
"description": "Belvo has a limit regarding the time it takes to log in, retrieve account data, and log out. A timeout occurs when there is a very high amount of data and everything could not be obtained within the allotted time.\n \n"
}
CreditScoreGetByLink428Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenRequiredResponse"
}
}
CreditScoreGetByLink500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
CreditScoreGetByLinkResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
},
{
"$ref": "#/components/schemas/InvalidPeriodError"
}
]
}
}
CreditScoreGetDetailsById404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
CreditScoreGetDetailsByIdResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
CreditScoreListAllResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
CreditScorePaginatedResponse
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/common_pagination_properties"
},
{
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CreditScore"
},
"description": "Array of credit score objects."
}
}
}
]
}
CreditScoreReasonCode
{
"type": "object",
"properties": {
"code": {
"type": "string",
"example": "C06",
"pattern": "[A-Z][0-9]{2}",
"description": "The reason code for the credit score.\n"
},
"description": {
"type": "string",
"example": "Out of Pattern transaction checking deposit day",
"pattern": "^.{1,160}$",
"maxLength": 160,
"minLength": 1,
"description": "A description of the reason code.\n"
}
},
"description": "An array of codes that explain the reason behind the credit score."
}
CreditScoreRequest
{
"type": "object",
"required": [
"link"
],
"properties": {
"link": {
"type": "string",
"format": "uuid",
"example": "2ccd5e15-194a-4a19-a45a-e7223c7e6717",
"description": "The `link.id` that you want to get information for."
},
"date_to": {
"type": "string",
"example": "2023-02-28",
"pattern": "[0-9]{4}-[0-9]{2}-[0-9]{2}",
"description": "The date until when you want to calculate the credit score for, in `YYYY-MM-DD` format.\n\nIf not provided, we calculate the credit score using from the time of the request and use up to 365 days of data (if available).\n\n\n⚠️ The value of `date_to` cannot be greater than today's date (in other words, no future dates).\n"
},
"save_data": {
"type": "boolean",
"default": true,
"description": "Indicates whether or not to persist the data in Belvo. By default, this is set to `true` and we return a 201 Created response.\n\nWhen set to `false`, the data won't be persisted and we return a 200 OK response.\n"
}
}
}
DocumentIdBusiness
{
"type": "object",
"required": [
"document_type",
"document_number"
],
"properties": {
"document_type": {
"type": "string",
"example": "NIT",
"description": "The type of ID document."
},
"document_number": {
"type": "string",
"example": "8312224477",
"description": "The number of the ID document."
}
},
"description": "Object containing information about the ID document of the tax payer."
}
DocumentIdIndividual
{
"type": "object",
"required": [
"document_type",
"document_number"
],
"properties": {
"document_type": {
"type": "string",
"example": "NIT",
"description": "The type of ID document."
},
"document_number": {
"type": "string",
"example": "7113223466",
"description": "The number of the ID document."
}
},
"description": "Object containing information about the ID document of the tax payer."
}
DocumentInformationBusiness
{
"type": "object",
"required": [
"name",
"type",
"form_number",
"year"
],
"properties": {
"name": {
"type": "string",
"example": "Declaracion de Renta y Complementario o de Ingresos y Patrimonio para Personas Juridicas y Asimiladas y Personas Naturales y Asimiladas no Residentes y Sucesiones Iliquidas de Causantes no Residentes",
"description": "The name of the tax document."
},
"type": {
"type": "string",
"example": "110",
"description": "The type of tax declaration form. For DIAN, this will be either `110` or `210`."
},
"year": {
"type": "integer",
"example": 2021,
"nullable": true,
"description": "The year of this tax declaration.\n"
},
"form_number": {
"type": "string",
"example": "2117680087604",
"description": "The institution-provided identifier for the tax declaration."
}
},
"description": "Object containing detailed information about the fiscal document."
}
DocumentInformationIndividual
{
"type": "object",
"required": [
"name",
"type",
"form_number",
"year"
],
"properties": {
"name": {
"type": "string",
"example": "Declaracion de Renta y Complementario o de Ingresos y Patrimonio para Personas Juridicas y Asimiladas y Personas Naturales y Asimiladas no Residentes y Sucesiones Iliquidas de Causantes no Residentes",
"description": "The name of the tax document."
},
"type": {
"type": "string",
"example": "110",
"description": "The type of tax declaration form. For DIAN, this will be either `110` or `210`."
},
"year": {
"type": "integer",
"example": 2021,
"nullable": true,
"description": "The year of this tax declaration.\n"
},
"form_number": {
"type": "string",
"example": "2117680087604",
"description": "Institution-provided identifier for the tax declaration."
}
},
"description": "Object containing detailed information about the fiscal document."
}
EmploymentRecord
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "fef05fc8-7357-4a4a-9d29-55038ea31a04",
"description": "The unique identifier created by Belvo for the current IMSS statement."
},
"link": {
"type": "string",
"format": "uuid",
"example": "27c1d5cf-e8fb-433a-a2f7-d246de199c01",
"description": "The unique identifier created by Belvo for the current user."
},
"files": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmploymentRecordFile"
},
"nullable": true,
"description": "Additional PDF binary files relating to the individual's employment."
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2020-04-23T21:32:55.336854+00:00",
"description": "The ISO-8601 timestamp of when the data point was initially created in Belvo's database."
},
"report_date": {
"type": "string",
"format": "date",
"example": "2023-01-19",
"description": "The date when the employment record report was generated, in `YYYY-MM-DD` format."
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2020-04-23T21:32:55.336854+00:00",
"description": "The ISO-8601 timestamp when the data point was collected."
},
"personal_data": {
"$ref": "#/components/schemas/EmploymentRecordPersonalData"
},
"employment_records": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmploymentRecordDetail"
},
"description": "Details regarding the individual's employment history."
},
"internal_identification": {
"type": "string",
"example": "BLPM951331IONVGR54",
"description": "Unique ID for user according to the institution. For IMSS Mexico, this is the CURP."
},
"social_security_summary": {
"$ref": "#/components/schemas/EmploymentRecordSocialSecuritySummary"
}
},
"description": "Employment record response payload"
}
EmploymentRecordDetail
{
"type": "object",
"properties": {
"state": {
"type": "string",
"example": "DISTRITO FEDERAL",
"description": "In what geographical state the individual was employed, according to the country.\n"
},
"currency": {
"type": "string",
"example": "MXN",
"description": "The three-letter currency code in which the salary is paid.\n"
},
"employer": {
"type": "string",
"example": "Batman Enterprises CDMX",
"description": "The official name of the employer.\n"
},
"end_date": {
"type": "string",
"format": "date",
"example": "2019-12-31",
"nullable": true,
"description": "Date when employment finished, in `YYYY-MM-DD` format.\n"
},
"start_date": {
"type": "string",
"format": "date",
"example": "2019-10-10",
"description": "Date when employment started, in `YYYY-MM-DD` format.\n"
},
"employer_id": {
"type": "string",
"example": "780-BAT-88769-CDMX",
"description": "The official ID of the employer, according to the country.\n"
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2020-04-23T21:32:55.336854+00:00",
"description": "The ISO-8601 timestamp when the data point was collected."
},
"monthly_salary": {
"type": "number",
"format": "float",
"description": "The monthly salary of the individual, including any additional perks.\n"
},
"weeks_employed": {
"type": "integer",
"format": "int32",
"example": 12,
"description": "Number of weeks that the individual was employed.\n"
},
"most_recent_base_salary": {
"type": "number",
"format": "float",
"example": 762.54,
"description": "The most recent base salary the individual earned.\n\nFor Mexico, this is the *daily* rate that the individual earned, including the perks that the individual is entitled to throughout the year.\n"
},
"employment_status_updates": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmploymentRecordEmploymentStatusUpdates"
},
"nullable": true,
"description": "Details regarding any employment changes of the individual."
}
},
"description": "Details regarding the individual's employment history."
}
EmploymentRecordDocumentId
{
"type": "object",
"properties": {
"document_type": {
"$ref": "#/components/schemas/EnumEmploymentRecordDocumentType"
},
"document_number": {
"type": "string",
"example": "10277663582",
"nullable": true,
"description": "The ID document's number (as a string).\n"
}
},
"description": "Details regarding the individual's ID documents."
}
EmploymentRecordEmploymentStatusUpdates
{
"type": "object",
"nullable": true,
"properties": {
"event": {
"$ref": "#/components/schemas/EnumEmploymentRecordStatusUpdateEvents"
},
"base_salary": {
"type": "number",
"format": "float",
"example": 1033.09,
"description": "The base salary of the individual, current as of the `update_date`.\n"
},
"update_date": {
"type": "string",
"format": "date",
"example": "2021-09-01",
"description": "The date that the employment event occurred, in `YYYY-MM-DD` format.\n"
}
},
"description": "Details regarding any employment changes of the individual."
}
EmploymentRecordEntitlement
{
"type": "object",
"properties": {
"status": {
"$ref": "#/components/schemas/EnumEmploymentRecordStatus"
},
"valid_until": {
"type": "string",
"format": "date",
"example": null,
"nullable": true,
"description": "Date until when the individual is covered by health insurance and/or company benefits. If `null` the employee is currently working and no end date is required.\n"
},
"entitled_to_company_benefits": {
"type": "boolean",
"example": true,
"description": "Indicates whether or not the individual is entitled to company benefits.\n"
},
"entitled_to_health_insurance": {
"type": "boolean",
"example": true,
"description": "Indicated whether or not the individual is entitled to health insurance.\n"
}
},
"description": "Details regarding the benefits the individual is entitled to."
}
EmploymentRecordFile
{
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "ReporteSemanasCotizadas_190123",
"description": "The title of the document.\n"
},
"value": {
"type": "string",
"example": "=PDF_BINARY=",
"nullable": true,
"description": "The PDF binary of the file (as a string).\n\n> **Note**: In our sandbox environment, this field will return `null`.\n"
}
},
"description": "Additional PDF binary files relating to the individual's employment."
}
EmploymentRecordPersonalData
{
"type": "object",
"properties": {
"email": {
"type": "string",
"example": "bruce.banner@avengers.com",
"nullable": true,
"deprecated": true,
"description": "The email address of the individual.\n"
},
"last_name": {
"type": "string",
"example": "Banner del Torro",
"nullable": true,
"description": "The last name of the individual.\n"
},
"birth_date": {
"type": "string",
"format": "date",
"example": "2022-02-09",
"nullable": true,
"description": "The date of birth of the individual, in `YYYY-MM-DD` format.\n"
},
"first_name": {
"type": "string",
"example": "Bruce",
"nullable": true,
"description": "The first name of the individual.\n"
},
"document_ids": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmploymentRecordDocumentId"
},
"description": "Details regarding the individual's ID documents."
},
"entitlements": {
"$ref": "#/components/schemas/EmploymentRecordEntitlement"
},
"official_name": {
"type": "string",
"example": "Bruce Banner del Torro",
"nullable": true,
"description": "The legal name of the individual\n"
}
},
"description": "Details regarding the personal information of the individual."
}
EmploymentRecordRequest
{
"type": "object",
"required": [
"link"
],
"properties": {
"link": {
"type": "string",
"format": "uuid",
"example": "d686c617-6d9e-4bc6-9801-5ac276ccb6a2",
"description": "The `link.id` you want to retrieve employment records for."
},
"save_data": {
"type": "boolean",
"default": true,
"description": "Indicates whether or not to persist the data in Belvo. By default, this is set to `true` and we return a 201 Created response.\n\nWhen set to `false`, the data won't be persisted and we return a 200 OK response.\n"
},
"attach_pdf": {
"type": "boolean",
"default": false,
"description": "When set to `true`, you will receive the PDF in binary format in the response.\n"
}
}
}
EmploymentRecordSocialSecuritySummary
{
"type": "object",
"properties": {
"weeks_redeemed": {
"type": "integer",
"format": "int32",
"example": 0,
"nullable": true,
"description": "Number of weeks the individual needed to take out of their pension.\n"
},
"weeks_reinstated": {
"type": "integer",
"format": "int32",
"example": 0,
"nullable": true,
"description": "Number of weeks the individual has paid back into their pension (*AFORE*), after having redeemed them previously.\n"
},
"weeks_contributed": {
"type": "integer",
"format": "int32",
"example": 188,
"nullable": true,
"description": "Number of weeks the individual has contributed to their social security, based on the number of weeks the individual has worked according to IMSS.\n"
}
},
"description": "Details regarding the individual's social security contributions."
}
EmploymentRecordsMexicoDeleteRecord404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
EmploymentRecordsMexicoDeleteRecordResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
EmploymentRecordsMexicoGetDetails201Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/EmploymentRecord"
}
}
EmploymentRecordsMexicoGetDetails400Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
}
]
}
}
EmploymentRecordsMexicoGetDetails401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
EmploymentRecordsMexicoGetDetails404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
EmploymentRecordsMexicoGetDetails408Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RequestTimeoutError"
},
"title": "Request Timeout",
"description": "Belvo has a limit regarding the time it takes to log in, retrieve account data, and log out. A timeout occurs when there is a very high amount of data and everything could not be obtained within the allotted time.\n \n"
}
EmploymentRecordsMexicoGetDetails428Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenRequiredResponse"
}
}
EmploymentRecordsMexicoGetDetails500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
EmploymentRecordsMexicoGetDetailsResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/EmploymentRecord"
}
}
EmploymentRecordsMexicoListAllResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
EmploymentRecordsPaginatedResponse
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/common_pagination_properties"
},
{
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmploymentRecord"
},
"description": "Array of employment record objects."
}
}
}
]
}
EnumAccountCategory
{
"enum": [
"CHECKING_ACCOUNT",
"CREDIT_CARD",
"INVESTMENT_ACCOUNT",
"LOAN_ACCOUNT",
"PENSION_FUND_ACCOUNT",
"SAVINGS_ACCOUNT",
"UNCATEGORIZED",
null
],
"type": "string",
"example": "CHECKING_ACCOUNT",
"nullable": true,
"description": "The type of account.\nWe return one of the following enum values:\n - `CHECKING_ACCOUNT`\n - `CREDIT_CARD`\n - `INVESTMENT_ACCOUNT`\n - `LOAN_ACCOUNT`\n - `PENSION_FUND_ACCOUNT`\n - `SAVINGS_ACCOUNT`\n - `UNCATEGORIZED`\n - `null`\n"
}
EnumAccountCategoryOpenFinance
{
"enum": [
"ADVANCE_DEPOSIT_ACCOUNT",
"CHECKING_ACCOUNT",
"CREDIT_CARD",
"FINANCING_ACCOUNT",
"INVESTMENT_ACCOUNT",
"INVOICE_FINANCING_ACCOUNT",
"LOAN_ACCOUNT",
"PENSION_FUND_ACCOUNT",
"SAVINGS_ACCOUNT",
"UNCATEGORIZED"
],
"type": "string",
"example": "CHECKING_ACCOUNT",
"nullable": true,
"description": "The type of account.\nWe return one of the following enum values:\n - `ADVANCE_DEPOSIT_ACCOUNT`\n - `CHECKING_ACCOUNT`\n - `CREDIT_CARD`\n - `FINANCING_ACCOUNT`\n - `INVESTMENT_ACCOUNT`\n - `INVOICE_FINANCING_ACCOUNT`\n - `LOAN_ACCOUNT`\n - `PENSION_FUND_ACCOUNT`\n - `SAVINGS_ACCOUNT`\n - `UNCATEGORIZED`\n"
}
EnumAccountCreditCardNetwork
{
"enum": [
"VISA",
"MASTERCARD",
"AMERICAN_EXPRESS",
"DINERS_CLUB",
"HIPERCARD",
"BANDEIRA_PROPRIA",
"CHEQUE_ELETRONICO",
"ELO",
"OTHER"
],
"type": "string",
"example": "MASTERCARD",
"description": "The credit network that the card is associated with. We return one of the following values:\n\n - `VISA`\n - `MASTERCARD`\n - `AMERICAN_EXPRESS`\n - `DINERS_CLUB`\n - `HIPERCARD`\n - `BANDEIRA_PROPRIA`\n - `CHEQUE_ELETRONICO`\n - `ELO`\n - `OTHER`\n\n > **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
}
EnumAccountLoanDataContractRemainingFrequency
{
"enum": [
"DAY",
"WEEK",
"MONTH",
"YEAR",
"NO_DEADLINE_REMAINING",
null
],
"type": "string",
"example": "MONTH",
"nullable": true,
"description": "The frequency of the remaining contracted installment payments, as defined when the contract was first signed. We return one of the following:\n- `DAY`\n- `WEEK`\n- `MONTH`\n- `YEAR`\n- `NO_DEADLINE_REMAINING`\n- `null`\n"
}
EnumAccountLoanDataContractedChargeType
{
"enum": [
"LATE_PAYMENT_INTEREST_FEE",
"LATE_PAYMENT_PENALTY_FEE",
"DEFAULT_INTEREST_FEE",
"LOAN_CONTRACT_TAX",
"LATE_PAYMENT_TAX",
"NO_CHARGE",
"OTHER"
],
"type": "string",
"example": "LATE_PAYMENT_INTEREST_FEE",
"description": "The type of contracted charge. We return one of the following values:\n\n - `LATE_PAYMENT_INTEREST_FEE`\n - `LATE_PAYMENT_PENALTY_FEE`\n - `DEFAULT_INTEREST_FEE`\n - `LOAN_CONTRACT_TAX`\n - `LATE_PAYMENT_TAX`\n - `NO_CHARGE`\n - `OTHER`\n\n > **Non-nullable:** A value must be returned by Brazil's open finance network if the `contracted_charges` field is available.\n"
}
EnumAccountLoanDataFeeCharge
{
"enum": [
"MINIMUM",
"MAXIMUM",
"FIXED",
"PERCENTAGE"
],
"type": "string",
"example": "FIXED",
"description": "Billing method, as agreed upon with the institution. We return one of the following values:\n\n - `MINIMUM`\n - `MAXIMUM`\n - `FIXED`\n - `PERCENTAGE`\n\n > **Non-nullable:** A value must be returned by Brazil's open finance network if the `fees` field is available.\n"
}
EnumAccountLoanDataFeeChargeType
{
"enum": [
"SINGLE",
"PER_INSTALLMENT"
],
"type": "string",
"example": "SINGLE",
"description": "Indicates the type of charge. We return one of the following values:\n\n - `SINGLE`\n - `PER_INSTALLMENT`\n\n > **Non-nullable:** A value must be returned by Brazil's open finance network if the `fees` field is available.\n"
}
EnumAccountLoanDataFeeType
{
"enum": [
"OPERATION_FEE",
"INSURANCE_FEE",
"OTHERS",
null
],
"type": "string",
"example": null,
"nullable": true,
"description": "**Note:** This field is not applicable for OF Brazil and will return null.\n"
}
EnumAccountLoanDataInstallmentFrequency
{
"enum": [
"IRREGULAR",
"WEEKLY",
"FORTNIGHTLY",
"MONTHLY",
"BIMONTHLY",
"QUARTERLY",
"BIANNUALLY",
"ANNUALLY",
"OTHER"
],
"type": "string",
"example": "MONTHLY",
"description": "The frequency that the installments are paid. We return one of the following values:\n\n - `IRREGULAR`\n - `WEEKLY`\n - `FORTNIGHTLY`\n - `MONTHLY`\n - `BIMONTHLY`\n - `QUARTERLY`\n - `BIANNUALLY`\n - `ANNUALLY`\n - `OTHER`\n\n > **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
}
EnumAccountLoanDataInterestRateDataRateType
{
"enum": [
"SIMPLE",
"COMPOUND"
],
"type": "string",
"example": "SIMPLE",
"description": "The type of interest rate. We return one of the following values:\n\n - `SIMPLE`\n - `COMPOUND`\n\n > **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
}
EnumAccountLoanDataInterestRateDataReferenceIndexType
{
"enum": [
"WITHOUT_INDEX_TYPE",
"PRE_FIXED",
"POST_FIXED",
"FLOATING",
"INDEXED_PRICE",
"RURAL_CREDIT",
"OTHER_INDEX"
],
"type": "string",
"example": "FLOATING",
"description": "The reference index rate. We return one of the following values:\n\n - `WITHOUT_INDEX_TYPE`\n - `PRE_FIXED`\n - `POST_FIXED`\n - `FLOATING`\n - `INDEXED_PRICE`\n - `RURAL_CREDIT`\n - `OTHER_INDEX`\n\n > **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
}
EnumAccountLoanDataInterestRateDataTaxType
{
"enum": [
"NOMINAL",
"EFFECTIVE"
],
"type": "string",
"example": "NOMINAL",
"description": "The type of interest rate tax. We return one of the following values:\n\n - `NOMINAL`\n - `EFFECTIVE`\n \n > **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
}
EnumAccountLoanDataInterestRateType
{
"enum": [
"MONTHLY",
"YEARLY"
],
"type": "string",
"example": "MONTHLY",
"description": "The period that the interest is applied to the loan.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
}
EnumAccountsLoanDataContractInstallmentFrequency
{
"enum": [
"DAY",
"WEEK",
"MONTH",
"YEAR",
"NO_DEADLINE_REMAINING",
null
],
"type": "string",
"example": "MONTH",
"nullable": true,
"description": "The frequency of contracted installment payments, as defined when the contract was first signed. We return one of the following:\n\n - `DAY`\n - `WEEK`\n - `MONTH`\n - `YEAR`\n - `NO_DEADLINE_REMAINING`\n - `null`\n"
}
EnumCategorizationAccountCategory
{
"enum": [
"CHECKING_ACCOUNT",
"CREDIT_CARD",
"LOAN_ACCOUNT",
"SAVINGS_ACCOUNT"
],
"type": "string",
"example": "CREDIT_CARD",
"description": "The type of account.\n\nCan be either:\n - `CHECKING_ACCOUNT`\n - `CREDIT_CARD`\n - `LOAN_ACCOUNT`\n - `SAVINGS_ACCOUNT`\n"
}
EnumCategorizationAccountHolderType
{
"enum": [
"INDIVIDUAL",
"BUSINESS"
],
"type": "string",
"example": "INDIVIDUAL",
"description": "The type of account holder.\n\nCan be either:\n\n - `INDIVIDUAL`\n - `BUSINESS`\n"
}
EnumCategorizationTransactionCategory
{
"enum": [
"Bills & Utilities",
"Credits & Loans",
"Deposits",
"Fees & Charges",
"Food & Groceries",
"Home & Life",
"Income & Payments",
"Insurance",
"Investments & Savings",
"Online Platforms & Leisure",
"Personal Shopping",
"Taxes",
"Transfers",
"Transport & Travel",
"Unknown",
"Withdrawal & ATM",
null
],
"type": "string",
"example": "Income & Payments",
"nullable": true,
"description": "The name of the category to which this transaction belongs. For more info about this feature, check our [Transaction categorization](https://developers.belvo.com/docs/banking#categorizing-transactions) article. \n\nWe return one of the following enum values:\n\n - `Bills & Utilities`\n - `Credits & Loans`\n - `Deposits`\n - `Fees & Charges`\n - `Food & Groceries`\n - `Home & Life`\n - `Income & Payments`\n - `Insurance`\n - `Investments & Savings`\n - `Online Platforms & Leisure`\n - `Personal Shopping`\n - `Taxes`\n - `Transfers`\n - `Transport & Travel`\n - `Unknown`\n - `Withdrawal & ATM`\n - `null`\n"
}
EnumCategorizationTransactionSubcategory
{
"enum": [
"Electricity & Energy",
"Rent",
"Telecommunications",
"Water",
"Auto",
"Credit Card",
"Instalment",
"Interest & Charges",
"Mortgage",
"Pay Advance",
"Personal",
"Adjustments",
"Bank Fees",
"Chargeback",
"Refund",
"Blocked Balances",
"Alimony",
"Alcohol & Tobacco",
"Bakery & Coffee",
"Bars & Nightclubs",
"Convenience Store",
"Delivery",
"Groceries",
"Restaurants",
"Education",
"Gyms & Fitness",
"Hair & Beauty",
"Health",
"Home Decor & Appliances",
"Laundry & Dry Cleaning",
"Pharmacies",
"Professional Services",
"Veterinary Services",
"Freelance",
"Interest",
"Retirement",
"Salary",
"Government",
"Home Insurance",
"Auto Insurance",
"Health & Life Insurance",
"Savings",
"Fixed income",
"Equity",
"Investment Funds",
"Derivatives",
"Cryptocurrencies",
"Apps, Software and Cloud Services",
"Events, Parks and Museums",
"Gambling",
"Gaming",
"Lottery",
"Movie & Audio",
"Books & News",
"Clothing & Accessories",
"Department Store",
"Electronics",
"E-commerce",
"Gifts",
"Office Supplies",
"Pet Supplies",
"Auto Tax & Fees",
"Donation",
"Government Fees",
"Income Tax",
"Real Estate Tax & Fees",
"Tax Return",
"Accommodation",
"Auto Expenses",
"Auto Rental",
"Flights",
"Gas",
"Mileage Programs",
"Parking & Tolls",
"Public Transit",
"Taxis & Rideshares",
"Other",
null
],
"type": "string",
"example": "Freelance",
"nullable": true,
"description": "The transactions subcategory. For more info about this feature, check our [Transaction categorization](https://developers.belvo.com/docs/banking#categorizing-transactions) article. \n\n\nWe return one of the following enum values:\n\n - `Electricity & Energy`\n - `Rent`\n - `Telecommunications`\n - `Water`\n - `Auto`\n - `Credit Card`\n - `Instalment`\n - `Interest & Charges`\n - `Mortgage`\n - `Pay Advance`\n - `Personal`\n - `Adjustments`\n - `Bank Fees`\n - `Chargeback`\n - `Refund`\n - `Blocked Balances`\n - `Alimony`\n - `Alcohol & Tobacco`\n - `Bakery & Coffee`\n - `Bars & Nightclubs`\n - `Convenience Store`\n - `Delivery`\n - `Groceries`\n - `Restaurants`\n - `Education`\n - `Gyms & Fitness`\n - `Hair & Beauty`\n - `Health`\n - `Home Decor & Appliances`\n - `Laundry & Dry Cleaning`\n - `Pharmacies`\n - `Professional Services`\n - `Veterinary Services`\n - `Freelance`\n - `Interest`\n - `Retirement`\n - `Salary`\n - `Government`\n - `Home Insurance`\n - `Auto Insurance`\n - `Health & Life Insurance`\n - `Savings`\n - `Fixed income`\n - `Equity`\n - `Investment Funds`\n - `Derivatives`\n - `Cryptocurrencies`\n - `Apps, Software and Cloud Services`\n - `Events, Parks and Museums`\n - `Gambling`\n - `Gaming`\n - `Lottery`\n - `Movie & Audio`\n - `Books & News`\n - `Clothing & Accessories`\n - `Department Store`\n - `Electronics`\n - `E-commerce`\n - `Gifts`\n - `Office Supplies`\n - `Pet Supplies`\n - `Auto Tax & Fees`\n - `Donation`\n - `Government Fees`\n - `Income Tax`\n - `Real Estate Tax & Fees`\n - `Tax Return`\n - `Accommodation`\n - `Auto Expenses`\n - `Auto Rental`\n - `Flights`\n - `Gas`\n - `Mileage Programs`\n - `Parking & Tolls`\n - `Public Transit`\n - `Taxis & Rideshares`\n - `Other`\n - `null`\n"
}
EnumCategorizationTransactionType
{
"enum": [
"INFLOW",
"OUTFLOW"
],
"type": "string",
"example": "OUTFLOW",
"description": "The direction of the transaction.\n\nCan be either:\n\n - `INFLOW` indicates a received transaction.\n - `OUTFLOW` indicates a sent transaction.\n"
}
EnumCreditCardLimitType
{
"enum": [
"TOTAL_LIMIT",
"MODAL_LIMIT"
],
"type": "string",
"example": "TOTAL_LIMIT",
"description": "The type of limit. We return one of the following values:\n\n - `TOTAL_LIMIT`\n - `MODAL_LIMIT`\n\n > **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
}
EnumEmploymentRecordDocumentType
{
"enum": [
"NSS",
"CURP"
],
"type": "string",
"example": "NSS",
"nullable": true,
"description": "The type of document related to the individual. We return one of the following values:\n\n - `NSS`\n - `CURP`\n \n"
}
EnumEmploymentRecordStatus
{
"enum": [
"EMPLOYED",
"UNEMPLOYED"
],
"type": "string",
"example": "EMPLOYED",
"nullable": true,
"description": "Indicates whether or not the individual is currently `EMPLOYED` or `UNEMPLOYED`.\n"
}
EnumEmploymentRecordStatusUpdateEvents
{
"enum": [
"DISMISSED_RESIGNED",
"SALARY_MODIFICATION",
"HIRED",
"VOLUNTARY_CONTRIBUTION",
"ABSENCE",
"SICK_LEAVE"
],
"type": "string",
"example": "HIRED",
"nullable": true,
"description": "The event that caused the change in employment status or salary. We return one of the following values:\n \n - `DISMISSED_RESIGNED`\n - `SALARY_MODIFICATION`\n - `HIRED`\n - `VOLUNTARY_CONTRIBUTION`\n - `ABSENCE`\n - `SICK_LEAVE`\n \n"
}
EnumIncomeMinimumConfidenceLevelRequest
{
"enum": [
"HIGH",
"MEDIUM",
"LOW"
],
"type": "string",
"example": "HIGH",
"description": "The minimum confidence level of the incomes you want to get information for.\n\nYou can send through one of the following values:\n\n - `HIGH`\n - `MEDIUM`\n - `LOW`\n"
}
EnumIncomeSourceType
{
"enum": [
"BANK"
],
"type": "string",
"example": "BANK",
"description": "The type of source we generate income insights from.\nWe return one of the following enum values:\n\n - `BANK`\n"
}
EnumIncomeStreamConfidence
{
"enum": [
"HIGH",
"MEDIUM",
"LOW"
],
"type": "string",
"example": "HIGH",
"description": "Belvo's level of confidence for future incomes.\n\nWe return one of the following enum values:\n\n - `HIGH`\n - `MEDIUM`\n - `LOW`\n"
}
EnumIncomeStreamFrequency
{
"enum": [
"MONTHLY",
"FORTNIGHTLY",
"WEEKLY",
"IRREGULAR",
"SINGLE"
],
"type": "string",
"example": "MONTHLY",
"description": "How often the income is received.\n\nWe return one of the following enum values:\n\n - `MONTHLY` - For transactions that occur once per month.\n - `FORTNIGHTLY` - For transactions that occur once every two weeks.\n - `WEEKLY` - For transactions that occur once per week.\n - `IRREGULAR` - For transactions that do not occur on a defined frequency pattern.\n - `SINGLE` - For transactions that occur only once and do not repeat.\n"
}
EnumIncomeStreamType
{
"enum": [
"SALARY",
"GOVERNMENT",
"INTEREST",
"RENT",
"RETIREMENT",
"FREELANCE",
"ALTERNATIVE_INCOME",
"TRANSFER",
"DEPOSIT",
"UNKNOWN"
],
"type": "string",
"example": "SALARY",
"description": "The type of income used in the calculations.\n\nWe return one of the following enum values:\n\n - `SALARY`\n - `GOVERNMENT`\n - `INTEREST`\n - `RENT`\n - `RETIREMENT`\n - `FREELANCE`\n - `ALTERNATIVE_INCOME`\n - `TRANSFER`\n - `DEPOSIT`\n - `UNKNOWN`\n"
}
EnumIncomeVerificationAccountCategory
{
"enum": [
"CHECKING_ACCOUNT",
"SAVINGS_ACCOUNT"
],
"type": "string",
"example": "CHECKING_ACCOUNT",
"description": "The type of account.\n\nCan be either:\n - `CHECKING_ACCOUNT`\n - `SAVINGS_ACCOUNT`\n"
}
EnumIncomeVerificationAccountHolderType
{
"enum": [
"INDIVIDUAL"
],
"type": "string",
"example": "INDIVIDUAL",
"description": "The type of account holder. Can be:\n\n - `INDIVIDUAL`\n"
}
EnumIncomeVerificationType
{
"enum": [
"INFLOW"
],
"type": "string",
"example": "INFLOW",
"nullable": true,
"description": "The direction of the transaction:\n \n- `INFLOW` indicates money coming into the account.\n"
}
EnumInstitutionIntegrationType
{
"enum": [
"credentials",
"openfinance"
],
"type": "string",
"example": "credentials",
"description": "The type of technology used to access the institution. We return one of the following values:\n\n- `credentials`: Uses Belvo's scraping technology, combined with user credentials, to perform requests.\n- `openfinance`: Uses the bank's open finance API to perform requests.\n"
}
EnumInstitutionStatus
{
"enum": [
"healthy",
"down"
],
"type": "string",
"example": "healthy",
"description": "Indicates whether Belvo's integration with the institution is currently active (`healthy`) or undergoing maintenance (`down`).\n"
}
EnumInstitutionType
{
"enum": [
"bank",
"fiscal",
"employment"
],
"type": "string",
"description": "The type of institution. We return one of the following values:\n\n - `bank`\n - `fiscal`\n - `employment`\n"
}
EnumInvoiceAllowedIncomeTypesRequest
{
"enum": [
"SALARY",
"GOVERNMENT",
"INTEREST",
"RENT",
"RETIREMENT",
"FREELANCE",
"ALTERNATIVE_INCOME",
"TRANSFER",
"DEPOSIT",
"UNKNOWN"
],
"type": "string",
"example": "SALARY",
"description": "The categories of the incomes you want to get information for. \n\nYou can send through one or more of the following values:\n - `SALARY`\n - `GOVERNMENT`\n - `INTEREST`\n - `RENT`\n - `RETIREMENT`\n - `FREELANCE`\n - `ALTERNATIVE_INCOME`\n - `TRANSFER`\n - `DEPOSIT`\n - `UNKNOWN`\n"
}
EnumInvoiceDianInvoiceType
{
"enum": [
"Factura Electrónica de Venta"
],
"type": "string",
"example": "Factura Electrónica de Venta",
"nullable": true,
"description": "The fiscal institution's classification of the invoice.\n\nFor Colombia's DIAN, we return one of the following values:\n\n - `Factura Electrónica de Venta`\n"
}
EnumInvoiceDianPaymentMethod
{
"enum": [
"Contado",
"Crédito",
null
],
"type": "string",
"example": "Contado",
"nullable": true,
"description": "The payment method used for this invoice, as defined by the legal entity of the country.\n\nFor DIAN Colombia, we return one of the following values:\n\n - `Contado`\n - `Crédito`\n - `null`\n"
}
EnumInvoiceSatInvoiceType
{
"enum": [
"Egreso",
"Ingreso",
"Nómina",
"Pago",
"Traslado"
],
"type": "string",
"example": "Ingreso",
"nullable": true,
"description": "The fiscal institution's classification of the invoice.\n\nFor Mexico's SAT, we return one of the following values:\n\n - `Egreso`\n - `Ingreso`\n - `Nómina`\n - `Pago`\n - `Traslado`\n"
}
EnumInvoiceSatPaymentMethod
{
"enum": [
"PUE",
"PIP",
"PPD",
null
],
"type": "string",
"example": "PUE",
"nullable": true,
"description": "The payment method code used for this invoice, as defined by the legal entity of the country.\n\n- 🇲🇽 Mexico [SAT catalog reference article](https://developers.belvo.com/docs/sat-catalogs#payment-method). For Mexico, we return `PUE`, `PIP`, `PPD`, or `null`.\n"
}
EnumInvoiceType
{
"enum": [
"OUTFLOW",
"INFLOW",
null
],
"type": "string",
"example": "INFLOW",
"nullable": true,
"description": "The direction of the invoice (from the perspective of the Link owner).\n- `OUTFLOW` indicates a sent invoice.\n- `INFLOW` indicates a received invoice.\n"
}
EnumLinkAccessModeRequest
{
"enum": [
"single",
"recurrent"
],
"type": "string",
"default": "recurrent",
"description": "The type of link to create.\n\n- Use `single` to do ad hoc one-time POST requests for accounts, owners, and transactions.\n- Use `recurrent` to have Belvo access information on a recurrent basis so you always have fresh account, owner, balance, and transaction data.\n\nFor more information, see our [Links](https://developers.belvo.com/docs/links-and-institutions#links) article.\n"
}
EnumLinkAccessModeResponse
{
"enum": [
"single",
"recurrent",
null
],
"type": "string",
"example": "recurrent",
"nullable": true,
"description": "The link type.\nFor more information, see our [Links](https://developers.belvo.com/docs/links-and-institutions#links) article.\nWe return one of the following enum values:\n - `single`\n - `recurrent`\n - `null`\n"
}
EnumLinkRefreshRate
{
"enum": [
"6h",
"12h",
"24h",
"7d",
"30d",
null
],
"type": "string",
"default": "7d",
"example": "7d",
"nullable": true,
"description": "The update refresh rate for the recurrent link. For more information, check out our [recurrent link documentation](https://developers.belvo.com/docs/links-and-institutions#recurrent-links) in our DevPortal.\nWe return one of the following enum values:\n - `6h`\n - `12h`\n - `24h`\n - `7d` (default)\n - `30d` (once a month)\n - `null` (for single links)\n"
}
EnumLinkStatus
{
"enum": [
"valid",
"invalid",
"unconfirmed",
"token_required"
],
"type": "string",
"example": "valid",
"description": "The current status of the link. For more information, see our [Link](https://developers.belvo.com/docs/links-and-institutions#links) article in the devportal.\nWe return one of the following values:\n - `valid`\n - `invalid`\n - `unconfirmed`\n - `token_required`\n"
}
EnumLoanDataFeeType
{
"enum": [
"OPERATION_FEE",
"INSURANCE_FEE",
"OTHERS"
],
"type": "string",
"example": "OPERATION_FEE",
"description": "The type of fee. We return one of the following values:\n\n - `OPERATION_FEE`\n - `INSURANCE_FEE`\n - `OTHERS`\n"
}
EnumLoanDataInterestRateType
{
"enum": [
"MONTHLY",
"YEARLY"
],
"type": "string",
"example": "MONTHLY",
"nullable": true,
"description": "The period that the interest is applied to the loan. We return one of the following values:\n\n - `MONTHLY`\n - `YEARLY`\n"
}
EnumOwnerBusinessInformedRevenueFrequency
{
"enum": [
"DAILY",
"WEEKLY",
"FORTNIGHTLY",
"MONTHLY",
"BIMONTHLY",
"QUARTERLY",
"BIANNUALLY",
"ANNUALLY",
"OTHERS",
null
],
"type": "string",
"example": "MONTHLY",
"nullable": true,
"description": "Indicates how often the business declares their revenue. We return one of the following values:\n \n - `DAILY`\n - `WEEKLY`\n - `FORTNIGHTLY`\n - `MONTHLY`\n - `BIMONTHLY`\n - `QUARTERLY`\n - `BIANNUALLY`\n - `ANNUALLY`\n - `OTHERS`\n - `null`\n"
}
EnumOwnerBusinessProductType
{
"enum": [
"SAVINGS_ACCOUNT",
"CHECKING_ACCOUNT",
null
],
"type": "string",
"example": "SAVINGS_ACCOUNT",
"nullable": true,
"description": "The additional products the business has at the institution. We return one of the following values:\n\n - `SAVINGS_ACCOUNT`\n - `CHECKING_ACCOUNT`\n - `null`\n \n"
}
EnumOwnerFiliationType
{
"enum": [
"MOTHER",
"FATHER",
null
],
"type": "string",
"example": "MOTHER",
"nullable": true,
"description": "The familial relationship. We return one of the following values:\n\n - `MOTHER`\n - `FATHER`\n - `null`\n \n"
}
EnumOwnerGender
{
"enum": [
"FEMALE",
"MALE",
"OTHER"
],
"type": "string",
"example": "FEMALE",
"nullable": true,
"description": "The individual's gender. We return on of the following values:\n\n - `FEMALE`\n - `MALE`\n - `OTHER`\n \n"
}
EnumOwnerIndividualDocumentIdType
{
"enum": [
"DRIVERS_LICENCE",
"PASSPORT",
"ID_CARD",
"FISCAL_ID",
"FOREIGNER_REGISTRATION_CARD",
"OTHER",
null
],
"type": "string",
"example": "DRIVERS_LICENCE",
"nullable": true,
"description": "The type of ID document. We return one of the following values:\n\n - `DRIVERS_LICENCE`\n - `PASSPORT`\n - `ID_CARD`\n - `FISCAL_ID`\n - `FOREIGNER_REGISTRATION_CARD`\n - `OTHER`\n - `null`\n \n"
}
EnumOwnerIndividualFinancialProfileOccupationCode
{
"enum": [
"BRAZIL_PUBLIC_OFFICE",
"BRAZIL_OCCUPATION_CODE",
"OTHER",
null
],
"type": "string",
"example": "BRAZIL_OCCUPATION_CODE",
"nullable": true,
"description": "The area of employment of the individual. We return one of the following values:\n\n - `BRAZIL_PUBLIC_OFFICE`\n - `BRAZIL_OCCUPATION_CODE`\n - `OTHER`\n - `null`\n"
}
EnumOwnerIndividualProductType
{
"enum": [
"SAVINGS_ACCOUNT",
"CHECKING_ACCOUNT",
null
],
"type": "string",
"example": "SAVINGS_ACCOUNT",
"nullable": true,
"description": "The additional products the individual has at the institution. We return one of the following values:\n\n - `SAVINGS_ACCOUNT`\n - `CHECKING_ACCOUNT`\n - `null`\n"
}
EnumOwnerInformedIncomeFrequency
{
"enum": [
"DAILY",
"WEEKLY",
"FORTNIGHTLY",
"MONTHLY",
"BIMONTHLY",
"QUARTERLY",
"BIANNUALLY",
"ANNUALLY",
"OTHERS"
],
"type": "string",
"example": "MONTHLY",
"nullable": true,
"description": "Indicates how often the individual receives their salary. We return one of the following values:\n\n - `DAILY`\n - `WEEKLY`\n - `FORTNIGHTLY`\n - `MONTHLY`\n - `BIMONTHLY`\n - `QUARTERLY`\n - `BIANNUALLY`\n - `ANNUALLY`\n - `OTHERS`\n"
}
EnumOwnerMaritalStatus
{
"enum": [
"SINGLE",
"MARRIED",
"WIDOWED",
"SEPARATED",
"DIVORCED",
"CIVIL_UNION",
"OTHER"
],
"type": "string",
"example": "SINGLE",
"nullable": true,
"description": "The individual's marital status. We return one of the following values:\n\n - `SINGLE`\n - `MARRIED`\n - `WIDOWED`\n - `SEPARATED`\n - `DIVORCED`\n - `CIVIL_UNION`\n - `OTHER`\n"
}
EnumOwnerPartyDocumentType
{
"enum": [
"CPF",
"CNPJ",
"OTHER_TRAVEL_DOCUMENT",
"PASSPORT"
],
"type": "string",
"example": "CPF",
"nullable": true,
"description": "The type of ID document the party provided when being added to the account. We return one of the following values:\n\n - `CPF`\n - `CNPJ`\n - `OTHER_TRAVEL_DOCUMENT`\n - `PASSPORT`\n"
}
EnumOwnerPartyPersonType
{
"enum": [
"INDIVIDUAL",
"COMPANY"
],
"type": "string",
"example": "INDIVIDUAL",
"nullable": true,
"description": "The type of person that is an ownership party of the account. We return one of the following values:\n\n - `INDIVIDUAL`\n - `COMPANY`\n \n"
}
EnumOwnerPartyType
{
"enum": [
"MEMBER",
"ADMINISTRATOR"
],
"type": "string",
"example": "MEMBER",
"nullable": true,
"description": "The access type that the `person_type` has to the account. We return one of the following values:\n\n- `MEMBER` indicates that the `person_type` has read access to the account.\n- `ADMINISTRATOR` indicates that the `person_type` can perform all actions for the account (including transfers).\n"
}
EnumOwnerPhoneNumberType
{
"enum": [
"LANDLINE",
"MOBILE",
"OTHER",
null
],
"type": "string",
"example": "MOBILE",
"nullable": true,
"description": "The type of phone number. We return one of the following values:\n\n - `LANDLINE`\n - `MOBILE`\n - `OTHER`\n - `null`\n"
}
EnumOwnerProcuratorType
{
"enum": [
"LEGAL_REPRESENTATIVE",
"ATTORNEY",
null
],
"type": "string",
"example": "LEGAL_REPRESENTATIVE",
"nullable": true,
"description": "The type of representative that can access and make changes to the account. We return one of the following values:\n\n - `LEGAL_REPRESENTATIVE`\n - `ATTORNEY`\n - `null`\n \n"
}
EnumRecurringExpenseCategory
{
"enum": [
"Bills & Utilities",
"Credits & Loans",
"Insurance",
"Online Platforms & Leisure",
"Transport & Travel",
"Taxes"
],
"type": "string",
"example": "Online Platforms & Leisure",
"description": "The transaction category for the recurring expense. For more information on the available categories, please see our [Transaction categorization documentation](https://developers.belvo.com/docs/banking#categorizing-transactions).\n\n- `Online Platforms & Leisure` (Netflix, Spotify, Gym Memberships)\n- `Bills & Utilities` (electricity, telephone, internet)\n- `Credits & Loans` (credit card cash advances, student loan, watercraft lease)\n- `Insurance` (home, car, and health & life insurance)\n- `Transport & Travel` (Uber trip, airbnb, parking)\n- `Taxes` (service fee, donation, court taxes)\n"
}
EnumRecurringExpenseFrequency
{
"enum": [
"MONTHLY"
],
"type": "string",
"default": "MONTHLY",
"example": "MONTHLY",
"description": "The frequency at which this recurring expense occurs.\n\n\nℹ️ **Note:** Belvo only identifies `MONTHLY` frequencies.\n"
}
EnumRecurringExpensePaymentType
{
"enum": [
"SUBSCRIPTION",
"REGULAR"
],
"type": "string",
"example": "SUBSCRIPTION",
"nullable": true,
"description": "The type of recurring expense. We return one of the following values:\n\n - `SUBSCRIPTION`\n - `REGULAR`\n"
}
EnumRiskInsightTransactionType
{
"enum": [
"INFLOW",
"OUTFLOW"
],
"type": "string",
"example": "INFLOW",
"nullable": true,
"description": "The direction of the transaction:\n \n- `INFLOW` indicates money coming into the account.\n- `OUTFLOW` indicates money leaving the account.\n"
}
EnumTaxComplianceStatusOutcome
{
"enum": [
"POSITIVE",
"NEGATIVE",
"NO_OBLIGATIONS"
],
"type": "string",
"example": "NEGATIVE",
"nullable": true,
"description": "Indicates whether the taxpayer is complying to all their tax obligations\n(`POSITIVE`), if they are not (`NEGATIVE`), or have none to comply to\n(`NO_OBLIGATIONS`).\n"
}
EnumTaxRetentionPaymentStatus
{
"enum": [
"PAID",
"PROVISIONED"
],
"type": "string",
"example": "PAID",
"nullable": true,
"description": "Indicates whether or not the tax has been paid or not. Can be either:\n - `PAID`\n - `PROVISIONED`\n"
}
EnumTaxRetentionReceiverNationality
{
"enum": [
"NATIONAL",
"FOREIGN"
],
"type": "string",
"example": "NATIONAL",
"nullable": true,
"description": "Whether the invoice receiver is a Mexican national or not. If the receiver is not considered a Mexican national, the retained taxes can be calculated differently. Possible values:\n - `NATIONAL`\n - `FOREIGN`\n"
}
EnumTaxRetentionType
{
"enum": [
"OUTFLOW",
"INFLOW"
],
"type": "string",
"example": "INFLOW",
"description": "The type of tax retention in relation to the invoice (from the perspective of the Link owner).\n\n- `OUTFLOW` relates to a tax retention for a sent invoice.\n- `INFLOW` related to a tax retention for a received invoice.\n"
}
EnumTransactionBillStatus
{
"enum": [
"PAID",
"CLOSED",
"OPEN",
"FUTURE",
null
],
"type": "string",
"example": "PAID",
"nullable": true,
"description": "The status of the bill that the transaction appears on. Can be one of:\n\n - `PAID`: The bill has been paid in full.\n - `CLOSED`: The bill has been closed by the institution.\n - `OPEN`: The bill is currently open. (Note: This is the main bill that Belvo retrieves balance data from).\n - `FUTURE`: The bill is pending.\n - `null`: No bill status was identified.\n \nℹ️ Note: Some banks consider CLOSED as PAID. \n"
}
EnumTransactionCategory
{
"enum": [
"Bills & Utilities",
"Credits & Loans",
"Deposits",
"Fees & Charges",
"Food & Groceries",
"Home & Life",
"Income & Payments",
"Insurance",
"Investments & Savings",
"Online Platforms & Leisure",
"Personal Shopping",
"Taxes",
"Transfers",
"Transport & Travel",
"Unknown",
"Withdrawal & ATM",
null
],
"type": "string",
"example": "Income & Payments",
"nullable": true,
"description": "The name of the transaction category.\n\n> **Get transaction categorization**\nWith [Transaction categorization](https://developers.belvo.com/docs/banking#categorizing-transactions), we clean and categorize transactions for you, turning raw data into actionable insights. To enable this feature, just [reach out](https://belvo.com/contact/?utm_source=documentation) to us, and we'll get right to it.\n\nWe return one of the following enum values:\n\n - `Bills & Utilities`\n - `Credits & Loans`\n - `Deposits`\n - `Fees & Charges`\n - `Food & Groceries`\n - `Home & Life`\n - `Income & Payments`\n - `Insurance`\n - `Investments & Savings`\n - `Online Platforms & Leisure`\n - `Personal Shopping`\n - `Taxes`\n - `Transfers`\n - `Transport & Travel`\n - `Unknown`*\n - `Withdrawal & ATM`\n - `null`\n\n\n \\* For clients not using our Transaction Categorization product, we return `null` instead.\n"
}
EnumTransactionCounterpartyType
{
"enum": [
"INDIVIDUAL",
"COMPANY",
null
],
"type": "string",
"example": "INDIVIDUAL",
"nullable": true,
"description": "The transaction counterparty type. We return one of the following values:\n\n - `INDIVIDUAL`\n - `COMPANY`\n - `null`\n"
}
EnumTransactionCreditCardDataCreditType
{
"enum": [
"REVOLVING_CREDIT",
"BILL_INSTALLMENT_PAYMENT",
"LOAN",
"OTHERS",
null
],
"type": "string",
"example": "BILL_INSTALLMENT_PAYMENT",
"nullable": true,
"description": "Other types of credit that have been contracted on the card. We return one of the following values:\n\n - `REVOLVING_CREDIT`\n - `BILL_INSTALLMENT_PAYMENT`\n - `LOAN`\n - `OTHERS`\n - `null`\n"
}
EnumTransactionCreditCardDataFeeType
{
"enum": [
"ANNUAL_FEE",
"NATIONAL_WITHDRAWAL",
"INTERNATIONAL_WITHDRAWAL",
"EMERGENCY_CREDIT_EVALUATION_FEE",
"DUPLICATE_ISSUANCE_FEE",
"PAYMENT_FEE",
"SMS_FEE",
"OTHERS",
null
],
"type": "string",
"example": "NATIONAL_WITHDRAWAL",
"nullable": true,
"description": "The fee that can be charged for a card transaction. We return one of the following values:\n\n - `ANNUAL_FEE`\n - `NATIONAL_WITHDRAWAL`\n - `INTERNATIONAL_WITHDRAWAL`\n - `EMERGENCY_CREDIT_EVALUATION_FEE`\n - `DUPLICATE_ISSUANCE_FEE`\n - `PAYMENT_FEE`\n - `SMS_FEE`\n - `OTHERS`\n - `null`\n"
}
EnumTransactionPaymentType
{
"enum": [
"FULL",
"INSTALLMENT",
null
],
"type": "string",
"example": "FULL",
"nullable": true,
"description": "The transaction payment type. We return one of the following values:\n\n - `FULL`\n - `INSTALLMENT`\n - `null`\n"
}
EnumTransactionStatus
{
"enum": [
"PENDING",
"PROCESSED",
"UNCATEGORIZED",
null
],
"type": "string",
"example": "PROCESSED",
"nullable": true,
"description": "The status of the transaction. We return one of the following values:\n\n - `PROCESSED` (The transaction has been processed by the institution.)\n - `PENDING` (The institution clearly states that the transaction has not yet been processed.)\n - `UNCATEGORIZED` (deprecated)\n - `null` (deprecated)\n \n"
}
EnumTransactionSubcategory
{
"enum": [
"Electricity & Energy",
"Rent",
"Telecommunications",
"Water",
"Auto",
"Credit Card",
"Instalment",
"Interest & Charges",
"Mortgage",
"Pay Advance",
"Personal",
"Adjustments",
"Bank Fees",
"Chargeback",
"Refund",
"Blocked Balances",
"Alimony",
"Alcohol & Tobacco",
"Bakery & Coffee",
"Bars & Nightclubs",
"Convenience Store",
"Delivery",
"Groceries",
"Restaurants",
"Education",
"Gyms & Fitness",
"Hair & Beauty",
"Health",
"Home Decor & Appliances",
"Laundry & Dry Cleaning",
"Pharmacies",
"Professional Services",
"Veterinary Services",
"Freelance",
"Interest",
"Retirement",
"Salary",
"Government",
"Home Insurance",
"Auto Insurance",
"Health & Life Insurance",
"Savings",
"Fixed income",
"Equity",
"Investment Funds",
"Derivatives",
"Cryptocurrencies",
"Apps, Software and Cloud Services",
"Events, Parks and Museums",
"Gambling",
"Gaming",
"Lottery",
"Movie & Audio",
"Books & News",
"Clothing & Accessories",
"Department Store",
"Electronics",
"E-commerce",
"Gifts",
"Office Supplies",
"Pet Supplies",
"Auto Tax & Fees",
"Donation",
"Government Fees",
"Income Tax",
"Real Estate Tax & Fees",
"Tax Return",
"Accommodation",
"Auto Expenses",
"Auto Rental",
"Flights",
"Gas",
"Mileage Programs",
"Parking & Tolls",
"Public Transit",
"Taxis & Rideshares",
"Other",
null
],
"type": "string",
"example": "Freelance",
"nullable": true,
"description": "The transaction subcategory.\n\n > **Get transaction categorization**\n For clients not using our [Transaction categorization](https://developers.belvo.com/docs/banking#categorizing-transactions), we return `null` instead. To enable this feature, just [reach out](https://belvo.com/contact/?utm_source=documentation) to us, and we'll get right to it.\n\n\nWe return one of the following enum values:\n\n - `Electricity & Energy`\n - `Rent`\n - `Telecommunications`\n - `Water`\n - `Auto`\n - `Credit Card`\n - `Instalment`\n - `Interest & Charges`\n - `Mortgage`\n - `Pay Advance`\n - `Personal`\n - `Adjustments`\n - `Bank Fees`\n - `Chargeback`\n - `Refund`\n - `Blocked Balances`\n - `Alimony`\n - `Alcohol & Tobacco`\n - `Bakery & Coffee`\n - `Bars & Nightclubs`\n - `Convenience Store`\n - `Delivery`\n - `Groceries`\n - `Restaurants`\n - `Education`\n - `Gyms & Fitness`\n - `Hair & Beauty`\n - `Health`\n - `Home Decor & Appliances`\n - `Laundry & Dry Cleaning`\n - `Pharmacies`\n - `Professional Services`\n - `Veterinary Services`\n - `Freelance`\n - `Interest`\n - `Retirement`\n - `Salary`\n - `Government`\n - `Home Insurance`\n - `Auto Insurance`\n - `Health & Life Insurance`\n - `Savings`\n - `Fixed income`\n - `Equity`\n - `Investment Funds`\n - `Derivatives`\n - `Cryptocurrencies`\n - `Apps, Software and Cloud Services`\n - `Events, Parks and Museums`\n - `Gambling`\n - `Gaming`\n - `Lottery`\n - `Movie & Audio`\n - `Books & News`\n - `Clothing & Accessories`\n - `Department Store`\n - `Electronics`\n - `E-commerce`\n - `Gifts`\n - `Office Supplies`\n - `Pet Supplies`\n - `Auto Tax & Fees`\n - `Donation`\n - `Government Fees`\n - `Income Tax`\n - `Real Estate Tax & Fees`\n - `Tax Return`\n - `Accommodation`\n - `Auto Expenses`\n - `Auto Rental`\n - `Flights`\n - `Gas`\n - `Mileage Programs`\n - `Parking & Tolls`\n - `Public Transit`\n - `Taxis & Rideshares`\n - `Other`\n - `null`\n"
}
EnumTransactionType
{
"enum": [
"OUTFLOW",
"INFLOW",
null
],
"type": "string",
"example": "INFLOW",
"nullable": true,
"description": "The direction of the transaction:\n- `INFLOW` indicates money coming into the account.\n- `OUTFLOW` indicates money going out of the account.\n- `null` when no information was present regarding the direction of the transaction.\n"
}
EquityStatementBusiness
{
"type": "object",
"required": [
"cash_and_cash_equivalents",
"investments_and_derivative_financial_instruments",
"accounts_documents_and_finance_leases_receivable",
"inventory",
"property_plant_and_equipment_investment_properties",
"total_gross_equity",
"debts",
"total_net_equity"
],
"properties": {
"debts": {
"type": "number",
"format": "float",
"example": 207030000,
"description": "Total debts that the company currently has."
},
"inventory": {
"type": "number",
"format": "float",
"example": 0,
"description": "Total financial value of the company's sellable inventory."
},
"total_net_equity": {
"type": "number",
"format": "float",
"example": 13830000,
"description": "The total net equity of the company (`total_gross_equity` - `debts`)."
},
"total_gross_equity": {
"type": "number",
"format": "float",
"example": 220860000,
"description": "Total gross equity."
},
"cash_and_cash_equivalents": {
"type": "number",
"format": "float",
"example": 4648000,
"description": "Total cash (or cash equivalents) that the business currently holds at the end of the fiscal year."
},
"accounts_documents_and_finance_leases_receivable": {
"type": "number",
"format": "float",
"example": 0,
"description": "Total of all payments the company expects to receive (for example, from partial invoices that have not been paid yet)."
},
"investments_and_derivative_financial_instruments": {
"type": "number",
"format": "float",
"example": 77626000,
"description": "Total value of all investments, stocks, or similar, that the company has."
},
"property_plant_and_equipment_investment_properties": {
"type": "number",
"format": "float",
"example": 0,
"description": "Total value of real estate, plant infrastructure, or equipment that has been purchased."
}
},
"description": "Object containing the general fiscal situation of the taxpayer."
}
EquityStatementIndividual
{
"type": "object",
"required": [
"total_gross_equity",
"total_debts",
"total_net_equity"
],
"properties": {
"total_debts": {
"type": "number",
"format": "float",
"example": 77626000,
"description": "The total debts of the tax_payer"
},
"total_net_equity": {
"type": "number",
"format": "float",
"example": 0,
"description": "The total net equity value of the taxpayer."
},
"total_gross_equity": {
"type": "number",
"format": "float",
"example": 4648000,
"description": "The total gross equity of the tax payer."
}
},
"description": "Object containing the general fiscal situation of the taxpayer."
}
EyodCreditScoreAccountBody
{
"type": "object",
"required": [
"id",
"category",
"balance",
"balance_date",
"currency"
],
"properties": {
"id": {
"type": "string",
"example": "AGH7890098789087-Checking-Erebor",
"description": "Your unique ID for the user's account.\n"
},
"balance": {
"type": "number",
"format": "float",
"example": 12540.67,
"description": "The balance of the account."
},
"category": {
"enum": [
"CHECKING_ACCOUNT",
"CREDIT_CARD",
"LOAN_ACCOUNT",
"SAVINGS_ACCOUNT"
],
"type": "string",
"example": "CHECKING_ACCOUNT",
"description": "The category of the bank account. Can be either:\n\n - `CHECKING_ACCOUNT`\n - `CREDIT_CARD`\n - `LOAN_ACCOUNT`\n - `SAVINGS_ACCOUNT`\n"
},
"currency": {
"type": "string",
"example": "BRL",
"description": "The three-letter currency code of the `balance`. For example:\n\n • 🇧🇷 BRL (Brazilian Real)\n • 🇨🇴 COP (Colombian Peso)\n • 🇲🇽 MXN (Mexican Peso)\n\n**Note:** Ensure that the currency of the account and the transactions associated with it are the same. For example, if the currency of the account is `MXN`, then all the transactions associated with that account should also be in `MXN`.\n \n"
},
"balance_date": {
"type": "string",
"format": "date",
"example": "2023-06-01",
"description": "The date that the `balance` amount was retrieved, in `YYYY-MM-DD` format.\n\n**Note:** For each account you wish to have analyzed, try to provide the same date when the balance was available. \n"
}
},
"description": "EYOD Risk Insight account object.\n"
}
EyodCreditScoreRequest
{
"type": "object",
"required": [
"user_id",
"date_to",
"language",
"transactions",
"accounts"
],
"properties": {
"date_to": {
"type": "string",
"format": "date",
"example": "2023-06-01",
"description": "The date from which you want Belvo to start performing the credit score analysis, in `YYYY-MM-DD` format. If you do not specify a `date_to`, we use the current date at the time of your request.\n\n> **Note:**\n>\n> We recommend you use `date_to` if you do not have an account balance for the past few days.\n>\n> For example, if the last account balance date that you have a value for was last week, set the `date_to` parameter to that date. The credit score that you receive will be **relative** to the `date_to` parameter.\n"
},
"user_id": {
"type": "string",
"example": "AGH7890098789087",
"description": "Your unique ID for the user.\n"
},
"accounts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EyodCreditScoreAccountBody"
},
"description": "An array of account objects that the transactions are associated with.\n\n\nEach transaction you provide in the `transactions` array must have an associated account. If you provide transactions without an associated account, we return an error.\n\n**Note:** Each object corresponds to one unique account.\n"
},
"language": {
"type": "string",
"example": "pt",
"description": "The two-letter ISO 639-1 code for the language of the transaction. For example:\n \n - `pt` for Portugese\n\n > **Note**: At present, we only support `pt` for Portuguese.\n"
},
"transactions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EyodCreditScoreTransactionBody"
},
"maxItems": 10000,
"description": "An array of transaction objects that you want analyzed for the credit score analysis.\n\n\n**Note:** Each object corresponds to one unique transaction and you can send through up to 10,000 transactions per request.\n"
}
},
"description": "EYOD Credit Score request object.\n\n**Note:** You can only send through information for **one** user at a time.\n"
}
EyodCreditScoreTransactionBody
{
"type": "object",
"required": [
"transaction_id",
"account_id",
"value_date",
"type",
"amount",
"currency",
"description"
],
"properties": {
"type": {
"$ref": "#/components/schemas/EnumRiskInsightTransactionType"
},
"amount": {
"type": "number",
"format": "float",
"example": 650.89,
"maximum": 9999999999.99,
"minimum": 0,
"description": "The transaction amount.\n"
},
"currency": {
"type": "string",
"example": "BRL",
"description": "The three-letter currency code of the transaction. For example:\n\n • 🇧🇷 BRL (Brazilian Real)\n • 🇨🇴 COP (Colombian Peso)\n • 🇲🇽 MXN (Mexican Peso)\n\n**Note:** Ensure that the currency of the transaction and the account associated with it are the same. For example, if the currency of the account is `MXN`, then all the transactions associated with that account should also be in `MXN`.\n \n"
},
"account_id": {
"type": "string",
"example": "AGH7890098789087-Checking-Erebor",
"description": "Your unique ID for the account where the transaction occurred.\n\n**Note:** You must provide the details of this account in the `accounts` array of the Risk Insights request. Otherwise, we return an error.\n"
},
"value_date": {
"type": "string",
"format": "date",
"example": "2023-05-18",
"description": "The date when the transaction occurred, in `YYYY-MM-DD` format.\n\n**Note:** Transactions that occur after the `reference_date` are not considered in the risk insight analysis.\n"
},
"description": {
"type": "string",
"example": "Pagamento Netflix Maio 2023",
"maxLength": 500,
"description": "The description of the transaction.\n"
},
"transaction_id": {
"type": "string",
"example": "3CWE4927CF15355",
"description": "Your unique ID for the transaction."
}
},
"description": "The EYOD Risk Insight transaction object\n"
}
EyodIncomeVerificationBodyRequest
{
"type": "object",
"required": [
"transaction_id",
"account_holder_type",
"account_holder_id",
"account_id",
"account_category",
"value_date",
"description",
"type",
"amount",
"currency",
"institution"
],
"properties": {
"type": {
"$ref": "#/components/schemas/EnumIncomeVerificationType"
},
"amount": {
"type": "number",
"format": "float",
"example": 650.89,
"maximum": 9999999999.99,
"minimum": 0,
"description": "The income amount.\n"
},
"currency": {
"type": "string",
"example": "BRL",
"description": "The three-letter currency code of the income. For example:\n\n • 🇧🇷 BRL (Brazilian Real)\n • 🇨🇴 COP (Colombian Peso)\n • 🇲🇽 MXN (Mexican Peso)\n \n"
},
"account_id": {
"type": "string",
"example": "EBACA-89077589",
"description": "Your unique ID for the account where the transaction occurred.\n"
},
"value_date": {
"type": "string",
"format": "date",
"example": "2022-11-18",
"description": "The date when the income transaction occurred, in `YYYY-MM-DD` format.\n"
},
"description": {
"type": "string",
"example": "SALÁRIO MENSAL",
"description": "The description of the income.\n"
},
"institution": {
"type": "string",
"example": "Erebor Retail Brasil",
"description": "The institution where the account is registered.\n\n\n**Note:** This is the name that you use in your system to identify the institution. For example Erebor Retail Brasil Retail.\n"
},
"transaction_id": {
"type": "string",
"example": "3CWE4927CF15355",
"description": "Your unique ID for the income."
},
"account_category": {
"$ref": "#/components/schemas/EnumIncomeVerificationAccountCategory"
},
"account_holder_id": {
"type": "string",
"format": "uuid",
"example": "a61bc801-9fa5-457b-88ad-850c96eaca30",
"description": "Your unique ID for the account holder, in UUID format.\n"
},
"account_holder_type": {
"$ref": "#/components/schemas/EnumIncomeVerificationAccountHolderType"
}
}
}
EyodIncomeVerificationRequest
{
"type": "object",
"required": [
"language",
"transactions"
],
"properties": {
"date_to": {
"type": "string",
"example": "2022-12-30",
"pattern": "[0-9]{4}-[0-9]{2}-[0-9]{2}",
"description": "The date you want to stop getting incomes for, in `YYYY-MM-DD` format, within the last 365 days. When you use this parameter, you must also send `date_from`.\n\n\n⚠️ The value of `date_to` cannot be greater than today's date (in other words, no future dates).\n"
},
"language": {
"type": "string",
"example": "pt",
"description": "Two-letter ISO 639-1 code for the language of the transaction.\n"
},
"date_from": {
"type": "string",
"example": "2022-08-01",
"pattern": "[0-9]{4}-[0-9]{2}-[0-9]{2}",
"description": "The date from which you want to start getting incomes for, in `YYYY-MM-DD` format, within the last 365 days. When you use this parameter, you must also send `date_to`.\n\n\n⚠️ The value of `date_from` cannot be greater than `date_to`.\n"
},
"transactions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EyodIncomeVerificationBodyRequest"
},
"description": "An array of transaction objects that you want enriched.\n\n\n**Note:** Each object corresponds to one, unique transaction and you can send through up to 10,000 transactions per request.\n"
},
"allowed_income_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EnumInvoiceAllowedIncomeTypesRequest"
},
"description": "The categories of the incomes you want to get information for."
},
"minimum_confidence_level": {
"$ref": "#/components/schemas/EnumIncomeMinimumConfidenceLevelRequest"
}
}
}
GrossIncomeIndividual
{
"type": "object",
"required": [
"earned_income",
"fee_based_income",
"capital_income",
"non_labor_income"
],
"properties": {
"earned_income": {
"type": "number",
"format": "float",
"example": 115004000,
"description": "Income received from employment."
},
"capital_income": {
"type": "number",
"format": "float",
"example": 0,
"description": "Income received from an investment (such as dividends or from renting a property)."
},
"fee_based_income": {
"type": "number",
"format": "float",
"example": 0,
"description": "Income received from emitted invoices (for example, income that independent contractors or freelancers receive)."
},
"non_labor_income": {
"type": "number",
"format": "float",
"example": 0,
"description": "Income that cannot be classified into the other three fields (such as income from cryptocurrencies or regular transfers from parents)."
}
},
"description": "Object containing the declared gross income of the tax payer."
}
Income
{
"type": "object",
"required": [
"id",
"link",
"created_at",
"income_streams",
"income_source_type",
"first_transaction_date",
"last_transaction_date",
"number_of_income_streams",
"monthly_average",
"monthly_average_regular",
"monthly_average_irregular",
"monthly_average_low_confidence",
"monthly_average_medium_confidence",
"monthly_average_high_confidence",
"total_income_amount",
"total_regular_income_amount",
"total_low_confidence",
"total_medium_confidence",
"total_high_confidence"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "076c66e5-90f5-4e01-99c7-50e32f65ae42",
"description": "Belvo's unique identifier for the current income."
},
"link": {
"type": "string",
"format": "uuid",
"example": "f4621548-2f9e-440e-9ebd-ae8decac8c02",
"description": "The `link.id` the income analysis belongs to."
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-02-09T08:45:50.406032Z",
"description": "The ISO-8601 timestamp of when the data point was created in Belvo's database.\n"
},
"income_streams": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IncomeStreamsBody"
},
"description": "An array of enriched income stream objects."
},
"monthly_average": {
"type": "number",
"format": "float",
"example": 2500,
"description": "Average amount of income received per month across all the accounts for the specific user.\n"
},
"income_source_type": {
"$ref": "#/components/schemas/EnumIncomeSourceType"
},
"total_income_amount": {
"type": "number",
"format": "float",
"example": 22500,
"description": "Total amount of all income received for the specific user.\n"
},
"total_low_confidence": {
"type": "number",
"format": "float",
"example": 0,
"description": "Total amount of income for the specific user with `LOW` confidence.\n"
},
"last_transaction_date": {
"type": "string",
"format": "date",
"example": "2023-02-09",
"description": "The date when when the last transaction occurred, in `YYYY-MM-DD` format.\n"
},
"total_high_confidence": {
"type": "number",
"format": "float",
"example": 22500,
"description": "Total amount of income for the specific user with `HIGH` confidence.\n"
},
"first_transaction_date": {
"type": "string",
"format": "date",
"example": "2022-06-09",
"nullable": true,
"description": "The date when the first transaction occurred, in `YYYY-MM-DD` format.\n"
},
"monthly_average_regular": {
"type": "number",
"format": "float",
"example": 2500,
"description": "Average amount of regular income (with a frequency of `MONTHLY`, `FORTNIGHTLY`, or `WEEKLY`) received per month for the specific user.\n"
},
"total_medium_confidence": {
"type": "number",
"format": "float",
"example": 0,
"description": "Total amount of income for the specific user with `MEDIUM` confidence.\n"
},
"number_of_income_streams": {
"type": "integer",
"format": "int32",
"example": 1,
"description": "Number of total income streams analized.\n"
},
"monthly_average_irregular": {
"type": "number",
"format": "float",
"example": 0,
"description": "Average amount of irregular income (with a frequency of `SINGLE` or `IRREGULAR`) received per month for the specific user.\n"
},
"total_regular_income_amount": {
"type": "number",
"format": "float",
"example": 22500,
"description": "Total amount of regular income (with a frequency of `MONTHLY`, `FORTNIGHTLY`, `WEEKLY`) for the specific user.\n"
},
"total_irregular_income_amount": {
"type": "number",
"format": "float",
"example": 0,
"description": "Total amount of irregular income (with a frequency of `SINGLE` or `IRREGULAR`) for the specific user.\n"
},
"monthly_average_low_confidence": {
"type": "number",
"format": "float",
"example": 0,
"description": "Average amount of income received per month for the specific user with `LOW` confidence.\n"
},
"monthly_average_high_confidence": {
"type": "number",
"format": "float",
"example": 2500,
"description": "Average amount of income received per month for the specific user with `HIGH` confidence.\n"
},
"monthly_average_medium_confidence": {
"type": "number",
"format": "float",
"example": 0,
"description": "Average amount of income received per month for the specific user with `MEDIUM` confidence.\n"
}
},
"description": "Income insights"
}
IncomeEyod
{
"type": "object",
"required": [
"account_holder_id",
"income_streams",
"income_source_type",
"first_transaction_date",
"last_transaction_date",
"number_of_income_streams",
"monthly_average",
"monthly_average_regular",
"monthly_average_irregular",
"monthly_average_low_confidence",
"monthly_average_medium_confidence",
"monthly_average_high_confidence",
"total_income_amount",
"total_regular_income_amount",
"total_low_confidence",
"total_medium_confidence",
"total_high_confidence"
],
"properties": {
"income_streams": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IncomeStreamsBody"
},
"description": "An array of enriched income stream objects."
},
"monthly_average": {
"type": "number",
"format": "float",
"example": 2500,
"description": "Average amount of income received per month across all the accounts for the specific user.\n"
},
"account_holder_id": {
"type": "string",
"example": "f4621548-2f9e-440e-9ebd-ae8decac8c02",
"description": "The unique `account_holder_id` the account belongs to, as you provided in the Income Verification request."
},
"income_source_type": {
"$ref": "#/components/schemas/EnumIncomeSourceType"
},
"total_income_amount": {
"type": "number",
"format": "float",
"example": 22500,
"description": "Total amount of all income received for the specific user.\n"
},
"total_low_confidence": {
"type": "number",
"format": "float",
"example": 0,
"description": "Total amount of income for the specific user with `LOW` confidence.\n"
},
"last_transaction_date": {
"type": "string",
"format": "date",
"example": "2023-02-09",
"description": "The date when when the last transaction occurred, in `YYYY-MM-DD` format.\n"
},
"total_high_confidence": {
"type": "number",
"format": "float",
"example": 22500,
"description": "Total amount of income for the specific user with `HIGH` confidence.\n"
},
"first_transaction_date": {
"type": "string",
"format": "date",
"example": "2022-06-09",
"nullable": true,
"description": "The date when the first transaction occurred, in `YYYY-MM-DD` format.\n"
},
"monthly_average_regular": {
"type": "number",
"format": "float",
"example": 2500,
"description": "Average amount of regular income (with a frequency of `MONTHLY`, `FORTNIGHTLY`, or `WEEKLY`) received per month for the specific user.\n"
},
"total_medium_confidence": {
"type": "number",
"format": "float",
"example": 0,
"description": "Total amount of income for the specific user with `MEDIUM` confidence.\n"
},
"number_of_income_streams": {
"type": "integer",
"format": "int32",
"example": 1,
"description": "Number of total income streams analized.\n"
},
"monthly_average_irregular": {
"type": "number",
"format": "float",
"example": 0,
"description": "Average amount of irregular income (with a frequency of `SINGLE` or `IRREGULAR`) received per month for the specific user.\n"
},
"total_regular_income_amount": {
"type": "number",
"format": "float",
"example": 22500,
"description": "Total amount of regular income (with a frequency of `MONTHLY`, `FORTNIGHTLY`, `WEEKLY`) for the specific user.\n"
},
"total_irregular_income_amount": {
"type": "number",
"format": "float",
"example": 0,
"description": "Total amount of irregular income (with a frequency of `SINGLE` or `IRREGULAR`) for the specific user.\n"
},
"monthly_average_low_confidence": {
"type": "number",
"format": "float",
"example": 0,
"description": "Average amount of income received per month for the specific user with `LOW` confidence.\n"
},
"monthly_average_high_confidence": {
"type": "number",
"format": "float",
"example": 2500,
"description": "Average amount of income received per month for the specific user with `HIGH` confidence.\n"
},
"monthly_average_medium_confidence": {
"type": "number",
"format": "float",
"example": 0,
"description": "Average amount of income received per month for the specific user with `MEDIUM` confidence.\n"
}
},
"description": "Income insights"
}
IncomeStreamsBody
{
"type": "object",
"required": [
"account_id",
"income_type",
"frequency",
"monthly_average",
"average_income_amount",
"last_income_amount",
"currency",
"last_income_description",
"last_income_date",
"stability",
"regularity",
"trend",
"lookback_periods",
"full_periods",
"periods_with_income",
"number_of_incomes",
"confidence"
],
"properties": {
"trend": {
"type": "number",
"format": "float",
"example": 0,
"nullable": true,
"description": "The income trend during a period of time calculated between last income and first income received, where:\n - a negative float means that the income trend is decreasing during the time period.\n - a positive float means that the income trend is increasing during the time period.\n\n**Note:** For transactions with `frequency`=`SINGLE`, this value returns `null`.\n"
},
"currency": {
"type": "string",
"example": "BRL",
"description": "The three-letter currency code of the income. For example:\n\n • 🇧🇷 BRL (Brazilian Real)\n • 🇨🇴 COP (Colombian Peso)\n • 🇲🇽 MXN (Mexican Peso)\n \n"
},
"frequency": {
"$ref": "#/components/schemas/EnumIncomeStreamFrequency"
},
"stability": {
"type": "number",
"format": "float",
"example": 1,
"nullable": true,
"description": "The stability of the income based on its amount, with a range from 0 to 1, where 1 represents perfect stability.\n\n**Note:** For transactions with `frequency`=`SINGLE`, this value returns `null`.\n"
},
"account_id": {
"type": "string",
"example": "EBACA-89077589",
"description": "Unique ID for the bank account to be verified for income streams."
},
"confidence": {
"$ref": "#/components/schemas/EnumIncomeStreamConfidence"
},
"regularity": {
"type": "number",
"format": "float",
"example": 1,
"nullable": true,
"description": "The regularity of the income based in its frequency, with a range from 0 to 1, where 1 represents perfect regularity.\n\n**Note:** For transactions with `frequency`=`SINGLE`, this value returns `null`.\n"
},
"income_type": {
"$ref": "#/components/schemas/EnumIncomeStreamType"
},
"full_periods": {
"type": "integer",
"format": "int32",
"example": 9,
"description": "Number of period units (based on *rolling months*) with data to perform calculations.\n\n**Note:** A *rolling month* is a period of 30 days. For example, 2023-01-15 to 2023-02-15.\n"
},
"monthly_average": {
"type": "number",
"format": "float",
"example": 2500,
"description": "The average amount of income received from the source over `lookback_periods`.\n"
},
"last_income_date": {
"type": "string",
"format": "date",
"example": "2023-02-09",
"description": "The date when the most recent income from the stream was received, in `YYYY-MM-DD` format.\n"
},
"lookback_periods": {
"type": "integer",
"format": "int32",
"example": 9,
"description": "Number of period units (based on *rolling months*) used to generate insights and calculations.\n\n**Note:** A *rolling month* is a period of 30 days. For example, 2023-01-15 to 2023-02-15.\n"
},
"number_of_incomes": {
"type": "integer",
"format": "int32",
"example": 9,
"description": "Number of income transactions over the `lookback_periods`.\n"
},
"last_income_amount": {
"type": "number",
"format": "float",
"example": 2500,
"description": "The amount of the most recent income received from the source.\n"
},
"periods_with_income": {
"type": "integer",
"format": "int32",
"example": 9,
"description": "Number of period units (based on *rolling months*) with at least one income available.\n\n**Note:** A *rolling month* is a period of 30 days. For example, 2023-01-15 to 2023-02-15.\n"
},
"average_income_amount": {
"type": "number",
"format": "float",
"example": 2500,
"description": "The average income transaction amount from the source.\n"
},
"last_income_description": {
"type": "string",
"example": "Salário",
"description": "The description of the most recent income from the stream. \n"
}
},
"description": "A list of income streams for the account.\n\nFor each income stream, we provide additional insights such as:\n- Frequency, stability, and confidence level of the income transactions.\n- Key metrics about the transaction amounts.\nℹ️ If no income sources are found, we return an empty array.\n"
}
IncomeVerificationEnrichUserIncomes400Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
}
]
}
}
IncomeVerificationEnrichUserIncomes401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
IncomeVerificationEnrichUserIncomes403Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/AccessToResourceDenied"
},
"description": "This error occurs when you try to access Belvo's resource without the correct permissions.\n"
}
IncomeVerificationEnrichUserIncomes500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
IncomeVerificationEnrichUserIncomesResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/IncomeEyod"
}
}
IncomesDeleteIncome404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
IncomesDeleteIncomeResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
IncomesGetDetails404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
IncomesGetDetailsResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
IncomesGetInsights401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
IncomesGetInsights408Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RequestTimeoutError"
},
"title": "Request Timeout",
"description": "Belvo has a limit regarding the time it takes to log in, retrieve account data, and log out. A timeout occurs when there is a very high amount of data and everything could not be obtained within the allotted time.\n \n"
}
IncomesGetInsights428Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenRequiredResponse"
}
}
IncomesGetInsights500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
IncomesGetInsightsResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
},
{
"$ref": "#/components/schemas/InvalidPeriodError"
}
]
}
}
IncomesListAllResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
IncomesPaginatedResponse
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/common_pagination_properties"
},
{
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Income"
},
"description": "Array of income objects."
}
}
}
]
}
IncomesRequest
{
"type": "object",
"required": [
"link"
],
"properties": {
"link": {
"type": "string",
"format": "uuid",
"example": "2ccd5e15-194a-4a19-a45a-e7223c7e6717",
"description": "The `link.id` that you want to get information for."
},
"token": {
"type": "string",
"example": "1234ab",
"description": "The OTP token generated by the bank."
},
"date_to": {
"type": "string",
"example": "2020-12-30",
"pattern": "[0-9]{4}-[0-9]{2}-[0-9]{2}",
"description": "The date you want to stop getting incomes for, in `YYYY-MM-DD` format, within the last 365 days. When you use this parameter, you must also send `date_from`.\n\n\n⚠️ You must have at least 90 days between `date_from` and `date_to`.\n\n\n⚠️ The value of `date_to` cannot be greater than today's date (in other words, no future dates).\n"
},
"date_from": {
"type": "string",
"example": "2020-08-01",
"pattern": "[0-9]{4}-[0-9]{2}-[0-9]{2}",
"description": "The date from which you want to start getting incomes for, in `YYYY-MM-DD` format, within the last 365 days. When you use this parameter, you must also send `date_to`.\n\n\n⚠️ You must have at least 90 days between `date_from` and `date_to`.\n\n\n⚠️ The value of `date_from` cannot be greater than `date_to`.\n"
},
"save_data": {
"type": "boolean",
"default": true,
"description": "Indicates whether or not to persist the data in Belvo. By default, this is set to `true` and we return a 201 Created response.\n\nWhen set to `false`, the data won't be persisted and we return a 200 OK response.\n"
},
"allowed_income_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EnumInvoiceAllowedIncomeTypesRequest"
},
"description": "The categories of the incomes you want to get information for."
},
"minimum_confidence_level": {
"$ref": "#/components/schemas/EnumIncomeMinimumConfidenceLevelRequest"
}
}
}
IncomesResumeSession201Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Income"
}
}
IncomesResumeSession400Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
}
]
}
}
IncomesResumeSession401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
IncomesResumeSession408Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RequestTimeoutError"
},
"title": "Request Timeout",
"description": "Belvo has a limit regarding the time it takes to log in, retrieve account data, and log out. A timeout occurs when there is a very high amount of data and everything could not be obtained within the allotted time.\n \n"
}
IncomesResumeSession428Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenRequiredResponse"
}
}
IncomesResumeSession500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
IncomesResumeSessionResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Income"
}
}
Institution
{
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int32",
"example": 1003,
"description": "The ID of the institution as designated by Belvo."
},
"logo": {
"type": "string",
"example": "https://belvo-api-media.s3.amazonaws.com/logos/erebor_logo.png",
"nullable": true,
"description": "The URL of the institution's logo."
},
"name": {
"type": "string",
"example": "erebor_mx_retail",
"description": "The name of the institution, as designated by Belvo.\n\nPlease see our [Institutions](https://developers.belvo.com/docs/institution) DevPortal article for a detailed list of institution names.\n"
},
"type": {
"$ref": "#/components/schemas/EnumInstitutionType"
},
"status": {
"$ref": "#/components/schemas/EnumInstitutionStatus"
},
"website": {
"type": "string",
"example": "https://www.erebor.com/",
"nullable": true,
"description": "The URL of the institution's website."
},
"features": {
"type": "array",
"items": {
"$ref": "#/components/schemas/InstitutionsFeature"
},
"description": "The features that the institution supports. If the institution has no special features, then Belvo returns an empty array.\n\nHere is a list of the available features:\n- `token_required` indicates that the institution may require a token during link creation or when making any other requests.\n"
},
"icon_logo": {
"type": "string",
"example": "https://statics.belvo.io/widget/images/institutions/erebor.svg",
"nullable": true,
"description": "The URL of the institution's icon logo."
},
"resources": {
"type": "array",
"items": {
"type": "string",
"example": "ACCOUNTS",
"description": "A Belvo resource that the institution supports."
},
"example": [
"ACCOUNTS",
"BALANCES",
"INCOMES",
"OWNERS",
"RECURRING_EXPENSES",
"RISK_INSIGHTS",
"TRANSACTIONS"
],
"description": "A list of Belvo resources that you can use with the institution. This list includes one or more of the following resources:\n\n - `ACCOUNTS`\n - `BALANCES`\n - `EMPLOYMENT_RECORDS`\n - `INCOMES`\n - `INVOICES`\n - `OWNERS`\n - `RECURRING_EXPENSES`\n - `RISK_INSIGHTS`\n - `TRANSACTIONS`\n - `TAX_COMPLIANCE_STATUS`\n - `TAX_DECLARATIONS`\n - `TAX_RETENTIONS`\n - `TAX_RETURNS`\n - `TAX_STATUS`\n"
},
"text_logo": {
"type": "string",
"example": "https://statics.belvo.io/widget/images/institutions/erebor.svg",
"nullable": true,
"description": "The URL of the institution's text logo."
},
"form_fields": {
"type": "array",
"items": {
"$ref": "#/components/schemas/InstitutionsFormField"
}
},
"display_name": {
"type": "string",
"example": "Erebor Mexico",
"description": "The customer-facing name of the institution."
},
"country_codes": {
"type": "array",
"items": {
"type": "string",
"example": "MX"
},
"description": "The country codes where the institution is available, for example:\n- 🇧🇷 BR (Brazil)\n- 🇨🇴 CO (Colombia)\n- 🇲🇽 MX (Mexico) \n"
},
"primary_color": {
"type": "string",
"example": "#056dae",
"description": "The primary color on the institution's website."
},
"integration_type": {
"$ref": "#/components/schemas/EnumInstitutionIntegrationType"
}
}
}
InstitutionAccount
{
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "erebor_mx_retail",
"description": "The name of the institution, as designated by Belvo.\n\nPlease see our [Institutions](https://developers.belvo.com/docs/institution) DevPortal article for a detailed list of institution names.\n"
},
"type": {
"$ref": "#/components/schemas/EnumInstitutionType"
}
},
"description": "Details regarding the institution."
}
InstitutionDownError
{
"type": "object",
"title": "Institution Down",
"properties": {
"code": {
"type": "string",
"example": "institution_down",
"description": "A unique error code (`institution_down`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle <a href=\"https://developers.belvo.com/docs/belvo-api-errors#400-institution_down\" target=\"_blank\">400 institution_down errors</a>.\n"
},
"message": {
"type": "string",
"example": "The financial institution is down, try again later",
"description": "A short description of the error. \n\n\nFor `institution_down` errors, the description is:\n \n - `The financial institution is down, try again later`.\n"
},
"request_id": {
"type": "string",
"example": "9e7b283c6efa449c9c028a16b5c249fb",
"pattern": "[a-f0-9]{32}",
"description": "A 32-character unique ID of the request (matching a regex pattern of: `[a-f0-9]{32}`). Provide this ID when contacting the Belvo\nsupport team to accelerate investigations.\n"
}
},
"description": "This error occurs when the institution's website that you're trying to access is down due to maintenance or other issues, which means Belvo is unable to create new links or retrieve new data.\n"
}
InstitutionInactiveError
{
"type": "object",
"title": "Institution Inactive",
"properties": {
"code": {
"type": "string",
"example": "institution_inactive",
"description": "A unique error code (`institution_inactive`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle <a href=\"https://developers.belvo.com/docs/belvo-api-errors#400-institution_inactive\" target=\"_blank\">400 institution_inactive errors</a>.\n"
},
"message": {
"type": "string",
"example": "The institution has been temporarily deactivated",
"description": "A short description of the error. \n\n\nFor `institution_inactive` errors, the description is:\n \n - `The institution has been temporarily deactivated`.\n"
},
"request_id": {
"type": "string",
"example": "9e7b283c6efa449c9c028a16b5c249fb",
"pattern": "[a-f0-9]{32}",
"description": "A 32-character unique ID of the request (matching a regex pattern of: `[a-f0-9]{32}`). Provide this ID when contacting the Belvo\nsupport team to accelerate investigations.\n"
}
},
"description": "This error occurs when we (Belvo) have deactivated the institution in our API.\n"
}
InstitutionUnavailableError
{
"type": "object",
"title": "Institution Unavailable",
"properties": {
"code": {
"type": "string",
"example": "institution_unavailable",
"description": "A unique error code (`institution_unavailable`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how handle <a href=\"https://developers.belvo.com/docs/belvo-api-errors#400-institution_unavailable\" target=\"_blank\">400 institution_unavailable errors</a>.\n"
},
"message": {
"type": "string",
"example": "The financial institution is unavailable",
"description": "A short description of the error.\n\n\nFor `institution_unavailable` errors, the description is:\n \n - `The financial institution is unavailable`.\n"
},
"request_id": {
"type": "string",
"example": "9e7b283c6efa449c9c028a16b5c249fb",
"pattern": "[a-f0-9]{32}",
"description": "A 32-character unique ID of the request (matching a regex pattern of: `[a-f0-9]{32}`). Provide this ID when contacting the Belvo\nsupport team to accelerate investigations.\n"
}
},
"description": "This error occurs when the institution's website that you're trying to access is down due to maintenance or other issues, which means Belvo is unable to create new links or retrieve new data.\n"
}
InstitutionsFeature
{
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "token_required",
"description": "The name of the feature."
},
"description": {
"type": "string",
"example": "The institution may require a token during link creation or login",
"description": "The description of the feature."
}
}
}
InstitutionsFormField
{
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "username",
"description": "The username, password, or username type field."
},
"type": {
"type": "string",
"example": "text",
"description": "The input type for the form field. For example, string."
},
"label": {
"type": "string",
"example": "Client number",
"description": "The label of the form field. For example:\n- Client number\n- Key Bancanet\n- Document\n"
},
"values": {
"type": "array",
"items": {
"$ref": "#/components/schemas/InstitutionsFormFieldValues"
},
"description": "If the form field is for documents, the institution may require additional\ninput regarding the document type.\n"
},
"validation": {
"type": "string",
"example": "^.{1,}$",
"description": "The type of input validation used for the field."
},
"placeholder": {
"type": "string",
"example": "ABC333333A33",
"description": "The placeholder text in the form field."
},
"validation_message": {
"type": "string",
"example": "Invalid client number",
"description": "The message displayed when an invalid input is provided in the form field."
}
}
}
InstitutionsFormFieldValues
{
"type": "object",
"properties": {
"code": {
"type": "string",
"example": "001",
"description": "The code of the document."
},
"label": {
"type": "string",
"example": "Cédula de Ciudadanía",
"description": "The label for the field. For example:\n- Cédula de Ciudadanía\n- Cédula de Extranjería\n- Pasaporte\n"
},
"validation": {
"type": "string",
"example": "^.{1,}$",
"description": "The type of input validation used for the field."
},
"placeholder": {
"type": "string",
"example": "DEF4444908M22",
"description": "The placeholder text in the form field."
},
"validation_message": {
"type": "string",
"example": "Invalid document number",
"description": "The message displayed when an invalid input is provided in the form field."
}
}
}
InstitutionsGetAllResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
InstitutionsGetDetails404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
InstitutionsGetDetailsResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
InstitutionsPaginatedResponse
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/common_pagination_properties"
},
{
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Institution"
},
"description": "Array of institution objects."
}
}
}
]
}
InvalidAccessMode
{
"type": "object",
"title": "Invalid Access Mode",
"properties": {
"code": {
"type": "string",
"example": "invalid_link",
"description": "A unique error code (`invalid_access_mode_switch`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle <a href=\"https://developers.belvo.com/docs/belvo-api-errors#400-invalid_access_mode_switch\" target=\"_blank\">400 invalid_access_mode_switch errors</a>.\n"
},
"message": {
"type": "string",
"example": "This link doesn't have stored credentials hence it can't be switched to recurrent mode\"",
"description": "A short description of the error. \n\n\nFor `invalid_access_mode_switch` errors, the description is:\n \n - `This link doesn't have stored credentials hence it can't be switched to recurrent mode\"`.\n"
},
"request_id": {
"type": "string",
"example": "9e7b283c6efa449c9c028a16b5c249fb",
"pattern": "[a-f0-9]{32}",
"description": "A 32-character unique ID of the request (matching a regex pattern of: `[a-f0-9]{32}`). Provide this ID when contacting the Belvo\nsupport team to accelerate investigations.\n"
}
},
"description": "This error occurs when you try to update a link from single to recurrent, but there are no login credentials stored for the user.\n"
}
InvalidLinkError
{
"type": "object",
"title": "Invalid Link",
"properties": {
"code": {
"type": "string",
"example": "invalid_link",
"description": "A unique error code (`invalid_link`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle <a href=\"https://developers.belvo.com/docs/belvo-api-errors#400-invalid_link\" target=\"_blank\">400 invalid_link errors</a>.\n"
},
"message": {
"type": "string",
"example": "The link has been invalidated. You may need to update link credentials",
"description": "A short description of the error. \n\n\nFor `invalid_link` errors, the description is:\n \n - `The link has been invalidated. You may need to update link credentials`.\n"
},
"request_id": {
"type": "string",
"example": "9e7b283c6efa449c9c028a16b5c249fb",
"pattern": "[a-f0-9]{32}",
"description": "A 32-character unique ID of the request (matching a regex pattern of: `[a-f0-9]{32}`). Provide this ID when contacting the Belvo\nsupport team to accelerate investigations.\n"
}
},
"description": "This error occurs when you try to access an account but the user credentials are no longer valid, prompting an error from the institution.\n"
}
InvalidPeriodError
{
"type": "object",
"title": "Invalid Period",
"properties": {
"code": {
"type": "string",
"example": "invalid_period",
"description": "A unique error code (`invalid_period`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle <a href=\"https://developers.belvo.com/docs/belvo-api-errors#400-invalid_period\" target=\"_blank\">400 invalid_period errors</a>.\n"
},
"message": {
"type": "string",
"example": "The number of days between date_from and date_to must be at least 90 days",
"description": "A short description of the error. \n\n\nFor `invalid_period` errors, the description is:\n \n - `The number of days between date_from and date_to must be at least 90 days`.\n"
},
"request_id": {
"type": "string",
"example": "9e7b283c6efa449c9c028a16b5c249fb",
"pattern": "[a-f0-9]{32}",
"description": "A 32-character unique ID of the request (matching a regex pattern of: `[a-f0-9]{32}`). Provide this ID when contacting the Belvo\nsupport team to accelerate investigations.\n"
}
},
"description": "This error occurs when you request incomes for a link within a given date range, however, the period between `date_from` and `date_to` is less than 90 days.\n"
}
InvoiceDetailDian
{
"type": "object",
"required": [
"description",
"product_identification",
"quantity",
"unit_amount",
"unit_description",
"unit_code",
"pre_tax_amount",
"tax_percentage",
"tax_amount",
"total_amount"
],
"properties": {
"quantity": {
"type": "number",
"format": "float",
"example": 1,
"nullable": true,
"description": "The quantity of this invoice item."
},
"tax_type": {
"type": "string",
"example": "IVA",
"nullable": true,
"description": "The item's tax type."
},
"unit_code": {
"type": "string",
"example": "EA",
"nullable": true,
"description": "The unit of measure, as defined by the legal entity in the country.\n"
},
"tax_amount": {
"type": "number",
"format": "float",
"example": 64,
"nullable": true,
"description": "The amount of tax for this invoice item (`pre_tax_amount` x\n`tax_percentage`).\n"
},
"description": {
"type": "string",
"example": "December 2019 accounting fees",
"nullable": true,
"description": "The description of the invoice item (an invoice can have one or more\nitems).\n"
},
"unit_amount": {
"type": "number",
"format": "float",
"example": 5900,
"nullable": true,
"description": "The price of one singular item."
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2019-09-27T13:01:41.941Z",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"total_amount": {
"type": "number",
"format": "float",
"example": 464,
"nullable": true,
"description": "The total price for this invoice item (`pre_tax_amount` + `tax_amount`)."
},
"pre_tax_amount": {
"type": "number",
"format": "float",
"example": 5900,
"nullable": true,
"description": "The total price for this item before tax is applied (`quantity` x\n`unit_amount`).\n"
},
"tax_percentage": {
"type": "number",
"format": "float",
"example": 16,
"nullable": true,
"description": "The tax percentage to apply."
},
"unit_description": {
"type": "string",
"example": "cada",
"nullable": true,
"description": "The description of the item, as defined by the legal entity in the country.\n"
},
"product_identification": {
"type": "string",
"example": "AE001",
"nullable": true,
"description": "The identification code of the product or the service, as defined by the legal entity in the country.\n"
}
}
}
InvoiceDetailRetainedTaxSat
{
"type": "object",
"required": [
"tax",
"tax_percentage",
"retained_tax_amount"
],
"properties": {
"tax": {
"type": "string",
"example": "ISR",
"nullable": true,
"description": "The type of retained tax (for example, ISR, IVA or IEPS)."
},
"tax_type": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for SAT Mexico and will return `null`.\n"
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2019-09-27T13:01:41.941Z",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"tax_percentage": {
"type": "number",
"format": "float",
"example": 10,
"nullable": true,
"description": "The percentage of tax retained."
},
"retained_tax_amount": {
"type": "number",
"format": "float",
"example": 209.79,
"nullable": true,
"description": "The amount of retained tax."
}
}
}
InvoiceDetailSat
{
"type": "object",
"required": [
"description",
"product_identification",
"quantity",
"unit_amount",
"unit_description",
"unit_code",
"pre_tax_amount",
"tax_percentage",
"tax_amount",
"total_amount"
],
"properties": {
"quantity": {
"type": "number",
"format": "float",
"example": 10,
"nullable": true,
"description": "The quantity of this invoice item."
},
"tax_type": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"unit_code": {
"type": "string",
"example": "E48",
"nullable": true,
"description": "The unit of measure, as defined by the legal entity in the country. \n- 🇲🇽 Mexico [SAT catalog reference](https://developers.belvo.com/docs/sat-catalogs#unit-code)\n"
},
"tax_amount": {
"type": "number",
"format": "float",
"example": 64,
"nullable": true,
"description": "The amount of tax for this invoice item (`pre_tax_amount` x\n`tax_percentage`).\n"
},
"description": {
"type": "string",
"example": "December 2019 accounting fees",
"nullable": true,
"description": "The description of the invoice item (an invoice can have one or more items).\n"
},
"unit_amount": {
"type": "number",
"format": "float",
"example": 200,
"nullable": true,
"description": "The price of one a singular item."
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2019-09-27T13:01:41.941Z",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"total_amount": {
"type": "number",
"format": "float",
"example": 464,
"nullable": true,
"description": "The total price for this invoice item (`pre_tax_amount` + `tax_amount`)."
},
"pre_tax_amount": {
"type": "number",
"format": "float",
"example": 400,
"nullable": true,
"description": "The total price for this item before tax is applied (`quantity` x\n`unit_amount`).\n"
},
"retained_taxes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/InvoiceDetailRetainedTaxSat"
},
"description": "The retained tax on the invoice item."
},
"tax_percentage": {
"type": "number",
"format": "float",
"example": 16,
"nullable": true,
"description": "The tax percentage to apply."
},
"unit_description": {
"type": "string",
"example": "Unidad de servicio",
"nullable": true,
"description": "The description of the item, as defined by the legal entity in the country.\n- 🇲🇽 Mexico [SAT catalog reference](https://developers.belvo.com/docs/sat-catalogs#unit-code)\n"
},
"product_identification": {
"type": "string",
"example": "84101600",
"nullable": true,
"description": "The identification code of the product or the service, as defined by the legal entity in the country.\n- 🇲🇽 [Mexico](http://200.57.3.89/Pys/catPyS.aspx)\n"
}
}
}
InvoiceDian
{
"type": "object",
"title": "🇨🇴 DIAN Colombia",
"required": [
"type",
"invoice_identification",
"invoice_date",
"invoice_type",
"subtotal_amount",
"tax_amount",
"discount_amount",
"total_amount",
"currency",
"exchange_rate",
"status",
"sender_name",
"sender_id",
"receiver_name",
"receiver_id",
"certification_authority",
"certification_date",
"cancelation_status",
"cancelation_update_date",
"payment_type",
"payment_type_description",
"invoice_details",
"payroll",
"payments",
"collected_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "c749315b-eec2-435d-a458-06912878564f",
"description": "Belvo's unique identifier for the current invoice."
},
"xml": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"link": {
"type": "string",
"example": "30cb4806-6e00-48a4-91c9-ca55968576c8",
"description": "The `link.id` the invoice belongs to."
},
"type": {
"$ref": "#/components/schemas/EnumInvoiceType"
},
"folio": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"usage": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"status": {
"type": "string",
"example": "Aprobado",
"nullable": true,
"description": "The status of the invoice. Can be one of:\n\n - *Aprobado* (approved)\n - *Aprobado con notificación* (approved with notification)\n"
},
"payroll": {
"$ref": "#/components/schemas/InvoicesPayrollDian"
},
"version": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"currency": {
"type": "string",
"example": "COP",
"nullable": true,
"description": "The currency of the invoice. For example:\n \n - 🇧🇷 BRL (Brazilian Real)\n - 🇨🇴 COP (Colombian Peso)\n - 🇲🇽 MXN (Mexican Peso)\n - 🇺🇸 USD (United States Dollar)\n"
},
"payments": {
"type": "array",
"items": {
"$ref": "#/components/schemas/InvoicesPaymentsDian"
},
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"warnings": {
"$ref": "#/components/schemas/InvoiceWarningsDian"
},
"sender_id": {
"type": "string",
"example": "YHS922233648",
"nullable": true,
"description": "The fiscal ID of the invoice sender."
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-02-09T08:45:50.406032Z",
"description": "The ISO-8601 timestamp of when the data point was last updated in Belvo's database.\n"
},
"tax_amount": {
"type": "number",
"format": "float",
"example": 64,
"nullable": true,
"description": "The amount of tax for this invoice (sum of each item's `tax_amount`).\n"
},
"receiver_id": {
"type": "string",
"example": "BBB222222BB22",
"nullable": true,
"description": "The fiscal ID of the invoice receiver."
},
"sender_name": {
"type": "string",
"example": "ACME Corp Colombia",
"nullable": true,
"description": "The name of the invoice sender."
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2019-09-27T13:01:41.941Z",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"invoice_date": {
"type": "string",
"example": "2019-12-01",
"nullable": true,
"description": "The date of the invoice, in `YYYY-MM-DD` format."
},
"invoice_type": {
"$ref": "#/components/schemas/EnumInvoiceDianInvoiceType"
},
"payment_type": {
"type": "string",
"example": "47",
"nullable": true,
"description": "The payment type code used for this invoice, as defined by the country legal entity.\n\nFor detailed information regarding DIAN's payment types, please see their [official PDF](https://www.dian.gov.co/impuestos/factura-electronica/Documents/Anexo_tecnico_factura_electronica_vr_1_7_2020.pdf). \n"
},
"total_amount": {
"type": "number",
"format": "float",
"example": 454,
"nullable": true,
"description": "The total amount of the invoice (`subtotal_amount` + `tax_amount` -\n`discount_amount`)\n"
},
"exchange_rate": {
"type": "number",
"format": "float",
"example": 0.053,
"nullable": true,
"description": "The exchange rate used in this invoice for the currency.\n"
},
"receiver_name": {
"type": "string",
"example": "Roadrunner Traps Colombia",
"nullable": true,
"description": "The name of the invoice receiver."
},
"payment_method": {
"$ref": "#/components/schemas/EnumInvoiceDianPaymentMethod"
},
"place_of_issue": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"sender_details": {
"$ref": "#/components/schemas/InvoiceSenderDetailsDian"
},
"discount_amount": {
"type": "number",
"format": "float",
"example": 10,
"nullable": true,
"description": "The total amount discounted in this invoice.\n"
},
"expiration_date": {
"type": "string",
"format": "date",
"example": "2022-08-19",
"nullable": true,
"description": "The date when the invoice is set to expire, in `YYYY-MM-DD` format.\n\nFor example: If the invoice is paid in installments, this field indicates the date when the installment is to be paid.\n"
},
"invoice_details": {
"type": "array",
"items": {
"$ref": "#/components/schemas/InvoiceDetailDian"
},
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"subtotal_amount": {
"type": "number",
"format": "float",
"example": 400,
"nullable": true,
"description": "The pretax amount of this invoice (sum of each item's `pre_tax_amount`).\n"
},
"receiver_details": {
"$ref": "#/components/schemas/InvoicesReceiverDetailsDian"
},
"cancelation_status": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"certification_date": {
"type": "string",
"format": "date",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"invoice_identification": {
"type": "string",
"example": "89868fda605e6250a7ecb910dc57ed6f8147c6dc39ec90805bb655a0646e6cc3f991f93463f62e03d236b9cc9c293edc",
"nullable": true,
"description": "The fiscal institution's unique ID for the invoice."
},
"cancelation_update_date": {
"type": "string",
"format": "date",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"certification_authority": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"sender_tax_fraud_status": {
"type": "string",
"example": null,
"nullable": true,
"description": "Indicates whether or not the sender is on a tax fraud list for having submitted incorrect data, having outstanding payments, or having conducted business that is in violation of the fiscal institution's regulations.\n\n**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"payment_type_description": {
"type": "string",
"example": null,
"nullable": true,
"description": "The description of the payment method used for this invoice.\n"
},
"receiver_tax_fraud_status": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"payment_method_description": {
"type": "string",
"example": null,
"nullable": true,
"deprecated": true,
"description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our [Deprecated fields](https://developers.belvo.com/reference/using-the-api-reference#%EF%B8%8F-deprecated-fields) explanation.*\n\n*The description of the payment method used for this invoice.*\n"
}
}
}
InvoiceSenderDetailsDian
{
"type": "object",
"nullable": true,
"properties": {
"email": {
"type": "string",
"example": "acme_colombia@gmail.com",
"nullable": true,
"description": "The sender's email address.\n"
},
"address": {
"type": "string",
"example": "Calle 144 No. 12-09",
"nullable": true,
"description": "The sender's address.\n"
},
"country": {
"type": "string",
"example": "Colombia",
"nullable": true,
"description": "The country where the sender pays their taxes.\n"
},
"regimen": {
"type": "string",
"example": "Régimen Simple de Tributación - SIMPLE",
"nullable": true,
"description": "The sender's regimen type.\n\nFor detailed information regarding DIAN's regimens, please see their [official PDF](https://www.dian.gov.co/impuestos/factura-electronica/Documents/Anexo_tecnico_factura_electronica_vr_1_7_2020.pdf). \n"
},
"tax_scheme": {
"type": "string",
"example": "01-IVA",
"nullable": true,
"description": "The sender's fiscal responsibilities.\n\nFor detailed information regarding DIAN's tax schemes, please see their [official PDF](https://www.dian.gov.co/impuestos/factura-electronica/Documents/Anexo_tecnico_factura_electronica_vr_1_7_2020.pdf). \n"
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2020-04-23T21:32:55.336854+00:00",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected."
},
"phone_number": {
"type": "string",
"example": "576606522566",
"nullable": true,
"description": "The sender's phone number.\n"
},
"tax_payer_type": {
"type": "string",
"example": "Persona Natural",
"nullable": true,
"description": "Indicates if the sender is a business or an individual. Can be either:\n \n - `Persona Jurídica`\n - `Persona Natural`\n"
}
},
"description": "Details regarding the sender.\n"
}
InvoiceWarningsDian
{
"type": "object",
"nullable": true,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"message": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
}
},
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
}
InvoiceWarningsSat
{
"type": "object",
"nullable": true,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"example": "sat_xml_limit_reached",
"nullable": true,
"description": "The warning code. Can be one of:\n\n - `sat_xml_limit_reached`\n - `sat_service_unavailable`\n - `null`\n"
},
"message": {
"type": "string",
"example": "The daily limit for XML downloads set by SAT was reached so this invoice\nmight be missing data. Please check https://tinyurl.com/yydzhy5d for more\ninformation on this error.\n",
"nullable": true,
"description": "The description of the warning.\n\nThe message will depend on the warning code:\n\n`sat_xml_limit_reached`<br>\nThe daily limit for XML downloads set by SAT was reached so this invoice might be missing data. Please check https://tinyurl.com/yydzhy5d for more information on this error.\n\n`sat_service_unavailable` <br>\nDownloading invoices details is not available. The SAT portal raised a 503 error.\n"
}
},
"description": "Object containing information about any warnings related to this invoice.\n"
}
InvoiceWithIdSat
{
"type": "object",
"title": "🇲🇽 SAT Mexico",
"required": [
"type",
"invoice_identification",
"invoice_date",
"invoice_type",
"subtotal_amount",
"tax_amount",
"discount_amount",
"total_amount",
"currency",
"exchange_rate",
"status",
"sender_name",
"sender_id",
"receiver_name",
"receiver_id",
"certification_authority",
"certification_date",
"cancelation_status",
"cancelation_update_date",
"payment_type",
"payment_type_description",
"invoice_details",
"payroll",
"payments",
"collected_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "c749315b-eec2-435d-a458-06912878564f",
"description": "Belvo's unique identifier used to reference the current invoice."
},
"xml": {
"type": "string",
"nullable": true,
"description": "XML of the invoice document.\n"
},
"link": {
"type": "string",
"example": "30cb4806-6e00-48a4-91c9-ca55968576c8",
"description": "The `link.id` the invoice belongs to."
},
"type": {
"$ref": "#/components/schemas/EnumInvoiceType"
},
"folio": {
"type": "string",
"example": "26",
"nullable": true,
"description": "The internal control number that the taxpayer assigns to the invoice.\n"
},
"usage": {
"type": "string",
"example": "P01",
"nullable": true,
"description": "The invoice's usage code, as defined by the legal entity of the country. \n\n- 🇲🇽 Mexico [SAT catalog reference article](https://developers.belvo.com/docs/sat-catalogs#usage)\n"
},
"status": {
"type": "string",
"example": "Vigente",
"nullable": true,
"description": "The status of the invoice. Can be either *Vigente* (valid) or *Cancelado*\n(cancelled).\n"
},
"payroll": {
"$ref": "#/components/schemas/InvoicesPayrollSat"
},
"version": {
"type": "string",
"example": "3.3",
"nullable": true,
"description": "The CFDI version of the invoice.\n"
},
"currency": {
"type": "string",
"example": "MXN",
"nullable": true,
"description": "The currency of the invoice. For example:\n \n - 🇧🇷 BRL (Brazilian Real)\n - 🇨🇴 COP (Colombian Peso)\n - 🇲🇽 MXN (Mexican Peso)\n - 🇺🇸 USD (United States Dollar)\n"
},
"payments": {
"type": "array",
"items": {
"$ref": "#/components/schemas/InvoicesPaymentsSat"
},
"description": "A list detailing all the invoice payments.\n"
},
"warnings": {
"$ref": "#/components/schemas/InvoiceWarningsSat"
},
"sender_id": {
"type": "string",
"example": "AAA111111AA11",
"nullable": true,
"description": "The fiscal ID of the invoice sender"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-02-09T08:45:50.406032Z",
"description": "The ISO-8601 timestamp of when the data point was last updated in Belvo's database.\n"
},
"tax_amount": {
"type": "number",
"format": "float",
"example": 64,
"nullable": true,
"description": "The amount of tax for this invoice (sum of each item's `tax_amount`).\n"
},
"receiver_id": {
"type": "string",
"example": "BBB222222BB22",
"nullable": true,
"description": "The fiscal ID of the invoice receiver."
},
"sender_name": {
"type": "string",
"example": "ACME CORP",
"nullable": true,
"description": "The name of the invoice sender."
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2019-09-27T13:01:41.941Z",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"invoice_date": {
"type": "string",
"example": "2019-12-01",
"nullable": true,
"description": "The date of the invoice, in `YYYY-MM-DD` format."
},
"invoice_type": {
"$ref": "#/components/schemas/EnumInvoiceSatInvoiceType"
},
"payment_type": {
"type": "string",
"example": "99",
"nullable": true,
"description": "The payment type code used for this invoice, as defined by the country legal entity.\n\n- 🇲🇽 Mexico [SAT catalog reference article](https://developers.belvo.com/docs/sat-catalogs#payment-type)\n"
},
"total_amount": {
"type": "number",
"format": "float",
"example": 454,
"nullable": true,
"description": "The total amount of the invoice (`subtotal_amount` + `tax_amount` -\n`discount_amount`)\n"
},
"exchange_rate": {
"type": "number",
"format": "float",
"example": 0.052,
"nullable": true,
"description": "The exchange rate used in this invoice for the currency.\n"
},
"receiver_name": {
"type": "string",
"example": "BELVO CORP",
"nullable": true,
"description": "The name of the invoice receiver."
},
"payment_method": {
"$ref": "#/components/schemas/EnumInvoiceSatPaymentMethod"
},
"place_of_issue": {
"type": "string",
"example": "01165",
"nullable": true,
"description": "The postcode of where the invoice was issued.\n"
},
"discount_amount": {
"type": "number",
"format": "float",
"example": 10,
"nullable": true,
"description": "The total amount discounted in this invoice.\n"
},
"invoice_details": {
"type": "array",
"items": {
"$ref": "#/components/schemas/InvoiceDetailSat"
},
"description": "A list of descriptions for each item (purchased product or service provided) in the invoice.\n"
},
"subtotal_amount": {
"type": "number",
"format": "float",
"example": 400,
"nullable": true,
"description": "The pretax amount of this invoice (sum of each item's `pre_tax_amount`).\n"
},
"cancelation_status": {
"type": "string",
"nullable": true,
"description": "If the invoice is cancelled, this field indicates the status of the cancellation.\n"
},
"certification_date": {
"type": "string",
"format": "date",
"example": "2019-12-01",
"nullable": true,
"description": "The date of the fiscal certification, in `YYYY-MM-DD` format.\n"
},
"invoice_identification": {
"type": "string",
"example": "A1A1A1A1-2B2B-3C33-D44D-555555E55EE",
"nullable": true,
"description": "The fiscal institution's unique ID for the invoice."
},
"cancelation_update_date": {
"type": "string",
"format": "date",
"example": "2019-12-02",
"nullable": true,
"description": "The date of the invoice cancelation, in `YYYY-MM-DD` format.\n"
},
"certification_authority": {
"type": "string",
"example": "CCC333333CC33",
"nullable": true,
"description": "The fiscal ID of the certification provider.\n"
},
"sender_blacklist_status": {
"type": "string",
"example": null,
"nullable": true,
"deprecated": true,
"description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our [Deprecated fields](https://developers.belvo.com/reference/using-the-api-reference#%EF%B8%8F-deprecated-fields) explanation.*\nPlease use `sender_tax_fraud_status` instead.\n"
},
"sender_tax_fraud_status": {
"type": "string",
"example": "NO_TAX_FRAUD_STATUS",
"nullable": true,
"description": "Indicates whether or not the sender is on SAT's tax fraud list for having submitted incorrect data, having outstanding payments, or having conducted business that is in violation of the fiscal institution's regulations.<br><br>\n\nSAT updates the tax fraud list every three months. <br><br>\n\nFor more information regarding the reason's a taxpayer can be put on the tax fraud list, please see [Article 69](http://omawww.sat.gob.mx/cifras_sat/Paginas/datos/vinculo.html?page=ListCompleta69.html) and [Article 69-B](http://omawww.sat.gob.mx/cifras_sat/Paginas/datos/vinculo.html?page=ListCompleta69B.html) of Mexico's Código Fiscal de la Federación.\n<br><br>\n\nPossible statuses are:\n\n- `INVESTIGATING` <br>\nThe fiscal institution has identified irregularities and open an investigation regarding the taxpayer.\n<br>\n- `DISMISSED` <br>\nThe fiscal institution has investigated the taxpayer and declared them innocent.\n<br>\n- `CONFIRMED` <br>\nThe fiscal institution has confirmed that the taxpayer is guilty.\n<br>\n- `OVERTURNED` <br>\nThe fiscal institution has reassessed a previously confirmed taxpayer and, based on new evidence, has taken the taxpayer off the tax fraud list.\n<br>\n- `NO_TAX_FRAUD_STATUS` <br>\nThe receiver or sender is not found in the list (in other words, they are complying with the fiscal institution's regulations).\n"
},
"payment_type_description": {
"type": "string",
"example": null,
"nullable": true,
"deprecated": true,
"description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our [Deprecated fields](https://developers.belvo.com/reference/using-the-api-reference#%EF%B8%8F-deprecated-fields) explanation.*\n"
},
"receiver_blacklist_status": {
"type": "string",
"example": null,
"nullable": true,
"deprecated": true,
"description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our [Deprecated fields](https://developers.belvo.com/reference/using-the-api-reference#%EF%B8%8F-deprecated-fields) explanation.*\nPlease use `receiver_tax_fraud_status` instead.\n"
},
"receiver_tax_fraud_status": {
"type": "string",
"example": "NO_TAX_FRAUD_STATUS",
"nullable": true,
"description": "Indicates whether or not the receiver is on SAT's tax fraud list for having submitted incorrect data, having outstanding payments, or having conducted business that is in violation of the fiscal institution's regulations.<br><br>\n\nSAT updates the tax fraud list every three months. <br><br>\n\nFor more information regarding the reason's a taxpayer can be put on the tax fraud list, please see [Article 69](http://omawww.sat.gob.mx/cifras_sat/Paginas/datos/vinculo.html?page=ListCompleta69.html) and [Article 69-B](http://omawww.sat.gob.mx/cifras_sat/Paginas/datos/vinculo.html?page=ListCompleta69B.html) of Mexico's Código Fiscal de la Federación.\n<br><br>\n\nPossible statuses are:\n\n- `INVESTIGATING` <br>\nThe fiscal institution has identified irregularities and open an investigation regarding the taxpayer.\n<br>\n- `DISMISSED` <br>\nThe fiscal institution has investigated the taxpayer and declared them innocent.\n<br>\n- `CONFIRMED` <br>\nThe fiscal institution has confirmed that the taxpayer is guilty.\n<br>\n- `OVERTURNED` <br>\nThe fiscal institution has reassessed a previously confirmed taxpayer and, based on new evidence, has taken the taxpayer off the tax fraud list.\n<br>\n- `NO_TAX_FRAUD_STATUS` <br>\nThe receiver or sender is not found in the list (in other words, they are complying with the fiscal institution's regulations).\n"
},
"payment_method_description": {
"type": "string",
"example": null,
"nullable": true,
"deprecated": true,
"description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our [Deprecated fields](https://developers.belvo.com/reference/using-the-api-reference#%EF%B8%8F-deprecated-fields) explanation.*\n\n*The description of the payment method used for this invoice.*\n"
}
}
}
InvoicesCompleteRequest201Response
{
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/InvoiceWithIdSat"
},
{
"$ref": "#/components/schemas/InvoiceDian"
}
]
}
}
InvoicesCompleteRequest400Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
}
]
}
}
InvoicesCompleteRequest401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
InvoicesCompleteRequest408Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RequestTimeoutError"
},
"title": "Request Timeout",
"description": "Belvo has a limit regarding the time it takes to log in, retrieve account data, and log out. A timeout occurs when there is a very high amount of data and everything could not be obtained within the allotted time.\n \n"
}
InvoicesCompleteRequest428Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenRequiredResponse"
}
}
InvoicesCompleteRequest500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
InvoicesCompleteRequestResponse
{
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/InvoiceWithIdSat"
},
{
"$ref": "#/components/schemas/InvoiceDian"
}
]
}
}
InvoicesDeleteInvoice404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
InvoicesDeleteInvoiceResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
InvoicesGetDetails401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
InvoicesGetDetails404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
InvoicesGetDetailsResponse
{
"oneOf": [
{
"$ref": "#/components/schemas/InvoiceWithIdSat"
},
{
"$ref": "#/components/schemas/InvoiceDian"
}
]
}
InvoicesGetLinkInvoices201Response
{
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/InvoiceWithIdSat"
},
{
"$ref": "#/components/schemas/InvoiceDian"
}
]
}
}
InvoicesGetLinkInvoices400Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
}
]
}
}
InvoicesGetLinkInvoices401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
InvoicesGetLinkInvoices408Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RequestTimeoutError"
},
"title": "Request Timeout",
"description": "Belvo has a limit regarding the time it takes to log in, retrieve account data, and log out. A timeout occurs when there is a very high amount of data and everything could not be obtained within the allotted time.\n \n"
}
InvoicesGetLinkInvoices500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
InvoicesGetLinkInvoicesResponse
{
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/InvoiceWithIdSat"
},
{
"$ref": "#/components/schemas/InvoiceDian"
}
]
}
}
InvoicesListAllResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
InvoicesPaymentsDian
{
"type": "object",
"required": [
"date",
"payment_type",
"currency",
"exchange_rate",
"amount",
"operation_number",
"beneficiary_account_number",
"payer_rfc",
"payer_account_number",
"payer_bank_name",
"related_documents"
],
"properties": {
"date": {
"type": "string",
"format": "date-time",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"amount": {
"type": "number",
"format": "float",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"currency": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"payer_rfc": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"payment_type": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"exchange_rate": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"beneficiary_rfc": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"payer_bank_name": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"operation_number": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"related_documents": {
"type": "array",
"items": {
"$ref": "#/components/schemas/InvoicesPaymentsRelatedDocumentsDian"
},
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"payer_account_number": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"beneficiary_account_number": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
}
}
}
InvoicesPaymentsRelatedDocumentsDian
{
"type": "object",
"required": [
"invoice_identification",
"currency",
"payment_method",
"previous_balance",
"amount_paid",
"outstanding_balance"
],
"properties": {
"currency": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"amount_paid": {
"type": "number",
"format": "float",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"payment_method": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"previous_balance": {
"type": "number",
"format": "float",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"partiality_number": {
"type": "integer",
"format": "int32",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"outstanding_balance": {
"type": "number",
"format": "float",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"invoice_identification": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
}
},
"description": "List of all the related deferred invoices affected by the payment."
}
InvoicesPaymentsRelatedDocumentsSat
{
"type": "object",
"required": [
"invoice_identification",
"currency",
"payment_method",
"previous_balance",
"amount_paid",
"outstanding_balance"
],
"properties": {
"currency": {
"type": "string",
"example": "MXN",
"nullable": true,
"description": "The currency of the related invoice. For example:\n \n- 🇧🇷 BRL (Brazilian Real)\n- 🇨🇴 COP (Colombian Peso)\n- 🇲🇽 MXN (Mexican Peso)\n \n Please note that other currencies other than in the list above may be returned.\n"
},
"amount_paid": {
"type": "number",
"format": "float",
"example": 8000,
"nullable": true,
"description": "The amount paid in this installment.\n"
},
"payment_method": {
"type": "string",
"example": "PPD",
"nullable": true,
"description": "The payment method of the related invoice.\n"
},
"previous_balance": {
"type": "number",
"format": "float",
"example": 18877.84,
"nullable": true,
"description": "The invoice amount before the payment.\n"
},
"partiality_number": {
"type": "integer",
"format": "int32",
"example": 1,
"description": "The payment installment number.\n"
},
"outstanding_balance": {
"type": "number",
"format": "float",
"example": 10877.84,
"nullable": true,
"description": "The amount remaining to be paid.\n"
},
"invoice_identification": {
"type": "string",
"example": "7EE015F3-6311-11EA-B02A-00155D014007",
"nullable": true,
"description": "The fiscal institution's unique ID for the related deferred invoice.\n"
}
},
"description": "List of all the related deferred invoices affected by the payment."
}
InvoicesPaymentsSat
{
"type": "object",
"required": [
"date",
"payment_type",
"currency",
"exchange_rate",
"amount",
"operation_number",
"beneficiary_account_number",
"payer_rfc",
"payer_account_number",
"payer_bank_name",
"related_documents"
],
"properties": {
"date": {
"type": "string",
"format": "date-time",
"example": "2020-03-17T12:00:00.000Z",
"nullable": true,
"description": "ISO-8601 timestamp when the payment was made.\n"
},
"amount": {
"type": "number",
"format": "float",
"example": 8000.5,
"nullable": true,
"description": "The invoice amount, in the currency of the original invoice.\n"
},
"currency": {
"type": "string",
"example": "BRL",
"nullable": true,
"description": "The currency of the payment. For example:\n\n- 🇧🇷 BRL (Brazilian Real)\n- 🇨🇴 COP (Colombian Peso)\n- 🇲🇽 MXN (Mexican Peso)\n\nPlease note that other currencies other than in the list above may be returned.\n"
},
"payer_rfc": {
"type": "string",
"example": "BKJM840515VB1",
"nullable": true,
"description": "The fiscal ID of the payment issuer.\n"
},
"payment_type": {
"type": "string",
"example": "03",
"nullable": true,
"description": "Payment type code used for this invoice, as defined by the country's legal entity.\n\n- 🇲🇽 Mexico [SAT catalog reference article](https://developers.belvo.com/docs/sat-catalogs#payment-type)\n"
},
"exchange_rate": {
"type": "string",
"example": "3.75",
"nullable": true,
"description": "The `currency` to MXN currency exchange rate when the payment was made.\n"
},
"beneficiary_rfc": {
"type": "string",
"example": "BNM840515VB1",
"nullable": true,
"description": "The fiscal ID of the payment beneficiary.\n"
},
"payer_bank_name": {
"type": "string",
"example": "CITI BANAMEX",
"nullable": true,
"description": "The banking institution that was used by the payment issuer.\n"
},
"operation_number": {
"type": "string",
"example": "831840",
"nullable": true,
"description": "The fiscal institution's internal identifier for the operation.\n"
},
"related_documents": {
"type": "array",
"items": {
"$ref": "#/components/schemas/InvoicesPaymentsRelatedDocumentsSat"
},
"description": "A list of all the related deferred invoices affected by the payment.\n"
},
"payer_account_number": {
"type": "string",
"example": "13343663245699",
"nullable": true,
"description": "The bank account number of the payment issuer.\n"
},
"beneficiary_account_number": {
"type": "string",
"example": "12343453245633",
"nullable": true,
"description": "The bank account number of the payment beneficiary.\n"
}
}
}
InvoicesPayrollDian
{
"type": "object",
"nullable": true,
"required": [
"version",
"type",
"payment_date",
"date_from",
"date_to",
"days",
"amount"
],
"properties": {
"days": {
"type": "integer",
"format": "int32",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"type": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"amount": {
"type": "number",
"format": "float",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"date_to": {
"type": "string",
"format": "date",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"version": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"date_from": {
"type": "string",
"format": "date",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"payment_date": {
"type": "string",
"format": "date",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
}
},
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
}
InvoicesPayrollSat
{
"type": "object",
"nullable": true,
"required": [
"version",
"type",
"payment_date",
"date_from",
"date_to",
"days",
"amount"
],
"properties": {
"days": {
"type": "integer",
"format": "int32",
"example": 30,
"nullable": true,
"description": "The number of days covered by the payment.\n"
},
"type": {
"type": "string",
"example": "O",
"nullable": true,
"description": "The payroll type, as defined by the legal entity of the country.\n\n- 🇲🇽 Mexico [SAT catalog reference article](https://developers.belvo.com/docs/sat-catalogs#payroll-type)\n"
},
"amount": {
"type": "number",
"format": "float",
"example": 20400.1,
"description": "The total amount of the payroll payment.\n"
},
"date_to": {
"type": "string",
"format": "date",
"example": "2018-07-31",
"nullable": true,
"description": "The end date of the payment period, in `YYYY-MM-DD` format.\n"
},
"version": {
"type": "string",
"example": "1.2",
"description": "The version of the payroll object.\n"
},
"date_from": {
"type": "string",
"format": "date",
"example": "2018-07-01",
"nullable": true,
"description": "The start date of the payment period, in `YYYY-MM-DD` format.\n"
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2019-09-27T13:01:41.941Z",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"payment_date": {
"type": "string",
"format": "date",
"description": "The payment date, in `YYYY-MM-DD` format.\n"
}
},
"description": "Details regarding the payroll payment. Only applicable for payroll invoices.\n"
}
InvoicesReceiverDetailsDian
{
"type": "object",
"nullable": true,
"properties": {
"email": {
"type": "string",
"example": "acme_colombia@gmail.com",
"nullable": true,
"description": "The receiver's email address.\n"
},
"address": {
"type": "string",
"example": "Calle 144 No. 12-09",
"nullable": true,
"description": "The receiver's address.\n"
},
"country": {
"type": "string",
"example": "Colombia",
"nullable": true,
"description": "The country where the receiver pays their taxes.\n"
},
"regimen": {
"type": "string",
"example": "Régimen Simple de Tributación - SIMPLE",
"nullable": true,
"description": "The receiver's regimen type.\n\nFor detailed information regarding DIAN's regimens, please see their [official PDF](https://www.dian.gov.co/impuestos/factura-electronica/Documents/Anexo_tecnico_factura_electronica_vr_1_7_2020.pdf). \n"
},
"tax_scheme": {
"type": "string",
"example": "01-IVA",
"nullable": true,
"description": "The receiver's fiscal responsibilities.\n\nFor detailed information regarding DIAN's tax schemes, please see their [official PDF](https://www.dian.gov.co/impuestos/factura-electronica/Documents/Anexo_tecnico_factura_electronica_vr_1_7_2020.pdf). \n"
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2020-04-23T21:32:55.336854+00:00",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected."
},
"phone_number": {
"type": "string",
"example": "576606522566|",
"nullable": true,
"description": "The receiver's phone number.\n"
},
"tax_payer_type": {
"type": "string",
"example": "Persona Natural",
"nullable": true,
"description": "Indicates if the receiver is a business or an individual. Can be either:\n \n - `Persona Jurídica`\n - `Persona Natural`\n"
}
},
"description": "Details regarding the receiver.\n"
}
InvoicesRequest
{
"type": "object",
"required": [
"date_from",
"date_to",
"link",
"type"
],
"properties": {
"link": {
"type": "string",
"format": "uuid",
"example": "d4617561-1c01-4b2f-83b6-a594f7b3bc57",
"description": "The fiscal `link.id` to use."
},
"type": {
"$ref": "#/components/schemas/EnumInvoiceType"
},
"date_to": {
"type": "string",
"example": "2020-02-01",
"pattern": "[0-9]{4}-[0-9]{2}-[0-9]{2}",
"description": "The date you want to stop getting invoices for, in `YYYY-MM-DD` format.\n\n⚠️ The number of days between `date_from` and `date_to` cannot be over 365.\n\n⚠️ The value of `date_to` cannot be greater than today's date (in other words, no future dates).\n"
},
"date_from": {
"type": "string",
"example": "2020-01-01",
"pattern": "[0-9]{4}-[0-9]{2}-[0-9]{2}",
"description": "The date from which you want to start getting invoices for, in `YYYY-MM-DD` format.\n\n⚠️ The value of `date_from` cannot be greater than `date_to`.\n"
},
"save_data": {
"type": "boolean",
"default": true,
"example": true,
"description": "Indicates whether or not to persist the data in Belvo. By default, this is set to `true` and we return a 201 Created response.\n\nWhen set to `false`, the data won't be persisted and we return a 200 OK response.\n"
},
"attach_xml": {
"type": "boolean",
"default": false,
"description": "When set to `true`, you will receive the XML invoice in the\nresponse.\n"
}
}
}
InvoicesResponsePaginatedResponse
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/common_pagination_properties"
},
{
"properties": {
"results": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/InvoiceWithIdSat"
},
{
"$ref": "#/components/schemas/InvoiceDian"
}
]
},
"description": "Array of invoice objects."
}
}
}
]
}
Link
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "30cb4806-6e00-48a4-91c9-ca55968576c8",
"description": "Belvo's unique ID for the current Link."
},
"status": {
"$ref": "#/components/schemas/EnumLinkStatus"
},
"stale_in": {
"type": "string",
"example": "90d",
"nullable": true,
"description": "Indicates how long any data will be stored in Belvo's database for the link (both single and recurrent), relative to the `last_accessed_at` parameter.\n"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-02-09T08:45:50.406032Z",
"description": "The ISO-8601 timestamp of when the data point was last updated in Belvo's database.\n"
},
"created_by": {
"type": "string",
"format": "uuid",
"example": "bcef7f35-67f2-4b19-b009-cb38795faf09",
"description": "The unique ID for the user that created this link."
},
"access_mode": {
"$ref": "#/components/schemas/EnumLinkAccessModeResponse"
},
"external_id": {
"type": "string",
"example": "56ab5706-6e00-48a4-91c9-ca55968678d9",
"nullable": true,
"minLength": 3,
"description": "The `external_id` you provided as an additional identifier for the link.\nFor more information, see our [Link creation\narticle](https://developers.belvo.com/docs/link-creation-best-practices#adding-your-own-identifier).\n"
},
"institution": {
"type": "string",
"example": "erebor_mx_retail",
"description": "Belvo's name for the institution.\n"
},
"refresh_rate": {
"$ref": "#/components/schemas/EnumLinkRefreshRate"
},
"fetch_resources": {
"type": "array",
"items": {
"type": "string",
"example": "ACCOUNTS",
"description": "A Belvo resource that the institution supports."
},
"example": [
"ACCOUNTS",
"TRANSACTIONS"
],
"description": "An array of resources that you will receive a historical update for.\n"
},
"last_accessed_at": {
"type": "string",
"format": "date-time",
"example": "2019-09-27T13:02:03.584Z",
"nullable": true,
"description": "The ISO-8601 timestamp of Belvo's most recent successful access to the institution for the given link.\n"
},
"credentials_storage": {
"type": "string",
"example": "27d",
"description": "Indicates how long credentials are stored. For links where `access_mode=recurrent`, this is set to `store`.\n\nWe return one of the following values:\n\n - `store` - credentials are stored (until the link is deleted).\n - `nostore` - credentials are not stored.\n - Any value between `1d` and `365d` to indicate the number of days the credentials are stored (from when the link was `created_at`).\n \n"
},
"institution_user_id": {
"type": "string",
"example": "sooE7XJWEKypZJR603ecaWYk-8Ap0oD8Nr1pBQ4eG9c=",
"pattern": "[A-Za-z0-9\\-=_]{44}",
"description": "<div style=\"background-color:#f4f6f8; border-left: 6px solid #0663F9;padding: 12px;margin-left: 25px; border-radius: 4px; margin-right: 25px\">\n<strong>Info:</strong> Only applicable for links created <b>after 08-02-2022</b>.\n</div>\n\n\nA unique 44-character string that can be used to identify a user at a given institution.\n\n\n📚 Check out our [Avoiding duplicated links](https://developers.belvo.com/docs/link-creation-best-practices#avoiding-duplicated-links) DevPortal article for more information and tips on how to use it.\n"
}
}
}
LinksChangeAccessMode401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
LinksChangeAccessMode404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
LinksChangeAccessMode428Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenRequiredResponse"
}
}
LinksChangeAccessMode500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
LinksChangeAccessModeResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/InvalidAccessMode"
},
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
}
]
}
}
LinksDeleteLinkAccounts404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
LinksDeleteLinkAccountsResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
LinksGetDetails404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
LinksGetDetailsResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
LinksListAllResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
LinksPutRequest
{
"type": "object",
"required": [
"institution",
"username",
"password"
],
"properties": {
"token": {
"type": "string",
"example": "1234ab",
"description": "The MFA token required by the bank to log in.\n"
},
"password": {
"type": "string",
"example": "password",
"description": "The end-user's password used to log in to the institution."
},
"password2": {
"type": "string",
"example": "pin",
"description": "The end-user's second password used to log in to the institution.\n\nℹ️ This is only required by some institutions. To know which institutions require a second password, get the [details](https://developers.belvo.com/reference/detailinstitution) for the institution and check the `form_fields` array in the response.\n"
},
"certificate": {
"type": "string",
"example": "1234567890abcd=",
"description": "For certain fiscal institutions, it is possible to log in using a certificate and a private key, which enables a faster connection to the institution.\n\nBelvo supports a base64 encoded `certificate`. If the `certificate` parameter is used, you *must* also provide the `private_key` parameter.\n"
},
"private_key": {
"type": "string",
"example": "1234567890abcd=",
"description": "For certain fiscal institutions, it is possible to log in using a certificate and a private key, which enables a faster connection to the institution.\n\nBelvo supports a base64 encoded `private_key`. If the `private_key` parameter is used, you *must* also provide the `certificate` parameter.\n"
},
"username_type": {
"type": "string",
"example": "001",
"description": "Type of document to be used as a username.\n\n Some banking institutions accept different documents to be used as the `username` to login. For example, the *Cédula de Ciudadanía*, *Cédula de Extranjería*, *Pasaporte'*, and so on.\n\n For banks that require a document to log in, you **must** provide the `username_type` parameter to specify which document is used when creating the link.\n\n ℹ️ To know which institutions require the `username_type` parameter, get the [details](https://developers.belvo.com/reference/detailinstitution) for the institution and check the `form_fields` array in the response.\n\n For a list of standards codes, see the table below.\n\n| Code | Description |\n|-----------|-------|\n| `001` | Cédula de Ciudadanía |\n| `002` | Cédula de Extranjería |\n| `003` | Pasaporte |\n| `004` | Tarjeta de Identidad |\n| `005` | Registro Civil |\n| `006` | Número Identificación Personal |\n| `020` | NIT |\n| `021` | NIT Persona Natural |\n| `022` | NIT Persona Extranjera |\n| `023` | NIT Persona Jurídica |\n| `024` | NIT Menores |\n| `025` | NIT Desasociado |\n| `030` | Trj. Seguro Social Extranjero |\n| `031` | Sociedad Extranjera sin NIT en Colombia |\n| `032` | Fideicomiso |\n| `033` | RIF Venezuela |\n| `034` | CIF |\n| `035` | Número de Identidad |\n| `036` | RTN |\n| `037` | Cédula de Identidad |\n| `038` | DIMEX |\n| `039` | CED |\n| `040` | PAS |\n| `041` | Documento Único de Identidad |\n| `042` | NIT Salvadoreño |\n| `100` | Agência e conta |\n| `101` | Código do operador |\n| `102` | Cartão de crédito |\n| `103` | CPF |\n"
}
}
}
LinksRegisterNewLink401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
LinksRegisterNewLink428Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenRequiredResponse"
}
}
LinksRegisterNewLink500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
LinksRegisterNewLinkResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/400InvalidCredentialsStorageError"
},
{
"$ref": "#/components/schemas/400InvalidFetchHistorical"
},
{
"$ref": "#/components/schemas/400InvalidResourcesError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
}
]
}
}
LinksRequest
{
"type": "object",
"required": [
"institution",
"username"
],
"properties": {
"token": {
"type": "string",
"example": "1234ab",
"description": "The MFA token required by the bank to log in.\n\nWe do not recommend sending the authentication token in the same request as registering the user. See our [Handling multi-factor authentication](https://developers.belvo.com/docs/handling-2-factor-authentication) article for more information and best practices.\n"
},
"password": {
"type": "string",
"example": "password",
"description": "The end-user's password used to log in to the institution.\n\nℹ️ **Note**: You must send through a password for all institutions except for IMSS (`imss_mx_employment`).\n"
},
"stale_in": {
"type": "string",
"example": "42d",
"description": "Indicates how long any data should be stored in Belvo's database for the link (both single and recurrent). For example, if you send through `90d`, Belvo will remove any data from its database relating to the user after 90 days.\n\n> **Note**: Belvo will only remove data for links that have not been updated in the period you provide in `stale_in`.\n> \n> For example, if you set `stale_in` to `42d` and only request information once on that day, then Belvo will remove any data associated with the link after 42 days. However, if you make another request five days later, then Belvo will restart the day counter to that day.\n\nBy default Belvo stores user data for 365 days, unless the link is deleted.\n"
},
"username": {
"type": "string",
"example": "username",
"description": "The end-user's username (or ID) used to log in to the institution."
},
"password2": {
"type": "string",
"example": "pin",
"description": "The end-user's second password used to log in to the institution.\n\nℹ️ This is only required by some institutions. To know which institutions require a second password, get the [details](https://developers.belvo.com/reference/detailinstitution) for the institution and check the `form_fields` array in the response.\n"
},
"username2": {
"type": "string",
"example": "secondusername",
"description": "The end-user's second username (or email address) used to log in to the institution.\n\nℹ️ This is only required by some institutions. To know which institutions require a second username, get the [details](https://developers.belvo.com/reference/detailinstitution) for the institution and check the `form_fields` array in the response.\n"
},
"username3": {
"type": "string",
"example": "thirdusername",
"description": "The end-user's third username used to log in to the institution.\n\nℹ️ This is only required by some institutions. To know which institutions require a third username, get the [details](https://developers.belvo.com/reference/detailinstitution) for the institution and check the `form_fields` array in the response.\n"
},
"access_mode": {
"$ref": "#/components/schemas/EnumLinkAccessModeRequest"
},
"external_id": {
"type": "string",
"example": "56ab5706-6e00-48a4-91c9-ca55968678d9",
"minLength": 3,
"description": "An additional identifier for the link, provided by you, to store\nin the Belvo database. **Cannot** include any Personal Identifiable Information (PII). **Must** be at least three characters long.\n\n\nIf we identify that the identifier contains PII, we will force a `null` value. For more information, see our [Link\ncreation\narticle](https://developers.belvo.com/docs/link-creation-best-practices#adding-your-own-identifier).\n"
},
"institution": {
"type": "string",
"example": "erebor_mx_retail",
"pattern": "[a-z]+_[a-z]{2}_[a-z]+",
"description": "The Belvo name for the institution."
},
"username_type": {
"type": "string",
"example": "001",
"description": "Type of document to be used as a username.\n\nSome banking institutions accept different documents to be used as the `username` to login. For example, the *Cédula de Ciudadanía*, *Cédula de Extranjería*, *Pasaporte'*, and so on.\n\nFor banks that require a document to log in, you **must** provide the `username_type` parameter to specify which document is used when creating the link.\n\nℹ️ To know which institutions require the `username_type` parameter, get the [details](https://developers.belvo.com/reference/detailinstitution) for the institution and check the `form_fields` array in the response.\n\nFor a list of standards codes, see the table below.\n\n| Code | Description |\n|-----------|-------|\n| `001` | Cédula de Ciudadanía |\n| `002` | Cédula de Extranjería |\n| `003` | Pasaporte |\n| `004` | Tarjeta de Identidad |\n| `005` | Registro Civil |\n| `006` | Número Identificación Personal |\n| `020` | NIT |\n| `021` | NIT Persona Natural |\n| `022` | NIT Persona Extranjera |\n| `023` | NIT Persona Jurídica |\n| `024` | NIT Menores |\n| `025` | NIT Desasociado |\n| `030` | Trj. Seguro Social Extranjero |\n| `031` | Sociedad Extranjera sin NIT en Colombia |\n| `032` | Fideicomiso |\n| `033` | RIF Venezuela |\n| `034` | CIF |\n| `035` | Número de Identidad |\n| `036` | RTN |\n| `037` | Cédula de Identidad |\n| `038` | DIMEX |\n| `039` | CED |\n| `040` | PAS |\n| `041` | Documento Único de Identidad |\n| `042` | NIT Salvadoreño |\n| `100` | Agência e conta |\n| `101` | Código do operador |\n| `102` | Cartão de crédito |\n| `103` | CPF |\n"
},
"fetch_resources": {
"type": "array",
"items": {
"type": "string",
"example": "ACCOUNTS",
"description": "A Belvo resource that the institution supports."
},
"example": [
"ACCOUNTS",
"TRANSACTIONS"
],
"description": "An array of resources that you would like to receive a historical update for.\n\nFor banking institutions, you can select the following resources:\n - `ACCOUNTS`\n - `OWNERS`\n - `TRANSACTIONS`\n - `BILLS` (only for OFDA institutions)\n - `INCOMES`\n - `RECURRING_EXPENSES`\n - `RISK_INSIGHTS`\n - `CREDIT_SCORE`\n\n\nFor fiscal institutions, you can select the following resources:\n - `INVOICES`\n - `TAX_COMPLIANCE_STATUS`\n - `TAX_DECLARATIONS`\n - `TAX_RETENTIONS`\n - `TAX_RETURNS`\n - `TAX_STATUS`\n\nFor employment institutions, you can select the following resources:\n - `OWNERS`\n - `EMPLOYMENT_RECORDS`\n - `EMPLOYMENT_METRICS`\n \n"
},
"credentials_storage": {
"type": "string",
"example": "27d",
"description": "Indicates whether or not to store credentials (and the duration for which to store the credentials).\n\n- For recurrent links, this is set to `store` by default (and cannot be changed). \n- For single links, this is set to `365d` by default.\n\nChoose either:\n - `store` to store credentials (until the link is deleted)\n - `nostore` to not store credentials\n - Any value between `1d` and `365d` to indicate the number of days you want the credentials to be stored.\n"
}
}
}
LinksResumeSession401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
LinksResumeSession428Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenRequiredResponse"
}
}
LinksResumeSession500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
LinksResumeSessionResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
}
]
}
}
LinksUpdateCredentials401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
LinksUpdateCredentials404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
LinksUpdateCredentials428Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenRequiredResponse"
}
}
LinksUpdateCredentials500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
LinksUpdateCredentialsResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
}
]
}
}
LoginError
{
"type": "object",
"title": "Login Error",
"properties": {
"code": {
"type": "string",
"example": "login_error",
"description": "A unique error code (`login_error`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle <a href=\"https://developers.belvo.com/docs/belvo-api-errors#400-login_error\" target=\"_blank\">400 login_error errors</a>.\n"
},
"message": {
"type": "string",
"example": "Invalid credentials provided to login to the institution",
"description": "A short description of the error. \n\n\nFor `login_error` errors, the description can be one of the following:\n\n - `Invalid credentials provided to login to the institution`\n - `A MFA token is required by the institution, but it's not supported yet by Belvo.`\n - `Impossible to login, something unexpected happened while logging into the institution. Try again later.`\n - `Login not attempted due to invalid credentials`\n - `Missing credentials to login to the institution`\n - `The user account access was forbidden by the institution`\n - `The user account is locked, user needs to contact the institution to unlock it`\n \n"
},
"request_id": {
"type": "string",
"example": "9e7b283c6efa449c9c028a16b5c249fb",
"pattern": "[a-f0-9]{32}",
"description": "A 32-character unique ID of the request (matching a regex pattern of: `[a-f0-9]{32}`). Provide this ID when contacting the Belvo\nsupport team to accelerate investigations.\n"
}
},
"description": "This error can occur when:\n\n - the credentials that your user provides are incorrect or missing.\n - the MFA token your user provides is not supported by Belvo.\n - there is an issue with the institution that prevents logins.\n - the user's account is either locked or the user does not have permission to access their internet banking.\n"
}
NetIncomeIndividual
{
"type": "object",
"required": [
"earned_income",
"fee_based_income",
"capital_income",
"non_labor_income"
],
"properties": {
"earned_income": {
"type": "number",
"format": "float",
"example": 115004000,
"description": "Income received from employment."
},
"capital_income": {
"type": "number",
"format": "float",
"example": 0,
"description": "Income received from an investment (such as dividends or from renting a property)."
},
"fee_based_income": {
"type": "number",
"format": "float",
"example": 0,
"description": "Income received from emitted invoices (for example, income independent contractors or freelancers receive)."
},
"non_labor_income": {
"type": "number",
"format": "float",
"example": 0,
"description": "Income that cannot be classified into the other three fields (such as income from cryptocurrencies or regular transfers from parents)."
}
},
"description": "Object containing the declared net income of the tax payer. The values are calculated as the `gross_income` - `non_taxable_income`."
}
NonTaxableIncomeIndividual
{
"type": "object",
"required": [
"earned_income",
"fee_based_income",
"capital_income",
"non_labor_income"
],
"properties": {
"earned_income": {
"type": "number",
"format": "float",
"example": 115004000,
"description": "Income received from employment."
},
"capital_income": {
"type": "number",
"format": "float",
"example": 0,
"description": "Income received from an investment (such as dividends or from renting a property)."
},
"fee_based_income": {
"type": "number",
"format": "float",
"example": 0,
"description": "Income received from emitted invoices (for example, income independent contractors or freelancers receive)."
},
"non_labor_income": {
"type": "number",
"format": "float",
"example": 0,
"description": "Income that cannot be classified into the other three fields (such as income from cryptocurrencies or regular transfers from parents)."
}
},
"description": "Object containing the declared non-taxable income of the tax payer."
}
NotFoundError
{
"type": "object",
"title": "Not Found",
"properties": {
"code": {
"type": "string",
"example": "not_found",
"description": "A unique error code (`not_found`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle <a href=\"https://developers.belvo.com/docs/belvo-api-errors#404-not_found\" target=\"_blank\">404 not_found errors</a>.\n"
},
"message": {
"type": "string",
"example": "Not found",
"description": "A short description of the error. \n\n\nFor `not_found` errors, the description is:\n \n - `Not found`\n"
},
"request_id": {
"type": "string",
"example": "9e7b283c6efa449c9c028a16b5c249fb",
"pattern": "[a-f0-9]{32}",
"description": "A 32-character unique ID of the request (matching a regex pattern of: `[a-f0-9]{32}`). Provide this ID when contacting the Belvo\nsupport team to accelerate investigations.\n"
}
}
}
Owner
{
"type": "object",
"title": "Owner Standard (Multi-Region)",
"required": [
"id",
"link",
"internal_identification",
"display_name",
"email",
"phone_number",
"address",
"collected_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "c749315b-eec2-435d-a458-06912878564f",
"description": "Belvo's unique identifier used to reference the current owner."
},
"link": {
"type": "string",
"format": "uuid",
"example": "30cb4806-6e00-48a4-91c9-ca55968576c8",
"description": "Belvo's unique ID for the current Link."
},
"email": {
"type": "string",
"format": "email",
"example": "johndoe@belvo.com",
"nullable": true,
"maxLength": 256,
"description": "The account owner's registered email address."
},
"address": {
"type": "string",
"example": "Carrer de la Llacuna, 162, 08018 Barcelona",
"nullable": true,
"description": "The accounts owners registered address."
},
"last_name": {
"type": "string",
"example": null,
"nullable": true,
"deprecated": true,
"description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our [Deprecated fields](https://developers.belvo.com/reference/using-the-api-reference#%EF%B8%8F-deprecated-fields) explanation.*\n\n*The last name of the account owner.*\n"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-02-09T08:45:50.406032Z",
"description": "The ISO-8601 timestamp of when the data point was last updated in Belvo's database.\n"
},
"first_name": {
"type": "string",
"example": null,
"nullable": true,
"deprecated": true,
"description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our [Deprecated fields](https://developers.belvo.com/reference/using-the-api-reference#%EF%B8%8F-deprecated-fields) explanation.*\n\n*The first name of the account owner.*\n"
},
"document_id": {
"$ref": "#/components/schemas/OwnerDocumentId"
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2019-09-27T13:01:41.941Z",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"display_name": {
"type": "string",
"example": "John Doe",
"nullable": true,
"maxLength": 128,
"description": "The full name of the owner, as provided by the bank."
},
"phone_number": {
"type": "string",
"example": "+52-XXX-XXX-XXXX",
"nullable": true,
"description": "The account owner's registered phone number."
},
"business_name": {
"type": "string",
"example": null,
"nullable": true,
"deprecated": true,
"description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our [Deprecated fields](https://developers.belvo.com/reference/using-the-api-reference#%EF%B8%8F-deprecated-fields) explanation.*\n\n*The name of the business.*\n"
},
"second_last_name": {
"type": "string",
"example": null,
"nullable": true,
"deprecated": true,
"description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our [Deprecated fields](https://developers.belvo.com/reference/using-the-api-reference#%EF%B8%8F-deprecated-fields) explanation.*\n\n*The second last name of the account owner.*\n"
},
"internal_identification": {
"type": "string",
"example": "7e5838e4",
"nullable": true,
"description": "The institution's internal identifier for the owner."
}
}
}
OwnerAddresses
{
"type": "object",
"nullable": true,
"required": [
"is_main",
"address",
"additional_info",
"district_name",
"town",
"town_code",
"state",
"postcode",
"country_name",
"country_code",
"latitude",
"longitude"
],
"properties": {
"town": {
"type": "string",
"example": "Brasilia",
"pattern": "^[\\w\\W\\s]{0,50}$",
"maxLength": 50,
"description": "The user's town.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"state": {
"type": "string",
"example": "SP",
"pattern": "^[\\w\\W\\s]{0,2}$",
"nullable": true,
"maxLength": 2,
"description": "The state that the address is located in.\n"
},
"address": {
"type": "string",
"example": "Av Naburo Ykesaki, 1270",
"pattern": "^[\\w\\W\\s]{0,150}$",
"maxLength": 150,
"description": "The user's address.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"is_main": {
"type": "boolean",
"example": true,
"description": "Boolean to indicate if this is the user's main address.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"latitude": {
"type": "string",
"example": "-23.5475000",
"pattern": "^-?\\d{1,2}\\.\\d{1,9}$",
"nullable": true,
"maxLength": 13,
"description": "The geographic latitude coordinate.\n"
},
"postcode": {
"type": "string",
"example": "17500001",
"pattern": "^\\d{8}$",
"maxLength": 8,
"description": "The postcode of the address.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"longitude": {
"type": "string",
"example": "-46.6361100",
"pattern": "^-?\\d{1,3}\\.\\d{1,8}$",
"nullable": true,
"maxLength": 13,
"description": "The geographic longitude coordinate.\n"
},
"town_code": {
"type": "string",
"example": "3550308",
"pattern": "\\d{7}$",
"nullable": true,
"maxLength": 7,
"description": "The seven-digit code for the town, if applicable.\n\nFor Brazil, this is the IBGE town code.\n"
},
"country_code": {
"type": "string",
"example": "BRA",
"pattern": "^([A-Z]{3})$",
"nullable": true,
"maxLength": 3,
"description": "The three-letter country code (ISO-3166 Alpha 3 compliant).\n"
},
"country_name": {
"type": "string",
"example": "Brasil",
"pattern": "^[\\w\\W\\s]{0,80}$",
"maxLength": 80,
"description": "The name of the country.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"district_name": {
"type": "string",
"example": "CENTRO",
"pattern": "^[\\w\\W\\s]{0,50}$",
"nullable": true,
"maxLength": 50,
"description": "The distrct of the address.\n"
},
"additional_info": {
"type": "string",
"example": "In between two palm trees",
"pattern": "^[\\w\\W\\s]{0,150}$",
"nullable": true,
"maxLength": 150,
"description": "Additional information regarding the user's address.\n"
}
},
"description": "Detailed information regarding the owner's addresses."
}
OwnerBusinessDocumentIds
{
"type": "object",
"nullable": true,
"required": [
"type",
"type_additional_info",
"number",
"check_digit",
"issue_date",
"expiration_date",
"country_of_issuance",
"additional_info"
],
"properties": {
"type": {
"$ref": "#/components/schemas/EnumOwnerIndividualDocumentIdType"
},
"number": {
"type": "string",
"example": "DL-7896829-7",
"pattern": "^[\\w\\W]{0,40}$",
"maxLength": 40,
"description": "The ID document's number.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"issue_date": {
"type": "string",
"format": "date",
"example": null,
"pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$",
"nullable": true,
"maxLength": 10,
"description": "The date the the ID document was issued, in `YYYY-MM-DD` format.\n\n> **Note**: This field is not applicable for Business ID documents and will return `null`.\n"
},
"check_digit": {
"type": "string",
"example": null,
"pattern": "^[\\w\\W\\s]{0,2}$",
"maxLength": 2,
"description": "The check digit of the ID document.\n\n> **Note**: This field is not applicable for Business ID documents and will return `null`.\n"
},
"additional_info": {
"type": "string",
"example": null,
"pattern": "^[\\w\\W\\s]{0,100}$",
"nullable": true,
"maxLength": 100,
"description": "Additional information about the ID document.\n\n> **Note**: This field is not applicable for Business ID documents and will return `null`.\n"
},
"expiration_date": {
"type": "string",
"format": "date",
"example": "2019-01-01",
"pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$",
"nullable": true,
"maxLength": 10,
"description": "The date the the ID document expires, in `YYYY-MM-DD` format.\n"
},
"country_of_issuance": {
"type": "string",
"example": "CAN",
"pattern": "^(\\w{3}){1}$",
"nullable": true,
"maxLength": 3,
"description": "The three-letter country code that issued the document (in ISO-3166 Alpha 3 format).\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"type_additional_info": {
"type": "string",
"example": "EIN",
"pattern": "^[\\w\\W\\s]{0,70}$",
"nullable": true,
"maxLength": 70,
"description": "Additional information regarding the document type.\n\n> Note: For Business ID documents, this field must return a value from Brazil's open finance network.\n"
}
},
"description": "Detailed information regarding additional documents provided to prove the business's ID."
}
OwnerBusinessEconomicActivies
{
"type": "object",
"nullable": true,
"required": [
"is_main",
"code"
],
"properties": {
"code": {
"type": "string",
"example": "8599604",
"pattern": "^\\d{2,7}$",
"maxLength": 7,
"minLength": 2,
"description": "The code of the economic activity, as given by the country.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `economic_activities` field is available.\n"
},
"is_main": {
"type": "boolean",
"example": true,
"description": "Boolean to indicate whether this is the business's main economic activity.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `economic_activities` field is available.\n"
}
},
"description": "Details regarding the reported economic activities of the business."
}
OwnerBusinessFinancialProfile
{
"type": "object",
"nullable": true,
"required": [
"economic_activities",
"informed_revenue",
"patrimony"
],
"properties": {
"patrimony": {
"$ref": "#/components/schemas/OwnerBusinessPatrimony"
},
"informed_revenue": {
"$ref": "#/components/schemas/OwnerBusinessInformedRevenue"
},
"economic_activities": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OwnerBusinessEconomicActivies"
},
"description": "Details regarding the reported economic activities of the business."
}
},
"description": "Information regarding the financial profile of the individual."
}
OwnerBusinessFinancialRelation
{
"type": "object",
"nullable": true,
"required": [
"start_date",
"product_services",
"procurators",
"products"
],
"properties": {
"products": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OwnerBusinessProducts"
},
"description": "Details regarding any additional products that the business has with the institution."
},
"start_date": {
"type": "string",
"format": "date-time",
"example": "2021-05-21T08:30:00Z",
"pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])T(?:[01]\\d|2[0123]):(?:[012345]\\d):(?:[012345]\\d)Z$",
"maxLength": 20,
"description": "The ISO-8601 timestamp when the financial relationship between the business and the institution started.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"procurators": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OwnerProcurators"
},
"description": "Information regarding any individuals or companies that can act on behalf of the owner."
},
"product_services": {
"type": "array",
"items": {
"type": "string",
"example": "CONTA_DEPOSITO_A_VISTA",
"description": "The name of the product, according to the institution.\n"
},
"minItems": 1,
"description": "A list of products that the business has with the institution.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
}
},
"description": "Details regarding any additional relationship the business has with the institution (for example, other accounts or products they have with the institution)."
}
OwnerBusinessInformedRevenue
{
"type": "object",
"nullable": true,
"required": [
"frequency",
"frequency_additional_info",
"amount",
"currency",
"year"
],
"properties": {
"year": {
"type": "integer",
"example": 2022,
"maximum": 2090,
"minimum": 1700,
"maxLength": 4,
"description": "The year when revenue was last declared.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `informed_revenue` field is available.\n"
},
"amount": {
"type": "number",
"example": 45391.89,
"pattern": "^\\d{1,15}\\.\\d{2,4}$",
"description": "The reported revenue of the business.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `informed_revenue` field is available.\n"
},
"currency": {
"type": "string",
"example": "BRL",
"pattern": "^[A-Z]{3}$",
"maxLength": 3,
"description": "The three-letter currency code (ISO-4217).\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `informed_revenue` field is available.\n"
},
"frequency": {
"$ref": "#/components/schemas/EnumOwnerBusinessInformedRevenueFrequency"
},
"frequency_additional_info": {
"type": "string",
"example": "Recently switched from weekly to monthly.",
"pattern": "[\\w\\W\\s]*",
"nullable": true,
"maxLength": 100,
"description": "Additional information regarding the frequency.\n"
}
},
"description": "Information regarding the business's reported revenue."
}
OwnerBusinessOpenFinanceBrazil
{
"type": "object",
"title": "Owner Business (OFDA Brazil)",
"required": [
"id",
"link",
"internal_identification",
"collected_at",
"created_at",
"company_name",
"trade_name",
"incorporation_date",
"companies_id",
"document_id",
"additional_documents",
"email",
"emails",
"address",
"addresses",
"phone_number",
"phone_numbers",
"parties",
"financial_profile",
"financial_relation"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "c749315b-eec2-435d-a458-06912878564f",
"description": "Belvo's unique identifier used to reference the current owner."
},
"link": {
"type": "string",
"format": "uuid",
"example": "30cb4806-6e00-48a4-91c9-ca55968576c8",
"description": "Belvo's unique ID for the current Link."
},
"email": {
"type": "string",
"format": "email",
"example": "johndoe@belvo.com",
"nullable": true,
"maxLength": 256,
"description": "The account owner's registered email address."
},
"emails": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OwnerEmails"
},
"minItems": 0,
"description": "Additional list of emails the owner provided."
},
"address": {
"type": "string",
"example": "Carrer de la Llacuna, 162, 08018 Barcelona",
"nullable": true,
"description": "The accounts owners registered address."
},
"parties": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OwnerParties"
},
"minItems": 1,
"description": "Detailed information regarding the parties allowed to act on the owner's behalf.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"addresses": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OwnerAddresses"
},
"minItems": 1,
"description": "Detailed information regarding the owner's addresses."
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-02-09T08:45:50.406032Z",
"description": "The ISO-8601 timestamp of when the data point was last updated in Belvo's database.\n"
},
"trade_name": {
"type": "string",
"example": "WayneCorp",
"pattern": "^[\\w\\W]{0,128}$",
"nullable": true,
"maxLength": 128,
"description": "The trade name of the business.\n"
},
"document_id": {
"$ref": "#/components/schemas/OwnerDocumentIdOpenFinanceBrazil"
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2019-09-27T13:01:41.941Z",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"companies_id": {
"type": "array",
"items": {
"type": "string",
"example": "01773247000103",
"pattern": "^\\d{14}$",
"maxLength": 14,
"description": "The institutions responsible for the creation and verification of the owner.\n"
},
"minItems": 1,
"description": "The institutions responsible for the creation and verification of the owner.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"company_name": {
"type": "string",
"example": "Wayne Enterprises",
"pattern": "^[\\w\\W]{0,128}$",
"maxLength": 128,
"description": "The full (official) name of the business, as provided by the institution.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"phone_number": {
"type": "string",
"example": "+52-XXX-XXX-XXXX",
"nullable": true,
"description": "The account owner's registered phone number."
},
"phone_numbers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OwnerPhoneNumbers"
},
"minItems": 0,
"description": "Detailed information regarding the owner's `phone_number`s."
},
"financial_profile": {
"$ref": "#/components/schemas/OwnerBusinessFinancialProfile"
},
"financial_relation": {
"$ref": "#/components/schemas/OwnerBusinessFinancialRelation"
},
"incorporation_date": {
"type": "string",
"format": "date",
"example": "1988-07-15",
"pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$",
"maxLength": 10,
"description": "The date that the business was incorporated, in `YYYY-MM-DD` format.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"additional_documents": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OwnerBusinessDocumentIds"
},
"minItems": 1,
"description": "Detailed information regarding additional documents provided to prove the business's ID.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"internal_identification": {
"type": "string",
"example": "7e5838e4",
"nullable": true,
"description": "The institution's internal identifier for the owner."
}
}
}
OwnerBusinessPatrimony
{
"type": "object",
"nullable": true,
"required": [
"amount",
"currency",
"date"
],
"properties": {
"date": {
"type": "string",
"format": "date",
"example": "2022-12-12",
"pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$",
"maxLength": 10,
"description": "The date that the reported assets applied, in `YYYY-MM-DD` format.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `patrimony` field is available.\n"
},
"amount": {
"type": "number",
"format": "float",
"example": 45391.89,
"pattern": "^\\d{1,15}\\.\\d{2,4}$",
"description": "The reported assets of the business.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `patrimony` field is available.\n"
},
"currency": {
"type": "string",
"example": "BRL",
"pattern": "^[A-Z]{3}$",
"maxLength": 3,
"description": "The three-letter currency code (ISO-4217).\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `patrimony` field is available.\n"
}
},
"description": "Information regarding the individual's reported assets."
}
OwnerBusinessProducts
{
"type": "object",
"nullable": true,
"required": [
"type",
"subtype",
"agency",
"clearing_code",
"number",
"check_digit"
],
"properties": {
"type": {
"$ref": "#/components/schemas/EnumOwnerBusinessProductType"
},
"agency": {
"type": "string",
"example": "6272",
"pattern": "^\\d{1,4}$",
"nullable": true,
"maxLength": 4,
"description": "The branch code where the product was opened.\n"
},
"number": {
"type": "string",
"example": "24550245",
"pattern": "^\\d{8,20}$",
"maxLength": 20,
"description": "The account number of the product.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `products` field is available.\n"
},
"subtype": {
"type": "string",
"example": "CONJUNTA_SIMPLES",
"description": "The subtype of the product that the business has at the institution.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `products` field is available.\n"
},
"check_digit": {
"type": "string",
"example": "7",
"pattern": "^[\\w\\W\\s]{0,2}$",
"maxLength": 2,
"description": "The check digit of the product's number.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `products` field is available.\n"
},
"clearing_code": {
"type": "string",
"example": "001",
"pattern": "^\\d{3}$",
"maxLength": 3,
"description": "The banking clearing code for the product.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `products` field is available.\n"
}
},
"description": "Details regarding any additional products that the individual has with the institution."
}
OwnerDocumentId
{
"type": "object",
"nullable": true,
"required": [
"document_type",
"document_number"
],
"properties": {
"document_type": {
"type": "string",
"example": "CPF",
"nullable": true,
"description": "The type of document the owner provided to the institution to open the account. Common document types are:\n\n🇧🇷 Brazil\n- `CPF` (*Cadastro de Pessoas Físicas*)\n- `CNPJ`(*Cadastro Nacional de Pessoas Jurídicas*)\n\n🇨🇴 Colombia\n- `CC`(*Cédula de Ciudadanía*)\n- `NIT` (*Número de Identificación Tributaria*)\n\n🇲🇽 Mexico\n- `CURP` (*Clave Única de Registro de Población*)\n- `NISS` (*Número de Seguridad Social*)\n- `RFC` (*Registro Federal de Contribuyentes*)\n"
},
"document_number": {
"type": "string",
"example": "235578435-S",
"nullable": true,
"description": "The document's identification number."
}
},
"description": "Information regarding the identification document the owner provided to the bank."
}
OwnerDocumentIdOpenFinanceBrazil
{
"type": "object",
"required": [
"document_type",
"document_number"
],
"properties": {
"document_type": {
"type": "string",
"example": "CPF",
"description": "The type of document the owner provided to the institution to open the account. Common document types are:\n\n🇧🇷 Brazil\n- `CPF` (*Cadastro de Pessoas Físicas*)\n- `CNPJ`(*Cadastro Nacional de Pessoas Jurídicas*)\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"document_number": {
"type": "string",
"example": "235578435-S",
"description": "The document's identification number.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
}
},
"description": "Information regarding the identification document the owner provided to the bank.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
}
OwnerEmails
{
"type": "object",
"nullable": true,
"required": [
"is_main",
"email"
],
"properties": {
"email": {
"type": "string",
"example": "homen_morcego@gmail.com",
"pattern": "^[\\w\\W\\s]{0,320}$",
"maxLength": 320,
"description": "The user's email address.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"is_main": {
"type": "boolean",
"example": true,
"description": "Boolean to indicate if this is the user's main email address.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
}
},
"description": "Additional list of emails the owner provided."
}
OwnerFiliations
{
"type": "object",
"required": [
"type",
"civil_name",
"social_name"
],
"properties": {
"type": {
"$ref": "#/components/schemas/EnumOwnerFiliationType"
},
"civil_name": {
"type": "string",
"example": "Bruce Wayne",
"pattern": "^[\\w\\W\\s]{0,70}$",
"maxLength": 70,
"description": "The person's full name.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"social_name": {
"type": "string",
"example": "The Dark Knight",
"pattern": "^[\\w\\W\\s]{0,70}$",
"nullable": true,
"maxLength": 70,
"description": "The person's social name.\n"
}
},
"description": "Information regarding any familial relationships of the individual."
}
OwnerIndividualDocumentIds
{
"type": "object",
"nullable": true,
"required": [
"type",
"type_additional_info",
"number",
"check_digit",
"issue_date",
"expiration_date",
"country_of_issuance",
"additional_info"
],
"properties": {
"type": {
"$ref": "#/components/schemas/EnumOwnerIndividualDocumentIdType"
},
"number": {
"type": "string",
"example": "DL-7896829-7",
"pattern": "^[\\w\\W\\s]{0,40}$",
"maxLength": 40,
"description": "The ID document's number.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"issue_date": {
"type": "string",
"format": "date",
"example": "2019-01-01",
"pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$",
"nullable": true,
"maxLength": 10,
"description": "The date the the ID document was issued, in `YYYY-MM-DD` format.\n"
},
"check_digit": {
"type": "string",
"example": "7",
"pattern": "^[\\w\\W\\s]{0,2}$",
"maxLength": 2,
"description": "The check digit of the ID document.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"additional_info": {
"type": "string",
"example": "The document has water damage",
"pattern": "^[\\w\\W\\s]{0,100}$",
"nullable": true,
"maxLength": 100,
"description": "Additional information about the ID document.\n"
},
"expiration_date": {
"type": "string",
"format": "date",
"example": "2019-01-01",
"pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$",
"nullable": true,
"maxLength": 10,
"description": "The date the the ID document expires, in `YYYY-MM-DD` format.\n"
},
"country_of_issuance": {
"type": "string",
"example": "CAN",
"pattern": "^[\\w]{3}$",
"nullable": true,
"maxLength": 3,
"description": "The three-letter country code that issued the document (in ISO-3166 Alpha 3 format).\n\nThis field must be returned when the `type` is `PASSPORT`.\n"
},
"type_additional_info": {
"type": "string",
"example": "Learner's licence",
"pattern": "^[\\w\\W\\s]{0,70}$",
"nullable": true,
"maxLength": 70,
"description": "Additional information regarding the document type.\n\n> Note: For Business ID documents, this field must return a value from Brazil's open finance network.\n"
}
},
"description": "Detailed information regarding additional documents provided to prove the individuals ID."
}
OwnerIndividualFinancialProfile
{
"type": "object",
"nullable": true,
"required": [
"company_id",
"occupation_code",
"occupation_description",
"informed_income",
"patrimony"
],
"properties": {
"patrimony": {
"$ref": "#/components/schemas/OwnerIndividualPatrimony"
},
"company_id": {
"type": "string",
"example": "50685362000135",
"pattern": "^\\d{14}$",
"nullable": true,
"maxLength": 14,
"description": "The identifier of the company where the individual is employed.\n"
},
"informed_income": {
"$ref": "#/components/schemas/OwnerIndividualInformedIncome"
},
"occuptation_code": {
"$ref": "#/components/schemas/EnumOwnerIndividualFinancialProfileOccupationCode"
},
"occupation_description": {
"type": "string",
"example": "01",
"pattern": "[\\w\\W\\s]*",
"nullable": true,
"maxLength": 100,
"description": "Information regarding the individual's occupation.\n"
}
},
"description": "Information regarding the financial profile of the individual."
}
OwnerIndividualFinancialRelation
{
"type": "object",
"nullable": true,
"required": [
"start_date",
"product_services",
"product_services_additional_info",
"procurators",
"products"
],
"properties": {
"products": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OwnerIndividualProducts"
},
"description": "Details regarding any additional products that the individual has with the institution."
},
"start_date": {
"type": "string",
"format": "date-time",
"example": "2021-05-21T08:30:00Z",
"pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])T(?:[01]\\d|2[0123]):(?:[012345]\\d):(?:[012345]\\d)Z$",
"maxLength": 20,
"description": "The ISO-8601 timestamp when the financial relationship between the individual and the institution started.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"procurators": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OwnerProcurators"
},
"description": "Information regarding any individuals or companies that can act on behalf of the owner."
},
"product_services": {
"type": "array",
"items": {
"type": "string",
"example": "CONTA_DEPOSITO_A_VISTA",
"description": "The name of the product, according to the institution.\n"
},
"minItems": 1,
"description": "A list of products that the individual has with the institution.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"product_services_additional_info": {
"type": "string",
"example": "Joint account with Robin",
"pattern": "^[\\w\\W]*$",
"nullable": true,
"maxLength": 100,
"description": "Additional information regarding the products that the individual has.\n"
}
},
"description": "Details regarding any additional relationship the individual has with the institution (for example, other accounts or products they have with the institution)."
}
OwnerIndividualInformedIncome
{
"type": "object",
"required": [
"frequency",
"amount",
"currency",
"date"
],
"properties": {
"date": {
"type": "string",
"format": "date",
"example": "2020-03-19",
"pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$",
"maxLength": 10,
"description": "Date when the individual last received their salary.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"amount": {
"type": "number",
"format": "float",
"example": 45391.89,
"pattern": "^\\d{1,15}\\.\\d{2,4}$",
"maxLength": 20,
"minLength": 1,
"description": "The reported income that the individual receives.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"currency": {
"type": "string",
"example": "BRL",
"pattern": "^[A-Z]{3}$",
"maxLength": 3,
"description": "The three-letter currency code (ISO-4217).\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"frequency": {
"$ref": "#/components/schemas/EnumOwnerInformedIncomeFrequency"
}
},
"description": "Information regarding the individual's reported income.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
}
OwnerIndividualNationalityDocumentId
{
"type": "object",
"nullable": true,
"required": [
"type",
"type_additional_info",
"number",
"issue_date",
"expiration_date",
"country_of_issuance",
"additional_info"
],
"properties": {
"type": {
"$ref": "#/components/schemas/EnumOwnerIndividualDocumentIdType"
},
"number": {
"type": "string",
"example": "DL-7896829-7",
"pattern": "^[\\w\\W\\s]{0,40}$",
"maxLength": 40,
"description": "The ID document's number.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"issue_date": {
"type": "string",
"format": "date",
"example": "2019-01-01",
"pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$",
"nullable": true,
"maxLength": 10,
"description": "The date the the ID document was issued, in `YYYY-MM-DD` format.\n"
},
"additional_info": {
"type": "string",
"example": "The document has water damage",
"pattern": "^[\\w\\W\\s]{0,100}$",
"nullable": true,
"maxLength": 100,
"description": "Additional information about the ID document.\n"
},
"expiration_date": {
"type": "string",
"format": "date",
"example": "2019-01-01",
"pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$",
"nullable": true,
"maxLength": 10,
"description": "The date the the ID document expires, in `YYYY-MM-DD` format.\n"
},
"country_of_issuance": {
"type": "string",
"example": "CAN",
"pattern": "^[\\w]{3}$",
"nullable": true,
"maxLength": 3,
"description": "The three-letter country code that issued the document (in ISO-3166 Alpha 3 format).\n\nThis field must be returned when the `type` is `PASSPORT`.\n"
}
},
"description": "Detailed information regarding additional documents provided to prove the individuals ID."
}
OwnerIndividualOpenFinanceBrazil
{
"type": "object",
"title": "Owner Individual (OFDA Brazil)",
"required": [
"id",
"link",
"internal_identification",
"collected_at",
"created_at",
"display_name",
"social_name",
"birth_date",
"marital_status",
"marital_status_additional_info",
"gender",
"companies_id",
"is_local_resident",
"document_id",
"additional_documents",
"nationalities",
"email",
"emails",
"address",
"addresses",
"phone_number",
"phone_numbers",
"filiations",
"financial_profile",
"financial_relation"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "c749315b-eec2-435d-a458-06912878564f",
"description": "Belvo's unique identifier used to reference the current owner."
},
"link": {
"type": "string",
"format": "uuid",
"example": "30cb4806-6e00-48a4-91c9-ca55968576c8",
"description": "Belvo's unique ID for the current Link."
},
"email": {
"type": "string",
"format": "email",
"example": "johndoe@belvo.com",
"nullable": true,
"maxLength": 320,
"description": "The account owner's registered email address.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"emails": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OwnerEmails"
},
"minItems": 0,
"description": "Additional list of emails the owner provided.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"gender": {
"$ref": "#/components/schemas/EnumOwnerGender"
},
"address": {
"type": "string",
"example": "Carrer de la Llacuna, 162, 08018 Barcelona",
"nullable": true,
"description": "The account owner's registered address.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"addresses": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OwnerAddresses"
},
"minItems": 1,
"description": "Detailed information regarding the owner's addresses.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"birth_date": {
"type": "string",
"format": "date",
"example": "1988-07-15",
"pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$",
"maxLength": 10,
"description": "The individual's date of birth, in `YYYY-MM-DD` format.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-02-09T08:45:50.406032Z",
"description": "The ISO-8601 timestamp of when the data point was last updated in Belvo's database.\n"
},
"filiations": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OwnerFiliations"
},
"minItems": 1,
"description": "Information regarding any familial relationships of the individual.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"document_id": {
"$ref": "#/components/schemas/OwnerDocumentIdOpenFinanceBrazil"
},
"social_name": {
"type": "string",
"example": "O Piadista",
"pattern": "^[\\w\\W]{0,128}$",
"nullable": true,
"maxLength": 128,
"description": "The social name of the individual, as generally accepted by the country.\n"
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2019-09-27T13:01:41.941Z",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"companies_id": {
"type": "array",
"items": {
"type": "string",
"example": "01773247000103",
"pattern": "^\\d{14}$",
"maxLength": 14,
"description": "The institutions responsible for the creation and verification of the owner.\n"
},
"minItems": 1,
"description": "The institutions responsible for the creation and verification of the owner.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"display_name": {
"type": "string",
"example": "Jack Oswald White",
"pattern": "^[\\w\\W]{0,128}$",
"maxLength": 128,
"description": "The full name of the individual, as provided by the institution.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"phone_number": {
"type": "string",
"example": "+52-XXX-XXX-XXXX",
"nullable": true,
"description": "The account owner's registered phone number.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"nationalities": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OwnerNationalities"
},
"minItems": 1,
"nullable": true,
"description": "Detailed information regarding the individual's nationalities.\n\nOnly required to be returned when `is_local_resident` is set to `false`.\n"
},
"phone_numbers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OwnerPhoneNumbers"
},
"minItems": 0,
"description": "Detailed information regarding the owner's phone numbers.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"marital_status": {
"$ref": "#/components/schemas/EnumOwnerMaritalStatus"
},
"financial_profile": {
"$ref": "#/components/schemas/OwnerIndividualFinancialProfile"
},
"is_local_resident": {
"type": "boolean",
"example": true,
"description": "Boolean to indicate if the individual is a local resident of the country.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"financial_relation": {
"$ref": "#/components/schemas/OwnerIndividualFinancialRelation"
},
"additional_documents": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OwnerIndividualDocumentIds"
},
"minItems": 1,
"description": "Detailed information regarding additional documents provided to prove the individuals ID.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"internal_identification": {
"type": "string",
"example": "7e5838e4",
"nullable": true,
"description": "The institution's internal identifier for the owner."
},
"marital_status_additional_info": {
"type": "string",
"example": "It's complicated",
"pattern": "^[\\w\\W]{0,50}$",
"nullable": true,
"maxLength": 50,
"description": "Additional information about the individual's marital status.\n"
}
}
}
OwnerIndividualPatrimony
{
"type": "object",
"nullable": true,
"required": [
"amount",
"currency",
"year"
],
"properties": {
"year": {
"type": "integer",
"format": "int32",
"example": 2020,
"maximum": 2090,
"minimum": 1700,
"description": "The year that the reported assets applied. \n\n> **Non-nullable:** A value must be returned by Brazil's open finance network when the `patrimony` object is available.\n"
},
"amount": {
"type": "number",
"format": "float",
"example": 45391.89,
"pattern": "^\\d{1,15}\\.\\d{2,4}$",
"description": "The reported assets of the individual.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network when the `patrimony` object is available.\n"
},
"currency": {
"type": "string",
"example": "BRL",
"pattern": "^[A-Z]{3}$",
"maxLength": 3,
"description": "The three-letter currency code (ISO-4217).\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network when the `patrimony` object is available.\n"
}
},
"description": "Information regarding the individual's reported assets (if available)."
}
OwnerIndividualProducts
{
"type": "object",
"nullable": true,
"required": [
"type",
"subtype",
"agency",
"clearing_code",
"number",
"check_digit"
],
"properties": {
"type": {
"$ref": "#/components/schemas/EnumOwnerIndividualProductType"
},
"agency": {
"type": "string",
"example": "6272",
"pattern": "^\\d{1,4}$",
"nullable": true,
"maxLength": 4,
"description": "The branch code where the product was opened.\n"
},
"number": {
"type": "string",
"example": "24550245",
"pattern": "^\\d{8,20}$",
"maxLength": 20,
"description": "The account number of the product.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `procurators` field is available.\n"
},
"subtype": {
"type": "string",
"example": "CONJUNTA_SIMPLES",
"nullable": true,
"description": "The subtype of the product that the individual has at the institution.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `products` field is available.\n"
},
"check_digit": {
"type": "string",
"example": "7",
"pattern": "[\\w\\W\\s]*",
"maxLength": 2,
"description": "The check digit of the product's number.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `products` field is available.\n"
},
"clearing_code": {
"type": "string",
"example": "001",
"pattern": "^\\d{3}$",
"maxLength": 3,
"description": "The banking clearing code for the product.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `products` field is available.\n"
}
},
"description": "Details regarding any additional products that the individual has with the institution."
}
OwnerNationalities
{
"type": "object",
"required": [
"info",
"documents"
],
"properties": {
"info": {
"type": "string",
"example": "CAN",
"pattern": "^\\S[\\s\\S]*$",
"nullable": true,
"maxLength": 40,
"description": "The nationality of the individual.\n"
},
"documents": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OwnerIndividualNationalityDocumentId"
}
}
},
"description": "Detailed information regarding the individual's nationalities."
}
OwnerParties
{
"type": "object",
"nullable": true,
"required": [
"person_type",
"type",
"display_name",
"social_name",
"trade_name",
"start_date",
"percentage_type",
"document_type",
"document_number",
"document_issue_date",
"document_expiration_date",
"document_country",
"document_additional_info"
],
"properties": {
"type": {
"$ref": "#/components/schemas/EnumOwnerPartyType"
},
"start_date": {
"type": "string",
"format": "date",
"example": "2021-07-15",
"pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$",
"nullable": true,
"maxLength": 10,
"description": "The date that the party was added to the account, in `YYYY-MM-DD` format.\n"
},
"trade_name": {
"type": "string",
"example": "WayneCorp",
"pattern": "^[\\w\\W]{0,128}$",
"nullable": true,
"maxLength": 128,
"description": "The trade name of the business. Only applicable if the `person_type` is `COMPANY`.\n"
},
"person_type": {
"$ref": "#/components/schemas/EnumOwnerPartyPersonType"
},
"social_name": {
"type": "string",
"example": "O Piadista",
"pattern": "^[\\w\\W]{0,128}$",
"nullable": true,
"maxLength": 128,
"description": "The social name of the individual, as generally accepted by the country. Only applicable if the `person_type` is `INDIVIDUAL`.\n"
},
"company_name": {
"type": "string",
"example": "Wayne Enterprises",
"pattern": "^[\\w\\W]{0,128}$",
"nullable": true,
"maxLength": 128,
"description": "The full (official) name of the business. Only applicable if the `person_type` is `COMPANY`.\n"
},
"display_name": {
"type": "string",
"example": "Jack Oswald White",
"pattern": "^[\\w\\W]{0,128}$",
"nullable": true,
"maxLength": 128,
"description": "The full name of the individual, as provided by the institution. Only applicable if the `person_type` is `INDIVIDUAL`.\n"
},
"document_type": {
"$ref": "#/components/schemas/EnumOwnerPartyDocumentType"
},
"document_number": {
"type": "string",
"example": "DL-7896829-7",
"pattern": "^[\\w\\W\\s]{0,40}$",
"maxLength": 40,
"description": "The ID document's number.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"percentage_type": {
"type": "number",
"format": "float",
"example": 0.51,
"pattern": "^[01]\\.\\d{6}$",
"nullable": true,
"maxLength": 8,
"minLength": 8,
"description": "The party's equity interest.\n"
},
"document_country": {
"type": "string",
"example": "CAN",
"pattern": "^(\\w{3}){1}$",
"nullable": true,
"maxLength": 3,
"description": "The three-letter country code that issued the document (in ISO-3166 Alpha 3 format).\n"
},
"document_issue_date": {
"type": "string",
"format": "date",
"example": "2019-01-01",
"pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$",
"nullable": true,
"maxLength": 10,
"description": "The date the the ID document was issued, in `YYYY-MM-DD` format.\n"
},
"document_additional_info": {
"type": "string",
"example": "Confirmed CPF with their driver's licence.",
"pattern": "^[\\w\\W\\s]{0,100}$",
"nullable": true,
"maxLength": 100,
"description": "Additional information regarding the document.\n"
},
"document_expiration_date": {
"type": "string",
"format": "date",
"example": "2019-01-01",
"pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$",
"nullable": true,
"maxLength": 10,
"description": "The date the the ID document expires, in `YYYY-MM-DD` format.\n"
}
},
"description": "Detailed information regarding the parties allowed to act on the owner's behalf."
}
OwnerPhoneNumbers
{
"type": "object",
"nullable": true,
"required": [
"is_main",
"type",
"additional_info",
"number",
"country_code",
"area_code",
"extension"
],
"properties": {
"type": {
"$ref": "#/components/schemas/EnumOwnerPhoneNumberType"
},
"number": {
"type": "string",
"example": "29875132",
"pattern": "^([0-9]{8,11})$",
"maxLength": 11,
"description": "The phone number (not including the country, area, or extension codes).\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"is_main": {
"type": "boolean",
"example": true,
"description": "Boolean to indicate if this is the user's main phone number.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"area_code": {
"type": "string",
"example": "21",
"pattern": "^\\d{1,2}$",
"nullable": true,
"maxLength": 2,
"description": "The area dialling code.\n"
},
"extension": {
"type": "string",
"example": "932",
"pattern": "^\\d{1,5}$",
"nullable": true,
"maxLength": 5,
"description": "The extension code.\n"
},
"country_code": {
"type": "string",
"example": "351",
"pattern": "^\\d{1,4}$",
"nullable": true,
"maxLength": 4,
"description": "The country dialling code. For example: `351` (no `+`).\n"
},
"additional_info": {
"type": "string",
"example": "This is their work mobile number.",
"pattern": "^[\\w\\W\\s]{0,100}$",
"nullable": true,
"maxLength": 100,
"description": "Additional information about the phone number.\n"
}
},
"description": "Detailed information regarding the owners's `phone_number`s."
}
OwnerProcurators
{
"type": "object",
"nullable": true,
"required": [
"type",
"civil_name",
"social_name",
"document_number"
],
"properties": {
"type": {
"$ref": "#/components/schemas/EnumOwnerProcuratorType"
},
"civil_name": {
"type": "string",
"example": "Alfred Thaddeus Pennyworth",
"pattern": "^[\\w\\W]*$",
"maxLength": 70,
"description": "The representatives's full name.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `procurators` field is available.\n"
},
"social_name": {
"type": "string",
"example": "Alfred Pennyworth",
"pattern": "^[\\w\\W]*$",
"nullable": true,
"maxLength": 70,
"description": "The person's social name.\n"
},
"document_number": {
"type": "string",
"example": "73677831148",
"pattern": "^\\d{11}$",
"maxLength": 11,
"description": "The document number of the representative.\n\n**Note**: For individuals, this is Brazil's CPF number. For businesses, this is Brazil's CNPJ number.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `procurators` field is available.\n"
}
},
"description": "Information regarding any individuals or companies that can act on behalf of the owner."
}
OwnersBusinessPaginatedResponseOpenFinanceBrazil
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/common_pagination_properties"
},
{
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OwnerBusinessOpenFinanceBrazil"
},
"description": "Array of owner business (OFDA Brazil) objects."
}
}
}
],
"title": "Owner Business (OFDA Brazil)"
}
OwnersDeleteOwner404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
OwnersDeleteOwnerResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
OwnersGetDetails401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
OwnersGetDetails404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
OwnersGetDetailsResponse
{
"oneOf": [
{
"$ref": "#/components/schemas/Owner"
},
{
"$ref": "#/components/schemas/OwnerIndividualOpenFinanceBrazil"
},
{
"$ref": "#/components/schemas/OwnerBusinessOpenFinanceBrazil"
}
]
}
OwnersGetLinkOwner201Response
{
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/Owner"
},
{
"$ref": "#/components/schemas/OwnerIndividualOpenFinanceBrazil"
},
{
"$ref": "#/components/schemas/OwnerBusinessOpenFinanceBrazil"
}
]
}
}
OwnersGetLinkOwner400Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
}
]
}
}
OwnersGetLinkOwner401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
OwnersGetLinkOwner408Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RequestTimeoutError"
},
"title": "Request Timeout",
"description": "Belvo has a limit regarding the time it takes to log in, retrieve account data, and log out. A timeout occurs when there is a very high amount of data and everything could not be obtained within the allotted time.\n \n"
}
OwnersGetLinkOwner428Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenRequiredResponse"
}
}
OwnersGetLinkOwner500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
OwnersGetLinkOwnerResponse
{
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/Owner"
},
{
"$ref": "#/components/schemas/OwnerIndividualOpenFinanceBrazil"
},
{
"$ref": "#/components/schemas/OwnerBusinessOpenFinanceBrazil"
}
]
}
}
OwnersIndividualPaginatedResponseOpenFinanceBrazil
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/common_pagination_properties"
},
{
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OwnerIndividualOpenFinanceBrazil"
},
"description": "Array of owner objects."
}
}
}
],
"title": "Owner Individual (OFDA Brazil)"
}
OwnersListAll401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
OwnersListAllResponse
{
"oneOf": [
{
"$ref": "#/components/schemas/OwnersPaginatedResponse"
},
{
"$ref": "#/components/schemas/OwnersIndividualPaginatedResponseOpenFinanceBrazil"
},
{
"$ref": "#/components/schemas/OwnersBusinessPaginatedResponseOpenFinanceBrazil"
}
]
}
OwnersPaginatedResponse
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/common_pagination_properties"
},
{
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Owner"
},
"description": "Array of owner objects."
}
}
}
],
"title": "Owner Standard (Multi-Region)"
}
OwnersResumeRetrieveSession201Response
{
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/Owner"
},
{
"$ref": "#/components/schemas/OwnerIndividualOpenFinanceBrazil"
},
{
"$ref": "#/components/schemas/OwnerBusinessOpenFinanceBrazil"
}
]
}
}
OwnersResumeRetrieveSession400Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
}
]
}
}
OwnersResumeRetrieveSession401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
OwnersResumeRetrieveSession408Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RequestTimeoutError"
},
"title": "Request Timeout",
"description": "Belvo has a limit regarding the time it takes to log in, retrieve account data, and log out. A timeout occurs when there is a very high amount of data and everything could not be obtained within the allotted time.\n \n"
}
OwnersResumeRetrieveSession428Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenRequiredResponse"
}
}
OwnersResumeRetrieveSession500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
OwnersResumeRetrieveSessionResponse
{
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/Owner"
},
{
"$ref": "#/components/schemas/OwnerIndividualOpenFinanceBrazil"
},
{
"$ref": "#/components/schemas/OwnerBusinessOpenFinanceBrazil"
}
]
}
}
PaginatedResponseLink
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/common_pagination_properties"
},
{
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Link"
}
}
}
}
]
}
PatchBody
{
"type": "object",
"required": [
"session",
"link"
],
"properties": {
"link": {
"type": "string",
"format": "uuid",
"example": "683005d6-f45c-4adb-b289-f1a12f50f80c",
"description": "The `link.id` you want to resume. Must be the same `link.id` as the\none you receive in the 428 Token Required response that contains the\n`session` ID.\n"
},
"token": {
"type": "string",
"example": "1234ab",
"description": "The MFA token generated by the institution and required to continue\na session.\n"
},
"session": {
"type": "string",
"example": "6e7b283c6efa449c9c028a16b5c249fa",
"pattern": "[a-f0-9]{32}",
"description": "The session you want to resume. You need to use the `session` value\nthat is provided in the 428 Token Required response that you receive\nafter you make your POST request.\n"
},
"save_data": {
"type": "boolean",
"default": true,
"example": true,
"description": "Indicates whether or not to persist the data in Belvo. By default, this is set to `true` and we return a 201 Created response.\n\nWhen set to `false`, the data won't be persisted and we return a 200 OK response.\n"
}
},
"description": "A JSON object containing a session UUID and a MFA token"
}
PatchBodyWithoutSaveData
{
"type": "object",
"required": [
"session",
"link"
],
"properties": {
"link": {
"type": "string",
"format": "uuid",
"example": "683005d6-f45c-4adb-b289-f1a12f50f80c",
"description": "The `link.id` you want to resume. Must be the same `link.id` as the\none you receive in the 428 Token Required response that contains the\n`session` ID.\n"
},
"token": {
"type": "string",
"example": "1234ab",
"description": "The MFA token generated by the institution and required to continue\na session.\n"
},
"session": {
"type": "string",
"example": "6e7b283c6efa449c9c028a16b5c249fa",
"pattern": "[a-f0-9]{32}",
"description": "The session you want to resume. You need to use the `session` value\nthat is provided in the 428 Token Required response that you receive\nafter you make your POST request.\n"
}
},
"description": "A JSON object containing a session UUID and a MFA token"
}
PensionIncomeStatementIndividual
{
"type": "object",
"required": [
"net_pension_income",
"net_taxable_pension_income"
],
"properties": {
"net_pension_income": {
"type": "number",
"format": "float",
"example": 0,
"description": "The total net pension of the taxpayer."
},
"net_taxable_pension_income": {
"type": "number",
"format": "float",
"example": 0,
"description": "The total taxable pension income of the taxpayer."
}
},
"description": "Object containing the tax payer's total pension income."
}
RecurringExpenseSourceTransaction
{
"type": "object",
"nullable": true,
"required": [
"amount",
"description",
"value_date"
],
"properties": {
"amount": {
"type": "number",
"format": "float",
"example": 2145.45,
"description": "The transaction amount."
},
"value_date": {
"type": "string",
"format": "date",
"example": "2019-10-23",
"description": "The date when the transaction occurred, in `YYYY-MM-DD` format."
},
"description": {
"type": "string",
"example": "Netflix.com/march",
"nullable": true,
"description": "The description of the transaction provided by the institution. Usually, this is the text that the end user would see in the bank statement. The description can be an empty string.\n\n> **Note:** For EYOD Risk Insights, the description is the one that you provided in the initial request.\n"
}
},
"description": "An array of minified transaction objects used to evaluate the recurring expense. If no transactions were found, we return an empty array."
}
RecurringExpenses
{
"type": "object",
"required": [
"account",
"name",
"transactions",
"frequency",
"average_transaction_amount",
"median_transaction_amount",
"days_since_last_transaction",
"category",
"payment_type"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "076c66e5-90f5-4e01-99c7-50e32f65ae42",
"description": "Belvo's unique identifier used to reference the current recurring expense."
},
"name": {
"type": "string",
"default": null,
"example": "Netflix",
"nullable": true,
"description": "The name for the recurring expense.\n\nℹ️ **Note**: This information is taken from the description section of a transaction and then normalized to provide you with an easy-to-read name. As such, sometimes the name will reflect the merchant the payment is made to (for example, Netflix.com), while for other recurring expenses, this could be something like \"Monthly payment to John\".\n"
},
"account": {
"$ref": "#/components/schemas/Account"
},
"category": {
"$ref": "#/components/schemas/EnumRecurringExpenseCategory"
},
"frequency": {
"$ref": "#/components/schemas/EnumRecurringExpenseFrequency"
},
"payment_type": {
"$ref": "#/components/schemas/EnumRecurringExpensePaymentType"
},
"transactions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RecurringExpenseSourceTransaction"
},
"description": "An array of minified transaction objects used to evaluate the recurring expense. If no transactions were found, we return an empty array."
},
"median_transaction_amount": {
"type": "number",
"format": "float",
"example": 32.9,
"description": "The median transaction amount of the recurring expense."
},
"average_transaction_amount": {
"type": "number",
"format": "float",
"example": 32.9,
"description": "The average transaction amount of the recurring expense."
},
"days_since_last_transaction": {
"type": "integer",
"format": "int32",
"example": 5,
"description": "Number of days since the last recurring expense occurred.\n\nBased on the frequency, you can infer how many days until the next charge will occur.\n"
}
},
"description": "Recurring expense insights.\n\n\nℹ️ If no recurring expense insights are found, we return an empty array.\n"
}
RecurringExpensesDeleteExpense404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
RecurringExpensesDeleteExpenseResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
RecurringExpensesGetDetails401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
RecurringExpensesGetDetails404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
RecurringExpensesGetDetailsResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RecurringExpenses"
}
}
RecurringExpensesGetInsights201Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RecurringExpenses"
}
}
RecurringExpensesGetInsights400Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
},
{
"$ref": "#/components/schemas/InvalidPeriodError"
}
]
}
}
RecurringExpensesGetInsights401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
RecurringExpensesGetInsights408Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RequestTimeoutError"
},
"title": "Request Timeout",
"description": "Belvo has a limit regarding the time it takes to log in, retrieve account data, and log out. A timeout occurs when there is a very high amount of data and everything could not be obtained within the allotted time.\n \n"
}
RecurringExpensesGetInsights428Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenRequiredResponse"
}
}
RecurringExpensesGetInsights500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
RecurringExpensesGetInsightsResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RecurringExpenses"
}
}
RecurringExpensesListAllResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
RecurringExpensesPaginatedResponse
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/common_pagination_properties"
},
{
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RecurringExpenses"
},
"description": "Array of recurring expense objects."
}
}
}
]
}
RecurringExpensesRequest
{
"type": "object",
"required": [
"link"
],
"properties": {
"link": {
"type": "string",
"format": "uuid",
"example": "2ccd5e15-194a-4a19-a45a-e7223c7e6717",
"description": "The `link.id` that you want to get information for."
},
"token": {
"type": "string",
"example": "1234ab",
"description": "The OTP token generated by the bank."
},
"date_to": {
"type": "string",
"example": "2022-12-30",
"pattern": "[0-9]{4}-[0-9]{2}-[0-9]{2}",
"description": "The date you want to stop getting recurring expenses for, in `YYYY-MM-DD` format, within the last 365 days. When you use this parameter, you must also send `date_from`.\n\n\n\n\n⚠️ The value of `date_to` cannot be greater than today's date (in other words, no future dates).\n"
},
"date_from": {
"type": "string",
"example": "2022-08-01",
"pattern": "[0-9]{4}-[0-9]{2}-[0-9]{2}",
"description": "The date from which you want to start getting recurring expenses for, in `YYYY-MM-DD` format, within the last 365 days. When you use this parameter, you must also send `date_to`.\n\n\n\n\n⚠️ The value of `date_from` cannot be greater than `date_to`.\n"
},
"save_data": {
"type": "boolean",
"default": true,
"description": "Indicates whether or not to persist the data in Belvo. By default, this is set to `true` and we return a 201 Created response.\n\nWhen set to `false`, the data won't be persisted and we return a 200 OK response.\n"
}
}
}
RecurringExpensesResumeRequest201Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RecurringExpenses"
}
}
RecurringExpensesResumeRequest400Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
}
]
}
}
RecurringExpensesResumeRequest401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
RecurringExpensesResumeRequest408Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RequestTimeoutError"
},
"title": "Request Timeout",
"description": "Belvo has a limit regarding the time it takes to log in, retrieve account data, and log out. A timeout occurs when there is a very high amount of data and everything could not be obtained within the allotted time.\n \n"
}
RecurringExpensesResumeRequest428Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenRequiredResponse"
}
}
RecurringExpensesResumeRequest500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
RecurringExpensesResumeRequestResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RecurringExpenses"
}
}
ReportingId
{
"type": "object",
"required": [
"reporting_type",
"reporting_value"
],
"properties": {
"reporting_type": {
"type": "string",
"example": "sectional_address_code",
"description": "The type of reporting ID. For DIAN, this is the sectional address code (*Codigo Dirrecion Seccional*)"
},
"reporting_value": {
"type": "string",
"example": "32",
"description": "The value of the reporting ID."
}
},
"description": "Object containing information about where the tax payer reports their income."
}
RequestTimeoutError
{
"type": "object",
"title": "Request Timeout",
"properties": {
"code": {
"type": "string",
"example": "request_timeout",
"description": "A unique error code (`request_timeout`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle <a href=\"https://developers.belvo.com/docs/belvo-api-errors#408-request_timeout\" target=\"_blank\">408 request_timeout errors</a>.\n"
},
"message": {
"type": "string",
"example": "The request timed out, you can retry asking for less data by changing your query parameters",
"description": "A short description of the error. \n\n\nFor `request_timeout` errors, the description is:\n \n - `The request timed out, you can retry asking for less data by changing your query parameters`.\n"
},
"request_id": {
"type": "string",
"example": "9e7b283c6efa449c9c028a16b5c249fb",
"pattern": "[a-f0-9]{32}",
"description": "A 32-character unique ID of the request (matching a regex pattern of: `[a-f0-9]{32}`). Provide this ID when contacting the Belvo\nsupport team to accelerate investigations.\n"
}
},
"description": "Belvo has a limit regarding the time it takes to log in, retrieve account data, and log out. A timeout occurs when there is a very high amount of data and everything could not be obtained within the allotted time.\n"
}
RetentionBreakdown
{
"type": "object",
"required": [
"base_amount",
"tax_type",
"retained_amount",
"payment_status"
],
"properties": {
"tax_type": {
"type": "string",
"example": "01",
"nullable": true,
"description": "Optional attribute to indicate the type of tax withheld for the period or year according to the [SAT catalog](https://developers.belvo.com/docs/sat-catalogs#retention-code).\n"
},
"base_amount": {
"type": "number",
"format": "float",
"example": 0.03,
"nullable": true,
"description": "The base amount that was used to calculate the tax retention.\n"
},
"payment_status": {
"$ref": "#/components/schemas/EnumTaxRetentionPaymentStatus"
},
"retained_amount": {
"type": "number",
"format": "float",
"example": 0,
"nullable": true,
"description": "The amount retained.\n"
}
},
"description": "A breakdown of the retained taxes"
}
RiskInsights
{
"type": "object",
"required": [
"id",
"link",
"created_at",
"accounts",
"assets_metrics",
"transactions_metrics",
"balances_metrics",
"cashflow_metrics",
"credit_cards_metrics",
"loans_metrics",
"category_metrics"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "076c66e5-90f5-4e01-99c7-50e32f65ae42",
"description": "Belvo's unique ID for the risk insights request."
},
"link": {
"type": "string",
"format": "uuid",
"example": "30cb4806-6e00-48a4-91c9-ca55968576c8",
"description": "The `link.id` the risk insights analysis belongs to."
},
"accounts": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"example": "0d3ffb69-f83b-456e-ad8e-208d0998d71d",
"description": "The Belvo-generated ID for the account."
},
"example": [
"0d3ffb69-f83b-456e-ad8e-208d0998d71d",
"00293c8e-1152-440b-9892-3c071fb88672",
"cf638fba-ef45-4c10-bc6f-adecc4b2bf4e",
"3861a5da-ae9b-4f20-a632-a9294489d5ac",
"1f60315b-236d-498e-be7a-92bc613d329b",
"a2c8da63-ed51-41e6-891a-4ae7e784463a"
],
"nullable": true,
"description": "An array of Belvo-generated account numbers (UUIDs) that were used during the risk insights analysis. If no accounts were found, we return an empty array."
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-02-01T20:25:47.307911Z",
"description": "The ISO-8601 timestamp of when the data point was last updated in Belvo's database.\n"
},
"loans_metrics": {
"$ref": "#/components/schemas/RiskInsightsLoansMetrics"
},
"assets_metrics": {
"$ref": "#/components/schemas/RiskInsightsAssetMetrics"
},
"balances_metrics": {
"$ref": "#/components/schemas/RiskInsightsBalanceMetrics"
},
"cashflow_metrics": {
"$ref": "#/components/schemas/RiskInsightsCashflowMetrics"
},
"category_metrics": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RiskInsightsCategoryMetrics"
},
"description": "An array of aggregate metrics regarding the transaction categories and subcategories that Belvo has identified within the user's transaction history.\n\nIn the array, Belvo only returns categories that have been identified.\n"
},
"credit_cards_metrics": {
"$ref": "#/components/schemas/RiskInsightsCreditCardMetrics"
},
"transactions_metrics": {
"$ref": "#/components/schemas/RiskInsightsTransactionMetrics"
}
}
}
RiskInsightsAssetMetrics
{
"type": "object",
"nullable": true,
"required": [
"institutions",
"num_accounts",
"num_checking_accounts",
"num_savings_accounts",
"checking_accounts_balance",
"savings_accounts_balance"
],
"properties": {
"institutions": {
"type": "array",
"items": {
"type": "string",
"example": "erebor_mx_retail",
"description": "The name of the institution"
},
"example": [
"erebor_mx_retail"
],
"nullable": true,
"description": "An array of institutions from which account information was retrieved for the user. \n\n> **Note**: For most use cases, this array will only return one item.\n"
},
"num_assets_accounts": {
"type": "integer",
"format": "int32",
"example": 1,
"nullable": true,
"description": "The total number of accounts found for the user.\n"
},
"num_savings_accounts": {
"type": "integer",
"format": "int32",
"example": 1,
"nullable": true,
"description": "The total number of savings accounts found for the user.\n"
},
"num_checking_accounts": {
"type": "integer",
"format": "int32",
"example": 1,
"nullable": true,
"description": "The total number of checking accounts found for the user.\n"
},
"savings_accounts_balance": {
"type": "number",
"format": "float",
"example": 300.02,
"nullable": true,
"description": "The total closing balance of all savings accounts.\n"
},
"checking_accounts_balance": {
"type": "number",
"format": "float",
"example": 35901.46,
"nullable": true,
"description": "The total closing balance of all checking accounts.\n"
}
},
"description": "Aggregate details regarding the assets used in the risk insight analysis. For asset metrics, we only consider checking and savings accounts.\n\n\n> Asset metrics can provide a snapshot of your user's wealth and liquid assets, indicating how they manage their wealth and their current financial status.\n"
}
RiskInsightsBalanceMetrics
{
"type": "object",
"nullable": true,
"required": [
"closing_balance",
"min_balance_3d",
"min_balance_1w",
"min_balance_1m",
"min_balance_3m",
"min_balance_6m",
"min_balance_12m",
"mean_balance_3d",
"mean_balance_1w",
"mean_balance_1m",
"mean_balance_3m",
"mean_balance_6m",
"mean_balance_12m",
"max_balance_3d",
"max_balance_1w",
"max_balance_1m",
"max_balance_3m",
"max_balance_6m",
"max_balance_12m",
"std_balance_3d",
"std_balance_1w",
"std_balance_1m",
"std_balance_3m",
"std_balance_6m",
"std_balance_12m",
"balance_trend_3d",
"balance_trend_1w",
"balance_trend_1m",
"balance_trend_3m",
"balance_trend_6m",
"balance_trend_12m",
"days_balance_below_0_3d",
"days_balance_below_0_1w",
"days_balance_below_0_1m",
"days_balance_below_0_3m",
"days_balance_below_0_6m",
"days_balance_below_0_12m",
"days_balance_below_mean_3d",
"days_balance_below_mean_1w",
"days_balance_below_mean_1m",
"days_balance_below_mean_3m",
"days_balance_below_mean_6m",
"days_balance_below_mean_12m",
"days_balance_below_x_3d",
"days_balance_below_x_1w",
"days_balance_below_x_1m",
"days_balance_below_x_3m",
"days_balance_below_x_6m",
"days_balance_below_x_12m",
"balance_threshold_x"
],
"properties": {
"max_balance_1m": {
"type": "number",
"format": "float",
"example": 35901.46,
"nullable": true,
"description": "The maximum balance in the last month.\n"
},
"max_balance_1w": {
"type": "number",
"format": "float",
"example": 35901.46,
"nullable": true,
"description": "The maximum balance in the last week.\n"
},
"max_balance_3d": {
"type": "number",
"format": "float",
"example": 35901.46,
"nullable": true,
"description": "The maximum balance in the last three days.\n"
},
"max_balance_3m": {
"type": "number",
"format": "float",
"example": 35901.46,
"nullable": true,
"description": "The maximum balance in the last three months.\n"
},
"max_balance_6m": {
"type": "number",
"format": "float",
"example": 35901.46,
"nullable": true,
"description": "The maximum balance in the last six months.\n"
},
"min_balance_1m": {
"type": "number",
"format": "float",
"example": 33990.59,
"nullable": true,
"description": "The minimum balance in the last month.\n"
},
"min_balance_1w": {
"type": "number",
"format": "float",
"example": 34150.5,
"nullable": true,
"description": "The minimum balance in the last week).\n"
},
"min_balance_3d": {
"type": "number",
"format": "float",
"example": 35417.68,
"nullable": true,
"description": "The minimum balance in the last three days.\n"
},
"min_balance_3m": {
"type": "number",
"format": "float",
"example": 33990.59,
"nullable": true,
"description": "The minimum balance in the last three months.\n"
},
"min_balance_6m": {
"type": "number",
"format": "float",
"example": 33990.59,
"nullable": true,
"description": "The minimum balance in the six last months.\n"
},
"std_balance_1m": {
"type": "number",
"format": "float",
"example": 586.55,
"nullable": true,
"description": "The balance standard deviation in the last month.\n"
},
"std_balance_1w": {
"type": "number",
"format": "float",
"example": 764.03,
"nullable": true,
"description": "The balance standard deviation in the last week.\n"
},
"std_balance_3d": {
"type": "number",
"format": "float",
"example": 279.31,
"nullable": true,
"description": "The balance standard deviation in the last three days.\n"
},
"std_balance_3m": {
"type": "number",
"format": "float",
"example": 586.55,
"nullable": true,
"description": "The balance standard deviation in the last three months.\n"
},
"std_balance_6m": {
"type": "number",
"format": "float",
"example": 586.55,
"nullable": true,
"description": "The balance standard deviation in the last six months.\n"
},
"closing_balance": {
"type": "number",
"format": "float",
"example": 35901.46,
"nullable": true,
"description": "The balance of all the accounts at the `collected_at` time.\n"
},
"max_balance_12m": {
"type": "number",
"format": "float",
"example": 35901.46,
"nullable": true,
"description": "The maximum balance in the last twelve months.\n"
},
"mean_balance_1m": {
"type": "number",
"format": "float",
"example": 34816.08,
"nullable": true,
"description": "The mean balance in the last month.\n"
},
"mean_balance_1w": {
"type": "number",
"format": "float",
"example": 35077.1,
"nullable": true,
"description": "The mean balance in the last week.\n"
},
"mean_balance_3d": {
"type": "number",
"format": "float",
"example": 35659.57,
"nullable": true,
"description": "The mean balance in the last three days.\n"
},
"mean_balance_3m": {
"type": "number",
"format": "float",
"example": 34816.08,
"nullable": true,
"description": "The mean balance in the last three months.\n"
},
"mean_balance_6m": {
"type": "number",
"format": "float",
"example": 34816.08,
"nullable": true,
"description": "The mean balance in the last six months.\n"
},
"min_balance_12m": {
"type": "number",
"format": "float",
"example": 33990.59,
"nullable": true,
"description": "The minimum balance in the last twelve months.\n"
},
"std_balance_12m": {
"type": "number",
"format": "float",
"example": 586.55,
"nullable": true,
"description": "The balance standard deviation in the last twelve months.\n"
},
"balance_trend_1m": {
"type": "number",
"format": "float",
"example": 22.6,
"nullable": true,
"description": "The balance trend of the user in the last month.\n"
},
"balance_trend_1w": {
"type": "number",
"format": "float",
"example": 290.18,
"nullable": true,
"description": "The balance trend of the user in the last week.\n"
},
"balance_trend_3d": {
"type": "number",
"format": "float",
"example": 193.51,
"nullable": true,
"description": "The balance trend of the user in the last three days.\n"
},
"balance_trend_3m": {
"type": "number",
"format": "float",
"example": 22.6,
"nullable": true,
"description": "The balance trend of the user in the last three months.\n"
},
"balance_trend_6m": {
"type": "number",
"format": "float",
"example": 22.6,
"nullable": true,
"description": "The balance trend of the user in the last six months.\n"
},
"mean_balance_12m": {
"type": "number",
"format": "float",
"example": 34816.08,
"nullable": true,
"description": "The mean balance in the last twelve months.\n"
},
"balance_trend_12m": {
"type": "number",
"format": "float",
"example": 22.6,
"nullable": true,
"description": "The balance trend of the user in the last twelve months.\n"
},
"balance_threshold_x": {
"type": "number",
"format": "float",
"example": 1000,
"description": "The threshold used to compute `days_balance_below_x_period`. Please note, this is value is country specific (both in terms of the amount and the currency).\n"
},
"days_balance_below_0_1m": {
"type": "integer",
"format": "int32",
"example": 0,
"nullable": true,
"description": "The number of days that the total balance of the account is less than or equal to 0 in the last month.\n"
},
"days_balance_below_0_1w": {
"type": "integer",
"format": "int32",
"example": 0,
"nullable": true,
"description": "The number of days that the total balance of the account is less than or equal to 0 in the last week.\n"
},
"days_balance_below_0_3d": {
"type": "integer",
"format": "int32",
"example": 0,
"nullable": true,
"description": "The number of days that the total balance of the account is less than or equal to 0 in the last three days.\n"
},
"days_balance_below_0_3m": {
"type": "integer",
"format": "int32",
"example": 0,
"nullable": true,
"description": "The number of days that the total balance of the account is less than or equal to 0 in the last three months.\n"
},
"days_balance_below_0_6m": {
"type": "integer",
"format": "int32",
"example": 0,
"nullable": true,
"description": "The number of days that the total balance of the account is less than or equal to 0 in the last six months.\n"
},
"days_balance_below_x_1m": {
"type": "integer",
"format": "int32",
"example": 0,
"nullable": true,
"description": "The number of days that the total balance of the account is less than or equal to the amount specified in `balance_threshold_x` in the last month.\n"
},
"days_balance_below_x_1w": {
"type": "integer",
"format": "int32",
"example": 0,
"nullable": true,
"description": "The number of days that the total balance of the account is less than or equal to the amount specified in `balance_threshold_x` in the last week.\n"
},
"days_balance_below_x_3d": {
"type": "integer",
"format": "int32",
"example": 0,
"nullable": true,
"description": "The number of days that the total balance of the account is less than or equal to the amount specified in `balance_threshold_x` in the last three days.\n"
},
"days_balance_below_x_3m": {
"type": "integer",
"format": "int32",
"example": 0,
"nullable": true,
"description": "The number of days that the total balance of the account is less than or equal to the amount specified in `balance_threshold_x` in the last three months.\n"
},
"days_balance_below_x_6m": {
"type": "integer",
"format": "int32",
"example": 0,
"nullable": true,
"description": "The number of days that the total balance of the account is less than or equal to the amount specified in `balance_threshold_x` in the last six months.\n"
},
"days_balance_below_0_12m": {
"type": "integer",
"format": "int32",
"example": 0,
"nullable": true,
"description": "The number of days that the total balance of the account is less than or equal to 0 in the last twelve months.\n"
},
"days_balance_below_x_12m": {
"type": "integer",
"format": "int32",
"example": 0,
"nullable": true,
"description": "The number of days that the total balance of the account is less than or equal to the amount specified in `balance_threshold_x` in the last twelve months.\n"
},
"days_balance_below_mean_1m": {
"type": "integer",
"format": "int32",
"example": 17,
"nullable": true,
"description": "The number of days that the mean balance of the account is less than or equal to the amount specified in `mean_daily_balance_1m`.\n"
},
"days_balance_below_mean_1w": {
"type": "integer",
"format": "int32",
"example": 3,
"nullable": true,
"description": "The number of days that the mean balance of the account is less than or equal to the amount specified in `mean_daily_balance_1w`.\n"
},
"days_balance_below_mean_3d": {
"type": "integer",
"format": "int32",
"example": 2,
"nullable": true,
"description": "The number of days that the mean balance of the account is less than or equal to the amount specified in `mean_daily_balance_3d`.\n"
},
"days_balance_below_mean_3m": {
"type": "integer",
"format": "int32",
"example": 17,
"nullable": true,
"description": "The number of days that the mean balance of the account is less than or equal to the amount specified in `mean_daily_balance_3m`.\n"
},
"days_balance_below_mean_6m": {
"type": "integer",
"format": "int32",
"example": 17,
"nullable": true,
"description": "The number of days that the mean balance of the account is less than or equal to the amount specified in `mean_daily_balance_6m`.\n"
},
"days_balance_below_mean_12m": {
"type": "integer",
"format": "int32",
"example": 17,
"nullable": true,
"description": "The number of days that the mean balance of the account is less than or equal to the amount specified in `mean_daily_balance_12m`.\n"
}
},
"description": "Balance metrics calculated based on the user's balances from checking and savings accounts."
}
RiskInsightsCashflowMetrics
{
"type": "object",
"nullable": true,
"required": [
"max_positive_3d",
"max_positive_1w",
"max_positive_1m",
"max_positive_3m",
"max_positive_6m",
"max_positive_12m",
"max_negative_3d",
"max_negative_1w",
"max_negative_1m",
"max_negative_3m",
"max_negative_6m",
"max_negative_12m",
"mean_positive_3d",
"mean_positive_1w",
"mean_positive_1m",
"mean_positive_3m",
"mean_positive_6m",
"mean_positive_12m",
"mean_negative_3d",
"mean_negative_1w",
"mean_negative_1m",
"mean_negative_3m",
"mean_negative_6m",
"mean_negative_12m",
"sum_positive_3d",
"sum_positive_1w",
"sum_positive_1m",
"sum_positive_3m",
"sum_positive_6m",
"sum_positive_12m",
"sum_positive_trend_3d",
"sum_positive_trend_1w",
"sum_positive_trend_1m",
"sum_positive_trend_3m",
"sum_positive_trend_6m",
"sum_positive_trend_12m",
"sum_negative_3d",
"sum_negative_1w",
"sum_negative_1m",
"sum_negative_3m",
"sum_negative_6m",
"sum_negative_12m",
"sum_negative_trend_3d",
"sum_negative_trend_1w",
"sum_negative_trend_1m",
"sum_negative_trend_3m",
"sum_negative_trend_6m",
"sum_negative_trend_12m",
"positive_to_negative_ratio_3d",
"positive_to_negative_ratio_1w",
"positive_to_negative_ratio_1m",
"positive_to_negative_ratio_3m",
"positive_to_negative_ratio_6m",
"positive_to_negative_ratio_12m",
"net_cashflow_3d",
"net_cashflow_1w",
"net_cashflow_1m",
"net_cashflow_3m",
"net_cashflow_6m",
"net_cashflow_12m",
"net_cashflow_trend_3d",
"net_cashflow_trend_1w",
"net_cashflow_trend_1m",
"net_cashflow_trend_3m",
"net_cashflow_trend_6m",
"net_cashflow_trend_12m"
],
"properties": {
"max_negative_1m": {
"type": "number",
"format": "float",
"example": 5305.92,
"nullable": true,
"description": "The highest value of negative cash flow transactions in the last month.\n"
},
"max_negative_1w": {
"type": "number",
"format": "float",
"example": 3375.43,
"nullable": true,
"description": "The highest value of negative cash flow transactions in the last week.\n"
},
"max_negative_3d": {
"type": "number",
"format": "float",
"example": 3375.43,
"nullable": true,
"description": "The highest value of negative cash flow transactions in the last three days.\n"
},
"max_negative_3m": {
"type": "number",
"format": "float",
"example": 7535.85,
"nullable": true,
"description": "The highest value of negative cash flow transactions in the last three months.\n"
},
"max_negative_6m": {
"type": "number",
"format": "float",
"example": 7535.85,
"nullable": true,
"description": "The highest value of negative cash flow transactions in the last six months.\n"
},
"max_positive_1m": {
"type": "number",
"format": "float",
"example": 4012.61,
"nullable": true,
"description": "The highest value of positive cash flow transactions the last month.\n"
},
"max_positive_1w": {
"type": "number",
"format": "float",
"example": 3808.99,
"nullable": true,
"description": "The highest value of positive cash flow transactions the last week.\n"
},
"max_positive_3d": {
"type": "number",
"format": "float",
"example": 1850.12,
"nullable": true,
"description": "The highest value of positive cash flow transactions in the last three days.\n"
},
"max_positive_3m": {
"type": "number",
"format": "float",
"example": 5001.08,
"nullable": true,
"description": "The highest value of positive cash flow transactions the last three months.\n"
},
"max_positive_6m": {
"type": "number",
"format": "float",
"example": 8500,
"nullable": true,
"description": "The highest value of positive cash flow transactions the last six months.\n"
},
"net_cashflow_1m": {
"type": "number",
"format": "float",
"example": -2250.46,
"nullable": true,
"description": "The net cash flow in the last month.\n"
},
"net_cashflow_1w": {
"type": "number",
"format": "float",
"example": -1536.33,
"nullable": true,
"description": "The net cash flow in the last week.\n"
},
"net_cashflow_3d": {
"type": "number",
"format": "float",
"example": -1104.79,
"nullable": true,
"description": "The net cash flow in the last three days.\n"
},
"net_cashflow_3m": {
"type": "number",
"format": "float",
"example": 5588.51,
"nullable": true,
"description": "The net cash flow in the last three months.\n"
},
"net_cashflow_6m": {
"type": "number",
"format": "float",
"example": 22088.51,
"nullable": true,
"description": "The net cash flow in the last six months.\n"
},
"sum_negative_1m": {
"type": "number",
"format": "float",
"example": 55243.82,
"nullable": true,
"description": "The sum total of all transactions leading to a negative cash flow in the last month.\n"
},
"sum_negative_1w": {
"type": "number",
"format": "float",
"example": 14862.25,
"nullable": true,
"description": "The sum total of all transactions leading to a negative cash flow in the last week.\n"
},
"sum_negative_3d": {
"type": "number",
"format": "float",
"example": 6746.95,
"nullable": true,
"description": "The sum total of all transactions leading to a negative cash flow in the last three days.\n"
},
"sum_negative_3m": {
"type": "number",
"format": "float",
"example": 158108.77,
"nullable": true,
"description": "The sum total of all transactions leading to a negative cash flow in the last three months.\n"
},
"sum_negative_6m": {
"type": "number",
"format": "float",
"example": 167108.77,
"nullable": true,
"description": "The sum total of all transactions leading to a negative cash flow in the last six months.\n"
},
"sum_positive_1m": {
"type": "number",
"format": "float",
"example": 52993.36,
"nullable": true,
"description": "The sum total of all transactions leading to a positive cash flow in the last month.\n"
},
"sum_positive_1w": {
"type": "number",
"format": "float",
"example": 13325.92,
"nullable": true,
"description": "The sum total of all transactions leading to a positive cash flow in the last week.\n"
},
"sum_positive_3d": {
"type": "number",
"format": "float",
"example": 5642.16,
"nullable": true,
"description": "The sum total of all transactions leading to a positive cash flow in the last three days.\n"
},
"sum_positive_3m": {
"type": "number",
"format": "float",
"example": 163697.28,
"nullable": true,
"description": "The sum total of all transactions leading to a positive cash flow in the last three months.\n"
},
"sum_positive_6m": {
"type": "number",
"format": "float",
"example": 189197.28,
"nullable": true,
"description": "The sum total of all transactions leading to a positive cash flow in the last six months.\n"
},
"max_negative_12m": {
"type": "number",
"format": "float",
"example": 7535.85,
"nullable": true,
"description": "The highest value of negative cash flow transactions in the last twelve months.\n"
},
"max_positive_12m": {
"type": "number",
"format": "float",
"example": 8500,
"nullable": true,
"description": "The highest value of positive cash flow transactions the last twelve months.\n"
},
"mean_negative_1m": {
"type": "number",
"format": "float",
"example": 1904.96,
"nullable": true,
"description": "The mean value of the negative cash flow transactions in the last month.\n"
},
"mean_negative_1w": {
"type": "number",
"format": "float",
"example": 2477.04,
"nullable": true,
"description": "The mean value of the negative cash flow transactions in the last week.\n"
},
"mean_negative_3d": {
"type": "number",
"format": "float",
"example": 3373.48,
"nullable": true,
"description": "The mean value of the negative cash flow transactions in the last three days.\n"
},
"mean_negative_3m": {
"type": "number",
"format": "float",
"example": 1838.47,
"nullable": true,
"description": "The mean value of the negative cash flow transactions in the last three months.\n"
},
"mean_negative_6m": {
"type": "number",
"format": "float",
"example": 1877.63,
"nullable": true,
"description": "The mean value of the negative cash flow transactions in the last six months.\n"
},
"mean_positive_1m": {
"type": "number",
"format": "float",
"example": 1827.36,
"nullable": true,
"description": "The mean value of the positive cash flow transactions in the last month.\n"
},
"mean_positive_1w": {
"type": "number",
"format": "float",
"example": 1665.74,
"nullable": true,
"description": "The mean value of the positive cash flow transactions in the last week.\n"
},
"mean_positive_3d": {
"type": "number",
"format": "float",
"example": 1410.54,
"nullable": true,
"description": "The mean value of the positive cash flow transactions in the last three days.\n"
},
"mean_positive_3m": {
"type": "number",
"format": "float",
"example": 1881.58,
"nullable": true,
"description": "The mean value of the positive cash flow transactions in the last three months.\n"
},
"mean_positive_6m": {
"type": "number",
"format": "float",
"example": 2102.19,
"nullable": true,
"description": "The mean value of the positive cash flow transactions in the last six months.\n"
},
"net_cashflow_12m": {
"type": "number",
"format": "float",
"example": 55088.51,
"nullable": true,
"description": "The net cash flow in the last twelve months.\n"
},
"sum_negative_12m": {
"type": "number",
"format": "float",
"example": 185108.77,
"nullable": true,
"description": "The sum total of all transactions leading to a negative cash flow in the last twelve months.\n"
},
"sum_positive_12m": {
"type": "number",
"format": "float",
"example": 240197.28,
"nullable": true,
"description": "The sum total of all transactions leading to a positive cash flow in the last twelve months.\n"
},
"mean_negative_12m": {
"type": "number",
"format": "float",
"example": 1948.51,
"nullable": true,
"description": "The mean value of the negative cash flow transactions in the last twelve months.\n"
},
"mean_positive_12m": {
"type": "number",
"format": "float",
"example": 2502.06,
"nullable": true,
"description": "The mean value of the positive cash flow transactions in the last twelve months.\n"
},
"net_cashflow_trend_1m": {
"type": "number",
"format": "float",
"example": 1.3034,
"nullable": true,
"description": "The net cash flow trend in the last month.\n"
},
"net_cashflow_trend_1w": {
"type": "number",
"format": "float",
"example": 163.8856,
"nullable": true,
"description": "The net cash flow trend in the last week.\n"
},
"net_cashflow_trend_3d": {
"type": "number",
"format": "float",
"example": 1448.683,
"nullable": true,
"description": "The net cash flow trend in the last three days months.\n"
},
"net_cashflow_trend_3m": {
"type": "number",
"format": "float",
"example": -0.472,
"nullable": true,
"description": "The net cash flow trend in the last three months.\n"
},
"net_cashflow_trend_6m": {
"type": "number",
"format": "float",
"example": -15.1286,
"nullable": true,
"description": "The net cash flow trend in the last six months.\n"
},
"sum_negative_trend_1m": {
"type": "number",
"format": "float",
"example": 58.376,
"nullable": true,
"description": "The negative cash flow trend based on the sum of all negative transactions in the last month.\n"
},
"sum_negative_trend_1w": {
"type": "number",
"format": "float",
"example": 254.2517,
"nullable": true,
"description": "The negative cash flow trend based on the sum of all negative transactions in the last week.\n"
},
"sum_negative_trend_3d": {
"type": "number",
"format": "float",
"example": -3.91,
"nullable": true,
"description": "The negative cash flow trend based on the sum of all negative transactions in the last three days.\n"
},
"sum_negative_trend_3m": {
"type": "number",
"format": "float",
"example": 2.5895,
"nullable": true,
"description": "The negative cash flow trend based on the sum of all negative transactions in the last three months.\n"
},
"sum_negative_trend_6m": {
"type": "number",
"format": "float",
"example": -1.4824,
"nullable": true,
"description": "The negative cash flow trend based on the sum of all negative transactions in the last six months.\n"
},
"sum_positive_trend_1m": {
"type": "number",
"format": "float",
"example": 22.7315,
"nullable": true,
"description": "The positive cash flow trend based on the sum of all positive transactions in the last month.\n"
},
"sum_positive_trend_1w": {
"type": "number",
"format": "float",
"example": -84.0393,
"nullable": true,
"description": "The positive cash flow trend based on the sum of all positive transactions in the last week.\n"
},
"sum_positive_trend_3d": {
"type": "number",
"format": "float",
"example": 98.902,
"nullable": true,
"description": "The positive cash flow trend based on the sum of all positive transactions in the last three days.\n"
},
"sum_positive_trend_3m": {
"type": "number",
"format": "float",
"example": 1.8398,
"nullable": true,
"description": "The positive cash flow trend based on the sum of all positive transactions in the last three months.\n"
},
"sum_positive_trend_6m": {
"type": "number",
"format": "float",
"example": -17.1869,
"nullable": true,
"description": "The positive cash flow trend based on the sum of all positive transactions in the last six months.\n"
},
"net_cashflow_trend_12m": {
"type": "number",
"format": "float",
"example": -21.5511,
"nullable": true,
"description": "The net cash flow trend in the last twelve months.\n"
},
"sum_negative_trend_12m": {
"type": "number",
"format": "float",
"example": -4.2394,
"nullable": true,
"description": "The negative cash flow trend based on the sum of all negative transactions in the last twelve months.\n"
},
"sum_positive_trend_12m": {
"type": "number",
"format": "float",
"example": -25.9856,
"nullable": true,
"description": "The positive cash flow trend based on the sum of all positive transactions in the last twelve months.\n"
},
"positive_to_negative_ratio_1m": {
"type": "number",
"format": "float",
"example": 0.96,
"nullable": true,
"description": "The ratio between sum_positive / sum_negative in the last month.\n\nℹ️ If the ratio is greater than `1`, it means that the user has more income than outgoing, indicating that they spend less than they earn.\n\n**Note**: In the case that there have been no outgoing transactions, the value will be `null`.\n"
},
"positive_to_negative_ratio_1w": {
"type": "number",
"format": "float",
"example": 0.9,
"nullable": true,
"description": "The ratio between sum_positive / sum_negative in the last week.\n\nℹ️ If the ratio is greater than `1`, it means that the user has more income than outgoing, indicating that they spend less than they earn.\n\n**Note**: In the case that there have been no outgoing transactions, the value will be `null`.\n"
},
"positive_to_negative_ratio_3d": {
"type": "number",
"format": "float",
"example": 0.84,
"nullable": true,
"description": "The ratio between sum_positive / sum_negative in the last three days.\n\nℹ️ If the ratio is greater than `1`, it means that the user has more income than outgoing, indicating that they spend less than they earn.\n\n**Note**: In the case that there have been no outgoing transactions, the value will be `null`.\n"
},
"positive_to_negative_ratio_3m": {
"type": "number",
"format": "float",
"example": 1.04,
"nullable": true,
"description": "The ratio between sum_positive / sum_negative in the last three months.\n\nℹ️ If the ratio is greater than `1`, it means that the user has more income than outgoing, indicating that they spend less than they earn.\n\n**Note**: In the case that there have been no outgoing transactions, the value will be `null`.\n"
},
"positive_to_negative_ratio_6m": {
"type": "number",
"format": "float",
"example": 1.13,
"nullable": true,
"description": "The ratio between sum_positive / sum_negative in the last six months.\n\nℹ️ If the ratio is greater than `1`, it means that the user has more income than outgoing, indicating that they spend less than they earn.\n\n**Note**: In the case that there have been no outgoing transactions, the value will be `null`.\n"
},
"positive_to_negative_ratio_12m": {
"type": "number",
"format": "float",
"example": 1.3,
"nullable": true,
"description": "The ratio between sum_positive / sum_negative in the last twelve months.\n\nℹ️ If the ratio is greater than `1`, it means that the user has more income than outgoing, indicating that they spend less than they earn.\n\n**Note**: In the case that there have been no outgoing transactions, the value will be `null`.\n"
}
},
"description": "Aggregate metrics calculated based on the user's transactions from checking, savings, credit, and loan accounts. However, internal transfers (transfers between accounts belonging to the same link) are not used in the calculation.\n\n\n> ℹ️ **Note**\n>\n> If there is not enough transactional data for a given period, we return `null`. For example, if the account has only been open for 15 days (or you have only provided data for just 15 days), we return values for `_3d`, `_1w`, and `_1m`, however for `_3m` we will return `null` as there is no data for months two and three.\n"
}
RiskInsightsCategoryMetrics
{
"type": "object",
"properties": {
"category": {
"$ref": "#/components/schemas/EnumTransactionCategory"
},
"trend_3m": {
"type": "number",
"format": "float",
"example": 0,
"nullable": true,
"description": "The net category transaction trend (incoming - outgoing transactions for the category) for the period."
},
"subcategory": {
"$ref": "#/components/schemas/EnumTransactionSubcategory"
},
"net_amount_3m": {
"type": "number",
"format": "float",
"example": 642.76,
"nullable": true,
"description": "The net amount of the transactions for this category in the last three months (calculated as the total incoming - total outgoing transactions for this category)."
},
"category_inflow_ratio_3m": {
"type": "number",
"format": "float",
"example": 1,
"nullable": true,
"description": "The ratio of `net_amount_3m` divided by the sum of all incoming categorized transactions (including the current category) for the same period.\n\nNote: If there are no inflow transactions for the period, this value will return `null`.\n"
}
}
}
RiskInsightsCreditCardMetrics
{
"type": "object",
"nullable": true,
"required": [
"num_accounts",
"sum_credit_limit",
"sum_credit_used",
"credit_card_limit_utilization"
],
"properties": {
"num_accounts": {
"type": "integer",
"format": "int32",
"example": 2,
"minimum": 0,
"description": "Number of credit cards accounts associated to the user.\n"
},
"sum_credit_used": {
"type": "number",
"format": "float",
"example": 101020.14,
"nullable": true,
"description": "Sum total of all credit used.\n"
},
"sum_credit_limit": {
"type": "number",
"format": "float",
"example": 106560,
"nullable": true,
"description": "Sum total of all credit cards' limits.\n"
},
"credit_card_limit_utilization": {
"type": "number",
"format": "float",
"example": 0.95,
"nullable": true,
"description": "The percentage of the credit card limit used.\n"
}
},
"description": "Aggregated metrics calculated based on the user's credit card accounts.\n\n> Credit card metrics illustrate a customer's credit card habits, revealing how many credit card accounts a customer has, their total credit limit, how much of that limit they're using, and the rate of their credit card limit utilization.\n"
}
RiskInsightsDeleteSpecificInsight404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
RiskInsightsDeleteSpecificInsightResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
RiskInsightsGetDetails401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
RiskInsightsGetDetails404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
RiskInsightsGetDetailsResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RiskInsights"
}
}
RiskInsightsGetForLink401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
RiskInsightsGetForLink408Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RequestTimeoutError"
},
"title": "Request Timeout",
"description": "Belvo has a limit regarding the time it takes to log in, retrieve account data, and log out. A timeout occurs when there is a very high amount of data and everything could not be obtained within the allotted time.\n \n"
}
RiskInsightsGetForLink428Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenRequiredResponse"
}
}
RiskInsightsGetForLink500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
RiskInsightsGetForLinkResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
},
{
"$ref": "#/components/schemas/InvalidPeriodError"
}
]
}
}
RiskInsightsListAllRiskInsightsResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
RiskInsightsLoansMetrics
{
"type": "object",
"nullable": true,
"required": [
"num_accounts",
"sum_loans_principal",
"sum_loans_outstanding_principal",
"sum_loans_monthly_payment",
"loan_limit_utilization",
"overdraft_limit",
"overdraft_limit_utilization"
],
"properties": {
"num_accounts": {
"type": "integer",
"format": "int32",
"example": 1,
"description": "The number of loan accounts associated with the user.\n"
},
"overdraft_limit": {
"type": "number",
"format": "float",
"example": 900,
"nullable": true,
"description": "The total overdraft limit of all checking and savings accounts.\n"
},
"sum_loans_principal": {
"type": "number",
"format": "float",
"example": 5000,
"nullable": true,
"description": "Sum total of the principal for all of the user's loan accounts.\n"
},
"loan_limit_utilization": {
"type": "number",
"format": "float",
"example": 0.3,
"nullable": true,
"description": "The percentage of the loan limit used.\n"
},
"sum_loans_monthly_payment": {
"type": "number",
"format": "float",
"example": 400,
"nullable": true,
"description": "Sum total of the monthly payments for all the user's loan accounts.\n"
},
"overdraft_limit_utilization": {
"type": "number",
"format": "float",
"example": 0.4,
"nullable": true,
"description": "The percentage of the overdraft limit used.\n"
},
"sum_loans_outstanding_principal": {
"type": "number",
"format": "float",
"example": 2000,
"nullable": true,
"description": "Sum total of the outstanding principal for all the user's loan accounts.\n"
}
},
"description": "Aggregated metrics calculated based on the user's loan accounts and checking accounts that have an overdraft.\n\n> Loan metrics help in understanding a customer's borrowing and repayment behavior, which can help in assessing their ability to take on additional credit and potential default risks.\n"
}
RiskInsightsPaginatedResponse
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/common_pagination_properties"
},
{
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RiskInsights"
},
"description": "Array of risk insights objects."
}
}
}
]
}
RiskInsightsResumeInsightsSession201Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RiskInsights"
}
}
RiskInsightsResumeInsightsSession400Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
}
]
}
}
RiskInsightsResumeInsightsSession401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
RiskInsightsResumeInsightsSession408Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RequestTimeoutError"
},
"title": "Request Timeout",
"description": "Belvo has a limit regarding the time it takes to log in, retrieve account data, and log out. A timeout occurs when there is a very high amount of data and everything could not be obtained within the allotted time.\n \n"
}
RiskInsightsResumeInsightsSession428Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenRequiredResponse"
}
}
RiskInsightsResumeInsightsSession500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
RiskInsightsResumeInsightsSessionResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RiskInsights"
}
}
RiskInsightsTransactionMetrics
{
"type": "object",
"nullable": true,
"required": [
"num_transactions_3d",
"num_transactions_1w",
"num_transactions_1m",
"num_transactions_3m",
"num_transactions_6m",
"num_transactions_12m",
"max_num_transactions_3d",
"max_num_transactions_1w",
"max_num_transactions_1m",
"max_num_transactions_3m",
"max_num_transactions_6m",
"max_num_transactions_12m",
"mean_num_transactions_3d",
"mean_num_transactions_1w",
"mean_num_transactions_1m",
"mean_num_transactions_3m",
"mean_num_transactions_6m",
"mean_num_transactions_12m",
"num_incoming_transactions_3d",
"num_incoming_transactions_1w",
"num_incoming_transactions_1m",
"num_incoming_transactions_3m",
"num_incoming_transactions_6m",
"num_incoming_transactions_12m",
"max_num_incoming_transactions_3d",
"max_num_incoming_transactions_1w",
"max_num_incoming_transactions_1m",
"max_num_incoming_transactions_3m",
"max_num_incoming_transactions_6m",
"max_num_incoming_transactions_12m",
"mean_num_incoming_transactions_3d",
"mean_num_incoming_transactions_1w",
"mean_num_incoming_transactions_1m",
"mean_num_incoming_transactions_3m",
"mean_num_incoming_transactions_6m",
"mean_num_incoming_transactions_12m",
"sum_incoming_amount_3d",
"sum_incoming_amount_1w",
"sum_incoming_amount_1m",
"sum_incoming_amount_3m",
"sum_incoming_amount_6m",
"sum_incoming_amount_12m",
"max_incoming_amount_3d",
"max_incoming_amount_1w",
"max_incoming_amount_1m",
"max_incoming_amount_3m",
"max_incoming_amount_6m",
"max_incoming_amount_12m",
"mean_incoming_amount_3d",
"mean_incoming_amount_1w",
"mean_incoming_amount_1m",
"mean_incoming_amount_3m",
"mean_incoming_amount_6m",
"mean_incoming_amount_12m",
"num_outgoing_transactions_3d",
"num_outgoing_transactions_1w",
"num_outgoing_transactions_1m",
"num_outgoing_transactions_3m",
"num_outgoing_transactions_6m",
"num_outgoing_transactions_12m",
"max_num_outgoing_transactions_3d",
"max_num_outgoing_transactions_1w",
"max_num_outgoing_transactions_1m",
"max_num_outgoing_transactions_3m",
"max_num_outgoing_transactions_6m",
"max_num_outgoing_transactions_12m",
"mean_num_outgoing_transactions_3d",
"mean_num_outgoing_transactions_1w",
"mean_num_outgoing_transactions_1m",
"mean_num_outgoing_transactions_3m",
"mean_num_outgoing_transactions_6m",
"mean_num_outgoing_transactions_12m",
"sum_outgoing_amount_3d",
"sum_outgoing_amount_1w",
"sum_outgoing_amount_1m",
"sum_outgoing_amount_3m",
"sum_outgoing_amount_6m",
"sum_outgoing_amount_12m",
"max_outgoing_amount_3d",
"max_outgoing_amount_1w",
"max_outgoing_amount_1m",
"max_outgoing_amount_3m",
"max_outgoing_amount_6m",
"max_outgoing_amount_12m",
"mean_outgoing_amount_3d",
"mean_outgoing_amount_1w",
"mean_outgoing_amount_1m",
"mean_outgoing_amount_3m",
"mean_outgoing_amount_6m",
"mean_outgoing_amount_12m",
"days_without_transactions_3d",
"days_without_transactions_1w",
"days_without_transactions_1m",
"days_without_transactions_3m",
"days_without_transactions_6m",
"days_without_transactions_12m",
"days_since_last_transaction",
"days_since_last_incoming_transaction",
"days_since_last_outgoing_transaction",
"days_history"
],
"properties": {
"days_history": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 365,
"description": "The number of days between when the risk insight request was made and the first transaction.\n"
},
"num_transactions_1m": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 168,
"description": "The total number of transactions analyzed to determine the risk insights for the last month (incoming and outgoing).\n"
},
"num_transactions_1w": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 46,
"description": "The total number of transactions analyzed to determine the risk insights for the last week (incoming and outgoing).\n"
},
"num_transactions_3d": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 26,
"description": "The total number of transactions analyzed to determine the risk insights for the last three days (incoming and outgoing).\n"
},
"num_transactions_3m": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 460,
"description": "The total number of transactions analyzed to determine the risk insights for the last three months (incoming and outgoing).\n"
},
"num_transactions_6m": {
"type": "integer",
"format": "int32",
"default": 670,
"example": 472,
"description": "The total number of transactions analyzed to determine the risk insights for the last six months (incoming and outgoing).\n"
},
"num_transactions_12m": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 496,
"description": "The total number of transactions analyzed to determine the risk insights for the last twelve months (incoming and outgoing).\n"
},
"max_incoming_amount_1m": {
"type": "number",
"format": "float",
"example": 3000,
"nullable": true,
"description": "The highest value inflow transaction in the last month.\n"
},
"max_incoming_amount_1w": {
"type": "number",
"format": "float",
"example": 3000,
"nullable": true,
"description": "The highest value inflow transaction in the last week.\n"
},
"max_incoming_amount_3d": {
"type": "number",
"format": "float",
"example": 3000,
"nullable": true,
"description": "The highest value inflow transaction in the last three days.\n"
},
"max_incoming_amount_3m": {
"type": "number",
"format": "float",
"example": 3000,
"nullable": true,
"description": "The highest value inflow transaction in the last three months.\n"
},
"max_incoming_amount_6m": {
"type": "number",
"format": "float",
"example": 3000,
"nullable": true,
"description": "The highest value inflow transaction in the last six months.\n"
},
"max_outgoing_amount_1m": {
"type": "number",
"format": "float",
"example": 3000,
"nullable": true,
"description": "The highest value outflow transaction in the last month.\n"
},
"max_outgoing_amount_1w": {
"type": "number",
"format": "float",
"example": 3000,
"nullable": true,
"description": "The highest value outflow transaction in the last week.\n"
},
"max_outgoing_amount_3d": {
"type": "number",
"format": "float",
"example": 3000,
"nullable": true,
"description": "The highest value outflow transaction in the last three days.\n"
},
"max_outgoing_amount_3m": {
"type": "number",
"format": "float",
"example": 3000,
"nullable": true,
"description": "The highest value outflow transaction in the last three months.\n"
},
"max_outgoing_amount_6m": {
"type": "number",
"format": "float",
"example": 3000,
"nullable": true,
"description": "The highest value outflow transaction in the last six months.\n"
},
"sum_incoming_amount_1m": {
"type": "number",
"format": "float",
"example": 75993.36,
"nullable": true,
"description": "The total sum of all inflow transactions for the last month.\n"
},
"sum_incoming_amount_1w": {
"type": "number",
"format": "float",
"example": 24825.92,
"nullable": true,
"description": "The total sum of all inflow transactions for the last week.\n"
},
"sum_incoming_amount_3d": {
"type": "number",
"format": "float",
"example": 17142.16,
"nullable": true,
"description": "The total sum of all inflow transactions for the last three days.\n"
},
"sum_incoming_amount_3m": {
"type": "number",
"format": "float",
"example": 198197.28,
"nullable": true,
"description": "The total sum of all inflow transactions for the last three months.\n"
},
"sum_incoming_amount_6m": {
"type": "number",
"format": "float",
"example": 223697.28,
"nullable": true,
"description": "The total sum of all inflow transactions for the last six months.\n"
},
"sum_outgoing_amount_1m": {
"type": "number",
"format": "float",
"example": 78243.82,
"nullable": true,
"description": "The total sum of all outflow transactions for the last month.\n"
},
"sum_outgoing_amount_1w": {
"type": "number",
"format": "float",
"example": 26362.25,
"nullable": true,
"description": "The total sum of all outflow transactions for the last week.\n"
},
"sum_outgoing_amount_3d": {
"type": "number",
"format": "float",
"example": 18246.95,
"nullable": true,
"description": "The total sum of all outflow transactions for the last three days.\n"
},
"sum_outgoing_amount_3m": {
"type": "number",
"format": "float",
"example": 192608.77,
"nullable": true,
"description": "The total sum of all outflow transactions for the last three months.\n"
},
"sum_outgoing_amount_6m": {
"type": "number",
"format": "float",
"example": 201608.77,
"nullable": true,
"description": "The total sum of all outflow transactions for the last six months.\n"
},
"max_incoming_amount_12m": {
"type": "number",
"format": "float",
"example": 3000,
"nullable": true,
"description": "The highest value inflow transaction in the last twelve months.\n"
},
"max_num_transactions_1m": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 18,
"description": "The maximum number of transactions for the last month.\n"
},
"max_num_transactions_1w": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 10,
"description": "The maximum number of transactions for the last week.\n"
},
"max_num_transactions_3d": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 10,
"description": "The maximum number of transactions for the last three days.\n"
},
"max_num_transactions_3m": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 18,
"description": "The maximum number of transactions for the last three months.\n"
},
"max_num_transactions_6m": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 18,
"description": "The maximum number of transactions for the last six months.\n"
},
"max_outgoing_amount_12m": {
"type": "number",
"format": "float",
"example": 3000,
"nullable": true,
"description": "The highest value outflow transaction in the last twelve months.\n"
},
"mean_incoming_amount_1m": {
"type": "number",
"format": "float",
"example": 949.92,
"nullable": true,
"description": "The mean incoming value of all transactions in the last month.\n"
},
"mean_incoming_amount_1w": {
"type": "number",
"format": "float",
"example": 1182.19,
"nullable": true,
"description": "The mean incoming value of all transactions in the last week.\n"
},
"mean_incoming_amount_3d": {
"type": "number",
"format": "float",
"example": 1428.51,
"nullable": true,
"description": "The mean incoming value of all transactions in the last three days.\n"
},
"mean_incoming_amount_3m": {
"type": "number",
"format": "float",
"example": 865.49,
"nullable": true,
"description": "The mean incoming value of all transactions in the last three months.\n"
},
"mean_incoming_amount_6m": {
"type": "number",
"format": "float",
"example": 939.9,
"nullable": true,
"description": "The mean incoming value of all transactions in the last six months.\n"
},
"mean_outgoing_amount_1m": {
"type": "number",
"format": "float",
"example": 889.13,
"nullable": true,
"description": "The mean outgoing value of all transaction in the last month.\n"
},
"mean_outgoing_amount_1w": {
"type": "number",
"format": "float",
"example": 1054.49,
"nullable": true,
"description": "The mean outgoing value of all transaction in the last week.\n"
},
"mean_outgoing_amount_3d": {
"type": "number",
"format": "float",
"example": 1303.35,
"nullable": true,
"description": "The mean outgoing value of all transaction in the last three days.\n"
},
"mean_outgoing_amount_3m": {
"type": "number",
"format": "float",
"example": 833.8,
"nullable": true,
"description": "The mean outgoing value of all transaction in the last three months.\n"
},
"mean_outgoing_amount_6m": {
"type": "number",
"format": "float",
"example": 861.58,
"nullable": true,
"description": "The mean outgoing value of all transaction in the last six months.\n"
},
"sum_incoming_amount_12m": {
"type": "number",
"format": "float",
"example": 274697.28,
"nullable": true,
"description": "The total sum of all inflow transactions for the last twelve months.\n"
},
"sum_outgoing_amount_12m": {
"type": "number",
"format": "float",
"example": 219608.77,
"nullable": true,
"description": "The total sum of all outflow transactions for the last twelve months.\n"
},
"max_num_transactions_12m": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 18,
"description": "The maximum number of transactions for the last twelve months.\n"
},
"mean_incoming_amount_12m": {
"type": "number",
"format": "float",
"example": 1073.04,
"nullable": true,
"description": "The mean incoming value of all transactions in the last twelve months.\n"
},
"mean_num_transactions_1m": {
"type": "number",
"format": "float",
"default": 0,
"example": 5.42,
"description": "The mean number of transactions for the last month.\n"
},
"mean_num_transactions_1w": {
"type": "number",
"format": "float",
"default": 0,
"example": 5.75,
"description": "The mean number of transactions for the last week.\n"
},
"mean_num_transactions_3d": {
"type": "number",
"format": "float",
"default": 0,
"example": 6.5,
"description": "The mean number of transactions for the last three days.\n"
},
"mean_num_transactions_3m": {
"type": "number",
"format": "float",
"default": 0,
"example": 5.05,
"description": "The mean number of transactions for the last three months.\n"
},
"mean_num_transactions_6m": {
"type": "number",
"format": "float",
"default": 0,
"example": 2.61,
"description": "The mean number of transactions for the last six months.\n"
},
"mean_outgoing_amount_12m": {
"type": "number",
"format": "float",
"example": 915.04,
"nullable": true,
"description": "The mean outgoing value of all transaction in the last twelve months.\n"
},
"mean_num_transactions_12m": {
"type": "number",
"format": "float",
"default": 0,
"example": 1.37,
"description": "The mean number of transactions for the last twelve months.\n"
},
"days_since_last_transaction": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 0,
"description": "The number of days since the last transaction occurred.\n"
},
"days_without_transactions_1m": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 0,
"description": "The number of days that no transactions occurred within the last month.\n"
},
"days_without_transactions_1w": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 0,
"description": "The number of days that no transactions occurred within the last week.\n"
},
"days_without_transactions_3d": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 0,
"description": "The number of days that no transactions occurred within the last three days.\n"
},
"days_without_transactions_3m": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 0,
"description": "The number of days that no transactions occurred within the last three months.\n"
},
"days_without_transactions_6m": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 87,
"description": "The number of days that no transactions occurred within the last six months.\n"
},
"num_incoming_transactions_1m": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 80,
"description": "The total number of inflow transactions for the last month.\n"
},
"num_incoming_transactions_1w": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 21,
"description": "The total number of inflow transactions for the last week.\n"
},
"num_incoming_transactions_3d": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 12,
"description": "The total number of inflow transactions for the last three days.\n"
},
"num_incoming_transactions_3m": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 229,
"description": "The total number of inflow transactions for the last three months.\n"
},
"num_incoming_transactions_6m": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 238,
"description": "The total number of inflow transactions for the last six months.\n"
},
"num_outgoing_transactions_1m": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 88,
"description": "To total number of outflow transactions in the last month.\n"
},
"num_outgoing_transactions_1w": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 25,
"description": "To total number of outflow transactions in the last week.\n"
},
"num_outgoing_transactions_3d": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 14,
"description": "To total number of outflow transactions in the last three days.\n"
},
"num_outgoing_transactions_3m": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 231,
"description": "To total number of outflow transactions in the last three months.\n"
},
"num_outgoing_transactions_6m": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 234,
"description": "To total number of outflow transactions in the last six months.\n"
},
"days_without_transactions_12m": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 261,
"description": "The number of days that no transactions occurred within the last twelve months.\n"
},
"num_incoming_transactions_12m": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 256,
"description": "The total number of inflow transactions for the last twelve months.\n"
},
"num_outgoing_transactions_12m": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 240,
"description": "To total number of outflow transactions in the last twelve months.\n"
},
"max_num_incoming_transactions_1m": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 10,
"description": "The maximum number of inflow transactions for the last month.\n"
},
"max_num_incoming_transactions_1w": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 6,
"description": "The maximum number of inflow transactions for the last week.\n"
},
"max_num_incoming_transactions_3d": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 6,
"description": "The maximum number of inflow transactions for the last three days.\n"
},
"max_num_incoming_transactions_3m": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 10,
"description": "The maximum number of inflow transactions for the last three months.\n"
},
"max_num_incoming_transactions_6m": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 10,
"description": "The maximum number of inflow transactions for the last six months.\n"
},
"max_num_outgoing_transactions_1m": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 8,
"description": "The maximum number of outflow transactions for the last month.\n"
},
"max_num_outgoing_transactions_1w": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 6,
"description": "The maximum number of outflow transactions for the last week.\n"
},
"max_num_outgoing_transactions_3d": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 6,
"description": "The maximum number of outflow transactions for the last three days.\n"
},
"max_num_outgoing_transactions_3m": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 9,
"description": "The maximum number of outflow transactions for the last three months.\n"
},
"max_num_outgoing_transactions_6m": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 9,
"description": "The maximum number of outflow transactions for the last six months.\n"
},
"max_num_incoming_transactions_12m": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 10,
"description": "The maximum number of inflow transactions for the last twelve months.\n"
},
"max_num_outgoing_transactions_12m": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 9,
"description": "The maximum number of outflow transactions for the last twelve months.\n"
},
"mean_num_incoming_transactions_1m": {
"type": "number",
"format": "float",
"default": 0,
"example": 2.58,
"description": "The mean number of inflow transactions for the last month.\n"
},
"mean_num_incoming_transactions_1w": {
"type": "number",
"format": "float",
"default": 0,
"example": 2.62,
"description": "The mean number of inflow transactions for the last week.\n"
},
"mean_num_incoming_transactions_3d": {
"type": "number",
"format": "float",
"default": 0,
"example": 3,
"description": "The mean number of inflow transactions for the last three days.\n"
},
"mean_num_incoming_transactions_3m": {
"type": "number",
"format": "float",
"default": 0,
"example": 2.52,
"description": "The mean number of inflow transactions for the last three months.\n"
},
"mean_num_incoming_transactions_6m": {
"type": "number",
"format": "float",
"default": 0,
"example": 1.31,
"description": "The mean number of inflow transactions for the last six months.\n"
},
"mean_num_outgoing_transactions_1m": {
"type": "number",
"format": "float",
"default": 0,
"example": 2.84,
"description": "The mean number of outflow transactions for the last month.\n"
},
"mean_num_outgoing_transactions_1w": {
"type": "number",
"format": "float",
"default": 0,
"example": 3.12,
"description": "The mean number of outflow transactions for the last week.\n"
},
"mean_num_outgoing_transactions_3d": {
"type": "number",
"format": "float",
"default": 0,
"example": 3.5,
"description": "The mean number of outflow transactions for the last three days.\n"
},
"mean_num_outgoing_transactions_3m": {
"type": "number",
"format": "float",
"default": 0,
"example": 2.54,
"description": "The mean number of outflow transactions for the last three months.\n"
},
"mean_num_outgoing_transactions_6m": {
"type": "number",
"format": "float",
"default": 0,
"example": 1.29,
"description": "The mean number of outflow transactions for the last six months.\n"
},
"mean_num_incoming_transactions_12m": {
"type": "number",
"format": "float",
"default": 0,
"example": 0.71,
"description": "The mean number of inflow transactions for the last twelve months.\n"
},
"mean_num_outgoing_transactions_12m": {
"type": "number",
"format": "float",
"default": 0,
"example": 0.66,
"description": "The mean number of outflow transactions for the last twelve months.\n"
},
"days_since_last_incoming_transaction": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 0,
"description": "The number of days since the last inflow transaction occurred.\n"
},
"days_since_last_outgoing_transaction": {
"type": "integer",
"format": "int32",
"default": 0,
"example": 0,
"description": "The number of days since the last outflow transaction occurred.\n"
}
},
"description": "Aggregated metrics calculated based on the user's transactions from checking, savings, credit card, and loan accounts.\n\n\n> ℹ️ **Note**\n>\n> If there is not enough transactional data for a given period, we return `null` for calculated fields and `0` for 'count-based' fields. For example, if the account has only been open for five days (or you have provided data just for five days), we return values for `_3d`, `_1w`, and `_1m`, however:\n> \n> - `mean_num_transactions_3m` will return `null` as there is no data for months two and three (calculated field).\n> - `num_transactions_3m` will return `0` as there is no data for months two and three ('count-based' field)\n"
}
SessionExpiredError
{
"type": "object",
"title": "Session Expired",
"properties": {
"code": {
"type": "string",
"example": "session_expired",
"description": "A unique error code (`session_expired`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle <a href=\"https://developers.belvo.com/docs/belvo-api-errors#400-session_expired\" target=\"_blank\">400 session_expired errors</a>.\n"
},
"message": {
"type": "string",
"example": "The session you are trying to resume has expired, please start again from register/retrieve endpoint",
"description": "A short description of the error. \n\n\nFor `session_expired` errors, the description is:\n \n - `The session you are trying to resume has expired, please start again from register/retrieve endpoint`.\n"
},
"request_id": {
"type": "string",
"example": "9e7b283c6efa449c9c028a16b5c249fb",
"pattern": "[a-f0-9]{32}",
"description": "A 32-character unique ID of the request (matching a regex pattern of: `[a-f0-9]{32}`). Provide this ID when contacting the Belvo\nsupport team to accelerate investigations.\n"
}
},
"description": "This error occurs when you try to resume a request session that has already expired. This is usually because the user took too long to provide their authentication token.\n"
}
StandardRequest
{
"type": "object",
"required": [
"link"
],
"properties": {
"link": {
"type": "string",
"format": "uuid",
"example": "2ccd5e15-194a-4a19-a45a-e7223c7e6717",
"description": "The `link.id` that you want to get information for."
},
"token": {
"type": "string",
"example": "1234ab",
"description": "The OTP token generated by the bank."
},
"save_data": {
"type": "boolean",
"default": true,
"description": "Indicates whether or not to persist the data in Belvo. By default, this is set to `true` and we return a 201 Created response.\n\nWhen set to `false`, the data won't be persisted and we return a 200 OK response.\n"
}
}
}
TaxAssessmentBusiness
{
"type": "object",
"required": [
"net_income_taxable",
"fortuitous_profit_tax",
"total_tax_on_taxable_net_income",
"net_income_tax",
"total_tax_due",
"total_withholdings_for_the_taxable_year_to_be_declared",
"total_withheld_tax",
"total_balance_payable",
"total_balance_in_favor",
"total_payment"
],
"properties": {
"total_payment": {
"type": "number",
"format": "float",
"example": 0,
"description": "The total the tax payer is required to pay, taking into account deductions and fiscal credits."
},
"total_tax_due": {
"type": "number",
"format": "float",
"example": 5764000,
"description": "After further deductions, this is the final calculated tax that the taxpayer is required to pay."
},
"net_income_tax": {
"type": "number",
"format": "float",
"example": 5764000,
"description": "After additional deductions that you can apply, this will be the net income tax. If no further deduction are identified, this value will be the same as `total_tax_on_taxable_net_income`."
},
"net_income_taxable": {
"type": "number",
"format": "float",
"example": 18594000,
"description": "The net income on which tax can be applied."
},
"fortuitous_profit_tax": {
"type": "number",
"format": "float",
"example": 0,
"description": "The tax applied on your unexpected income (such as lottery wins or house sales)."
},
"total_balance_payable": {
"type": "number",
"format": "float",
"example": 0,
"description": "How much the tax payer is required to pay."
},
"total_balance_in_favor": {
"type": "number",
"format": "float",
"example": 1889000,
"description": "How much the tax payer is expected to receive."
},
"total_tax_on_taxable_net_income": {
"type": "number",
"format": "float",
"example": 5764000,
"description": "The calculated total tax that can be applied on the tax payer's taxable income (total income - exemptions - deductions)."
},
"total_withholdings_for_the_taxable_year_to_be_declared": {
"type": "number",
"format": "float",
"example": 7361000,
"description": "How much the tax payer has already paid througout the fiscal year."
}
},
"description": "Object containing the calculated tax assessment of the tax payer. This includes the total taxable income, the income tax applied, and taxes already withheld."
}
TaxAssessmentIndividual
{
"type": "object",
"required": [
"fortuitous_profit_tax",
"total_tax_on_taxable_net_income",
"net_income_tax",
"total_tax_due",
"previous_year_balance",
"total_withheld_tax",
"balance_payable",
"balance_refundable",
"total_payment"
],
"properties": {
"total_payment": {
"type": "number",
"format": "float",
"example": 0,
"description": "The total the tax payer is required to pay, taking into account deductions and fiscal credits."
},
"total_tax_due": {
"type": "number",
"format": "float",
"example": 9144000,
"description": "After further deductions, this is the final calculated tax that the taxpayer is required to pay."
},
"net_income_tax": {
"type": "number",
"format": "float",
"example": 9144000,
"description": "After additional deductions that you can apply, this will be the net income tax. If not further deduction are identified, this value will be the same as `total_tax_on_taxable_net_income`."
},
"balance_payable": {
"type": "number",
"format": "float",
"example": 0,
"description": "How much the tax payer is required to pay."
},
"balance_refundable": {
"type": "number",
"format": "float",
"example": 84000,
"description": "How much the tax payer is expected to receive. For DIAN, this will count as credit for the next fiscal year (see `previous_year_balance`)."
},
"total_withheld_tax": {
"type": "number",
"format": "float",
"example": 7714000,
"description": "The total tax already withheld in the current fiscal year."
},
"fortuitous_profit_tax": {
"type": "number",
"format": "float",
"example": 0,
"description": "The tax applied on your unexpected income (such as lottery wins or house sales)."
},
"previous_year_balance": {
"type": "number",
"format": "float",
"example": 1514000,
"description": "Only applicable for DIAN.\n\n\nThe amount the tax payer has as a \"credit\" fromt he previous year (this is equal to the `balance_refundable`) of the previous year.\n"
},
"total_tax_on_taxable_net_income": {
"type": "number",
"format": "float",
"example": 9144000,
"description": "The calculated total tax that can be applied on the tax payer's taxable income (total income - exemptions - deductions)."
}
},
"description": "Object containing the calculated tax assessment of the tax payer. This includes the total taxable income, the income tax applied, and taxes already withheld."
}
TaxComplianceStatus
{
"type": "object",
"required": [
"pdf",
"collected_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "91106968-1abd-4d64-85c1-4e73d96fb997",
"description": "Unique identifier created by Belvo used to reference the current Tax\nCompliance Status.\n"
},
"pdf": {
"type": "string",
"format": "binary",
"example": "=PDF-STRING=",
"nullable": true,
"description": "Tax compliance status PDF as a binary."
},
"rfc": {
"type": "string",
"example": "KDFC211118IS0",
"nullable": true,
"description": "The account holder's RFC (Registro Federal de Contribuyentes) number."
},
"outcome": {
"$ref": "#/components/schemas/EnumTaxComplianceStatusOutcome"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-02-09T08:45:50.406032Z",
"description": "The ISO-8601 timestamp of when the data point was last updated in Belvo's database.\n"
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2022-02-09T08:45:50.406032Z",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"internal_identification": {
"type": "string",
"example": "20NE1234567",
"nullable": true,
"description": "The institution’s internal identification number for the document."
}
}
}
TaxComplianceStatusDeleteSpecificTaxComplianceStatus404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
TaxComplianceStatusDeleteSpecificTaxComplianceStatusResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
TaxComplianceStatusGetDetails404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
TaxComplianceStatusGetDetailsResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
TaxComplianceStatusGetFiscalLinkInfo401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
TaxComplianceStatusGetFiscalLinkInfo408Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RequestTimeoutError"
},
"title": "Request Timeout",
"description": "Belvo has a limit regarding the time it takes to log in, retrieve account data, and log out. A timeout occurs when there is a very high amount of data and everything could not be obtained within the allotted time.\n \n"
}
TaxComplianceStatusGetFiscalLinkInfo500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
TaxComplianceStatusGetFiscalLinkInfoResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
}
]
}
}
TaxComplianceStatusListAllResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
TaxComplianceStatusPaginatedResponse
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/common_pagination_properties"
},
{
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TaxComplianceStatus"
},
"description": "Array of tax compliance status objects."
}
}
}
]
}
TaxComplianceStatusRequest
{
"type": "object",
"required": [
"link"
],
"properties": {
"link": {
"type": "string",
"format": "uuid",
"example": "d4617561-1c01-4b2f-83b6-a594f7b3bc57",
"description": "The fiscal `link.id` to use."
},
"save_data": {
"type": "boolean",
"default": true,
"example": true,
"description": "Indicates whether or not to persist the data in Belvo. By default, this is set to `true` and we return a 201 Created response.\n\nWhen set to `false`, the data won't be persisted and we return a 200 OK response.\n"
},
"attach_pdf": {
"type": "boolean",
"default": false,
"description": "When set to `true`, you will receive the PDF in binary format in\nthe response.\n"
}
}
}
TaxDeclarationBusiness
{
"type": "object",
"title": "Business Tax Declaration",
"required": [
"id",
"link",
"collected_at",
"created_at",
"document_information",
"tax_payer_information",
"equity_statement",
"annual_income_statement",
"annual_costs_and_deductions_statement",
"tax_assessment",
"date_issued",
"pdf"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "1c83ead8-6665-429c-a17a-ddc76cb3a95e",
"description": "Belvo's unique ID for the current tax declaration."
},
"pdf": {
"type": "string",
"example": "==BINARY-STRING==",
"nullable": true,
"description": "The PDF of the tax declaration, as a binary string."
},
"link": {
"type": "string",
"format": "uuid",
"example": "8a95ca1a-1a7a-4ce0-8599-f8ff1dc792ac",
"description": "Belvo's unique ID of the user that this tax declaration is associated with."
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2020-04-23T21:30:20.336854+00:00",
"description": "The ISO-8601 timestamp of when the data point was last updated in Belvo's database."
},
"date_issued": {
"type": "string",
"format": "date",
"example": "2022-09-02",
"description": "The date the tax declaration was issued by the fiscal institution."
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2020-04-23T21:32:55.336854+00:00",
"description": "The ISO-8601 timestamp when the data point was collected."
},
"tax_assessment": {
"$ref": "#/components/schemas/TaxAssessmentBusiness"
},
"equity_statement": {
"$ref": "#/components/schemas/EquityStatementBusiness"
},
"document_information": {
"$ref": "#/components/schemas/DocumentInformationBusiness"
},
"tax_payer_information": {
"$ref": "#/components/schemas/TaxPayerInformationBusiness"
},
"annual_income_statement": {
"$ref": "#/components/schemas/AnnualIncomeStatementBusiness"
},
"annual_costs_and_deductions_statement": {
"$ref": "#/components/schemas/AnnualCostsAndDeductionsStatementBusiness"
}
}
}
TaxDeclarationBusinessPaginated
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/common_pagination_properties"
},
{
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TaxDeclarationBusiness"
},
"description": "Array of Business Tax Declaration objects."
}
}
}
],
"title": "Tax Declaration Business"
}
TaxDeclarationIndividual
{
"type": "object",
"title": "Individual Tax Declaration",
"required": [
"id",
"link",
"collected_at",
"created_at",
"document_information",
"tax_payer_information",
"equity_statement",
"annual_income_statement",
"pension_income_statement",
"tax_assessment",
"date_issued",
"pdf"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "1c83ead8-6665-429c-a17a-ddc76cb3a95e",
"description": "Belvo's unique ID for the current tax declaration."
},
"pdf": {
"type": "string",
"example": "==BINARY-STRING==",
"nullable": true,
"description": "The PDF of the tax declaration, as a binary string."
},
"link": {
"type": "string",
"format": "uuid",
"example": "8a95ca1a-1a7a-4ce0-8599-f8ff1dc792ac",
"description": "Belvo's unique ID of the user that this tax declaration is associated with."
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2020-04-23T21:30:20.336854+00:00",
"description": "The ISO-8601 timestamp of when the data point was last updated in Belvo's database."
},
"date_issued": {
"type": "string",
"format": "date",
"example": "2022-09-02",
"description": "The date the tax declaration was issued by the fiscal institution."
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2020-04-23T21:32:55.336854+00:00",
"description": "The ISO-8601 timestamp when the data point was collected."
},
"tax_assessment": {
"$ref": "#/components/schemas/TaxAssessmentIndividual"
},
"equity_statement": {
"$ref": "#/components/schemas/EquityStatementIndividual"
},
"document_information": {
"$ref": "#/components/schemas/DocumentInformationIndividual"
},
"tax_payer_information": {
"$ref": "#/components/schemas/TaxPayerInformationIndividual"
},
"annual_income_statement": {
"$ref": "#/components/schemas/AnnualIncomeStatementIndividual"
},
"pension_income_statement": {
"$ref": "#/components/schemas/PensionIncomeStatementIndividual"
}
}
}
TaxDeclarationIndividualPaginated
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/common_pagination_properties"
},
{
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TaxDeclarationIndividual"
},
"description": "Array of Individual Tax Declaration objects."
}
}
}
],
"title": "Tax Declaration Individual"
}
TaxDeclarationsDeleteSpecificDeclaration404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
TaxDeclarationsDeleteSpecificDeclarationResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
TaxDeclarationsGetDetails401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
TaxDeclarationsGetDetails404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
TaxDeclarationsGetDetailsResponse
{
"oneOf": [
{
"$ref": "#/components/schemas/TaxDeclarationIndividual"
},
{
"$ref": "#/components/schemas/TaxDeclarationBusiness"
}
]
}
TaxDeclarationsGetFiscalLink201Response
{
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TaxDeclarationBusiness"
},
{
"$ref": "#/components/schemas/TaxDeclarationIndividual"
}
]
}
}
TaxDeclarationsGetFiscalLink400Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
}
]
}
}
TaxDeclarationsGetFiscalLink401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
TaxDeclarationsGetFiscalLink500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
TaxDeclarationsGetFiscalLinkResponse
{
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TaxDeclarationBusiness"
},
{
"$ref": "#/components/schemas/TaxDeclarationIndividual"
}
]
}
}
TaxDeclarationsListAll401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
TaxDeclarationsListAllResponse
{
"oneOf": [
{
"$ref": "#/components/schemas/TaxDeclarationIndividualPaginated"
},
{
"$ref": "#/components/schemas/TaxDeclarationBusinessPaginated"
}
]
}
TaxDeclarationsRequest
{
"type": "object",
"title": "Tax Declarations",
"required": [
"link",
"type",
"year_to",
"year_from"
],
"properties": {
"link": {
"type": "string",
"format": "uuid",
"example": "d4617561-1c01-4b2f-83b6-a594f7b3bc57",
"description": "The fiscal `link.id` you want specific tax declaration information for."
},
"year_to": {
"type": "string",
"example": "2019",
"description": "The year you want to stop getting tax declaration for, in `YYYY` format.\n"
},
"save_data": {
"type": "boolean",
"default": true,
"example": true,
"description": "Indicates whether or not to persist the data in Belvo. By default, this is set to `true` and we return a 201 Created response.\n\nWhen set to `false`, the data won't be persisted and we return a 200 OK response.\n"
},
"year_from": {
"type": "string",
"example": "2018",
"description": "The starting year you want to get tax declaration for, in `YYYY` format.\n"
},
"attach_pdf": {
"type": "boolean",
"default": false,
"example": false,
"description": "When this is set to `true`, you will receive the PDF as a binary string in\nthe response.\n"
}
},
"description": "Request body for tax declrarations"
}
TaxPayerInformationBusiness
{
"type": "object",
"required": [
"first_last_name",
"second_last_name",
"first_name",
"other_names",
"company_name",
"main_economic_activity",
"document_id",
"reporting_id"
],
"properties": {
"first_name": {
"type": "string",
"example": "Carlos",
"nullable": true,
"description": "The tax payer's first name."
},
"document_id": {
"$ref": "#/components/schemas/DocumentIdBusiness"
},
"other_names": {
"type": "string",
"example": "Alberto",
"nullable": true,
"description": "Additional names of the tax payer."
},
"company_name": {
"type": "string",
"example": "Trusty Spanners",
"description": "The name of the company, as registered at the institution."
},
"reporting_id": {
"$ref": "#/components/schemas/ReportingId"
},
"first_last_name": {
"type": "string",
"example": "Restrepo",
"nullable": true,
"description": "The tax payer's first last name."
},
"second_last_name": {
"type": "string",
"example": "Vives",
"nullable": true,
"description": "The tax payer's second last name."
},
"main_economic_activity": {
"type": "string",
"example": "0032",
"description": "The main economic activity the tax payer is involved in."
}
},
"description": "Object containing information about the tax payer."
}
TaxPayerInformationIndividual
{
"type": "object",
"required": [
"first_last_name",
"second_last_name",
"first_name",
"other_names",
"main_economic_activity",
"document_id",
"reporting_id"
],
"properties": {
"first_name": {
"type": "string",
"example": "Carlos",
"description": "The tax payer's first name."
},
"document_id": {
"$ref": "#/components/schemas/DocumentIdIndividual"
},
"other_names": {
"type": "string",
"example": "Alberto",
"description": "Additional names of the tax payer."
},
"reporting_id": {
"$ref": "#/components/schemas/ReportingId"
},
"first_last_name": {
"type": "string",
"example": "Restrepo",
"description": "The tax payer's first last name."
},
"second_last_name": {
"type": "string",
"example": "Vives",
"description": "The tax payer's second last name."
},
"main_economic_activity": {
"type": "string",
"example": "0010",
"description": "The main economic activity the tax payer is involved in."
}
},
"description": "Object containing information about the tax payer."
}
TaxRetentions
{
"type": "object",
"required": [
"collected_at",
"invoice_identification",
"version",
"code",
"issued_at",
"certified_at",
"cancelled_at",
"sender_id",
"sender_name",
"receiver_nationality",
"receiver_id",
"receiver_name",
"total_invoice_amount",
"total_taxable_amount",
"total_exempt_amount",
"total_retained_amount",
"retention_breakdown",
"xml"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "c749315b-eec2-435d-a458-06912878564f",
"description": "Belvo's unique identifier used to reference the current tax retention statement."
},
"xml": {
"type": "string",
"example": "=XML-STRING=",
"nullable": true,
"description": "The tax retention document in XML form.\n"
},
"code": {
"type": "integer",
"format": "int32",
"example": 25,
"nullable": true,
"description": "The tax retention code. For more information, see our [SAT Catalogs DevPortal article](https://developers.belvo.com/docs/sat-catalogs#retention-code).\n"
},
"link": {
"type": "string",
"format": "uuid",
"example": "19697249-01b8-443e-a451-76bfc5fbeebf",
"description": "The `link.id` the tax retention belongs to."
},
"version": {
"type": "string",
"example": "1.0",
"nullable": true,
"description": "The CFDI version of the tax retentions.\n"
},
"issued_at": {
"type": "string",
"format": "date-time",
"example": "2019-01-03T21:10:40.000Z",
"nullable": true,
"description": "The ISO-8601 timestamp of when the tax retention was issued.\n"
},
"sender_id": {
"type": "string",
"example": "JKUF980404P0",
"nullable": true,
"description": "The fiscal ID of the invoice sender.\n"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-02-09T08:46:20.406032Z",
"description": "The ISO-8601 timestamp of when the data point was last updated in Belvo's database.\n"
},
"receiver_id": {
"type": "string",
"example": "GYGK3207809L1",
"nullable": true,
"description": "The fiscal ID of the invoice receiver.\n"
},
"sender_name": {
"type": "string",
"example": "Roberto Nunez Batman",
"nullable": true,
"description": "The name of the invoice sender.\n"
},
"cancelled_at": {
"type": "string",
"format": "date-time",
"example": null,
"nullable": true,
"description": "The ISO-8601 timestamp of when the tax retention was canceled (if applicable).\n"
},
"certified_at": {
"type": "string",
"format": "date-time",
"example": "2019-01-03T21:10:41.000Z",
"nullable": true,
"description": "The ISO-8601 timestamp of when the tax retention was certified.\n"
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2022-02-09T08:45:50.406032Z",
"nullable": true,
"description": "The ISO-8601 timestamp of when the data point was collected.\n"
},
"receiver_name": {
"type": "string",
"example": "ACME LTD",
"nullable": true,
"description": "The name of the invoice receiver.\n"
},
"retention_breakdown": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RetentionBreakdown"
},
"nullable": true,
"description": "A breakdown of the retained taxes.\n"
},
"total_exempt_amount": {
"type": "number",
"format": "float",
"example": 1000.8,
"nullable": true,
"description": "Total amount that is exempt from taxation.\n"
},
"receiver_nationality": {
"$ref": "#/components/schemas/EnumTaxRetentionReceiverNationality"
},
"total_invoice_amount": {
"type": "number",
"format": "float",
"example": 53249.8,
"nullable": true,
"description": "The total amount of the invoice that the tax retention relates to.\n"
},
"total_taxable_amount": {
"type": "number",
"format": "float",
"example": 43249,
"nullable": true,
"description": "The total amount that can be taxed. Calculated as `total_invoice_amount` - `total_exempt_amount`.\n"
},
"total_retained_amount": {
"type": "number",
"format": "float",
"example": 1550.7,
"nullable": true,
"description": "Total tax retained.\n"
},
"invoice_identification": {
"type": "string",
"format": "uuid",
"example": "def404af-5eef-4112-aa99-d1ec8493b89a",
"nullable": true,
"description": "The fiscal institution's unique ID for the invoice that the tax retention relates to.\n"
}
}
}
TaxRetentionsDeleteSpecificTaxRetention404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
TaxRetentionsDeleteSpecificTaxRetentionResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
TaxRetentionsGetDetails404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
TaxRetentionsGetDetailsResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
TaxRetentionsGetLinkTaxRetentions201Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/TaxRetentions"
}
}
TaxRetentionsGetLinkTaxRetentions400Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
}
]
}
}
TaxRetentionsGetLinkTaxRetentions401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
TaxRetentionsGetLinkTaxRetentions408Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RequestTimeoutError"
},
"title": "Request Timeout",
"description": "Belvo has a limit regarding the time it takes to log in, retrieve account data, and log out. A timeout occurs when there is a very high amount of data and everything could not be obtained within the allotted time.\n \n"
}
TaxRetentionsGetLinkTaxRetentions500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
TaxRetentionsGetLinkTaxRetentionsResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/TaxRetentions"
}
}
TaxRetentionsListAllResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
TaxRetentionsPaginatedResponse
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/common_pagination_properties"
},
{
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TaxRetentions"
},
"description": "Array of tax retentions objects."
}
}
}
]
}
TaxRetentionsRequest
{
"type": "object",
"required": [
"link",
"date_from",
"date_to",
"type"
],
"properties": {
"link": {
"type": "string",
"format": "uuid",
"example": "9e432f18-36ca-4bd6-a3f3-1971e58dc1e8",
"description": "The `link.id` that you want to get information for.\n"
},
"type": {
"$ref": "#/components/schemas/EnumTaxRetentionType"
},
"date_to": {
"type": "string",
"example": "2020-02-01",
"pattern": "[0-9]{4}-[0-9]{2}-[0-9]{2}",
"description": "The date you want to stop getting tax retentions for, in `YYYY-MM-DD` format.\n\n⚠️ The number of days between `date_from` and `date_to` cannot be over 365.\n"
},
"date_from": {
"type": "string",
"example": "2020-01-01",
"pattern": "[0-9]{4}-[0-9]{2}-[0-9]{2}",
"description": "The date from which you want to start getting tax retentions for, in `YYYY-MM-DD` format.\n\n⚠️ The value of `date_from` cannot be greater than `date_to`.\n"
},
"save_data": {
"type": "boolean",
"default": true,
"description": "Indicates whether or not to persist the data in Belvo. By default, this is set to `true` and we return a 201 Created response.\n\nWhen set to `false`, the data won't be persisted and we return a 200 OK response.\n"
},
"attach_xml": {
"type": "boolean",
"default": true,
"description": "When set to `true`, you will receive the XML tax retention in the\nresponse.\n"
}
}
}
TaxReturnBusiness
{
"type": "object",
"title": "Tax Return Business",
"required": [
"id",
"collected_at",
"created_at",
"informacion_general",
"datos_adicionales",
"estado_resultados",
"estado_posicion_financiera_balance",
"conciliacion_entre_resultado_contable_fiscal",
"deducciones_autorizadas",
"cifras_cierre_ejercicio",
"determinacion_del_impuesto_sobre_la_renta",
"dividendos_o_utilidades_distribuidos",
"detalle_pago_r1_isr_personas_morales",
"pdf",
"receipt_pdf"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "0d3ffb69-f83b-456e-ad8e-208d0998d71d",
"description": "Unique identifier created by Belvo used to reference the current Tax\nReturn.\n"
},
"pdf": {
"type": "string",
"format": "binary",
"example": "=PDF-STRING=",
"nullable": true,
"description": "Tax return PDF as a binary."
},
"ingressos": {
"type": "object",
"nullable": true,
"description": "> **Note**: Only applicable for tax return filed on or after 2022. For tax returns filed before 2022, this field will return `null`.\n\nDetails regarding the total amounts earned in the fiscal year.\n"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-02-09T08:45:50.406032Z",
"description": "The ISO-8601 timestamp of when the data point was last updated in Belvo's database.\n"
},
"receipt_pdf": {
"type": "string",
"format": "binary",
"example": "=PDF-STRING=",
"nullable": true,
"description": "The acknowledgement receipt from the fiscal institution confirming that\nthey received the tax return.\n"
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2019-09-27T13:01:41.941Z",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"determinacion": {
"type": "object",
"nullable": true,
"description": "> **Note**: Only applicable for tax return filed on or after 2022. For tax returns filed before 2022, this field will return `null`.\n\nDetails regarding the tax due or tax credit.\n"
},
"datos_adicionales": {
"type": "object",
"nullable": true,
"description": "Additional data regarding the tax return."
},
"estado_resultados": {
"type": "object",
"nullable": true,
"description": "Detailed information about the legal entity's yearly profit and loss.\n\n> **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.\n"
},
"informacion_general": {
"type": "object",
"nullable": true,
"description": "General information regarding the tax return (year, RFC, return type,\nperson/company name, and so on).\n"
},
"cifras_cierre_ejercicio": {
"type": "object",
"nullable": true,
"description": "Details regarding key numbers at the end of the fiscal exercise."
},
"deducciones_autorizadas": {
"type": "object",
"nullable": true,
"description": "Details regarding the legal entity's deductions."
},
"estado_posicion_financiera_balance": {
"type": "object",
"nullable": true,
"description": "Details regarding balance sheet of the legal entity.\n\n> **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.\n"
},
"detalle_pago_r1_isr_personas_morales": {
"type": "object",
"nullable": true,
"description": "Details of the tax payment."
},
"dividendos_o_utilidades_distribuidos": {
"type": "object",
"nullable": true,
"description": "Details regarding distributed dividends."
},
"determinacion_del_impuesto_sobre_la_renta": {
"type": "object",
"nullable": true,
"description": "Details regarding the final tax return."
},
"conciliacion_entre_resultado_contable_fiscal": {
"type": "object",
"nullable": true,
"description": "Details regarding the accounting reconciliation.\n\n> **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.\n"
}
},
"additionalProperties": true
}
TaxReturnBusinessMonthly
{
"type": "object",
"title": "Tax Return Business Monthly",
"required": [
"informacion_general",
"determinacion_isr",
"pdf",
"type",
"collected_at",
"detalle_pago_isr",
"determinacion_iva",
"detalle_pago_iva"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "0d3ffb69-f83b-456e-ad8e-208d0998d71d",
"description": "Unique identifier created by Belvo used to reference the current Tax\nReturn.\n"
},
"pdf": {
"type": "string",
"format": "binary",
"example": "=PDF-STRING=",
"nullable": true,
"description": "Tax return PDF as a binary."
},
"type": {
"type": "string",
"example": "monthly",
"nullable": true,
"description": "The type of tax return. Can be either monthly or annual."
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-02-09T08:45:50.406032Z",
"description": "The ISO-8601 timestamp of when the data point was last updated in Belvo's database.\n"
},
"receipt_pdf": {
"type": "string",
"format": "binary",
"example": "=PDF-STRING=",
"nullable": true,
"description": "The acknowledgement receipt from the fiscal institution confirming that\nthey received the tax return.\n"
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2019-09-27T13:01:41.941Z",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"detalle_pago_isr": {
"type": "object",
"nullable": true,
"description": "Information on the monthly provisional payments for the income tax."
},
"detalle_pago_iva": {
"type": "object",
"nullable": true,
"description": "Information on the monthly provisional payments for the VAT tax."
},
"determinacion_isr": {
"type": "object",
"nullable": true,
"description": "Information used to calculate the provisional income tax for the period."
},
"determinacion_iva": {
"type": "object",
"nullable": true,
"description": "Information used to calculate the provisional VAT tax for the period."
},
"informacion_general": {
"type": "object",
"nullable": true,
"description": "General information regarding the tax return (year, RFC, return type,\nperson/company name, and so on).\n"
}
},
"additionalProperties": true
}
TaxReturnPersonal
{
"type": "object",
"title": "Tax Return Personal",
"required": [
"informacion_general",
"sueldos_salarios",
"servicios_profesionales",
"dividendos",
"deducciones_personales",
"retenciones",
"determinacion_impuesto",
"pdf",
"receipt_pdf",
"collected_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "0d3ffb69-f83b-456e-ad8e-208d0998d71d",
"description": "Unique identifier created by Belvo used to reference the current Tax\nReturn.\n"
},
"pdf": {
"type": "string",
"format": "binary",
"example": "=PDF-STRING=",
"nullable": true,
"description": "Tax return PDF as a binary."
},
"link": {
"type": "string",
"format": "uuid",
"example": "30cb4806-6e00-48a4-91c9-ca55968576c8",
"description": "The `link.id` the statement belongs to"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-02-09T08:45:50.406032Z",
"description": "The ISO-8601 timestamp of when the data point was last updated in Belvo's database.\n"
},
"dividendos": {
"type": "object",
"nullable": true,
"description": "Details regarding dividends."
},
"receipt_pdf": {
"type": "string",
"format": "binary",
"example": "=PDF-STRING=",
"nullable": true,
"description": "The acknowledgement receipt from the fiscal institution confirming that\nthey received the tax return.\n"
},
"retenciones": {
"type": "object",
"nullable": true,
"description": "Details on the already withheld taxes."
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2019-09-27T13:01:41.941Z",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"sueldos_salarios": {
"type": "object",
"nullable": true,
"description": "Details regarding the income information together combined with withheld\ntaxes.\n"
},
"datos_informativos": {
"type": "object",
"nullable": true,
"description": "Extra informative data on the tax return."
},
"informacion_general": {
"type": "object",
"nullable": true,
"description": "General information on the tax return (year, RFC, return type,\nperson/company name, and so on).\n"
},
"deducciones_personales": {
"type": "object",
"nullable": true,
"description": "List of all personal tax deductions."
},
"determinacion_impuesto": {
"type": "object",
"nullable": true,
"description": "Details regarding the final tax return."
},
"servicios_profesionales": {
"type": "object",
"nullable": true,
"description": "Details regarding the income and tax information from professional\nservices provided.\n"
}
},
"additionalProperties": true
}
TaxReturnPersonalMonthly
{
"type": "object",
"title": "Tax Return Personal Monthly",
"required": [
"informacion_general",
"pdf",
"type",
"isr",
"iva",
"collected_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "0d3ffb69-f83b-456e-ad8e-208d0998d71d",
"description": "Unique identifier created by Belvo used to reference the current Tax\nReturn.\n"
},
"isr": {
"type": "object",
"nullable": true,
"description": "Information used to calculate the monthly provisional payments of the\nincome tax.\n"
},
"iva": {
"type": "object",
"nullable": true,
"description": "Information used to calculate the monthly provisional payments of the VAT\ntax.\n"
},
"pdf": {
"type": "string",
"format": "binary",
"example": "=PDF-STRING=",
"nullable": true,
"description": "Tax return PDF as a binary."
},
"type": {
"type": "string",
"example": "monthly",
"description": "The type of tax return. Can be either monthly or annual."
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-02-09T08:45:50.406032Z",
"description": "The ISO-8601 timestamp of when the data point was last updated in Belvo's database.\n"
},
"receipt_pdf": {
"type": "string",
"format": "binary",
"example": "=PDF-STRING=",
"nullable": true,
"description": "The acknowledgement receipt from the fiscal institution confirming that\nthey received the tax return.\n"
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2022-02-09T08:45:50.406032Z",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"informacion_general": {
"type": "object",
"nullable": true,
"description": "General information regarding the tax return (year, RFC, return type,\nperson/company name, and so on).\n"
}
},
"additionalProperties": true
}
TaxReturnsBusinessMonthlyPaginated
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/common_pagination_properties"
},
{
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TaxReturnBusinessMonthly"
},
"description": "Array of Monthly Business Tax Return objects."
}
}
}
],
"title": "Tax Return Personal Business Monthly",
"additionalProperties": true
}
TaxReturnsBusinessPaginated
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/common_pagination_properties"
},
{
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TaxReturnBusiness"
},
"description": "Array of Business Tax Return objects."
}
}
}
],
"title": "Tax Return Personal Business",
"additionalProperties": true
}
TaxReturnsDeleteSpecificTaxReturn404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
TaxReturnsDeleteSpecificTaxReturnResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
TaxReturnsGetDetails401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
TaxReturnsGetDetails404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
TaxReturnsGetDetailsResponse
{
"oneOf": [
{
"$ref": "#/components/schemas/TaxReturnPersonal"
},
{
"$ref": "#/components/schemas/TaxReturnPersonalMonthly"
},
{
"$ref": "#/components/schemas/TaxReturnBusiness"
},
{
"$ref": "#/components/schemas/TaxReturnBusinessMonthly"
}
]
}
TaxReturnsGetInformation201Response
{
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TaxReturnPersonal"
},
{
"$ref": "#/components/schemas/TaxReturnPersonalMonthly"
},
{
"$ref": "#/components/schemas/TaxReturnBusiness"
},
{
"$ref": "#/components/schemas/TaxReturnBusinessMonthly"
}
]
}
}
TaxReturnsGetInformation400Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
}
]
}
}
TaxReturnsGetInformation401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
TaxReturnsGetInformation500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
TaxReturnsGetInformationRequest
{
"oneOf": [
{
"$ref": "#/components/schemas/TaxReturnsMonthlyRequest"
},
{
"$ref": "#/components/schemas/TaxReturnsYearlyRequest"
}
]
}
TaxReturnsGetInformationResponse
{
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TaxReturnPersonal"
},
{
"$ref": "#/components/schemas/TaxReturnPersonalMonthly"
},
{
"$ref": "#/components/schemas/TaxReturnBusiness"
},
{
"$ref": "#/components/schemas/TaxReturnBusinessMonthly"
}
]
}
}
TaxReturnsListAll401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
TaxReturnsListAllResponse
{
"oneOf": [
{
"$ref": "#/components/schemas/TaxReturnsPersonalPaginated"
},
{
"$ref": "#/components/schemas/TaxReturnsPersonalMonthlyPaginated"
},
{
"$ref": "#/components/schemas/TaxReturnsBusinessPaginated"
},
{
"$ref": "#/components/schemas/TaxReturnsBusinessMonthlyPaginated"
}
]
}
TaxReturnsMonthlyRequest
{
"type": "object",
"title": "Monthly Tax Returns",
"required": [
"link",
"type",
"date_from",
"date_to"
],
"properties": {
"link": {
"type": "string",
"format": "uuid",
"example": "d4617561-1c01-4b2f-83b6-a594f7b3bc57",
"description": "The fiscal `link.id` you want specific tax return information for."
},
"type": {
"type": "string",
"default": "monthly",
"description": "The type of tax return to return. For monthly tax returns, this field must be set to `monthly`.\n"
},
"date_to": {
"type": "string",
"example": "2019-01-01",
"description": "The date you want to stop getting tax returns for, in `YYYY-MM-DD` format.\n\n\n⚠️ The value of `date_to` cannot be greater than today's date (in other words, no future dates).\n"
},
"date_from": {
"type": "string",
"example": "2018-01-01",
"description": "The starting date you want to get tax returns for, in `YYYY-MM-DD` format.\n\n\n⚠️ The value of `date_from` cannot be greater than `date_to`.\n"
},
"save_data": {
"type": "boolean",
"default": true,
"example": true,
"description": "Indicates whether or not to persist the data in Belvo. By default, this is set to `true` and we return a 201 Created response.\n\nWhen set to `false`, the data won't be persisted and we return a 200 OK response.\n"
},
"attach_pdf": {
"type": "boolean",
"default": false,
"example": false,
"description": "When this is set to `true`, you will receive the PDF as a binary string in\nthe response.\n"
}
},
"description": "Request body for monthly tax returns"
}
TaxReturnsPersonalMonthlyPaginated
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/common_pagination_properties"
},
{
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TaxReturnPersonalMonthly"
},
"description": "Array of Monthly Personal Tax Return objects."
}
}
}
],
"title": "Tax Return Personal Monthly",
"additionalProperties": true
}
TaxReturnsPersonalPaginated
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/common_pagination_properties"
},
{
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TaxReturnPersonal"
},
"description": "Array of Personal Tax Return objects."
}
}
}
],
"title": "Tax Return Personal",
"additionalProperties": true
}
TaxReturnsYearlyRequest
{
"type": "object",
"title": "Yearly Tax Returns",
"required": [
"link",
"type",
"year_to",
"year_from"
],
"properties": {
"link": {
"type": "string",
"format": "uuid",
"example": "d4617561-1c01-4b2f-83b6-a594f7b3bc57",
"description": "The fiscal `link.id` you want specific tax return information for."
},
"type": {
"type": "string",
"default": "yearly",
"description": "The type of tax return to return. For yearly tax returns this must be set to `yearly`.\n\nBy default, Belvo returns the yearly (annual) tax returns.\n"
},
"year_to": {
"type": "string",
"example": "2019",
"description": "The year you want to stop getting tax returns for, in `YYYY` format.\n"
},
"save_data": {
"type": "boolean",
"default": true,
"example": true,
"description": "Indicates whether or not to persist the data in Belvo. By default, this is set to `true` and we return a 201 Created response.\n\nWhen set to `false`, the data won't be persisted and we return a 200 OK response.\n"
},
"year_from": {
"type": "string",
"example": "2018",
"description": "The starting year you want to get tax returns for, in `YYYY` format.\n"
},
"attach_pdf": {
"type": "boolean",
"default": false,
"example": false,
"description": "When this is set to `true`, you will receive the PDF as a binary string in\nthe response.\n"
}
},
"description": "Request body for yearly tax returns"
}
TaxStatusAddressBetweenStreetDian
{
"type": "object",
"properties": {
"street_one": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"street_two": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
}
}
}
TaxStatusAddressBetweenStreetSat
{
"type": "object",
"properties": {
"street_one": {
"type": "string",
"example": "CALLE PRINCIPE",
"nullable": true,
"description": "The first street that `street` is located between."
},
"street_two": {
"type": "string",
"example": "CALLE NUEVA ROMA",
"nullable": true,
"description": "The second street that `street` is located between."
}
}
}
TaxStatusAddressDian
{
"type": "object",
"nullable": true,
"required": [
"postal_code"
],
"properties": {
"state": {
"type": "string",
"example": "Bogota DC",
"nullable": true,
"description": "The state that the address is in."
},
"street": {
"type": "string",
"example": "LA MALINCHE",
"nullable": true,
"description": "The tax payers street."
},
"suburb": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"locality": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"postal_code": {
"type": "string",
"example": "332-55",
"nullable": true,
"description": "The postcode of the address.\n"
},
"street_type": {
"type": "string",
"example": "CALLE",
"nullable": true,
"description": "The `street` type."
},
"municipality": {
"type": "string",
"example": "Bogota DC",
"nullable": true,
"description": "The municipality of the address."
},
"between_street": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TaxStatusAddressBetweenStreetDian"
},
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"exterior_number": {
"type": "string",
"example": "432",
"nullable": true,
"description": "The street number."
},
"interior_number": {
"type": "string",
"example": "AP 306",
"nullable": true,
"description": "Additional address information."
}
},
"description": "The tax payer's address details."
}
TaxStatusAddressSat
{
"type": "object",
"nullable": true,
"required": [
"postal_code"
],
"properties": {
"state": {
"type": "string",
"example": "Federal",
"nullable": true,
"description": "The state that the address is in."
},
"street": {
"type": "string",
"example": "LA MALINCHE",
"nullable": true,
"description": "The tax payers street."
},
"suburb": {
"type": "string",
"example": "BUENAVENTURA",
"nullable": true,
"description": "The suburb of the tax payer.\n"
},
"locality": {
"type": "string",
"example": "none",
"nullable": true,
"description": "The locality of the address.\n"
},
"postal_code": {
"type": "string",
"example": "21255",
"nullable": true,
"description": "The postcode of the address.\n"
},
"street_type": {
"type": "string",
"example": "CALLE",
"nullable": true,
"description": "The `street` type."
},
"municipality": {
"type": "string",
"example": "CDMX DC",
"nullable": true,
"description": "The municipality of the address."
},
"between_street": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TaxStatusAddressBetweenStreetSat"
},
"nullable": true,
"description": "Additional information about where the `street` is located.\n"
},
"exterior_number": {
"type": "string",
"example": "432",
"nullable": true,
"description": "The street number."
},
"interior_number": {
"type": "string",
"example": "PLANTA BAJA",
"nullable": true,
"description": "Additional address information."
}
},
"description": "The tax payer's address details."
}
TaxStatusDeleteSpecificTaxStatus404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
TaxStatusDeleteSpecificTaxStatusResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
TaxStatusDian
{
"type": "object",
"title": "DIAN 🇨🇴 Colombia",
"required": [
"id",
"link",
"collected_at",
"created_at",
"place_and_date_of_issuance",
"official_name",
"id_cif",
"tax_payer_information",
"address",
"economic_activity",
"regimes",
"obligations",
"digital_stamp",
"digital_stamp_chain",
"pdf"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "21e9e25b-10a8-48a5-9e6a-4072b364b53f",
"description": "Unique identifier created by Belvo used to reference the current Tax\nStatus.\n"
},
"pdf": {
"type": "string",
"format": "binary",
"example": "=PDF-STRING=",
"nullable": true,
"description": "Tax status PDF as a binary string."
},
"link": {
"type": "string",
"format": "uuid",
"example": "c2280c05-cbeb-4a29-ae53-8f837a77995b",
"description": "The `link.id` that the tax status is associated with."
},
"id_cif": {
"type": "string",
"example": "12345678901",
"nullable": true,
"description": "The taxpayer's *Cédula de ciudadanía* (CC) ID. Only applicable for individuals.\n"
},
"address": {
"$ref": "#/components/schemas/TaxStatusAddressDian"
},
"regimes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TaxStatusRegimensDian"
},
"nullable": true,
"description": "A list of regimen objects.\n"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-02-09T08:45:50.406032Z",
"description": "The ISO-8601 timestamp of when the data point was last updated in Belvo's database.\n"
},
"obligations": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TaxStatusObligationsDian"
},
"nullable": true,
"description": "Details regarding a business's obligations.\n\nℹ️ For non-business accounts, this field will return empty.\n"
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2020-04-23T21:32:55.336Z",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"digital_stamp": {
"type": "string",
"example": "\"44701362691\"\n",
"nullable": true,
"description": "The validation certificate of the document."
},
"official_name": {
"type": "string",
"example": "Jar Jar Transport",
"nullable": true,
"description": "The name of the business.\n\nNote: For individuals in Colombia, this field will return `null`.\n"
},
"economic_activity": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TaxStatusEconomicActivityDian"
},
"nullable": true,
"description": "A list of economic activity objects.\n"
},
"digital_stamp_chain": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"tax_payer_information": {
"$ref": "#/components/schemas/TaxStatusTaxPayerInformationDian"
},
"place_and_date_of_issuance": {
"type": "string",
"example": "2020-08-05/18:55:16",
"nullable": true,
"description": "The date when the tax status was issued. For example, `2020-08-05/18:55:16`."
}
}
}
TaxStatusEconomicActivityDian
{
"type": "object",
"properties": {
"order": {
"type": "string",
"example": "1",
"nullable": true,
"description": "The order of the economic activity."
},
"end_date": {
"type": "string",
"format": "date",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"percentage": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"initial_date": {
"type": "string",
"example": "2020-12-06",
"nullable": true,
"description": "The start date of the economic activity, in `YYYY-MM-DD` format."
},
"economic_activity": {
"type": "string",
"example": "112",
"nullable": true,
"description": "The economic activity code, according to the fiscal institution.\n\nFor detailed information regarding DIAN's economic activities, please see their [official PDF](https://www.dian.gov.co/impuestos/factura-electronica/Documents/Anexo_tecnico_factura_electronica_vr_1_7_2020.pdf). \n"
}
}
}
TaxStatusEconomicActivitySat
{
"type": "object",
"properties": {
"order": {
"type": "string",
"example": "2",
"nullable": true,
"description": "The order of the economic activity."
},
"end_date": {
"type": "string",
"format": "date",
"example": null,
"nullable": true,
"description": "The end date of the economic activity, in `YYYY-MM-DD` format.\n"
},
"percentage": {
"type": "string",
"example": "1",
"nullable": true,
"description": "The percentage of the economic activity.\n"
},
"initial_date": {
"type": "string",
"example": "2020-12-06",
"nullable": true,
"description": "The start date of the economic activity, in `YYYY-MM-DD` format."
},
"economic_activity": {
"type": "string",
"example": "Asalariado",
"nullable": true,
"description": "The description of the economic activity."
}
}
}
TaxStatusGetDetails401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
TaxStatusGetDetails404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
TaxStatusGetDetailsResponse
{
"anyOf": [
{
"$ref": "#/components/schemas/TaxStatusSat"
},
{
"$ref": "#/components/schemas/TaxStatusDian"
}
]
}
TaxStatusGetLinkTaxStatus201Response
{
"anyOf": [
{
"$ref": "#/components/schemas/TaxStatusSat"
},
{
"$ref": "#/components/schemas/TaxStatusDian"
}
]
}
TaxStatusGetLinkTaxStatus400Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
}
]
}
}
TaxStatusGetLinkTaxStatus401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
TaxStatusGetLinkTaxStatus408Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RequestTimeoutError"
},
"title": "Request Timeout",
"description": "Belvo has a limit regarding the time it takes to log in, retrieve account data, and log out. A timeout occurs when there is a very high amount of data and everything could not be obtained within the allotted time.\n \n"
}
TaxStatusGetLinkTaxStatus500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
TaxStatusGetLinkTaxStatusResponse
{
"anyOf": [
{
"$ref": "#/components/schemas/TaxStatusSat"
},
{
"$ref": "#/components/schemas/TaxStatusDian"
}
]
}
TaxStatusListAllResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
TaxStatusObligationsDian
{
"type": "object",
"properties": {
"end_date": {
"type": "string",
"format": "date",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"expiration": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"obligation": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"initial_date": {
"type": "string",
"format": "date",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
}
},
"description": "Details regarding a business's obligations.\n\nℹ️ For non-business accounts, this field will return empty.\n"
}
TaxStatusObligationsSat
{
"type": "object",
"properties": {
"end_date": {
"type": "string",
"format": "date",
"example": null,
"nullable": true,
"description": "The date when obligation ended, in `YYYY-MM-DD` format.\n"
},
"expiration": {
"type": "string",
"example": "Conjuntamente con la declaración anual del ejercicio.",
"nullable": true,
"description": "The deadline to fulfill the obligation, as imposed by the tax authority.\n"
},
"obligation": {
"type": "string",
"example": "Declaración informativa de IVA con la anual de ISR",
"nullable": true,
"description": "The description of the obligation.\n"
},
"initial_date": {
"type": "string",
"format": "date",
"example": "2020-12-06",
"nullable": true,
"description": "The date when obligation started, in `YYYY-MM-DD` format.\n"
}
},
"description": "Details regarding a business's obligations.\n\nℹ️ For non-business accounts, this field will return empty.\n"
}
TaxStatusPaginatedResponse
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/common_pagination_properties"
},
{
"properties": {
"results": {
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TaxStatusSat"
},
{
"$ref": "#/components/schemas/TaxStatusDian"
}
]
},
"description": "Array of tax status objects."
}
}
}
]
}
TaxStatusRegimensDian
{
"type": "object",
"required": [
"regimen",
"initial_date",
"end_date"
],
"properties": {
"regimen": {
"type": "string",
"example": "49-No responsable de IVA",
"nullable": true,
"description": "The description of the regimen."
},
"end_date": {
"type": "string",
"format": "date",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"initial_date": {
"type": "string",
"format": "date",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
}
}
}
TaxStatusRegimensSat
{
"type": "object",
"required": [
"regimen",
"initial_date",
"end_date"
],
"properties": {
"regimen": {
"type": "string",
"example": "Régimen de Ingresos por Dividendos (socios y accionistas)",
"nullable": true,
"description": "The description of the regimen."
},
"end_date": {
"type": "string",
"format": "date",
"example": null,
"nullable": true,
"description": "The end date of the regimen, in `YYYY-MM-DD` format.\n"
},
"initial_date": {
"type": "string",
"format": "date",
"example": "2020-12-06",
"nullable": true,
"description": "The start date of the regimen, in `YYYY-MM-DD` format.\n"
}
}
}
TaxStatusRequest
{
"type": "object",
"required": [
"link"
],
"properties": {
"link": {
"type": "string",
"format": "uuid",
"example": "d4617561-1c01-4b2f-83b6-a594f7b3bc57",
"description": "The fiscal `link.id` to use."
},
"save_data": {
"type": "boolean",
"default": true,
"example": true,
"description": "Indicates whether or not to persist the data in Belvo. By default, this is set to `true` and we return a 201 Created response.\n\nWhen set to `false`, the data won't be persisted and we return a 200 OK response.\n"
},
"attach_pdf": {
"type": "boolean",
"default": false,
"description": "When set to `true`, you will receive the PDF in binary format in\nthe response.\n"
}
}
}
TaxStatusSat
{
"type": "object",
"title": "SAT 🇲🇽 Mexico",
"required": [
"id",
"link",
"collected_at",
"created_at",
"place_and_date_of_issuance",
"official_name",
"id_cif",
"tax_payer_information",
"address",
"economic_activity",
"regimes",
"obligations",
"digital_stamp",
"digital_stamp_chain",
"pdf"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "21e9e25b-10a8-48a5-9e6a-4072b364b53f",
"description": "Unique identifier created by Belvo used to reference the current Tax\nStatus.\n"
},
"pdf": {
"type": "string",
"format": "binary",
"example": "=PDF-STRING=",
"nullable": true,
"description": "Tax status PDF as a binary string."
},
"link": {
"type": "string",
"format": "uuid",
"example": "c2280c05-cbeb-4a29-ae53-8f837a77995b",
"description": "The `link.id` that the tax status is associated with."
},
"id_cif": {
"type": "string",
"example": "12345678901",
"nullable": true,
"description": "The taxpayer's *Cédula de Identificación Fiscal* (CIF) ID.\n"
},
"address": {
"$ref": "#/components/schemas/TaxStatusAddressSat"
},
"regimes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TaxStatusRegimensSat"
},
"nullable": true,
"description": "A list of regimen objects.\n"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-02-09T08:45:50.406032Z",
"description": "The ISO-8601 timestamp of when the data point was last updated in Belvo's database.\n"
},
"obligations": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TaxStatusObligationsSat"
},
"nullable": true,
"description": "Details regarding a business's obligations.\n\nℹ️ For non-business accounts, this field will return empty.\n"
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2020-04-23T21:32:55.336Z",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"digital_stamp": {
"type": "string",
"example": "||2020/04/26|GHTF980303F7|CONSTANCIA DE SITUACIÓN\nFISCAL|2044441088666600000034||\n",
"nullable": true,
"description": "The validation certificate of the document."
},
"official_name": {
"type": "string",
"example": "John Doe",
"nullable": true,
"description": "The name of the person or business."
},
"economic_activity": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TaxStatusEconomicActivitySat"
},
"nullable": true,
"description": "A list of economic activity objects.\n"
},
"digital_stamp_chain": {
"type": "string",
"example": "EtenSA9t1adG7bn+Jj23kj43JK+XbMPxdOppwabhXD+pXseSqYowWWDna0mpUk3264lkj2345j23faNZB852dCDt9KAjow=\n",
"nullable": true,
"description": "A data chain containing the basic structure of a fiscal digital check. For Mexico, this is the *Comprobante Fiscal Digital por Internet* (CFDI).\n"
},
"tax_payer_information": {
"$ref": "#/components/schemas/TaxStatusTaxPayerInformationSat"
},
"place_and_date_of_issuance": {
"type": "string",
"example": "TLALPAN , CIUDAD DE MEXICO A 19 DE MARZO DE 2020",
"nullable": true,
"description": "The place and date of that the tax status was issued."
}
}
}
TaxStatusTaxPayerInformationDian
{
"type": "object",
"nullable": true,
"required": [
"rfc",
"start_operations_date",
"status_padron",
"last_status_change_date"
],
"properties": {
"rfc": {
"type": "string",
"example": "BEMP12345G58",
"nullable": true,
"description": "The tax payers's identification number (NIT).\n"
},
"curp": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"name": {
"type": "string",
"example": "JOHN",
"nullable": true,
"description": "The tax payers's first name."
},
"email": {
"type": "string",
"example": "john_doe@gmail.com",
"nullable": true,
"description": "Contact email address for the tax payer."
},
"phone": {
"type": "string",
"example": "1234567890",
"nullable": true,
"description": "Contact phone number for the tax payer."
},
"social_name": {
"type": "string",
"example": "John Doe SA DE CV",
"nullable": true,
"description": "The unique and exclusive name within the national territory that companies\nreceive for legal or administrative purposes.\n\n**Note**: Only applicable for businesses.\n"
},
"status_padron": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"commercial_name": {
"type": "string",
"example": "Jar Jar Transport",
"nullable": true,
"description": "The name of the business designated for consumers and the general public.\n\n**Note**: Only applicable for businesses.\n"
},
"first_last_name": {
"type": "string",
"example": "DOE",
"nullable": true,
"description": "The tax payers's first last name."
},
"second_last_name": {
"type": "string",
"example": "SCHMOE",
"nullable": true,
"description": "The tax payers's second last name."
},
"start_operations_date": {
"type": "string",
"format": "date",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"last_status_change_date": {
"type": "string",
"format": "date",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
}
},
"description": "Details regarding the taxpayer."
}
TaxStatusTaxPayerInformationSat
{
"type": "object",
"nullable": true,
"required": [
"rfc",
"start_operations_date",
"status_padron",
"last_status_change_date"
],
"properties": {
"rfc": {
"type": "string",
"example": "BEMP12345G58",
"nullable": true,
"description": "The tax payers's identification number (For Mexico, this is the RFC).\n"
},
"curp": {
"type": "string",
"example": null,
"nullable": true,
"description": "The tax payers's *Clave Única de Registro de Población* (CURP) number.\n"
},
"name": {
"type": "string",
"example": "JOHN",
"nullable": true,
"description": "The tax payers's first name."
},
"email": {
"type": "string",
"example": "john_doe@gmail.com",
"nullable": true,
"description": "Contact email address for the tax payer."
},
"phone": {
"type": "string",
"example": "1234567890",
"nullable": true,
"description": "Contact phone number for the tax payer."
},
"social_name": {
"type": "string",
"example": "John Doe SA DE CV",
"nullable": true,
"description": "The unique and exclusive name within the national territory that companies\nreceive for legal or administrative purposes.\n\n**Note**: Only applicable for businesses.\n"
},
"status_padron": {
"type": "string",
"example": null,
"nullable": true,
"description": "Status of the taxpayer in the Federal Register of Taxpayers (RFC). Can be `ACTIVO` or `INACTIVO`.\n"
},
"commercial_name": {
"type": "string",
"example": "Jar Jar Transport",
"nullable": true,
"description": "The name of the business designated for consumers and the general public.\n\n**Note**: Only applicable for businesses.\n"
},
"first_last_name": {
"type": "string",
"example": "DOE",
"nullable": true,
"description": "The tax payers's first last name."
},
"second_last_name": {
"type": "string",
"example": "SCHMOE",
"nullable": true,
"description": "The tax payers's second last name."
},
"start_operations_date": {
"type": "string",
"format": "date",
"example": null,
"nullable": true,
"description": "Date when the tax payer commenced taxable commercial activities, in `YYYY-MM-DD` format.\n"
},
"last_status_change_date": {
"type": "string",
"format": "date",
"example": null,
"nullable": true,
"description": "Date when `status_padron` was most recently updated, in `YYYY-MM-DD` format.\n"
}
},
"description": "Details regarding the taxpayer."
}
TokenRequiredResponse
{
"type": "object",
"properties": {
"code": {
"type": "string",
"example": "token_required",
"description": "A unique error code (`token_required`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle <a href=\"https://developers.belvo.com/docs/belvo-api-errors#428-token_required\" target=\"_blank\">428 token_required errors</a>.\n"
},
"link": {
"type": "string",
"format": "uuid",
"example": "30cb4806-6e00-48a4-91c9-ca55968576c8",
"description": "Unique identifier created by Belvo, used to reference the current\nLink.\n"
},
"expiry": {
"type": "integer",
"format": "int32",
"example": 9600,
"description": "Session duration time in seconds."
},
"message": {
"type": "string",
"example": "A MFA token is required by the institution to login",
"description": "A short description of the error. \n\n\nFor `token_required` errors, the description is:\n \n - `A MFA token is required by the institution to login`.\n"
},
"session": {
"type": "string",
"example": "2675b703b9d4451f8d4861a3eee54449",
"pattern": "[a-f0-9]{32}",
"description": "A 32-character unique ID of the login session (matching a regex pattern of: `[a-f0-9]{32}`).\n"
},
"request_id": {
"type": "string",
"example": "8c7b283c6efa449c9c028a16b5c249fa",
"pattern": "[a-f0-9]{32}",
"description": "A 32-character unique ID of the request (matching a regex pattern of: `[a-f0-9]{32}`). Provide this ID when contacting the Belvo\nsupport team to accelerate investigations.\n"
},
"token_generation_data": {
"$ref": "#/components/schemas/TokenRequiredResponseTokenGenerationData"
}
},
"description": "MFA Token Required"
}
TokenRequiredResponseTokenGenerationData
{
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "numeric",
"description": "Type of the data to generate the token (QR code, numeric\nchallenge).\n"
},
"value": {
"type": "string",
"example": "12345",
"description": "Value to use to generate the token."
},
"instructions": {
"type": "string",
"example": "Use this code to generate the token",
"description": "Instructions for token generation."
},
"expects_user_input": {
"type": "boolean",
"default": true,
"example": true,
"description": "Indicates whether the user needs to provide input in order to complete the authentication.\n\nWhen set to `false`, your user may need to:\n\n- confirm the login on another device\n- scan a QR code\n\nYou will still need to make a PATCH call to complete the request.\n"
}
},
"description": "Details on how to generate the token."
}
TooManySessionsError
{
"type": "object",
"title": "Too Many Sessions",
"properties": {
"code": {
"type": "string",
"example": "too_many_sessions",
"description": "A unique error code (`too_many_sessions`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle <a href=\"https://developers.belvo.com/docs/belvo-api-errors#400-too_many_sessions\" target=\"_blank\">400 too_many_sessions errors</a>.\n"
},
"message": {
"type": "string",
"example": "Impossible to login, a session is already opened with the institution for these credentials",
"description": "A short description of the error. \n\n\nFor `too_many_sessions` errors, the description is:\n \n - `Impossible to login, a session is already opened with the institution for these credentials`.\n"
},
"request_id": {
"type": "string",
"example": "9e7b283c6efa449c9c028a16b5c249fb",
"pattern": "[a-f0-9]{32}",
"description": "A 32-character unique ID of the request (matching a regex pattern of: `[a-f0-9]{32}`). Provide this ID when contacting the Belvo\nsupport team to accelerate investigations.\n"
}
},
"description": "This error occurs when:\n\n - a user is attempting to log in to their institution via Belvo while also already being logged in to their institution on a web browser or mobile app.\n - you make a request for information while Belvo is scraping data from the institution for that user.\n"
}
Transaction
{
"type": "object",
"title": "Transaction Standard (Multi-Region)",
"required": [
"value_date",
"accounting_date",
"amount",
"currency",
"description",
"reference",
"observations",
"balance",
"status",
"account",
"type",
"collected_at",
"category",
"merchant"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "076c66e5-90f5-4e01-99c7-50e32f65ae42",
"description": "Belvo's unique ID for the transaction."
},
"type": {
"$ref": "#/components/schemas/EnumTransactionType"
},
"amount": {
"type": "number",
"format": "float",
"example": 2145.45,
"pattern": "^\\d{1,15}\\.\\d{2,4}$",
"nullable": true,
"description": "The transaction amount.\nℹ️ The amount displayed is always positive as we indicate the direction of the transaction in the `type` parameter.\n"
},
"status": {
"$ref": "#/components/schemas/EnumTransactionStatus"
},
"account": {
"$ref": "#/components/schemas/Account"
},
"balance": {
"type": "number",
"format": "float",
"example": 16907.96,
"nullable": true,
"description": "The balance at the end of the transaction."
},
"category": {
"$ref": "#/components/schemas/EnumTransactionCategory"
},
"currency": {
"type": "string",
"example": "BRL",
"pattern": "^[A-Z]{3}$",
"nullable": true,
"maxLength": 3,
"description": "The three-letter currency code (ISO-4217).\n"
},
"merchant": {
"$ref": "#/components/schemas/TransactionMerchantData"
},
"reference": {
"type": "string",
"example": "8703",
"nullable": true,
"maxLength": 128,
"description": "The reference number of the transaction, provided by the bank."
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-02-09T08:45:50.406032Z",
"description": "The ISO-8601 timestamp of when the data point was last updated in Belvo's database.\n"
},
"value_date": {
"type": "string",
"format": "date",
"example": "2019-10-23",
"pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$",
"nullable": true,
"description": "The date when the transaction occurred, in `YYYY-MM-DD` format."
},
"description": {
"type": "string",
"example": "SEVEN BUDDHAS RFC:XXXXXXXXXX",
"nullable": true,
"description": "The description of transaction provided by the institution. Usually this\nis the text that the end user sees in the online platform.\n"
},
"subcategory": {
"$ref": "#/components/schemas/EnumTransactionSubcategory"
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2019-11-28T10:27:44.813Z",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"observations": {
"type": "string",
"example": "OPTIONAL OBSERVATIONS",
"nullable": true,
"description": "Additional observations provided by the institution on the transaction."
},
"accounting_date": {
"type": "string",
"example": "2019-10-23",
"nullable": true,
"description": "The date when the transaction was processed and accounted for by the institution, in `YYYY-MM-DD` format."
},
"credit_card_data": {
"$ref": "#/components/schemas/TransactionCreditCardData"
},
"internal_identification": {
"type": "string",
"example": "TXpRMU9UQTROMWhZV2xSU1FUazJSMDl",
"pattern": "^[a-zA-Z0-9][a-zA-Z0-9-]{0,99}$",
"nullable": true,
"maxLength": 100,
"minLength": 1,
"description": "The institution's internal identification for the transaction.\n"
}
}
}
TransactionCounterparty
{
"type": "object",
"nullable": true,
"required": [
"type",
"document_number",
"clearing_code",
"agency",
"check_digit",
"number"
],
"properties": {
"type": {
"$ref": "#/components/schemas/EnumTransactionCounterpartyType"
},
"agency": {
"type": "string",
"example": "6272",
"pattern": "^\\d{1,4}$",
"nullable": true,
"maxLength": 4,
"description": "The branch code where the account was opened.\n"
},
"number": {
"type": "string",
"example": "24550245",
"pattern": "^\\d{8,20}$",
"nullable": true,
"maxLength": 20,
"description": "The account number of the product.\n"
},
"check_digit": {
"type": "string",
"example": "7",
"pattern": "[\\w\\W\\s]*",
"nullable": true,
"maxLength": 2,
"description": "The check digit of the account number, if applicable.\n"
},
"clearing_code": {
"type": "string",
"example": "001",
"pattern": "^\\d{3}$",
"nullable": true,
"maxLength": 3,
"description": "The banking clearing code.\n"
},
"document_number": {
"type": "string",
"example": "73677831148",
"pattern": "^\\d{11}$",
"nullable": true,
"maxLength": 11,
"description": "The document number of the representative.\n\n**Note**: \n\nFor Brazil:\n - When the `type` is `INDIVIDUAL`, this is the CPF number.\n - When the `type` is `COMPANY`, this is the CNPJ number.\n"
}
},
"description": "Information regarding the other party of this transaction, if available."
}
TransactionCreditCardBill
{
"type": "object",
"nullable": true,
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "8e9d13c2-af41-4a49-b43e-2da012bd1d11",
"description": "The unique identifier created by Belvo used to reference the current credit card bill.\n\n> **Note**: This field is only returned for 'closed' bills (meaning the billing period has ended and the bill has been emitted). If the billing period is still ongoing, we return `null`.\n"
},
"internal_identification": {
"type": "string",
"example": "92792126019929279212650822221989319252576",
"pattern": "^[a-zA-Z0-9][a-zA-Z0-9-]{0,99}$",
"nullable": true,
"maxLength": 100,
"minLength": 1,
"description": "The institution's internal identifier for the bill.\n\n> **Note**: This field is only returned for 'closed' bills (meaning the billing period has ended and the bill has been emitted). If the billing period is still ongoing, we return `null`.\n"
}
},
"description": "Information regarding the bill that this transaction appears on.\n\nNote: This field is currrently unavailable and will only be available in Q4 2023.\n"
}
TransactionCreditCardData
{
"type": "object",
"nullable": true,
"properties": {
"bill_name": {
"type": "string",
"example": "apr-2020",
"nullable": true,
"description": "The title of the monthly credit card bill the transaction belongs to. The format of the returned value is institution specific, however, some common examples are:\n\n- diciembre-2021\n- dec-2021\n- dec-21\n"
},
"bill_amount": {
"type": "number",
"format": "float",
"example": 300,
"nullable": true,
"description": "The aggregate bill amount, as of `collected_at`."
},
"bill_status": {
"$ref": "#/components/schemas/EnumTransactionBillStatus"
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2019-09-27T13:01:41.941Z",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"previous_bill_total": {
"type": "string",
"example": "9614.30",
"nullable": true,
"description": "The total amount of the previous month's bill, if available."
}
},
"description": "Additional data provided by the institution for credit card transactions."
}
TransactionCreditCardDataOpenFinanceBrazil
{
"type": "object",
"nullable": true,
"required": [
"collected_at",
"bill_name",
"bill_status",
"previous_bill_total",
"bill_amount",
"card_number",
"fee_type",
"fee_type_additional_info",
"credits_type",
"credits_type_additional_info",
"installment_identifier",
"number_of_installments"
],
"properties": {
"fee_type": {
"$ref": "#/components/schemas/EnumTransactionCreditCardDataFeeType"
},
"bill_name": {
"type": "string",
"example": "apr-2020",
"nullable": true,
"description": "The title of the monthly credit card bill the transaction belongs to. The format of the returned value is institution specific, however, some common examples are:\n\n- diciembre-2021\n- dec-2021\n- dec-21\n\n> **Note**: This field is only returned for 'closed' bills (meaning the billing period has ended and the bill has been emitted). If the billing period is still ongoing, we return `null`.\n"
},
"bill_amount": {
"type": "number",
"format": "float",
"example": 300,
"pattern": "^-?\\d{1,15}\\.\\d{2,4}$",
"nullable": true,
"description": "The bill amount, as of `collected_at`. For more information, see `credit_card_bill`."
},
"bill_status": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note:** This field is not applicable for OFDA Brazil and will return `null`.\n"
},
"card_number": {
"type": "string",
"example": "4453",
"pattern": "^[a-zA-Z0-9][a-zA-Z0-9-]{0,99}$",
"maxLength": 100,
"minLength": 1,
"description": "The credit card number.\n\n**Note:** Often, this is just the last four digit of the credit card.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2019-09-27T13:01:41.941Z",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"credits_type": {
"$ref": "#/components/schemas/EnumTransactionCreditCardDataCreditType"
},
"bill_due_date": {
"type": "string",
"format": "date",
"example": "2023-06-17",
"nullable": true,
"description": "The date that the bill is due to be paid, in `YYYY-MM-DD` format.\n\n> **Note**: This field is only returned for 'closed' bills (meaning the billing period has ended and the bill has been emitted). If the billing period is still ongoing, we return `null`.\n"
},
"credit_card_bill": {
"$ref": "#/components/schemas/TransactionCreditCardBill"
},
"previous_bill_total": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note:** This field is not applicable for OFDA Brazil and will return `null`.\n"
},
"installment_identifier": {
"type": "string",
"example": "PARCELA_896",
"pattern": "^[\\w\\W\\s]{0,140}$",
"maxLength": 140,
"description": "An identifier for the installment, according to the institution.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"number_of_installments": {
"type": "integer",
"example": 4,
"maximum": 999,
"nullable": true,
"description": "The total number of installments for the card transaction, if applicable.\n"
},
"fee_type_additional_info": {
"type": "string",
"example": "ATM withdrawal in Curitiba.",
"pattern": "^[\\w\\W\\s]{0,140}$",
"nullable": true,
"maxLength": 140,
"description": "Additional information regarding the fee.\n"
},
"bill_internal_identification": {
"type": "string",
"example": "927921260199292792126508222219893192525A6",
"pattern": "^[a-zA-Z0-9][a-zA-Z0-9-]{0,99}$",
"nullable": true,
"maxLength": 100,
"minLength": 1,
"description": "The institution's internal identifier for the bill.\n\n> **Note**: This field is only returned for 'closed' bills (meaning the billing period has ended and the bill has been emitted). If the billing period is still ongoing, we return `null`.\n"
},
"credits_type_additional_info": {
"type": "string",
"example": "Some additional information.",
"pattern": "^[\\w\\W\\s]{0,140}$",
"nullable": true,
"maxLength": 140,
"description": "Additional information regarding the credit type.\n"
}
},
"description": "Additional data provided by the institution for credit card transactions."
}
TransactionLoanDataCharges
{
"type": "object",
"nullable": true,
"required": [
"type",
"info",
"amount"
],
"properties": {
"info": {
"type": "string",
"example": "Late payment charge.",
"pattern": "^[\\w\\W\\s]{0,140}$",
"maxLength": 140,
"description": "Additional information regarding the charge `type`.\n"
},
"type": {
"type": "string",
"example": "MULTA_ATRASO_PAGAMENTO",
"pattern": "^[\\w\\W\\s]{0,140}$",
"maxLength": 140,
"description": "The type of charge.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network when the `charges` field is present\n"
},
"amount": {
"type": "number",
"format": "float",
"example": 8903.77,
"pattern": "^-?\\d{1,15}\\.\\d{2,4}$",
"description": "The amount of the charge.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network when the `charges` field is present\n"
}
},
"description": "Details regarding the charges associated with this payment. Only applicable when `is_detached` = `true`."
}
TransactionLoanDataFees
{
"type": "object",
"nullable": true,
"required": [
"name",
"code",
"amount"
],
"properties": {
"code": {
"type": "string",
"example": "aval_bem",
"pattern": "^[\\w\\W\\s]{0,140}$",
"maxLength": 140,
"description": "The institution's code for the fee.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network when the `fees` field is present.\n"
},
"name": {
"type": "string",
"example": "Reavaliação periódica do bem",
"pattern": "^[\\w\\W\\s]{0,140}$",
"maxLength": 140,
"description": "The name of the fee.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network when the `fees` field is present.\n"
},
"amount": {
"type": "number",
"format": "float",
"example": 8903.77,
"pattern": "^-?\\d{1,15}\\.\\d{2,4}$",
"nullable": true,
"description": "The amount of the fee.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network when the `fees` field is present.\n"
}
},
"description": "Details regarding the fees associated with this payment. Only applicable when `is_detached` = `true`."
}
TransactionLoanDataOpenFinanceBrazil
{
"type": "object",
"nullable": true,
"required": [
"is_detached",
"installment_it",
"fees",
"charges"
],
"properties": {
"fees": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TransactionLoanDataFees"
},
"description": "Details regarding the fees associated with this payment. Only applicable when `is_detached` = `true`."
},
"charges": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TransactionLoanDataCharges"
},
"minItems": 0,
"description": "Details regarding the charges associated with this payment. Only applicable when `is_detached` = `true`."
},
"is_detached": {
"type": "boolean",
"example": true,
"description": "Boolean to indicate whether or not this loan payment was part of the original payment schedule.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"installment_id": {
"type": "string",
"example": "WGx0aExYcEJMVm93TFRsZFcyRXRla0V0V2pBdE9Wd3RYWH",
"pattern": "^[a-zA-Z0-9][a-zA-Z0-9-]{0,99}$",
"nullable": true,
"maxLength": 100,
"minLength": 1,
"description": "The institution's unique ID for this payment installment.\n"
}
},
"description": "Information regarding the loan transactional data, if applicable."
}
TransactionMerchantData
{
"type": "object",
"nullable": true,
"properties": {
"logo": {
"type": "string",
"example": "https://logo.clearbit.com/asesor-contable.es",
"nullable": true,
"description": "The URL to the merchant's logo."
},
"website": {
"type": "string",
"example": "https://merchants-r-us.com",
"nullable": true,
"description": "The URL to the merchant's website."
},
"merchant_name": {
"type": "string",
"example": "Merchants R Us Global",
"description": "The name of the merchant."
}
},
"description": "Additional data regarding the merchant involved in the transaction.\nWe only return merchant information for new transactions made from *checking* or *credit card* accounts.\n> **Get merchant information**\n We retrieve the merchant information for a transaction as part of our [Transaction categorization](https://developers.belvo.com/docs/banking#categorizing-transactions) product, turning raw data into actionable insights. To enable this product, just [reach out](https://belvo.com/contact/?utm_source=documentation) to us, and we'll get right to it.\n"
}
TransactionOpenFinanceBrazil
{
"type": "object",
"title": "Transaction (OFDA Brazil)",
"required": [
"id",
"internal_identification",
"account",
"collected_at",
"created_at",
"value_date",
"accounting_date",
"amount",
"local_currency_amount",
"balance",
"currency",
"description",
"observations",
"merchant",
"category",
"subcategory",
"reference",
"type",
"status",
"credit_card_data",
"counterparty",
"loan_data",
"payment_type",
"operation_type",
"operation_type_additional_info",
"mcc"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "076c66e5-90f5-4e01-99c7-50e32f65ae42",
"description": "Belvo's unique ID for the transaction."
},
"mcc": {
"type": "integer",
"format": "int32",
"example": 5137,
"pattern": "^[0-9]{4}$",
"nullable": true,
"description": "The four-digit (ISO-18245 compliant) Merchant Category Code (MCC) for the transaction. This field is only applicable for credit card transactions.\n"
},
"type": {
"$ref": "#/components/schemas/EnumTransactionType"
},
"amount": {
"type": "number",
"format": "float",
"example": 2145.45,
"pattern": "^\\d{1,15}\\.\\d{2,4}$",
"description": "The transaction amount.\nℹ️ The amount displayed is always positive as we indicate the direction of the transaction in the `type` parameter.\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"status": {
"$ref": "#/components/schemas/EnumTransactionStatus"
},
"account": {
"$ref": "#/components/schemas/AccountOpenFinanceBrazil"
},
"balance": {
"type": "number",
"format": "float",
"example": null,
"nullable": true,
"description": "**Note:** This field is not applicable for OF Brazil and will return null.\n"
},
"category": {
"$ref": "#/components/schemas/EnumTransactionCategory"
},
"currency": {
"type": "string",
"example": "BRL",
"pattern": "^[A-Z]{3}$",
"nullable": true,
"maxLength": 3,
"description": "The three-letter currency code (ISO-4217).\n"
},
"merchant": {
"$ref": "#/components/schemas/TransactionMerchantData"
},
"loan_data": {
"$ref": "#/components/schemas/TransactionLoanDataOpenFinanceBrazil"
},
"reference": {
"type": "string",
"example": null,
"nullable": true,
"maxLength": 128,
"description": "**Note:** This field is not applicable for OF Brazil and will return null.\n"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-02-09T08:45:50.406032Z",
"description": "The ISO-8601 timestamp of when the data point was last updated in Belvo's database.\n"
},
"value_date": {
"type": "string",
"format": "date",
"example": "2019-10-23",
"pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$",
"description": "The date when the transaction occurred, in `YYYY-MM-DD` format, in `YYYY-MM-DD` format.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"description": {
"type": "string",
"example": "SEVEN BUDDHAS RFC:XXXXXXXXXX",
"nullable": true,
"description": "The description of transaction provided by the institution. Usually this\nis the text that the end user sees in the online platform.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"subcategory": {
"$ref": "#/components/schemas/EnumTransactionSubcategory"
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2019-11-28T10:27:44.813Z",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"counterparty": {
"$ref": "#/components/schemas/TransactionCounterparty"
},
"observations": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note:** This field is not applicable for OF Brazil and will return null.\n"
},
"payment_type": {
"$ref": "#/components/schemas/EnumTransactionPaymentType"
},
"transacted_at": {
"type": "string",
"format": "date-time",
"example": "2024-02-20T12:29:03.374Z",
"pattern": "(^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])T(?:[01]\\d|2[0123]):(?:[012345]\\d):(?:[012345]\\d)\\.(?:[0-9]){3}Z$)",
"description": "The ISO-8601 timestamp of when the transaction occurred (in the UTC timezone).\n\n> **Note:** For transactions that occurred before 31.01.2024, the timestamp may only indicate the day (for example, `2016-01-29T00:00:00.000Z`). However, transactions that occurred after this date must include the date and time (`2024-02-20T12:29:03.374Z`).\n\n> **Institutions not abiding by this format:**\n> Some institutions may not provide the exact time of the transaction. In this case, the timestamp will be set to `00:00:00.000Z`.\n> Belvo has identified the following institutions as not abiding by the regulation and have raised the issue with regulators: Bradesco, Itau, and Sicoob.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network for **credit card and checking account transactions**.\n"
},
"operation_type": {
"type": "string",
"example": "TRANSFERENCIA_MESMA_INSTITUICAO",
"pattern": "^[A-Za-z_]{0,50}$",
"maxLength": 50,
"description": "The type of transaction. For example, a PIX payment or a deposit.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network for **non-loan account transactions**.\n"
},
"accounting_date": {
"type": "string",
"example": "2019-10-23",
"nullable": true,
"description": "The date when the transaction was processed and accounted for by the institution, in `YYYY-MM-DD` format.\n> **Non-nullable:** A value must be returned by Brazil's open finance network for **credit card transactions**."
},
"credit_card_data": {
"$ref": "#/components/schemas/TransactionCreditCardDataOpenFinanceBrazil"
},
"local_currency_amount": {
"type": "number",
"format": "float",
"example": 7623.64,
"pattern": "^\\d{1,15}\\.\\d{2,4}$",
"nullable": true,
"maxLength": 20,
"description": "The value of the transaction in the local currency.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network for **credit card transactions**.\n"
},
"internal_identification": {
"type": "string",
"example": "TXpRMU9UQTROMWhZV2xSU1FUazJSMDl",
"pattern": "^[a-zA-Z0-9][a-zA-Z0-9-]{0,99}$",
"maxLength": 100,
"minLength": 1,
"description": "The institution's internal identification for the transaction.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n"
},
"operation_type_additional_info": {
"type": "string",
"example": "Internal transfer.",
"pattern": "^\\S[\\s\\S]*$",
"nullable": true,
"maxLength": 140,
"description": "Additional information regarding the `operation_type`, if applicable.\n"
}
}
}
TransactionsCreateLinkTransactions201Response
{
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/Transaction"
},
{
"$ref": "#/components/schemas/TransactionOpenFinanceBrazil"
}
]
}
}
TransactionsCreateLinkTransactions400Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
}
]
}
}
TransactionsCreateLinkTransactions401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
TransactionsCreateLinkTransactions408Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RequestTimeoutError"
},
"title": "Request Timeout",
"description": "Belvo has a limit regarding the time it takes to log in, retrieve account data, and log out. A timeout occurs when there is a very high amount of data and everything could not be obtained within the allotted time.\n \n"
}
TransactionsCreateLinkTransactions428Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenRequiredResponse"
}
}
TransactionsCreateLinkTransactions500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
TransactionsCreateLinkTransactionsResponse
{
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/Transaction"
},
{
"$ref": "#/components/schemas/TransactionOpenFinanceBrazil"
}
]
}
}
TransactionsGetDetails401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
TransactionsGetDetails404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
TransactionsGetDetailsResponse
{
"oneOf": [
{
"$ref": "#/components/schemas/Transaction"
},
{
"$ref": "#/components/schemas/TransactionOpenFinanceBrazil"
}
]
}
TransactionsListAllTransactions401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
TransactionsListAllTransactionsResponse
{
"oneOf": [
{
"$ref": "#/components/schemas/TransactionsPaginatedResponse"
},
{
"$ref": "#/components/schemas/TransactionsPaginatedResponseOpenFinanceBrazil"
}
]
}
TransactionsPaginatedResponse
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/common_pagination_properties"
},
{
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Transaction"
},
"description": "Array of transaction objects (Multi-Region)."
}
}
}
],
"title": "Transactions Standard (Multi-Region)"
}
TransactionsPaginatedResponseOpenFinanceBrazil
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/common_pagination_properties"
},
{
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TransactionOpenFinanceBrazil"
},
"description": "Array of transaction objects (OFDA Brazil)."
}
}
}
],
"title": "Transactions (OFDA Brazil)"
}
TransactionsRemoveById404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
TransactionsRemoveByIdResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
TransactionsRequest
{
"type": "object",
"required": [
"link",
"date_from",
"date_to"
],
"properties": {
"link": {
"type": "string",
"format": "uuid",
"example": "2ccd5e15-194a-4a19-a45a-e7223c7e6717",
"description": "The `link.id` that you want to get information for."
},
"token": {
"type": "string",
"example": "1234ab",
"description": "The OTP token generated by the bank."
},
"account": {
"type": "string",
"format": "uuid",
"example": "d4617561-1c01-4b2f-83b6-a594f7b3bc57",
"description": "If provided, we return transactions only from this account."
},
"date_to": {
"type": "string",
"example": "2020-10-05",
"pattern": "[0-9]{4}-[0-9]{2}-[0-9]{2}",
"description": "The date you want to stop getting transactions for, in `YYYY-MM-DD` format.\n\n\n⚠️ The value of `date_to` cannot be greater than today's date (in other words, no future dates).\n"
},
"date_from": {
"type": "string",
"example": "2020-08-05",
"pattern": "[0-9]{4}-[0-9]{2}-[0-9]{2}",
"description": "The date from which you want to start getting transactions for, in `YYYY-MM-DD` format.\n\n\n⚠️ The value of `date_from` cannot be greater than `date_to`.\n"
},
"save_data": {
"type": "boolean",
"default": true,
"description": "Indicates whether or not to persist the data in Belvo. By default, this is set to `true` and we return a 201 Created response.\n\nWhen set to `false`, the data won't be persisted and we return a 200 OK response.\n"
}
}
}
TransactionsResumeRetrieveSession201Response
{
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/Transaction"
},
{
"$ref": "#/components/schemas/TransactionOpenFinanceBrazil"
}
]
}
}
TransactionsResumeRetrieveSession400Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
}
]
}
}
TransactionsResumeRetrieveSession401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
TransactionsResumeRetrieveSession408Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RequestTimeoutError"
},
"title": "Request Timeout",
"description": "Belvo has a limit regarding the time it takes to log in, retrieve account data, and log out. A timeout occurs when there is a very high amount of data and everything could not be obtained within the allotted time.\n \n"
}
TransactionsResumeRetrieveSession428Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenRequiredResponse"
}
}
TransactionsResumeRetrieveSession500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
TransactionsResumeRetrieveSessionResponse
{
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/Transaction"
},
{
"$ref": "#/components/schemas/TransactionOpenFinanceBrazil"
}
]
}
}
UnauthorizedError
{
"type": "object",
"title": "Unauthorized Error",
"properties": {
"code": {
"type": "string",
"example": "authentication_failed",
"description": "A unique error code (`authentication_failed`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle <a href=\"https://developers.belvo.com/docs/belvo-api-errors#401-authentication_failed\" target=\"_blank\">401 authentication_failed errors</a>.\n"
},
"message": {
"type": "string",
"example": "Invalid Secret Keys",
"description": "A short description of the error. \n\n\nFor `authentication_failed` errors, the description is:\n\n - `Invalid Secret Keys`.\n"
},
"request_id": {
"type": "string",
"example": "9e7b283c6efa449c9c028a16b5c249fb",
"pattern": "[a-f0-9]{32}",
"description": "A 32-character unique ID of the request (matching a regex pattern of: `[a-f0-9]{32}`). Provide this ID when contacting the Belvo\nsupport team to accelerate investigations.\n"
}
},
"description": "This error occurs when you try to make an API call using incorrect Belvo API credentials (either your secret key or secret password, or both, are incorrect).\n"
}
UnconfirmedLinkError
{
"type": "object",
"title": "Unconfirmed Link",
"properties": {
"code": {
"type": "string",
"example": "unconfirmed_link",
"description": "A unique error code (`unconfirmed_link`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle <a href=\"https://developers.belvo.com/docs/belvo-api-errors#400-unconfirmed_link\" target=\"_blank\">400 unconfirmed_link errors</a>.\n"
},
"message": {
"type": "string",
"example": "The link creation has not been completed yet",
"description": "A short description of the error. \n\n\nFor `unconfirmed_link` errors, the description is:\n \n - `The link creation has not been completed yet`.\n"
},
"request_id": {
"type": "string",
"example": "9e7b283c6efa449c9c028a16b5c249fb",
"pattern": "[a-f0-9]{32}",
"description": "A 32-character unique ID of the request (matching a regex pattern of: `[a-f0-9]{32}`). Provide this ID when contacting the Belvo\nsupport team to accelerate investigations.\n"
}
},
"description": "This error occurs when you try to access a link that was paused previously (and as such is not active now).\n\nA Link's status is set to `unconfirmed_link` when your user has not completed the Link creation process successfully (for example, they might not provide a valid MFA token).\n"
}
UnexpectedError
{
"type": "object",
"title": "Unexpected Error",
"properties": {
"code": {
"type": "string",
"example": "unexpected_error",
"description": "A unique error code (`unexpected_error`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle <a href=\"https://developers.belvo.com/docs/belvo-api-errors#500-unexpected_error\" target=\"_blank\">500 unexpected_error errors</a>.\n"
},
"message": {
"type": "string",
"example": "Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution",
"description": "A short description of the error. \n\n\nFor `unexpected_error` errors, the description is:\n \n - `Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution`.\n"
},
"request_id": {
"type": "string",
"example": "9e7b283c6efa449c9c028a16b5c249fb",
"pattern": "[a-f0-9]{32}",
"description": "A 32-character unique ID of the request (matching a regex pattern of: `[a-f0-9]{32}`). Provide this ID when contacting the Belvo\nsupport team to accelerate investigations.\n"
}
},
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n"
}
UnsupportedOperationError
{
"type": "object",
"title": "Unsupported Operation",
"properties": {
"code": {
"type": "string",
"example": "unsupported_operation",
"description": "A unique error code (`unsupported_operation`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle <a href=\"https://developers.belvo.com/docs/belvo-api-errors#400-unsupported_operation\" target=\"_blank\">400 unsupported_operation errors</a>.\n"
},
"message": {
"type": "string",
"example": "The resource you are trying to access is not supported by this institution",
"description": "A short description of the error. \n\n\nFor `unsupported_operation` errors, the description is:\n \n - `The resource you are trying to access is not supported by this institution`.\n"
},
"request_id": {
"type": "string",
"example": "9e7b283c6efa449c9c028a16b5c249fb",
"pattern": "[a-f0-9]{32}",
"description": "A 32-character unique ID of the request (matching a regex pattern of: `[a-f0-9]{32}`). Provide this ID when contacting the Belvo\nsupport team to accelerate investigations.\n"
}
},
"description": "This error occurs when you try to access some data operation that Belvo does not support for an institution. For example, trying to access the Balances resource for fiscal institutions.\n"
}
ValidationError
{
"type": "object",
"title": "Validation Error",
"properties": {
"code": {
"type": "string",
"example": "required",
"description": "A unique error code (`null`, `does_not_exist`, `required`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle:\n - <a href=\"https://developers.belvo.com/docs/belvo-api-errors#400-blank\" target=\"_blank\">400 blank errors</a>\n - <a href=\"https://developers.belvo.com/docs/belvo-api-errors#400-null\" target=\"_blank\">400 null errors</a>\n - <a href=\"https://developers.belvo.com/docs/belvo-api-errors#400-does_not_exist\" target=\"_blank\">400 does_not_exist errors</a>\n - <a href=\"https://developers.belvo.com/docs/belvo-api-errors#400-required\" target=\"_blank\">400 required errors</a>\n"
},
"field": {
"type": "string",
"example": "link",
"nullable": true,
"description": "Name of the field where the error was encountered.\n"
},
"message": {
"type": "string",
"example": "This field is required.",
"description": "A short description of the error. \n\n\nFor validation errors, the description can be (among others):\n \n - `This field is required.`\n - `Object with name=narnia does not exist.`\n - `This field may not be null.`\n - `This field may not be blank.`\n"
},
"request_id": {
"type": "string",
"example": "9e7b283c6efa449c9c028a16b5c249fb",
"pattern": "[a-f0-9]{32}",
"description": "A 32-character unique ID of the request (matching a regex pattern of: `[a-f0-9]{32}`). Provide this ID when contacting the Belvo\nsupport team to accelerate investigations.\n"
}
},
"description": "This error occurs when make a request that does not include all the required fields or includes invalid data.\n"
}
common_pagination_properties
{
"type": "object",
"properties": {
"next": {
"type": "string",
"format": "uri",
"example": "https://sandbox.belvo.com/api/{endpoint}/?page=2",
"nullable": true,
"description": "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`.\n\nIn 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`).\n"
},
"count": {
"type": "integer",
"format": "int32",
"example": 130,
"description": "The total number of results in your Belvo account."
},
"previous": {
"type": "string",
"format": "uri",
"example": null,
"nullable": true,
"description": "The URL to the previous page of results. If there is no previous page, the\nvalue is `null`.\n"
}
}
}