---
updatedAt: 2026-06-16T11:38:14.000Z
agentTools:
projectIndex: https://docs.qwist.com/llms.txt
---
# Get insurance
Get insurance by ID.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "nrich API",
"version": "2.10",
"contact": {
"name": "Qwist GmbH",
"email": "partnersupport@qwist.com",
"url": "https://qwist.com"
},
"description": "This is the reference for Qwist's nrich API"
},
"x-readme": {
"samples-languages": [
"json",
"shell"
]
},
"servers": [
{
"url": "https://api.nrich.qwist.cloud",
"description": "Staging environment"
}
],
"tags": [
{
"name": "Client Authorization"
},
{
"name": "User Management"
},
{
"name": "Accesses"
},
{
"name": "Loans"
},
{
"name": "Insurances"
},
{
"name": "Transaction Upload"
}
],
"paths": {
"/auth/token": {
"post": {
"tags": [
"Client Authorization"
],
"summary": "Create access token",
"operationId": "createAccessToken",
"description": "Create a new token to access user resources.",
"security": [
{
"client_auth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/UserCredentialRequest"
},
{
"$ref": "#/components/schemas/RefreshTokenRequest"
},
{
"$ref": "#/components/schemas/AuthorizationCodeRequest"
}
],
"discriminator": {
"propertyName": "grant_type",
"mapping": {
"password": "#/components/schemas/UserCredentialRequest",
"refresh_token": "#/components/schemas/RefreshTokenRequest",
"authorization_code": "#/components/schemas/AuthorizationCodeRequest"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccessToken"
},
"example": {
"access_token": "AoFmNJLDTW8jQtGSJ1iZeeoLiwNZ2ihz3iiCHGpuvE439nppuY",
"expires_in": 3600,
"scope": "accounts=ro balance=ro transactions=ro offline",
"token_type": "Bearer",
"refresh_token": "RTfI2WNyK78NozupDH9ai8GPRbjjdVsXPPt..."
}
}
}
},
"401": {
"$ref": "#/paths/~1catalog/get/responses/401"
},
"404": {
"description": "The specified resource was not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/paths/~1catalog/get/responses/401/content/application~1json/schema"
},
"example": {
"error": {
"code": 1002,
"group": "client",
"data": {},
"description": "Not found."
}
}
}
}
},
"4XX": {
"$ref": "#/paths/~1rest~1loans/get/responses/4XX"
}
}
}
},
"/rest/accesses": {
"get": {
"summary": "List provider accesses",
"operationId": "listProviderAccesses",
"description": "List all connected provider accesses of user.",
"tags": [
"Accesses"
],
"security": [
{
"user_auth": []
}
],
"parameters": [
{
"in": "query",
"name": "embed",
"schema": {
"type": "string",
"example": "(provider,access_method)"
},
"description": "The `embed` query parameter allows it to add additional information to the response. The format for the parameter value is a comma separated list of field names (that is optionally surrounded by parentheses). Currently supported fields to be embedded are \"provider\" and \"access_method\"."
},
{
"$ref": "#/paths/~1catalog/get/parameters/0"
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"created_at",
"access_method_id",
"auth_methods",
"auto_sync",
"credential",
"save_pin",
"status"
],
"properties": {
"id": {
"$ref": "#/paths/~1rest~1accesses~1{access-id}/get/parameters/0/schema"
},
"access_method_id": {
"$ref": "#/paths/~1rest~1accesses/post/requestBody/content/application~1json/schema/properties/access_method_id"
},
"consent": {
"$ref": "#/paths/~1rest~1accesses/post/requestBody/content/application~1json/schema/properties/consent",
"deprecated": true,
"description": "Will be removed in favor of `credential` in the future."
},
"credential": {
"$ref": "#/paths/~1rest~1accesses~1{access-id}~1credentials~1{credential-id}/get/responses/200/content/application~1json/schema",
"description": "The current credential used to authenticate with the financial provider."
},
"created_at": {
"description": "Entity creation timestamp.",
"example": "2026-04-01T18:30:00.000+00:00",
"type": "string",
"format": "date-time"
},
"auth_methods": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"$ref": "#/paths/~1rest~1accesses~1{access-id}~1syncs~1{sync-id}~1challenges~1{challenge-id}~1response/post/requestBody/content/application~1json/schema/oneOf/0/properties/method_id"
},
"type": {
"type": "string",
"description": "Type of authentication method.",
"enum": [
"SMS_OTP",
"PUSH_OTP",
"CHIP_OTP",
"PHOTO_OTP",
"DECOUPLED"
]
},
"name": {
"type": "string",
"example": "mobileTAN",
"description": "Name of the authentication method as used by the financial provider."
}
},
"required": [
"id",
"type",
"name"
]
},
"description": "List of supported methods for payment initiation and authentication."
},
"selected_auth_method": {
"$ref": "#/paths/~1rest~1accesses/get/responses/200/content/application~1json/schema/items/properties/auth_methods/items",
"description": "The method that was last selected for strong customer authentication. This method will be reused for subsequent synchronization or payment initiation operations by default.\n"
},
"auto_sync": {
"type": "boolean",
"description": "Indicates if the access is automatically synchronized.",
"example": false
},
"save_pin": {
"type": "boolean",
"default": false,
"description": "Indicates if the provider credentials are saved for this access.",
"example": true
},
"status": {
"type": "object",
"description": "Synchronization status",
"properties": {
"synced_at": {
"$ref": "#/paths/~1uploads/post/responses/200/content/application~1json/schema/properties/ended_at",
"description": "Time of last synchronization."
},
"succeeded_at": {
"$ref": "#/paths/~1uploads/post/responses/200/content/application~1json/schema/properties/ended_at",
"description": "Time of last successful synchronization."
},
"message": {
"type": "string",
"description": "Human-readable error message"
}
},
"required": [
"synced_at",
"succeeded_at"
]
},
"provider": {
"$ref": "#/paths/~1rest~1catalog~1banks/get/responses/200/content/application~1json/schema/items/allOf/0/allOf/1",
"description": "The details of the provider associated to this access. This field is only included if the query parameter `?embed=provider` is added to the request."
},
"access_method": {
"$ref": "#/paths/~1rest~1catalog~1banks/get/responses/200/content/application~1json/schema/items/allOf/0/allOf/0/properties/access_methods/items",
"description": "The details of the access method associated to this access. This field is only included if the query parameter `?embed=access_method` is added to the request."
}
}
}
}
}
}
},
"401": {
"$ref": "#/paths/~1catalog/get/responses/401"
}
}
}
},
"/rest/accesses/{access-id}": {
"get": {
"summary": "Get provider access",
"operationId": "getProviderAccess",
"description": "Retrieve the details of a specific provider access identified by its ID.",
"tags": [
"Accesses"
],
"security": [
{
"user_auth": []
}
],
"parameters": [
{
"name": "access-id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"example": "X12345.6",
"description": "nrich ID of the provider access."
}
},
{
"$ref": "#/paths/~1rest~1accesses/get/parameters/0"
},
{
"$ref": "#/paths/~1catalog/get/parameters/0"
}
],
"responses": {
"200": {
"$ref": "#/paths/~1rest~1accesses/post/responses/201"
},
"401": {
"$ref": "#/paths/~1catalog/get/responses/401"
},
"404": {
"$ref": "#/paths/~1auth~1token/post/responses/404"
}
}
}
},
"/rest/loans": {
"get": {
"summary": "List loans",
"operationId": "listLoans",
"description": "Retrieve a list of all available loans.",
"tags": [
"Loans"
],
"security": [
{
"user_auth": []
}
],
"responses": {
"200": {
"description": "List of loans.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/paths/~1rest~1loans~1{loan-id}/get/responses/200/content/application~1json/schema"
}
}
}
}
},
"400": {
"$ref": "#/paths/~1rest~1user/put/responses/400"
},
"401": {
"$ref": "#/paths/~1catalog/get/responses/401"
},
"4XX": {
"description": "Generic error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/paths/~1catalog/get/responses/401/content/application~1json/schema"
}
}
}
}
}
}
},
"/rest/loans/{loan-id}": {
"get": {
"summary": "Get loan",
"operationId": "getLoan",
"description": "Get loan by ID.",
"tags": [
"Loans"
],
"parameters": [
{
"name": "loan-id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"example": "L12345.6",
"description": "nrich ID of the loan."
}
}
],
"security": [
{
"user_auth": []
}
],
"responses": {
"200": {
"description": "Loan details.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"$ref": "#/paths/~1rest~1loans~1{loan-id}/get/parameters/0/schema"
},
"access_id": {
"$ref": "#/paths/~1rest~1accesses~1{access-id}/get/parameters/0/schema"
},
"name": {
"type": "string",
"description": "Name of the loan product.",
"example": "Cash Plus Now"
},
"type": {
"type": "string",
"enum": [
"BUSINESS",
"PERSONAL",
"MORTGAGE"
],
"description": "The type of the loan indicating its usage.",
"example": "PERSONAL"
},
"reference_id": {
"type": "string",
"description": "Reference or identification code for the loan product as provided by the bank.",
"example": 904404405
},
"linked_account": {
"type": "string",
"description": "Identification of the account from which the installments are deducted. This is usually an IBAN.",
"example": "DE93300308800013441006"
},
"borrower": {
"type": "object",
"description": "Details about the borrowing party.",
"properties": {
"id": {
"type": "string",
"description": "Identification number. For Spanish loans this can be the NIF/NIE.",
"example": "X12345678A"
},
"name": {
"type": "string",
"description": "The name of the borrowing party.",
"example": "Jose Gonzales"
}
},
"required": [
"name"
]
},
"currency": {
"type": "string",
"format": "ISO 4217:2015",
"default": "EUR",
"description": "Three-letter currency code."
},
"principal": {
"type": "number",
"format": "float",
"description": "The original amount of money that was agreed to borrow.",
"example": 30000
},
"balance": {
"type": "number",
"format": "float",
"description": "The amount of of money that is still owed to the lender. This is usually a negative value.",
"example": -15300
},
"matures_on": {
"$ref": "#/paths/~1auth~1users/get/parameters/2/schema",
"description": "The date on which the loan was agreed to be paid back.",
"example": "2023-12-01"
},
"interest": {
"type": "object",
"properties": {
"rate": {
"type": "number",
"format": "float",
"description": "The interest rate in percent.",
"example": 3.5
},
"type": {
"type": "string",
"enum": [
"FIXED",
"VARIABLE"
],
"description": "Indicates if the interest rate is fixed or variable throughout the runtime of the loan."
}
},
"required": [
"rate",
"type"
]
},
"next_payment_on": {
"$ref": "#/paths/~1auth~1users/get/parameters/2/schema",
"description": "The date on which the next installment is due to be paid.",
"example": "2023-02-01"
},
"next_payment_amount": {
"type": "number",
"format": "float",
"description": "The money amount to be paid with the next installment.",
"example": 1000
},
"last_payment_on": {
"$ref": "#/paths/~1auth~1users/get/parameters/2/schema",
"description": "The date on which the last installment was paid.",
"example": "2023-01-01"
},
"last_payment_amount": {
"type": "number",
"format": "float",
"description": "The money amount that was paid with the last installment.",
"example": 1000
},
"created_at": {
"$ref": "#/paths/~1rest~1accesses/get/responses/200/content/application~1json/schema/items/properties/created_at"
},
"modified_at": {
"description": "Entity modification timestamp.",
"example": "2026-04-01T20:15:00.000+00:00",
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"access_id",
"name",
"type",
"reference_id",
"borrower",
"currency",
"principal",
"balance",
"matures_on",
"interest",
"created_at",
"modified_at"
]
}
}
}
},
"400": {
"$ref": "#/paths/~1rest~1user/put/responses/400"
},
"401": {
"$ref": "#/paths/~1catalog/get/responses/401"
},
"404": {
"$ref": "#/paths/~1auth~1token/post/responses/404"
},
"4XX": {
"$ref": "#/paths/~1rest~1loans/get/responses/4XX"
}
}
}
},
"/rest/insurances/{insurance-id}": {
"get": {
"summary": "Get insurance",
"operationId": "getInsurance",
"description": "Get insurance by ID.",
"tags": [
"Insurances"
],
"parameters": [
{
"name": "insurance-id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"example": "I12345.6",
"description": "nrich ID of the insurance."
}
}
],
"security": [
{
"user_auth": []
}
],
"responses": {
"200": {
"description": "Insurance details",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"$ref": "#/paths/~1rest~1insurances~1{insurance-id}/get/parameters/0/schema"
},
"access_id": {
"$ref": "#/paths/~1rest~1accesses~1{access-id}/get/parameters/0/schema"
},
"name": {
"type": "string",
"description": "Name of the insurance product as supplied by the insurance company (e.g. Kaskoversicherung)",
"example": "Kaskoversicherung"
},
"kind": {
"type": "string",
"enum": [
"ACCIDENT",
"CAR",
"HEALTH",
"DEATH",
"LIABILITY",
"LIFE",
"PROPERTY",
"SAVINGS",
"TRAVEL",
"UNKNOWN"
],
"description": "Type of the insurance. Use this field to detect the type of the `details` field",
"example": "SAVINGS"
},
"holder": {
"description": "The insurance policy holder, the person who owns the policy",
"type": "object",
"properties": {
"reference_id": {
"type": "string",
"example": "HOLDER-ID-1234",
"description": "Reference or identification code of the policy holder provided by the insurance company"
},
"name": {
"type": "string",
"description": "Name of the policy holder",
"example": "John Doe"
},
"address": {
"type": "string",
"description": "The address of the policy holder",
"example": "Neuweg 1, 92919 Berlin, Germany"
},
"phone_number": {
"type": "string",
"description": "Phone number of the policy holder",
"example": "0123 456789"
},
"email": {
"$ref": "#/paths/~1rest~1user/put/requestBody/content/application~1json/schema/properties/email",
"description": "E-mail address of the policy holder"
},
"born_on": {
"description": "The date of birth of the person",
"type": "string",
"format": "date",
"example": "2023-01-14"
},
"is_self_employed": {
"type": "boolean",
"description": "A flag to detect whether the policy holder is self-employed"
}
},
"required": [
"reference_id",
"name",
"address",
"phone_number",
"email",
"born_on",
"is_self_employed"
]
},
"premium": {
"$ref": "#/paths/~1uploads/post/requestBody/content/application~1json/schema/properties/accounts/items/properties/balance",
"description": "Insurance premium amount"
},
"currency": {
"$ref": "#/paths/~1rest~1loans~1{loan-id}/get/responses/200/content/application~1json/schema/properties/currency",
"description": "Currency of the insurance premium"
},
"payment_frequency": {
"description": "The frequency at which the premium is deducted",
"type": "string",
"enum": [
"monthly",
"quarterly",
"half-yearly",
"yearly"
]
},
"starts_on": {
"$ref": "#/paths/~1auth~1users/get/parameters/2/schema",
"description": "The start date of the insurance coverage"
},
"due_on": {
"$ref": "#/paths/~1auth~1users/get/parameters/2/schema",
"description": "The date on which the insurance coverage will end"
},
"coverages": {
"type": "array",
"items": {
"type": "string",
"example": "Fires, Theft and vandalism"
},
"description": "The list of coverages that are provided by the insurance contract"
},
"claims": {
"type": "array",
"items": {
"type": "object",
"properties": {
"reference_id": {
"type": "string",
"example": "ID1234",
"description": "The reference id to the insurance claim provided by the insurance company"
},
"type": {
"type": "string",
"description": "Type of the insurance claim (e.g. Burglary and Theft, Fire)",
"example": "Fire"
},
"status": {
"type": "string",
"description": "The status of the insurance claim (e.g. Submitted, In review, On hold, Closed)",
"example": "Submitted"
},
"filed_at": {
"$ref": "#/paths/~1uploads/post/responses/200/content/application~1json/schema/properties/ended_at",
"description": "Date and time of submission of the insurance claim"
}
},
"required": [
"reference_id",
"type",
"status",
"filed_at"
]
},
"description": "Insurance claims claimed so far"
},
"created_at": {
"$ref": "#/paths/~1rest~1accesses/get/responses/200/content/application~1json/schema/items/properties/created_at"
},
"modified_at": {
"$ref": "#/paths/~1rest~1loans~1{loan-id}/get/responses/200/content/application~1json/schema/properties/modified_at"
},
"details": {
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Type of the savings insurance",
"example": "National Pension Scheme"
},
"net_plan_value": {
"$ref": "#/paths/~1uploads/post/requestBody/content/application~1json/schema/properties/accounts/items/properties/balance",
"description": "Net plan value of the savings insurance"
}
},
"required": [
"type",
"net_plan_value"
]
},
{
"type": "object",
"properties": {
"address": {
"type": "string",
"description": "Address of the insured property",
"example": "Neuweg 1, 92919 Berlin, Germany"
},
"registry_number": {
"type": "string",
"description": "Registry number of the insured property",
"example": "RN1234"
},
"year_of_construction": {
"type": "integer",
"description": "Year of construction of the insured property",
"example": 2020
},
"area": {
"type": "string",
"description": "Area the property in square meters",
"example": 220
},
"property_type": {
"type": "string",
"description": "Type of the insured property (e.g. Dwellings, Office)",
"example": "Office"
}
},
"required": [
"address",
"registry_number",
"year_of_construction",
"area",
"property_type"
]
},
{
"type": "object",
"properties": {
"owner": {
"type": "object",
"properties": {
"reference_id": {
"type": "string",
"description": "Reference or identification code of a person supplied by the insurance company. This can be used to identify given person on insurance provider side."
},
"name": {
"type": "string",
"description": "Full name of the person",
"example": "John Doe"
},
"born_on": {
"$ref": "#/paths/~1rest~1insurances~1{insurance-id}/get/responses/200/content/application~1json/schema/properties/holder/properties/born_on"
},
"age": {
"type": "integer",
"description": "The age of the insured person"
},
"driving_license_issued_on": {
"$ref": "#/paths/~1auth~1users/get/parameters/2/schema",
"description": "Issue date of the person's driving license"
}
},
"required": [
"reference_id",
"name",
"born_on",
"age",
"driving_license_issued_on"
]
},
"main_driver": {
"$ref": "#/paths/~1rest~1insurances~1{insurance-id}/get/responses/200/content/application~1json/schema/properties/details/oneOf/2/properties/owner"
},
"additional_drivers": {
"type": "array",
"items": {
"$ref": "#/paths/~1rest~1insurances~1{insurance-id}/get/responses/200/content/application~1json/schema/properties/details/oneOf/2/properties/owner"
}
},
"brand": {
"type": "string",
"description": "Brand of the insured car (e.g. Volkswagen)",
"example": "Volkswagen"
},
"model": {
"type": "string",
"description": "Model of the insured car (e.g. Golf)",
"example": "Golf"
},
"extended_model_info": {
"type": "string",
"description": "Extended model info of the car (e.g. GTI 1.6)",
"example": "GTI 1.6"
},
"license_plate": {
"type": "string",
"description": "The license plate number of the car (e.g. DE 1234)",
"example": "DE 1234"
},
"vehicle_type": {
"type": "string",
"description": "The type of the vehicle (e.g. Car, Truck, Bus)",
"example": "Bus"
},
"year_of_registration": {
"type": "integer",
"description": "Year of registration of the car (e.g. 2020)",
"example": 2020
},
"coverage_type": {
"type": "string",
"description": "The coverage type provided (e.g. Comprehensive, Third party)",
"example": "Comprehensive"
}
},
"required": [
"owner",
"main_driver",
"additional_drivers",
"brand",
"model",
"extended_model_info",
"license_plate",
"vehicle_type",
"year_of_registration",
"coverage_type"
]
},
{
"type": "object",
"properties": {
"insured_capital": {
"$ref": "#/paths/~1uploads/post/requestBody/content/application~1json/schema/properties/accounts/items/properties/balance",
"description": "The amount of insured capital"
},
"beneficiaries": {
"type": "array",
"items": {
"type": "object",
"properties": {
"reference_id": {
"type": "string",
"description": "Reference or identification code of the beneficiary provided by the insurance company. This ID is used to identify the beneficiary on the insurance provider side."
},
"name": {
"type": "string",
"description": "The full name of the beneficiary",
"example": "John Doe"
},
"born_on": {
"$ref": "#/paths/~1rest~1insurances~1{insurance-id}/get/responses/200/content/application~1json/schema/properties/holder/properties/born_on"
}
},
"required": [
"reference_id",
"name",
"born_on"
]
}
},
"coverage": {
"type": "string",
"description": "Coverage of the insurance"
}
},
"required": [
"insured_capital",
"beneficiaries",
"coverage"
]
},
{
"type": "object",
"properties": {
"beneficiaries": {
"type": "array",
"items": {
"$ref": "#/paths/~1rest~1insurances~1{insurance-id}/get/responses/200/content/application~1json/schema/properties/details/oneOf/3/properties/beneficiaries/items"
}
},
"co_payments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"amount": {
"$ref": "#/paths/~1uploads/post/requestBody/content/application~1json/schema/properties/accounts/items/properties/balance",
"description": "The amount that was co-paid"
},
"currency": {
"$ref": "#/paths/~1rest~1loans~1{loan-id}/get/responses/200/content/application~1json/schema/properties/currency"
},
"beneficiary": {
"type": "string",
"description": "Name of the beneficiary of the co-payment"
},
"paid_on": {
"$ref": "#/paths/~1auth~1users/get/parameters/2/schema",
"description": "The date on which the co-payment was done"
}
},
"required": [
"amount",
"currency",
"beneficiary",
"paid_on"
]
}
}
},
"required": [
"beneficiaries",
"co_payments"
]
}
],
"description": "The type of this field depends on the `kind` field. The following mapping defines the relationship between the `kind` and `details` field:
\n SAVINGS -> SavingsInsurancePROPERTY -> PropertyInsuranceCAR -> CarInsuranceLIFE -> LifeInsuranceHEALTH -> HealthInsurance
If kind contains a value that is not listed in the mapping above (e.g. ACCIDENT) then the details field will be omitted from the response."
}
},
"required": [
"id",
"access_id",
"name",
"kind",
"holder",
"premium",
"currency",
"coverages",
"claims",
"created_at",
"modified_at"
]
}
}
}
},
"400": {
"$ref": "#/paths/~1rest~1user/put/responses/400"
},
"401": {
"$ref": "#/paths/~1catalog/get/responses/401"
},
"404": {
"$ref": "#/paths/~1auth~1token/post/responses/404"
},
"4XX": {
"$ref": "#/paths/~1rest~1loans/get/responses/4XX"
}
}
}
},
"/auth/users": {
"get": {
"tags": [
"User Management"
],
"summary": "List users of client",
"operationId": "listClientUsers",
"security": [
{
"client_auth": []
}
],
"parameters": [
{
"in": "query",
"name": "count",
"schema": {
"type": "integer",
"default": 1000,
"example": 100
},
"description": "Limit the number of returned items. In combination with the offset parameter this can be used to paginate the result list."
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"default": 0,
"example": 200
},
"description": "Skip this number of items in the response. In combination with the count parameter this can be used to paginate the result list."
},
{
"in": "query",
"name": "since",
"schema": {
"type": "string",
"format": "date",
"example": "2023-01-14"
},
"description": "Only entities with a corresponding date **equal or newer** to this date will be selected.",
"example": "2020-02-01"
},
{
"in": "query",
"name": "until",
"schema": {
"$ref": "#/paths/~1auth~1users/get/parameters/2/schema"
},
"description": "Only entities with a corresponding date **equal or older** to this date will be selected.",
"example": "2020-02-01"
}
],
"responses": {
"200": {
"description": "List of users associated with authenticated client.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "List of users",
"properties": {
"users": {
"type": "array",
"items": {
"$ref": "#/paths/~1rest~1user/get/responses/200/content/application~1json/schema"
}
}
}
}
}
}
},
"400": {
"$ref": "#/paths/~1rest~1user/put/responses/400"
},
"401": {
"$ref": "#/paths/~1catalog/get/responses/401"
}
}
}
},
"/catalog": {
"get": {
"operationId": "listCatalogClientAuth",
"summary": "List complete catalog (client_auth)",
"description": "The real catalog contains thousands of entries, so expect the call to cause some traffic and delay. The example is only to highlight the data structure.\n*Note*: The client has to have the `accounts=rw` scope in order to retrieve the catalog.\n",
"tags": [
"Catalog"
],
"security": [
{
"client_auth": []
}
],
"parameters": [
{
"name": "Accept-Language",
"in": "header",
"description": "Setting the Accept-Language to one of the available languages will return results in this language.",
"schema": {
"type": "string",
"format": "ISO 639-1:2002"
},
"example": "de"
},
{
"in": "query",
"name": "country",
"required": false,
"description": "Two-letter country code. Show only resources within this country. Country code is case-sensitive.",
"schema": {
"type": "string",
"format": "ISO 3166-1 alpha-2",
"example": "DE",
"description": "Two-letter country code."
}
},
{
"in": "query",
"name": "q",
"required": false,
"description": "Query for the entire catalog. Will match banks on domestic bank code, BIC, name or nrich ID. Will match services based on name or nrich ID. Only exact matches are returned.",
"schema": {
"type": "string",
"example": "10020030"
}
}
],
"responses": {
"200": {
"description": "List of banks and services.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"banks": {
"type": "array",
"items": {
"$ref": "#/paths/~1rest~1catalog~1banks/get/responses/200/content/application~1json/schema/items"
},
"description": "List of supported banks"
},
"services": {
"type": "array",
"items": {
"$ref": "#/paths/~1rest~1catalog~1services/get/responses/200/content/application~1json/schema/items"
},
"description": "List of supported payment services"
}
}
}
}
}
},
"401": {
"description": "You are not authorized.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"x-extensible-enum": [
1000,
1001,
1002,
1003,
1004,
1005,
1006,
1007,
1008,
1010,
1011,
1020,
1021,
10000,
10001,
10002,
10003,
10004,
10005,
10006,
10007,
10008,
10009,
10010,
10011,
10012,
10013,
10014,
10015,
10016,
10017,
20000,
20001,
20002,
20003,
20004,
20005,
20006,
20007,
30000,
30005,
30006,
40000,
40001,
40002,
40003
],
"description": "| Code | Group | Description |\n| ------- | ------------ | --------------------------------------------------- |\n| 1000 | client | Invalid request |\n| 1001 | client | Entry already exists |\n| 1002 | client | Entity not found |\n| 1003 | client | Unauthorized |\n| 1004 | client | Invalid client authorization |\n| 1005 | client | Payment already processed |\n| 1006 | client | Unprocessable entity |\n| 1007 | client | Forbidden |\n| 1008 | client | Resource busy |\n| 1010 | client | User locked |\n| 1011 | client | Login credentials are incomplete or malformed |\n| 1020 | client | Maximum number of account synchronizations exceeded |\n| 1021 | client | PSU IP is required |\n| 10000 | user | Login credentials are invalid |\n| 10001 | user | PIN is invalid |\n| 10002 | user | Online access is blocked |\n| 10003 | user | TAN scheme not activated |\n| 10004 | user | TAN is invalid |\n| 10005 | user | No authorization for this account |\n| 10006 | user | Transaction rejected |\n| 10007 | user | PIN change necessary |\n| 10008 | user | No authorization for this business transaction |\n| 10009 | user | HBCI activation necessary |\n| 10010 | user | Account is blocked |\n| 10011 | user | Account no longer exists |\n| 10012 | user | TAN scheme is blocked |\n| 10013 | user | Status of transaction inconclusive |\n| 10014 | user | Account not activated for online banking |\n| 10015 | user | Redundant submissions |\n| 10016 | user | Invalid OTP |\n| 10017 | user | Invalid consent configuration |\n| 20000 | bank | Processing at the bank not possible |\n| 20001 | bank | Bank / account unknown |\n| 20002 | bank | Transaction canceled |\n| 20003 | bank | Maintenance |\n| 20004 | bank | Technical migration |\n| 20005 | bank | Transaction not possible |\n| 20006 | bank | Login not possible |\n| 20007 | bank | Pop up |\n| 30000 | general | Processing at nrich not possible |\n| 30005 | general | Task is expired |\n| 30006 | general | Service temporarily not available |\n| 40000 | general | Bank not supported |\n| 40001 | general | Direct access upgrade |\n| 40002 | general | Multi access upgrade |\n| 40003 | general | Partial access upgrade |\n"
},
"data": {
"type": "object",
"description": "Additional data."
},
"description": {
"type": "string",
"description": "Human readable description of the error."
},
"group": {
"type": "string",
"description": "The source of the error.",
"enum": [
"client",
"user",
"bank",
"general"
]
}
},
"required": [
"code",
"description",
"group"
]
}
},
"required": [
"error"
],
"example": {
"error": {
"code": 1000,
"data": {
"id": [
"Missing data for required field."
]
},
"description": "Invalid query-string parameters.",
"group": "client"
}
}
},
"example": {
"error": {
"code": 1003,
"group": "client",
"data": {},
"description": "Unauthorized."
}
}
}
}
}
}
}
},
"/rest/user": {
"put": {
"summary": "Modify user",
"operationId": "updateUser",
"description": "Update details of the user associated with the access token used for authentication.",
"tags": [
"User Management"
],
"security": [
{
"user_auth": []
}
],
"requestBody": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email",
"example": "user@example.com",
"description": "E-mail address/nrich account username."
},
"language": {
"type": "string",
"format": "ISO 639-1:2002",
"example": "de",
"description": "Two-letter language code."
},
"full_name": {
"type": "string",
"example": "John Doe",
"description": "Full name of the nrich account user."
},
"new_password": {
"$ref": "#/paths/~1auth~1user/post/requestBody/content/application~1json/schema/properties/password",
"description": "New finX account password. If this field is set, then the field `password` must be set too."
},
"password": {
"$ref": "#/paths/~1auth~1user/post/requestBody/content/application~1json/schema/properties/password",
"description": "Current finX account password."
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/paths/~1rest~1user/get/responses/200"
},
"400": {
"description": "Bad request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/paths/~1catalog/get/responses/401/content/application~1json/schema"
},
"example": {
"error": {
"code": 1000,
"group": "client",
"data": {},
"description": "Bad request."
}
}
}
}
},
"401": {
"$ref": "#/paths/~1catalog/get/responses/401"
}
}
}
},
"/uploads": {
"post": {
"summary": "Create a transaction upload job",
"operationId": "createUpload",
"description": "Creates a new user and associates it with the products and transactions received in the body of the request.",
"tags": [
"Transaction Upload"
],
"security": [
{
"user_auth": []
}
],
"requestBody": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"accounts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"balance": {
"type": "number",
"example": 23.99,
"description": "Monetary value."
},
"balance_date": {
"$ref": "#/paths/~1uploads/post/responses/200/content/application~1json/schema/properties/ended_at"
},
"currency": {
"$ref": "#/paths/~1rest~1loans~1{loan-id}/get/responses/200/content/application~1json/schema/properties/currency"
},
"iban": {
"type": "string",
"format": "ISO 13616:2007",
"example": "DE93300308800013441006",
"description": "International Bank Account Number (IBAN)."
},
"bic": {
"type": "string",
"format": "ISO 9362:2014",
"example": "TUBDDEDD",
"description": "Business Identifier Code (SWIFT-BIC)."
},
"owner": {
"type": "string",
"description": "Name of the account holder.",
"example": "John Doe"
},
"transactions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"iban": {
"$ref": "#/paths/~1uploads/post/requestBody/content/application~1json/schema/properties/accounts/items/properties/iban"
},
"bic": {
"$ref": "#/paths/~1uploads/post/requestBody/content/application~1json/schema/properties/accounts/items/properties/bic"
},
"amount": {
"$ref": "#/paths/~1uploads/post/requestBody/content/application~1json/schema/properties/accounts/items/properties/balance"
},
"booking_text": {
"type": "string",
"description": "Booking text further describing the type of transaction.",
"example": "Basislastschrift"
},
"creditor_id": {
"$ref": "#/paths/~1rpc~1categorize/post/requestBody/content/application~1json/schema/items/properties/creditor_id"
},
"currency": {
"$ref": "#/paths/~1rest~1loans~1{loan-id}/get/responses/200/content/application~1json/schema/properties/currency"
},
"end_to_end_reference": {
"$ref": "#/paths/~1rpc~1categorize/post/requestBody/content/application~1json/schema/items/properties/end_to_end_reference"
},
"mandate_reference": {
"$ref": "#/paths/~1rpc~1categorize/post/requestBody/content/application~1json/schema/items/properties/mandate_reference"
},
"name": {
"type": "string",
"description": "Name of the counterparty.",
"example": "AMAZON EU S.A R.L."
},
"purpose": {
"type": "string",
"description": "Purpose of the transaction potentially including other structured SEPA information (e.g. `EREF+`, `MREF+`).",
"example": "EREF+5B5U3FFS9EA2LS0O MREF+xJbwAFja+X58H3w,CTnl.ascP,WtKe CRED+DE24ZZZ00000561652 SVWZ+306-7405387-3384342 Amazon.de"
},
"sepa_purpose_code": {
"$ref": "#/paths/~1rpc~1categorize/post/requestBody/content/application~1json/schema/items/properties/sepa_purpose_code"
},
"booked_at": {
"$ref": "#/paths/~1uploads/post/responses/200/content/application~1json/schema/properties/ended_at"
},
"settled_at": {
"$ref": "#/paths/~1uploads/post/responses/200/content/application~1json/schema/properties/ended_at"
}
},
"required": [
"iban",
"amount",
"purpose",
"booked_at"
]
}
}
},
"required": [
"iban"
]
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "UUID",
"example": "a18952ae-a93e-48b5-b863-cf8e47156784",
"description": "nrich ID of transaction upload operation"
},
"status": {
"description": "The processing state that the work item currently is in.",
"type": "string",
"enum": [
"QUEUED",
"RUNNING",
"FAILED",
"AWAIT_AUTH",
"COMPLETED"
]
},
"created_at": {
"$ref": "#/paths/~1uploads/post/responses/200/content/application~1json/schema/properties/ended_at"
},
"ended_at": {
"type": "string",
"format": "date-time",
"example": "2026-04-21T09:30:00.000+00:00"
},
"started_at": {
"$ref": "#/paths/~1uploads/post/responses/200/content/application~1json/schema/properties/ended_at"
},
"access_token": {
"type": "string",
"description": "The access token for the current user as JSON Web Token according to RFC7519. It has a variable length and it is highly advised to not limit the size of the database field in your storage backend. If you have to specify a size for the corresponding database field a choice of at least 2048 bytes is highly recommended.",
"example": "AoFmNJLDTW8jQtGSJ1iZeeoLiwNZ2ihz3iiCHGpuvE439nppuY"
}
},
"required": [
"id",
"status",
"created_at",
"access_token"
]
}
}
}
},
"401": {
"$ref": "#/paths/~1catalog/get/responses/401"
}
}
}
}
},
"components": {
"securitySchemes": {
"user_auth": {
"type": "http",
"description": "In order to access any information belonging to a user, a client has to authenticate with a token linking itself to the user. This token is called an `access token` and contains information on the client, the user and the level of access the client has to the users data. In order to authenticate using such an access token the HTTP header `Authorization` is set to `Bearer `. The `access token` is formatted\nas a JSON Web Token according to [RFC7519](https://tools.ietf.org/html/rfc7519)\n\nSuch an `access token` is either returned when\n\n* exchanging an authorization code after a successful OAuth login flow\n* logging in with the user's credentials\n* exchanging a refresh token, which is returned at either of the aforementioned points\n\n**Authentication errors**\n\nIn case of an authentication error a HTTP code 401 response is returned containing further\ndetails on the kind of error in the `WWW-Authenticate` header.\n\nIn addition to the below listed scope the flags are used for simple boolean permissions.\n\n| Flag | Description |\n| -- | -- |\n| submit_payments | Allow submission of payments to bank server |\n| offline | Access finX API when the user is not present |\n| create_user | Allow creation of finX accounts |\n\n**Example**\n\nThe string `\"accounts=rw submit_payments\"` is URL-encoded and passed as the URL\nparameter `scope`.",
"scheme": "bearer",
"bearerFormat": "JWT",
"x-bearerInfoFunc": "app.decode_token",
"x-scopes": {
"accounts=rw": "Modify accounts",
"accounts=ro": "Read accounts",
"balance=ro": "Read account balance",
"securities=ro": "Read securities",
"transactions=ro": "Read transactions",
"transactions=rw": "Modify transactions",
"payments=ro": "Read payments",
"payments=rw": "Create/modify payments",
"submit_payments": "Submit payment to service provider",
"user=ro": "Read user information",
"user=rw": "Modify user information"
}
},
"client_auth": {
"x-basicInfoFunc": "app.basic_auth",
"type": "http",
"scheme": "basic",
"description": "Client authentication is performed via [HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication) with client ID as username and client secret as password."
}
}
}
}
```