Interhyp financing-application API

openapi: 3.2.0
info:
  title: Interhyp Submission Financing Application API
  version: 6.10.0
  contact:
    name: Interhyp AG (Team Provider Excellence)
    email: support_submission_api@interhyp.de
    url: https://www.interhyp.de
  license:
    name: Interhyp AG
  description: "This document describes the RESTful API and resources provided by Interhyp AG.<p> The RESTful API provides access to resources associated with submission process via *URI* paths, a client application will make an HTTP request using standard HTTP methods like *GET, PUT, POST and DELETE* and parse the response in *JSON* format.<p>\n## API Audience <br/>\nThe API is intended to be consumed by clients who want to integrate Interhyp submission process in their own workflow.\n+ Financing Partners\n## API design Principles <br/>\nDuring API design a set of principles were taken into consideration.\n+ API First\n+ Mobile First\n\n> API Endpoints provided by this RESTful API adhere to HTTP methods and hence are divided into two categories:\n+ Command Endpoints: represents HTTP methods *POST, PUT, PATCH and DELETE* where side effects are expected after calling such endpoints.\n+ Query Endpoints: represents HTTP method *GET* where no side effects could be expected.\n\n## Version and URI <br/>\nThis documentation is for **version 2** of submission API, which is currently the latest version.<p> The URIs for resources have the following structure: ``` https://<interhyp-url>/submission/v2/<resource-name> ``` <br/> For Example ``` https://api-test.interhyp.de/submission/v2/submissions/my-awesome-submission/financing-application ```\n## Security <br/>\n### Authentication <br/>\nIn order to grant access to the API resources, every client has to declare his identity using a `JWT` based Token. <br/> `OAuth 2.0` is used to secure all the API endpoints, See [Authentication Concept](docs/partners_authentication.pdf) for more details. <br/>\n### Authorization and Permissions <br/>\nAccess to the API resources is restricted to the target client, where a client may access only the resources that belong to him. Resources belong to a specific client are by no mean accessible by any other client with different identity. <br/>\n![API Authentication and Authorization](docs/sbm-api-security-diagram.png \"API Authentication and Authorization\")\n## Pagination, Expansion, and Deferred Processing <br/>\nPromoting Mobile First design principle requires employing a set of concepts as described below\n### Pagination\nThis API uses *Cursor-based* pagination to improve performance and minimize networks traffic, Pagination is enforced for operations that potentially could return a large collection of items. When a client makes a request to a paginated resource, the response wraps the returned array of values in a JSON object with paging metadata. For example: **<details>\n        <summary>Sample Response</summary>**\n  ```json\n  {\n    \"data\": [\n      \"_comment: here goes the actual resource collection ...\"\n    ],\n    \"paging\": {\n      \"cursor\": {\n        \"before\": \"string\",\n        \"after\": \"string\"\n      },\n      \"previous\": \"string\",\n      \"next\": \"string\"\n    }\n  }\n  ```\n</details>\n\nA cursor refers to a random string of characters which marks a specific item in a collection of data. <br/> The cursor will always point to the item, however it will be invalidated if the item is deleted or removed.\n> Therefore, as a client you shouldn't store cursors or assume that they will be valid in the future.\nA cursor-paginated resource supports the following parameters:\n* **_before_** : This is the cursor that points to the start of the page of data that has been returned.\n* **_after_** : This is the cursor that points to the end of the page of data that has been returned.\n* **_limit_** : This is the maximum number of objects that may be returned. A query may return fewer than the value of limit due to filtering. Do not depend on the number of results being fewer than the limit value to indicate that your query reached the end of the list of data, use the absence of `next` instead as described below.\n* **_previous_** : A Hyperlink that will return the previous page of data. If not included, this is the first page of data.\n* **_next_** : A Hyperlink that will return the next page of data. If not included, this is the last page of data.\n> The Absence of *next* hyperlink indicates that a query reached the end of the available result.\n### Expansion <br/>\nThis API uses *resource expansion*, which means that some parts of a resource are not returned unless specified in the request. This is useful for endpoints that return large resources in order to minimizes network traffic. <br/> The expansion is controlled as following:\n#### Query Parameter\n**_embed_** query parameter controllers which information the endpoint will deliver.\n> **By default:** *embed* query parameter is set to *False*, which means only basic information and a link for details and sub-resources will be returned.\nSetting *embed* query parameter to *True* guides the API to deliver all details and sub-resources associated with the requested resource.\n\n> **Tip:** Doing so will have a direct impact on the payload size and might affect response time as well.\nWe encourage following the provided links to access each specific resource, instead of providing all sub-resources for the returned collection.<br />\n\n**<details>\n        <summary>Sample Response</summary>**\n  ```json\n    {\n      \"data\": [\n        {\n          \"resource\": {\n            \"href\": \"http://some-domain/some/link/to/somewhere\",\n            \"embedded\": {\n              \"resource\": [\n                {\n                  \"detailed-attribute-1\": \"string\",\n                  \"detailed-attribute-2\": \"string\",\n                  \"detailed-attribute-3\": \"2019-11-29T18:24:49.777Z\",\n                  \"detailed-attribute-n\": \"string\"\n                }\n              ]\n            }\n          }\n        }\n      ]\n    }\n  ```\n</details>\n\n### Deferred Processing\nSome API endpoints may trigger long-running or computationally expensive tasks. In these cases, the endpoint will schedule an asynchronous command in order not to block the client for the whole processing time and as a result an appropriate *HTTP Status Code* indicates the asynchronous processing and a *commandId* will be returned.\n\nIn order to check for the status of the created command, section **_Commands_** provides *GET* endpoint to retrieve relevant information associated with the created command. For Example ``` GET https://api-test.interhyp.de/submission/v2/commands/my-awesome-command-id ```\n> **Tip:** More details will be provided in the respective endpoint.\n\n## Deprecation Policy <br/>\nAs the API evolves, fields may be replaced by other fields to better reflect the target structure or new requirements. We mark such fields as deprecated and document in the field's description the reason why it has been deprecated and provide information on the new field that should be used instead. We will communicate the planned end-of-life date for a deprecated field in its description once it is set.\nDuring the period when both fields are available, they will return the same result until the deprecated field reaches its end of life. However, to avoid any issues that may arise when the deprecated field is eventually removed from the API, we strongly recommend updating your code as soon as possible to use the new field.\n### Example\nPreviously, an applicant would have the fields `address` and `previousAddress`. Each would return a single address. We later introduced the field `livingAddresses` which returns an array of addresses and the date range in which they were used. The fields `address` and `previousAddress` were marked as deprecated, as the information could be obtained through the `livingAddresses` field. Still, we ensured that the `address` and `previousAddress` would return the correct data even for applicants which were created only with `livingAddresses`.\n\n## API client <br/>\nAs an API client you should adhere to the following robustness principle\n\n  + Tolerant Reader: Be tolerant with unknown fields in the payload. This is required to avoid new API versions if\n  new fields were added, i.e. ignore new fields but do not eliminate them from payload if needed\n  for subsequent *PUT* requests.\n\n  + Be prepared to handle HTTP status codes not explicitly specified in endpoint definitions.\n\n\n> **Tip:** In this API Open-Ended list of values (x-extensible-enum) instead of Enumerations are used\nEnumerations are per definition closed sets of values, that are assumed to be complete and not intended for extension. This closed principle of enumerations imposes compatibility issues when an enumeration must be extended.\n\nThis RESTful API has following sections, each interact with a specific part of the submission system.\n+ **_submissions_**: Provides endpoints for resources associated with a specific financing partner. For Example, accessing a specific submission resource, or searching all open submissions belong to a specific financing partner within a specific period of time.\n+ **_financing-application_**: Provides endpoints for resources not associate to a specific financing partner. Here all information collected from the Applicant during consultation phase could be delivered, such as Personal details, Credit Worthiness, desired Estate, etc ...\n+ **_logbook_**: Provides endpoints for submission logbook entries.\n+ **_commands_**: Provides endpoints for command resources, see *Deferred Processing*\n+ **_correspondence_**: Is currently still under design.\n\nThis RESTful API was created based on [OpenAPI 3.0 specification](http://spec.openapis.org/oas/v3.0.2)\nBy using the [OpenAPI-Spec generator](https://github.com/OpenAPITools/openapi-generator), you can easily generate an API client stub.\n> **Tip:** This API could be also viewed in [swagger editor](https://editor.swagger.io/) by copy/paste the content of this document in the editor."
servers:
- url: https://api-dev.ehyphome.de/submission/v2
  description: Test-Staging
- url: https://api-acc.ehyphome.de/submission/v2
  description: Acceptance-Staging
- url: https://api.interhyp.de/submission/v2
  description: Production
security:
- ApiKey: []
  BearerAuth: []
tags:
- name: financing-application
  description: provides endpoints for financing application resources not associate to a specific financing partner
paths:
  /financing-applications/{financingApplicationId}:
    get:
      summary: Get a exisiting financing application
      description: 'Delivers information about existing financing application

        '
      operationId: getFinancingApplicationById
      tags:
      - financing-application
      parameters:
      - $ref: '#/components/parameters/financing-application-id'
      - $ref: '#/components/parameters/embed'
      responses:
        '200':
          description: Financing application is returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancingApplication'
        '400':
          description: Error indicates missing or wrong request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
        '401':
          description: Error indicates no access to the required resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthProblem'
        '404':
          description: Error indicates that a requested financing application resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
  /financing-applications/{financingApplicationId}/applicant-relationships:
    get:
      summary: Get a list of applicant-relationships
      description: 'Delivers information about the relationship of the applicants involved in this financing application.

        '
      operationId: getApplicantRelationshipsByFinancingApplicationId
      tags:
      - financing-application
      parameters:
      - $ref: '#/components/parameters/financing-application-id'
      responses:
        '200':
          description: requested applicant relationsships are returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicantRelationshipsQuery'
        '400':
          description: Error indicates missing or wrong request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
        '401':
          description: Error indicates no access to the required resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthProblem'
        '404':
          description: Error indicates that the financing application resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
  /financing-applications/{financingApplicationId}/applicants:
    get:
      summary: Get applicants for a specific submission package.
      description: Delivers detailed information for applicants associated with this submission.
      operationId: getApplicantsByFinancingApplicationId
      tags:
      - financing-application
      parameters:
      - $ref: '#/components/parameters/financing-application-id'
      - $ref: '#/components/parameters/embed'
      responses:
        '200':
          description: Requested applicants are returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Applicants'
        '400':
          description: Error indicates missing or wrong request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
        '401':
          description: Error indicates no access to the required resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthProblem'
        '404':
          description: Error indicates that a requested submission resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
  /financing-applications/{financingApplicationId}/applicants/{applicantId}:
    get:
      summary: Get a specific mortgage applicant
      description: Delivers detailed information for mortgage applicant by his id.
      operationId: getApplicantById
      tags:
      - financing-application
      parameters:
      - $ref: '#/components/parameters/financing-application-id'
      - $ref: '#/components/parameters/applicant-id'
      responses:
        '200':
          description: Requested applicant is returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Applicant'
        '400':
          description: Error indicates missing or wrong request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
        '401':
          description: Error indicates no access to the required resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthProblem'
        '404':
          description: Error indicates that a requested applicant resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
  /financing-applications/{financingApplicationId}/applicants/{applicantId}/financial-standings:
    get:
      summary: Get applicant financial standings
      description: 'Delivers detailed information about an applicant financial standings associated with this financing application.


        Including periodical income, expenses, general equity and debts'
      operationId: getFinanceStandingsForApplicant
      tags:
      - financing-application
      parameters:
      - $ref: '#/components/parameters/financing-application-id'
      - $ref: '#/components/parameters/applicant-id'
      - $ref: '#/components/parameters/financial-standing-filter'
      - $ref: '#/components/parameters/embed'
      responses:
        '200':
          description: Requested applicant financial standings are returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialStandings'
        '400':
          description: Error indicates missing or wrong request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
        '401':
          description: Error indicates no access to the required resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthProblem'
        '404':
          description: Error indicates that a requested submission resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
  /financing-applications/{financingApplicationId}/consultation:
    get:
      summary: Get financing consultation
      description: Delivers detailed information about the consultation associated with this financing application.
      operationId: getConsultationByFinancingApplicationId
      tags:
      - financing-application
      parameters:
      - $ref: '#/components/parameters/financing-application-id'
      responses:
        '200':
          description: Requested financing consultation returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Consultation'
        '400':
          description: Error indicates missing or wrong request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
        '401':
          description: Error indicates no access to the required resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthProblem'
        '404':
          description: Error indicates that a requested submission resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
  /financing-applications/{financingApplicationId}/estates:
    get:
      summary: Get estates for a specific financing application.
      description: Delivers detailed information for the estates associated with this financing application. Estate could have a role as an object to be financed, an equity item or a guarantee (security).
      operationId: getEstatesByFinancingApplicationId
      tags:
      - financing-application
      parameters:
      - $ref: '#/components/parameters/financing-application-id'
      - $ref: '#/components/parameters/embed'
      responses:
        '200':
          description: Requested estates are returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Estates'
        '400':
          description: Error indicates missing or wrong request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
        '401':
          description: Error indicates no access to the required resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthProblem'
        '404':
          description: Error indicates that a requested financing application resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
  /financing-applications/{financingApplicationId}/estates/{estateId}:
    get:
      summary: Get a specific estate.
      description: Delivers detailed information for an estate by it's id.
      operationId: getEstateById
      tags:
      - financing-application
      parameters:
      - $ref: '#/components/parameters/estate-id'
      - $ref: '#/components/parameters/financing-application-id'
      responses:
        '200':
          description: Requested estate is returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Estate'
        '400':
          description: Error indicates missing or wrong request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
        '401':
          description: Error indicates no access to the required resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthProblem'
        '404':
          description: Error indicates that a requested mortgage property resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
  /financing-applications/{financingApplicationId}/financial-standings:
    get:
      summary: Get applicants financial standings
      description: 'Delivers detailed information about the applicants financial standings associated with this financing application as provided by the applicant during the consultation phase.


        Including periodical Income, Expenses, General Equity and Debts'
      operationId: getFinanceStandingsByFinancingApplicationId
      tags:
      - financing-application
      parameters:
      - $ref: '#/components/parameters/financing-application-id'
      - $ref: '#/components/parameters/financial-standing-filter'
      - $ref: '#/components/parameters/embed'
      responses:
        '200':
          description: Requested financial standings associated with this financing application are returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialStandings'
        '400':
          description: Error indicates missing or wrong request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
        '401':
          description: Error indicates no access to the required resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthProblem'
        '404':
          description: Error indicates that a requested submission resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
  /financing-applications/{financingApplicationId}/financial-standings/existing-loans/{debtId}:
    get:
      summary: Get a specific existing loan.
      description: Delivers detailed information for existing loan by it's id.
      operationId: getExistingLoanById
      tags:
      - financing-application
      parameters:
      - $ref: '#/components/parameters/financing-application-id'
      - $ref: '#/components/parameters/debt-id'
      responses:
        '200':
          description: Requested existing loan is returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExistingLoanDebt'
        '400':
          description: Error indicates missing or wrong request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
        '401':
          description: Error indicates no access to the required resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthProblem'
        '404':
          description: Error indicates that a requested existing morgage resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
  /financing-applications/{financingApplicationId}/financial-standings/{financialStandingId}:
    get:
      summary: Get a specific financial standing
      description: 'Delivers detailed information about a specific financial standing associated with this submission package.


        Including periodical income, expenses, general equity and debts'
      operationId: getFinanceStandingsById
      tags:
      - financing-application
      parameters:
      - $ref: '#/components/parameters/financing-application-id'
      - $ref: '#/components/parameters/financial-standing-id'
      responses:
        '200':
          description: Requested financial standing is returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialStanding'
        '400':
          description: Error indicates missing or wrong request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
        '401':
          description: Error indicates no access to the required resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthProblem'
        '404':
          description: Error indicates that a requested submission resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
  /financing-applications/{financingApplicationId}/households:
    get:
      summary: Get applicants household
      description: Delivers detailed information about the applicants households associated with this financing application.
      operationId: getHouseholdsByFinancingApplicationId
      tags:
      - financing-application
      parameters:
      - $ref: '#/components/parameters/financing-application-id'
      responses:
        '200':
          description: Requested households information are returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HouseholdsQuery'
        '400':
          description: Error indicates missing or wrong request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
        '401':
          description: Error indicates no access to the required resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthProblem'
        '404':
          description: Error indicates that a requested submission resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
  /financing-applications/{financingApplicationId}/informers:
    get:
      summary: Get consultation informers
      description: "Delivers detailed information about the consultation informers associated with this submission.\n\nThis endpoint utilizes *Expansion* feature, where *by default* only basic information shall be returned. In order to access more full details, two options are available\n\n  - follow provided links in order to navigate to submission sub-resources (i.e /v2/submissions/{submissionId}/overview)\n\n  - initiate the call with request parameter `embed` set to *TRUE* (i.e /v2/submissions/{submissionId}?embed=true)\n\nPlease refer to *Expansion* section for more details."
      operationId: getFinancingApplicationInformers
      tags:
      - financing-application
      parameters:
      - $ref: '#/components/parameters/financing-application-id'
      - $ref: '#/components/parameters/embed'
      responses:
        '200':
          description: Requested mortgage informers are returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Informers'
        '400':
          description: Error indicates missing or wrong request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
        '401':
          description: Error indicates no access to the required resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthProblem'
        '404':
          description: Error indicates that a requested submission resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
  /financing-applications/{financingApplicationId}/informers/{informerId}:
    get:
      summary: Get a specific mortgage informer
      description: Delivers detailed information for mortgage informer by his id.
      operationId: getFinancingApplicationInformerById
      tags:
      - financing-application
      parameters:
      - $ref: '#/components/parameters/financing-application-id'
      - $ref: '#/components/parameters/informer-id'
      responses:
        '200':
          description: Requested informer is returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Informer'
        '400':
          description: Error indicates missing or wrong request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFC7807Problem'
        '401':
          description: Error indicates no access to the required resource.
          content:
            applicati

# --- truncated at 32 KB (327 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/interhyp/refs/heads/main/openapi/interhyp-financing-application-api-openapi.yml