{
  "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"
}

{
  "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
}

{
  "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
}

{
  "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"
}

{
  "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"
    }
  }
}

{
  "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."
    }
  }
}

{
  "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."
}

{
  "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."
}

{
  "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"
}

{
  "type": "array",
  "items": {
    "anyOf": [
      {
        "$ref": "#/components/schemas/UnauthorizedError"
      },
      {
        "$ref": "#/components/schemas/401_consent_without_accounts_error"
      }
    ]
  }
}

{
  "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`."
    }
  }
}

{
  "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"
    }
  }
}

{
  "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."
    }
  }
}

{
  "type": "array",
  "items": {
    "anyOf": [
      {
        "$ref": "#/components/schemas/UnauthorizedError"
      },
      {
        "$ref": "#/components/schemas/401_consent_without_accounts_error"
      }
    ]
  }
}

{
  "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"
}

{
  "anyOf": [
    {
      "$ref": "#/components/schemas/TaxStatusSat"
    },
    {
      "$ref": "#/components/schemas/TaxStatusDian"
    }
  ]
}

{
  "anyOf": [
    {
      "$ref": "#/components/schemas/TaxStatusSat"
    },
    {
      "$ref": "#/components/schemas/TaxStatusDian"
    }
  ]
}

{
  "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"
      }
    ]
  }
}

{
  "type": "array",
  "items": {
    "anyOf": [
      {
        "$ref": "#/components/schemas/UnauthorizedError"
      },
      {
        "$ref": "#/components/schemas/401_consent_without_accounts_error"
      }
    ]
  }
}

{
  "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"
}

{
  "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"
}

{
  "anyOf": [
    {
      "$ref": "#/components/schemas/TaxStatusSat"
    },
    {
      "$ref": "#/components/schemas/TaxStatusDian"
    }
  ]
}

{
  "type": "array",
  "items": {
    "anyOf": [
      {
        "$ref": "#/components/schemas/UnauthorizedError"
      },
      {
        "$ref": "#/components/schemas/401_consent_without_accounts_error"
      }
    ]
  }
}

{
  "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"
}

{
  "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"
}

{
  "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."
        }
      }
    }
  ]
}

{
  "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"
    }
  }
}

{
  "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"
    }
  }
}

{
  "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"
    }
  }
}

{
  "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."
    }
  }
}

{
  "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."
}

{
  "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."
}

{
  "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"
}

{
  "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."
}

{
  "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"
}

{
  "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"
    }
  }
}

{
  "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."
}

{
  "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"
}

{
  "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."
}

{
  "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."
}

{
  "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`."
}

{
  "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`."
}

{
  "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."
}

{
  "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"
}

{
  "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"
    }
  }
}

{
  "type": "array",
  "items": {
    "oneOf": [
      {
        "$ref": "#/components/schemas/Transaction"
      },
      {
        "$ref": "#/components/schemas/TransactionOpenFinanceBrazil"
      }
    ]
  }
}

{
  "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"
      }
    ]
  }
}

{
  "type": "array",
  "items": {
    "anyOf": [
      {
        "$ref": "#/components/schemas/UnauthorizedError"
      },
      {
        "$ref": "#/components/schemas/401_consent_without_accounts_error"
      }
    ]
  }
}

{
  "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"
}

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/TokenRequiredResponse"
  }
}