---
title: "Create xs2a.risk object"
method: POST
path: "/risks"
tags: ["XS2A.risk"]
---

# Create xs2a.risk object

`POST /risks`

Create a xs2a.risk object and receive a wizard session key in return.

**Please Note**: In the following documentation of the request body, all available  risk checks are defined. It is important to note that they are optional, and that  you simply submit the risk check you need. You can find a more detailed explanation  of the risk checks [here](#tag/Embeddable-Risk-Checks).

**Important Note**: Using the request sample, can only be performed if all code sections are fully expanded.

## Request body

- Xs2aRisk
  - `bank_code` integer — bank code of the customers bank, requires also parameter country_id. If supplied the step/page for entering a bank code will be skipped.
  - `country_id` 'DE' | 'AT' | 'CH' — The 2-letter country code
  - `account_number` string — The (national) account number of the customer. Is the account number valid, an IBAN will be calculated using the bank code and the account number. Afterwards the procedure is equal to the following description for iban (see below). If you include this field, you must also include the parameter bank_code.
  - `iban` string — IBAN of the customer. If it is a valid IBAN, the IBAN will be pinned for the current session. The customer will not be able to choose a different account, even if there are more accounts available to chose from. If the given IBAN is not in the customer list of accounts, the transaction will be aborted. In the case of an invalid IBAN XS2A will return a validation error with HTTP status code 422.
  - `bic` string — BIC of the customer. If the given BIC is valid, the step/page for entering a bank code will be skipped.
  - `check_amount` number, float — The account balance amount to be checked against.
  - `check_currency_id` 'EUR' | 'CHF' — The id of the currency to be used.
  - `metadata` Metadata, nullable — An array of data which will be passed back to your application. With this field you can for example pass information about your customer ids, order ids and the like back to your application. Please beware of some restrictions for the metadata field: maximum of 3 values, maximum of a key length of 20 characters, maximum length of values is 128 characters. For privacy protection reason it is not allowed to use this field for transferring personal data (e.g. names or addresses).
  - `merchant_id` string — The internal ID of your merchant, if any.
  - `fints_product_id` string — The fints product ID can be enclosed in the initial request. If you have an eIDAS certificate, then you have to send it with every request.
  - `easy_onboarding` EasyOnboarding — An array of a success/abort_link to overwrite the statically stored values in the easyOboarding.
    - `success_link` string
    - `abort_link` string
  - `language` 'de' | 'en' — The initial language.
  - `xs2a_account_characteristics_check` Xs2aAccountCharacteristicsCheck — XS2A.account_characteristics_check allows you to retrieve many possible information about the account, like chargebacks, encashment, loans and other. Simply append an empty object to the XS2A.risk object to indicate you would like this check to be performed.
  - `xs2a_account_linked_offers_check` Xs2aAccountLinkedOffersCheck — The Account Linked Offers Check validates with the consent of the user, based on an account view, whether third party offers might be of interest to the user and hands over an advertising link for one-time use to a Tink Germany business partner.
  - `xs2a_account_snapshot` Xs2aAccountSnapshot
    - `days` integer — Range in days which should be used (min value: 10, max value: 365)
    - `from` string — A date in the format yyyy-mm-dd
    - `to` string — A date in the format yyyy-mm-dd
    - `filters` string[]
    - `all_accounts` boolean — True, if you want to receive all accounts including their turnovers
    - `all_tags` boolean — True, if you want full categorization of the turnovers
  - `xs2a_account_status_check` Xs2aAccountStatusCheck — With XS2A.xs2a_account_status_check a list of accounts within the bank connection can be requested. Basically you have to decide if the account status data for the reference account or all accounts within the bank account should be collected. In addition the request can be filtered over a period in days. As result you get data about account or accountholder identification, current account balance, turnovers and the quality of the turnovers.
    - `limit_turnover_days` integer — If needed limit the fetched turnovers to create it. Default 365. Valid Range: 10 - 365
    - `all_accounts` boolean — True, if you want to receive all accounts including their turnovers
  - `xs2a_age_verification_check` Xs2aAgeVerificationCheck — The XS2A.age_verification_check verifies the legal age of the account holder.
  - `xs2a_all_accounts_check` Xs2aAllAccountsCheck — XS2A.standing_orders_check allows you to retrieve all standing orders from an account. An XS2A.standing_orders_check has no additional parameters. Simply append an empty object to the XS2A.risk object to indicate you would like this check to be performed.
  - `xs2a_balance_check` Xs2aBalanceCheck
    - `check_amount` integer — Account balance amount to be checked against
    - `check_currency_id` 'EUR' | 'CHF' — The id of the currency to be used.
  - `xs2a_balance_overview` Xs2aBalanceOverview — XS2A.balance_overview returns the current running total of the chosen account. An XS2A.balance_overview has no additional parameters. Just append an empty object to the XS2A.risk object to indicate you would like this check to be performed.
  - `xs2a_cashflow_overview` Xs2aCashflowOverview — XS2A.cashflow_overview provides an cashflow overview for the requested risk date range. An XS2A.cashflow_overview has no additional parameters. Just append an empty object to the XS2A.risk object to indicate you would like this check to be performed.
  - `xs2a_chargeback_check` Xs2aChargebackCheck — XS2A.chargeback_check returns the number of detected chargeback transactions for the account. An XS2A.chargeback_check has no additional parameters. Just append an empty object to the XS2A.risk object to indicate you would like this check to be performed.
  - `xs2a_children_check` Xs2aChildrenCheck — The XS2A.children_check gathers payments from governmental facilities, which indicate how many children the account has. This risk-check has no configuration.
  - `xs2a_collection_check` Xs2aCollectionCheck — XS2A.collection_check is used to check whether the current open amount is available on the account and payment should be initiated. If this is not the case, then an individual installment payment is calculated and proposed. This information is supported by further relevant indicators.
    - `check_amount` integer — Account balance amount to be checked against
    - `check_currency_id` 'EUR' | 'CHF' — The id of the currency to be used.
  - `xs2a_credit_check` Xs2aCreditCheck — The XS2A.credit_check gathers various information about a customer. The check was designed for example to be used in a loan application process without the need to resort to some other medium.
    - `checks` string[]
  - `xs2a_direct_debit_check` Xs2aDirectDebitCheck
    - `check_amount` integer — Account balance amount to be checked against
    - `check_currency_id` 'EUR' | 'CHF' — The id of the currency to be used.
    - `start_date` string — Date format is "YYYY-mm-dd". An optional field. If a start_date is given, the field "end_date" has to be set as well. The start date can be no earlier than the day after the transaction. In case the start date is invalid or not set, the earliest bank work day will be used.
    - `end_date` string — Date format is "YYYY-mm-dd". An optional field. The end date has to be at lest 3 days after the start date and can be a maximum of 30 days into the future. If there is no end date given, the maximum of 30 days will be used.
  - `xs2a_fact_sheet_lists` Xs2aFactSheetLists
    - `limit_turnover_days` integer — If needed limit the fetched turnovers to create a fact_sheet_lists. Default 365. Valid Range: 10 - 365
    - `fields` object[]
      - `tags` string[]
      - `categories` string[]
      - `name` string
      - `min_amount` number
      - `max_amount` number
  - `xs2a_holder_identification_check` Xs2aHolderIdentificationCheck — XS2A.holder_identification_check. Using this module a list of names can be checked against the name of the accountholder of all accounts in the bank connection. For the request only the first name and last name must be transferred. As result you get the information if there is a match per account and given name and lastname.
    - `expect_holders` ExpectedHolderObject[], required — Array of objects containing firstnames and lastnames.
      - `firstname` string — The first name
      - `name` string — The last name
  - `xs2a_income_check` Xs2aIncomeCheck — The Income Check provides an overview of the account holder's various types of income. Each type of income is listed separately and the corresponding key figures are calculated so that the customer can only take into account the types of income that are relevant for him/her.
    - `limit_turnover_days` integer — Needed limit of the fetched turnovers to create it. Default days required 90. Valid Range: 90 / 180 / 365
  - `xs2a_insurance_contract_check` Xs2aInsuranceContractCheck — The XS2A.insurance_contract_check provides an overview of the users existing insurance contracts and provides important informations (e.g. insurance policy number) about the users insurance situation.
    - `days` integer — Range in days which should be used (min value: 90, max value: 365)
  - `xs2a_name_check` Xs2aNameCheck
    - `name` string, required — Name to compare against. Usually the surname.
    - `firstname` string, required — Firstname to compare against.
  - `xs2a_overdraft_limit_check` Xs2aOverdraftLimitCheck — XS2A.overdraft_limit_check returns the number of booking days of the given risk range. The number of days the account used the overdraft limit, the maximum amount of overdraft used, the average and the median used overdraft. An XS2A.overdraft_limit_check has no additional parameters. Just append an empty object to the XS2A.risk object to indicate you would like this check to be performed.
  - `xs2a_profit_loss_check` Xs2aProfitLossCheck — The P&L check (profit and loss check) provides a simplified P&L statement for B2B customers as well as an overview of other relevant operational KPIs. These can be, for example, other relevant income, expenses and cash flows from the account. In addition, the tax number is also shown (initially, only in Germany).
  - `xs2a_risk_calculations_check` Xs2aRiskCalculationsCheck — XS2A.risk_calculations_check allows you many things
    - `calculations` RiskCalculations[], required — Array of objects containing many manditory fields.
      - `tags` CalculationsTags[]
      - `categories` CalculationsCategories[]
      - `functions` CalculationsFunctions[]
      - `name` string — A name for this calculation
      - `days` integer — Days
      - `from` string — Starting date
      - `to` string — Ending date
      - `full_months` string — Full months
      - `children_categories` boolean — Children categories
      - `match_tags_with_categories` boolean — Match tags with categories
      - `include_current_month` boolean — If you are using full_month date range, you can also include the current ongoing month, by enabling the parameter. This has no affect on date ranges from, to & days.
  - `xs2a_seizure_check` Xs2aSeizureCheck — XS2a.seizure_check allows you to check for a seizire account.
    - `days` integer — The limit of turnover days for this check
  - `xs2a_standing_orders_check` Xs2aStandingOrdersCheck — XS2A.standing_orders_check allows you to retrieve all standing orders from an account. An XS2A.standing_orders_check has no additional parameters. Simply append an empty object to the XS2A.risk object to indicate you would like this check to be performed.

## Response `200`

Request successfully processed

- WizardSessionResponse
  - `wizard_session_key` string — Using the wizard_session_key you can now initialize our Wizard which is running on your website
  - `transaction` string — We suggest that you store the internally used XS2A transaction id transaction with your transaction data, because if you later have questions about a transaction, we need this number to be able to quickly assist you.

## Other responses

- `401` — Authentication failed API key missing or not valid
- `403` — Forbidden Access blocked
- `404` — Product not enabled or Not found The requested object does not exist on the server
- `422` — Validation failed Something is wrong with the user input
- `500` — An internal server problem occurred

---

[API](https://skmtc.dev/xs2a/apis/xs2a-api.md) · [All operations](https://skmtc.dev/xs2a/apis/xs2a-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/xs2a/xs2a-api/revisions/ae5fbc5feee3/schema)