# XML web service v4.1: changes from v4

Sep 30, 2026 · @Vitaly

## Overview

Version 4.1 adds optional conversion of monetary values into a currency of your choice, a probability of default in the credit opinion, detailed trademark data and an extension point for future fields. All additions are optional. The namespace is unchanged: `http://infoproff.com/`.

| Schema | v4 | v4.1 |
| --- | --- | --- |
| Report | `.../v4/report.xsd` | `.../v4.1/report.xsd` |
| Request | `.../v4/order.xsd` | `.../v4.1/order.xsd` |
| Credit opinion calculator | `.../v4/creditopinioncalculator.xsd` | unchanged |

**Compatibility.** We kept the changes to the schema to a minimum. Any report that is valid against the v4 schema is also valid against the v4.1 schema. However, a v4.1 report is not valid against the v4 schema. It can contain elements that do not exist in v4, for example `probability_of_default` and `converted`.

If you validate responses against the XML schema, switch validation to the v4.1 schema when you move to the v4.1 service.

## Main changes

1. **Conversion into another currency.** A new parameter `currency` is added to the report request. At the end of each record with monetary values, a `converted` element appears. It contains the exchange rate and the amounts converted into the selected currency.
2. **Trademarks.** New elements are added: owner, status, registration number, NICE classes, designated countries, registration expiry date and the logo in base64 format.
3. **Probability of default.** A new element `probability_of_default` is added to the credit opinion.
4. **Relaxed schema constraints.** Some elements became optional, and the minimum length of registration codes is reduced to one character. This allows reports with incomplete data to pass schema validation.
5. **Schema extensibility.** A new element `extension` is added. It allows new sections to be added without a new schema version.

## Request: target currency

`GetReportRequest` has a new optional element `currency`, placed after `lang`. The value is an ISO 4217 currency code in upper case, for example `USD`. The schema rejects lower-case or incomplete codes (`usd`, `US`).

```xml
<GetReportRequest>
    <order_id>119641</order_id>
    <lang>en</lang>
    <currency>USD</currency>
</GetReportRequest>
```

Without `currency`, or with `xsi:nil="true"`, the report contains original currencies only, as in v4.

## Currency conversion

If the request contains `currency`, each monetary value stays in its original element and original currency. A `converted` element with the converted values is added as the last child of the same parent. The child elements of `converted` have the same names as the original elements.

```xml
<item>
    <issued_capital>1612640</issued_capital>
    ...
    <start_date>2020-09-11</start_date>
    ...
    <converted currency="USD" scale="1" rate="1.1812" rate_date="2020-09-11"
               rate_source="ECB" src_currency="EUR">
        <issued_capital>1904850.37</issued_capital>
    </converted>
</item>
```

| Attribute | Meaning |
| --- | --- |
| `currency` | Target currency (ISO 4217) |
| `src_currency` | Original currency of the values |
| `rate` | Cross rate: units of the target currency per unit of the original currency |
| `rate_date` | Date of the rate actually applied (the nearest available to the date of the original data) |
| `rate_source` | Source of the rate: `ECB`, `other` or `same` (the currencies are equal, rate `1`) |
| `scale` | Scale of the converted values: `1`, `1000`, `1000000` or `1000000000` |
| `id`, `rate_ref` | Link between the rate and the values in financial statements (see below) |

Converted value (the original scale is taken from the original element):

```latex
\text{converted} = \frac{\text{original} \times \text{original scale} \times \text{rate}}{\text{scale}}
```

`converted` is omitted if there is nothing to convert or no rate is found. If the original currency equals the target currency, `converted` is present with rate `1` and source `same`.

`negative_information/debts/item` can contain two `converted` elements. The first one contains `amount` and `remainder` in the `currency` currency, and also `penalty` if `penalty_currency` equals `currency` or is not specified. The second one contains `penalty` and is present if `penalty_currency` differs from `currency`.

**Financial statements.** Each `position` contains `<converted rate_ref="..."><value>...</value></converted>` without rate attributes. The rate is given once per statement, in an empty `converted` element with the matching `id` at the end of `financial_statement`. The `id` is valid only within one report. The value of `id` can change on the next download.

```xml
<position>
    <position_code>1000</position_code>
    <value>161047000.00</value>
    <converted rate_ref="fx_fs_45c963c5"><value>197620773.70</value></converted>
</position>
...
<converted id="fx_fs_45c963c5" currency="USD" scale="1" rate="1.2271"
           rate_date="2020-12-31" rate_source="ECB" src_currency="EUR"/>
```

Positions of the document of type "Key Ratios" are not converted, because they contain non-monetary values. The exception is Working capital.

**Where conversion appears**

| Report element | Converted values |
| --- | --- |
| `summary/credit_rating_limit` | `credit_rating_limit` |
| `summary/latest_turnovers/item` | `value` |
| `credit_opinions/item` | `credit_limit`, `latest_turnover_range` |
| `general_data/capital_data/item` | `issued_capital`, `share_value`, `authorized_capital`, `paid_amount` |
| `shareholders/item` | `share_amount` |
| `subsidiaries_data/item` | `share_book_value` |
| `export_import_data/*/item`, `.../details/item` | `total_amount`, `amount` |
| `assets_data/real_estate_data/item` | `value` |
| `assets_data/vehicles/item` | `value` |
| `commercial_pledge_data/item/pledge_amounts/item` | `pledge_amount` |
| `negative_information/litigations/item` | `amount_of_claim` |
| `negative_information/debts/item` | `amount`, `remainder`, `penalty` |
| `financial_statements_data/financial_statement` | position `value` |
| `paid_taxes/item` | `amount` |
| `tenders/item` | `amount` |

## Trademarks

`general_data/trade_names_data/item` now contains trademark registration data. All new elements are added as optional for compatibility with the v4 schema. They are placed between `name` and the dates.

| Element | Content |
| --- | --- |
| `owner_name` | Trademark owner |
| `status` | Registration status, with the `key` and `lang` attributes |
| `number` | Registration number |
| `nice_classification/class` | NICE classes, in the order of the source |
| `designations/item/country_code` | Countries where the trademark is designated, ISO 3166 alpha-3 |
| `expiry_date` | Registration expiry date |
| `logo` | Trademark image in base64, with the `mime_type` attribute (for example, `image/jpeg`) |
| `extension` | Additional elements (see "Extension") |

## Credit opinion: probability of default

`credit_opinions/item` has a new optional element `probability_of_default`, placed after `rating_description`. It is the probability of payment default within the next 12 months, in percent, with two decimal places (`13.36` means 13.36%).

```xml
<credit_rating>B</credit_rating>
<rating_description key="7603" lang="en">Normal risk.</rating_description>
<probability_of_default>13.36</probability_of_default>
<credit_limit>3000000</credit_limit>
```

## Relaxed constraints

Some elements that were required in v4 can now be absent or empty. This keeps reports with incomplete source data valid. If your parser expects these elements, take their possible absence into account.

| Element | v4 | v4.1 |
| --- | --- | --- |
| `country_economic_overview/data_transparency_index` | Required | Optional |
| `country_economic_overview/country_development_indicators` | Required | Optional; omitted if there are no indicators for the country |
| `country_economic_overview/economic_forecast` | Required | Optional; omitted if no forecast was published by the report date |
| `assets_data/vehicles/item/value` | Required | Optional; omitted if the value is unknown |
| `tenders/item/amount` | Required, not nillable | Can be `xsi:nil="true"` if the amount is unknown |
| `registration_code`, `registration_data/item/code` | 3 to 64 characters | 1 to 64 characters |

## Extension

The new optional element `extension` allows us to add fields without releasing a new schema version. It is the last child element of `report` and of `trade_names_data/item`.

```xml
<extension>
    <mark_type>figurative</mark_type>
    <application>
        <number>2021/04512</number>
        <date>2021-04-14</date>
    </application>
</extension>
```

The schema does not validate the content of `extension`, and nesting of any depth is allowed. We announce and document the fields that appear there separately. Skip elements that you do not recognise.