Retrieving multicurrency information

Multicurrency reserves

Currency information is part of the default response for the GET /reserves endpoint, whether or not multicurrency has been enabled.

The following is a snippet of the response payload for a GET /reserves for a multicurrency reserve. Currency information appears in bold. Note the following:

The default currency for this instance of ClaimCenter is US dollars (usd).
- This is specified in the reportingAmount.currency field.
The claim's currency is US dollars (usd).
- This is specified in the claimAmount.currency field.
The reserving currency is British pounds (gbp).
- This is specified in the reservingAmount.currency field.
The reserve transaction is British pounds (gbp).
- Every reserve transaction consists of one of more line items. Both transactions and line items have currency values, but each is stored in different database tables. These currency values must always be explicitly stated and must always be the same, regardless of whether or not multicurrency is enabled.
- The currency for the transaction is specified in the parent currency field.
- The currency for each associated line item is specified in the lineItems.transactionAmount.currency field(s).

GET /claims/cc:SHRyrnPstWtq7HZ3nxLCC/reserves/cc:SojI8VceTmdlXU6k1pqOB

{
    "data": {
        "attributes": {
            "currency": {
                "code": "gbp",
                "name": "GBP"
            },
            "id": "cc:SojI8VceTmdlXU6k1pqOB",
            "lineItems": [
                {
                    "claimAmount": {
                        "amount": "1920.82",
                        "currency": "usd"
                    },
                    "id": "cc:SyLnqtJEkcI4X4WaFXbgP",
                    "reportingAmount": {
                        "amount": "1920.82",
                        "currency": "usd"
                    },
                    "reservingAmount": {
                        "amount": "1000.00",
                        "currency": "gbp"
                    },
                    "transactionAmount": {
                        "amount": "1000.00",
                        "currency": "gbp"
                    }
                }
            ],
            "reserveLine": {
                "costCategory": {
                    "code": "body",
                    "name": "Auto body"
                },
                "costType": {
                    "code": "claimcost",
                    "name": "Claim Cost"
                },
                "exposure": {
                    "displayName": "(1) 1st Party Vehicle - Allen Robertson",
                    "id": "cc:SfXS3Pey0Al29PI13KC5C",
                },
                "reservingCurrency": {
                    "code": "gbp",
                    "name": "GBP"
                }
            }
        }
    }
}

There is also a currency value specified in the reserveLine.reservingCurrency field. This field identifies the currency of the associated reserve line. A reserve line is a category that can be applied to a financial transactions. For a given exposure, each reserve line is uniquely identified by its cost type, cost category, and currency.

Multicurrency checks

Currency information is part of the default response for the GET /checks endpoint, whether or not multicurrency has been enabled.

The following is a snippet of the response payload for a GET /checks for a multicurrency check. Currency information appears in bold. Note the following:

The default currency for this instance of ClaimCenter is US dollars (usd).
- This is specified in the reportableAmount.currency field.
The reserve currency is British pounds (gbp).
- The reserving currency is British pounds (gbp). This is indicated in the display names of the payments. To see the actual currency code, you would need to GET the individual payment and inspect its reserve line.
The check currency is Euros (eur).
- This is specified in the grossAmount.currency field.

GET /claims/cc:SHRyrnPstWtq7HZ3nxLCC/checks/cc:SqK_OuzG48empV3wtydTH

{
    "data": {
        "attributes": {
            "grossAmount": {
                "amount": "20.00",
                "currency": "eur"
            },
            "id": "cc:SqK_OuzG48empV3wtydTH",
            "paymentMethod": {
                "code": "check",
                "name": "Check"
            },
            "payments": [
                {
                    "displayName": "(1) 1st Party Vehicle - Allen Robertson; 
                            Claim Cost/Auto body; GBP; Awaiting submission",
                    "id": "cc:SXGn6K7Zeidw8MAkv2sGx",
                    "type": "Payment",
                }
            ],
            "reportableAmount": {
                "amount": "20.00",
                "currency": "eur"
            }
        }
    }
}

Exchange rate information for transactions

In a multicurrency instance of ClaimCenter, ClaimCenter uses foreign exchange rates to convert amounts between the various currencies a claim may use. Every transaction stores two fundamental pieces of information about the exchange rates:

The rate itself (a numeric value, such as 1.2)
The type of rate (such as market or corporate)

Exchange rate schemas

The ExchangeRate data model

For ClaimCenter releases up to and including 2024.07 (Kufri), ClaimCenter had a single data model for storing exchange rates - the ExchangeRate data model . This includes the ExchangeRate and ExchangeRateSet entities. Exchange rates stored in these entities are not part of the Claim graph.

Exchange rates in the ExchangeRate data model could be one of two types. The type of rate is specified on the ExchangeRateSet entity. It has a MarketRates Boolean field.

When set to true, the rate to be used is a "market rate". It is fetched automatically.
When set to false, the rate is a "custom rate". It must be stated explicitly.

The ExchangeRateInUse data model

For ClaimCenter releases 2024.11 (Las Leñas) and after, ClaimCenter has two data models for storing exchange rates. ClaimCenter continues to have the ExchangeRate data model, and this is used to manage exchange rates created before Las Leñas. But there is also a second data model, the ExchangeRateInUse data model.

The ExchangeRateInUse data model includes a number of tables whose name ends in "ExchangeRateInUse", such as ClaimToReportingExchangeRateInUse. All of the entities delegate to the ExchangeRateInUseDelegate delegate, which implements the FXRate interface. Exchange rates stored in these entities are a part of the Claim graph.

The type of rate is specified in the ExchangeRateInUseDelegate delegate and therefore is part of every entity in the data model. It is specified by a Market field which is a typekey to the FXRateMarket typelist. In the base configuration, this typefield includes three typecodes: market, corporate, and manual.

For information on how to configure which data model ClaimCenter uses for newly created exchange rates, refer to the Configuration Guide.

Cloud API compatibility with exchange rate data models

To support both approaches to storing exchange rate data, as of 2024.11 (Las Leñas), Cloud API for ClaimCenter has two schemas for exchange rates:

TransactionExchangeRate, which captures exchange rate type information for exchange rates stored in the ExchangeRate data model.
ExchangeRateInUse, which captures exchange rate type information for exchange rates stored in the ExchangeRateInUse data model.

Both schemas have a rate field to identify the rate and a market field to identify the rate type.

In the TransactionExchangeRate schema, the market field is a Boolean.
In the ExchangeRateInUse schema, the market field is a typekey field whose values are set to typecodes from the FXRateMarket typelist

Both schemas are referenced by the Transaction schema. There are three pairs of fields. The fields start with the same name, but the fields that use the ExchangeRateInUse schema end in "InUse".

The following fields use the TransactionExchangeRate schema:
- claimToReportingExchangeRate
- transToClaimExchangeRate
- transToReservingExchangeRate
The following fields use the ExchangeRateInUse schema:
- claimToReportingExchangeRateInUse
- transToClaimExchangeRateInUse
- transToReservingExchangeRateInUse

Exchange rate schemas and GETs

Whenever you GET transaction information, for each transaction, Cloud API uses the schema that corresponds to the data model used to store the transaction. For more information on how ClaimCenter determines which model to use, refer to the Configuration Guide.

Note that it is technically possible for a single claim to have transactions that use different exchange rate schemas.

Exchange rate schemas and POSTs

Whenever you POST transaction information on an instance on or before 2024.07 (Kufri), the request object must adhere to the TransactionExchangeRate schema.

Whenever you POST transaction information on an instance on or after 2024.11 (Las Leñas), the request object must adhere to the schema that corresponds to the current setting of the UseDepricatedExchangeRates application configuration parameter. Thus:

If UseDepricatedExchangeRates is set to true, the request object must adhere to the TransactionExchangeRate schema.
If UseDepricatedExchangeRates is set to false, the request object must adhere to the ExchangeRateInUse schema.

The following request payload is an example of creating a transaction while UseDepricatedExchangeRates is set to true. The exchange rate information is in bold.

Command

POST /claims/cc:61/reserve-sets

Request

{
  "data": {
    "attributes": {
      "reservesToWrite": [
        {
          "claimToReportingExchangeRate": {
            "market": true,
            "rate": "1.2"
            },
          "reserveLine": {
            "costCategory": {
              "code": "body"
            },
            "costType": {
              "code": "claimcost"
            },
            "exposure": {
              "id": "cc:79"
            },
            "reservingCurrency": {
              "code": "usd"
            },
          "transToClaimExchangeRate": {
            "market": true,
            "rate": "1.2"
            },
          "transToReservingExchangeRate": {
            "market": true,
            "rate": "1.2"
            }
          },
          "lineItems": [
            {
              "transactionAmount": {
                "amount": "1000.00",
                "currency": "usd"
              }
            }
          ],
          "currency": {
            "code": "usd"
          }
        }
      ]
    }
  }
}

The following request payload is an example of creating a transaction while UseDepricatedExchangeRates is set to false. The exchange rate information is in bold.

Command

POST /claims/cc:61/reserve-sets

Request

{
  "data": {
    "attributes": {
      "reservesToWrite": [
        {
          "claimToReportingExchangeRateInUse": {
            "market": {
              "code": "market"
              },
            "rate": "1.2"
            },
          "reserveLine": {
            "costCategory": {
              "code": "body"
            },
            "costType": {
              "code": "claimcost"
            },
            "exposure": {
              "id": "cc:79"
            },
            "reservingCurrency": {
              "code": "usd"
            },
          "transToClaimExchangeRateInUse": {
            "market": {
              "code": "market"
              },
            "rate": "1.2"
            },
          "transToReservingExchangeRateInUse": {
            "market": {
              "code": "market"
              },
            "rate": "1.2"
            }
          },
          "lineItems": [
            {
              "transactionAmount": {
                "amount": "1000.00",
                "currency": "usd"
              }
            }
          ],
          "currency": {
            "code": "usd"
          }
        }
      ]
    }
  }
}