openapi: 3.0.3 info: title: Broker API description: API to retrieve information about a broker and manage his data. contact: name: Fonds Finanz Maklerservice GmbH url: https://www.fondsfinanz.de/ email: development@fondsfinanz.de version: 1.0.0 servers: - url: https://api.fondsfinanz.de description: Production paths: /brokers/{brokerId}: get: tags: - Broker summary: Retrieve a broker's data description: Retrieve information about a broker. parameters: - $ref: "#/components/parameters/brokerId" responses: "200": $ref: "#/components/responses/Broker" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "406": $ref: "#/components/responses/NotAcceptable" "500": $ref: "#/components/responses/InternalServerError" /brokers/{brokerId}/addresses: patch: tags: - Broker summary: Update a broker's addresses description: Initiate a partial update of a broker's addresses. parameters: - $ref: "#/components/parameters/brokerId" requestBody: $ref: "#/components/requestBodies/AddressesUpdate" responses: "204": $ref: "#/components/responses/NoContent" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "415": $ref: "#/components/responses/UnsupportedMediaType" "500": $ref: "#/components/responses/InternalServerError" /brokers/{brokerId}/addresses/{type}: delete: tags: - Broker summary: Delete a broker's address description: Delete one of the broker's addresses. parameters: - $ref: "#/components/parameters/brokerId" - name: type in: path description: The type of address to delete. required: true schema: type: string enum: - home responses: "204": $ref: "#/components/responses/NoContent" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalServerError" /brokers/{brokerId}/contact-details: patch: tags: - Broker summary: Update a broker's contact details description: Initiate a partial update of a broker's contact details. parameters: - $ref: "#/components/parameters/brokerId" requestBody: $ref: "#/components/requestBodies/ContactDetailsUpdate" responses: "204": $ref: "#/components/responses/NoContent" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "415": $ref: "#/components/responses/UnsupportedMediaType" "500": $ref: "#/components/responses/InternalServerError" /brokers/{brokerId}/contact-details/{type}: delete: tags: - Broker summary: Delete a broker's contact information description: Delete one of the broker's contact details. parameters: - $ref: "#/components/parameters/brokerId" - name: type in: path description: The type of contact information to delete. required: true schema: type: string enum: - phone - mobile - fax - web responses: "204": $ref: "#/components/responses/NoContent" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalServerError" /brokers/{brokerId}/consulting-contact: put: tags: - Broker summary: Update a broker's consulting contact description: Initiate an update of a broker's consulting contact. parameters: - $ref: "#/components/parameters/brokerId" requestBody: $ref: "#/components/requestBodies/ConsultingContactUpdate" responses: "204": $ref: "#/components/responses/NoContent" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "415": $ref: "#/components/responses/UnsupportedMediaType" "500": $ref: "#/components/responses/InternalServerError" /brokers/{brokerId}/phone-password: put: tags: - Broker summary: Update a broker's phone password description: Initiate an update of a broker's phone password. parameters: - $ref: "#/components/parameters/brokerId" requestBody: $ref: "#/components/requestBodies/PhonePasswordUpdate" responses: "204": $ref: "#/components/responses/NoContent" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "415": $ref: "#/components/responses/UnsupportedMediaType" "500": $ref: "#/components/responses/InternalServerError" /brokers/{brokerId}/subbrokers: get: tags: - Subbroker summary: List subbrokers description: List the direct subbrokers of a broker. parameters: - $ref: "#/components/parameters/brokerId" - name: filter[id] in: query description: Filter the subbrokers by broker ID. allowEmptyValue: false style: form explode: false schema: type: array items: $ref: "#/components/schemas/DataType.BrokerId" uniqueItems: true - name: filter[uuid] in: query description: Filter the subbrokers by broker UUID. allowEmptyValue: false style: form explode: false schema: type: array items: $ref: "#/components/schemas/DataType.Uuid" uniqueItems: true - name: page[number] in: query description: "Page number. If the page number exceeds totalPages, 400 Bad Request is returned." allowEmptyValue: false style: form schema: type: integer default: 1 minimum: 1 - name: page[size] in: query description: "The number of contracts per page. Allowed values are between 1 and 100, otherwise 400 Bad Request is returned." allowEmptyValue: false style: form schema: type: integer default: 30 maximum: 100 minimum: 1 responses: "200": $ref: "#/components/responses/SubbrokerCollection" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "406": $ref: "#/components/responses/NotAcceptable" "500": $ref: "#/components/responses/InternalServerError" /regional-director-structures: get: tags: - Regional Director Structures summary: List all regional directors and the brokers within their structure. description: List all regional directors and the brokers within their structure. parameters: - name: filter[lastChangedAt.ge] in: query description: | Filter list where lastChangedAt of an item is greater than or equal the given date. allowEmptyValue: false style: form schema: type: string format: date-time example: "2022-12-31T12:45:00Z" - name: filter[lastChangedAt.le] in: query description: | Filter list where lastChangedAt of an item is less than or equal the given date. allowEmptyValue: false style: form schema: type: string format: date-time example: "2020-01-01T09:00:00Z" security: - JWT_permission: [ target-entity:e60f95a4-fbb2-47bb-865f-56f2071de005 ] responses: "200": $ref: "#/components/responses/RegionalDirectorsCollection" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalServerError" /introducers: get: tags: - Introducers summary: List all introducers and the brokers within their structure. description: List all introducers and the brokers within their structure. parameters: - name: filter[lastChangedAt.ge] in: query description: | Filter list where lastChangedAt of an item is greater than or equal the given date. allowEmptyValue: false style: form schema: type: string format: date-time example: "2022-12-31T12:45:00Z" - name: filter[lastChangedAt.le] in: query description: | Filter list where lastChangedAt of an item is less than or equal the given date. allowEmptyValue: false style: form schema: type: string format: date-time example: "2020-01-01T09:00:00Z" security: - JWT_permission: [ target-entity:e60f95a4-fbb2-47bb-865f-56f2071de005 ] responses: "200": $ref: "#/components/responses/IntroducersCollection" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalServerError" /brokers/{brokerId}/dpa-status: get: tags: - Data Processing Agreement (DPA) summary: Retrieve DPA status description: Retrieve a broker's DPA status. parameters: - $ref: "#/components/parameters/brokerId" responses: "200": $ref: "#/components/responses/DpaStatus" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "406": $ref: "#/components/responses/NotAcceptable" "500": $ref: "#/components/responses/InternalServerError" /brokers/{brokerId}/dpa-applications: post: tags: - Data Processing Agreement (DPA) summary: Create a DPA application description: Create a DPA application for a broker. parameters: - $ref: "#/components/parameters/brokerId" responses: "201": $ref: "#/components/responses/DpaApplication" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" "500": $ref: "#/components/responses/InternalServerError" /brokers/{brokerId}/dpa-applications/blank: get: tags: - Data Processing Agreement (DPA) summary: Retrieve the blank DPA application description: Retrieve the blank DPA application in PDF format. parameters: - $ref: "#/components/parameters/brokerId" responses: "200": $ref: "#/components/responses/BlankDpaApplication" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "406": $ref: "#/components/responses/NotAcceptable" "500": $ref: "#/components/responses/InternalServerError" /brokers/{brokerId}/dpa-applications/{applicationUuid}/conclusion: post: tags: - Data Processing Agreement (DPA) summary: Conclude a DPA application description: Conclude a DPA contract for a broker. parameters: - $ref: "#/components/parameters/brokerId" - name: applicationUuid in: path description: The UUID of the DPA application. required: true schema: $ref: "#/components/schemas/DataType.Uuid" responses: "204": $ref: "#/components/responses/NoContent" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" "500": $ref: "#/components/responses/InternalServerError" components: parameters: brokerId: name: brokerId in: path description: The ID of the broker. required: true schema: $ref: "#/components/schemas/DataType.BrokerId" schemas: DataType.BrokerId: description: Fonds Finanz broker ID. type: string pattern: ^MAK\d{5,7}$ example: MAK12345 DataType.Uuid: description: UUID (version 4). type: string format: uuid pattern: ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$ example: 10f80a96-4c97-4033-818b-c9e02bf99afd DataType.LegalForm: description: | The legal form (see BiPRO legal form keys). * `02`: GBR * `03`: OHG * `04`: KG * `05`: GmbH * `07`: GmbH & Co KG * `09`: AG * `10`: e.V. * `12`: e.G. * `14`: e.K., e.Kfm., e.Kffr. (eingetragener Kaufmann / eigentragene Kauffrau) * `25`: Ltd (Private Company Limited by Shares) * `45`: Ltd. & Co. KG * `46`: Rechtsform ausländischen Rechts * `55`: UG (haftungsbeschränkt) & Co. KG * `62`: Einzelunternehmen einer sonstigen jurist. Person type: string enum: - "02" - "03" - "04" - "05" - "07" - "09" - "10" - "12" - "14" - "25" - "45" - "46" - "55" - "62" example: "05" DataType.BusinessPartnerId: description: Fonds Finanz business partner ID type: string pattern: ^VP\d{8}$ example: VP01234567 DataType.Salutation: description: | Salutation (see BiPRO salutation keys). * `0`: Without salutation * `1`: Mr * `2`: Ms * `4`: Mr and Mrs type: string enum: - "0" - "1" - "2" - "4" example: "2" DataType.ConsultingContactSalutation: description: | Salutation (see BiPRO salutation keys). * `1`: Mr * `2`: Ms type: string enum: - "1" - "2" example: "2" DataType.Name: description: The broker's last name. type: string nullable: true example: Mustermann DataType.FirstName: description: The broker's first name. type: string nullable: true example: Max DataType.Company: description: The broker's company name. type: string nullable: true example: Max Mustermann GmbH DataType.Email: description: The email address. type: string nullable: true example: max.mustermann@example.com DataType.TaxNumber: description: The broker's tax number. type: string nullable: true example: 123/456/01234 DataType.LoyaltyProgramStatus: description: The loyalty program status. type: string enum: - default - bronze - silver - gold - diamond example: diamond DataType.PhonePassword: description: The phone password. type: string minLength: 6 maxLength: 15 pattern: ^[a-zA-Z0-9]{6,15}$ example: t0pSecret DataType.MoneyLaunderingActStatus: description: | The money laundering act status. * `CERT_NOT_APPLICABLE`: Certification not applicable, i.e. the broker is not subject to the money laundering act. * `CERT_REQUIRED`: Certification is required, i.e. the broker has not yet provided a certification. * `CERT_EXPIRED`: Certification is expired, i.e. the broker must renew his certification. * `CERT_VALID`: Certification is valid. * `UNKNOWN`: The broker's status cannot be determined. type: string enum: - CERT_NOT_APPLICABLE - CERT_REQUIRED - CERT_EXPIRED - CERT_VALID - UNKNOWN example: CERT_VALID Dto.PhonePasswordUpdate: description: A phone password update. type: object additionalProperties: false required: - phonePassword properties: phonePassword: $ref: "#/components/schemas/DataType.PhonePassword" Dto.Broker: description: A broker. type: object additionalProperties: false required: - id - uuid - salutation - name - firstName - company - birthdate - legalForm - addresses - contactDetails - bankDetails - permissions - loyaltyProgram - consultingContact - phonePasswordAssigned - hasSubbrokers - partner_condition - partner_condition_date - partner_type - partner_status - structure_head - role_structure - main_broker properties: id: $ref: "#/components/schemas/DataType.BrokerId" uuid: $ref: "#/components/schemas/DataType.Uuid" salutation: $ref: "#/components/schemas/DataType.Salutation" name: $ref: "#/components/schemas/DataType.Name" firstName: $ref: "#/components/schemas/DataType.FirstName" company: $ref: "#/components/schemas/DataType.Company" birthdate: description: The broker's birthdate. type: string format: date nullable: true example: "1970-01-01" legalForm: nullable: true allOf: - $ref: "#/components/schemas/DataType.LegalForm" addresses: $ref: "#/components/schemas/Dto.Addresses" contactDetails: $ref: "#/components/schemas/Dto.ContactDetails" bankDetails: $ref: "#/components/schemas/Dto.BankDetails" permissions: $ref: "#/components/schemas/Dto.Permissions" loyaltyProgram: nullable: true allOf: - $ref: "#/components/schemas/Dto.LoyaltyProgram" consultingContact: nullable: true allOf: - $ref: "#/components/schemas/Dto.ConsultingContact" phonePasswordAssigned: description: Indicates whether a phone password is assigned. type: boolean example: true hasSubbrokers: description: Indicates whether a broker has subbrokers. type: boolean example: true partner_condition: $ref: "#/components/schemas/Dto.PartnerCondition" partner_condition_date: description: Indicates the partner condition date. type: string example: 2023-09-12 partner_type: $ref: "#/components/schemas/Dto.PartnerType" partner_status: $ref: "#/components/schemas/Dto.PartnerStatus" structure_head: description: Indicates if the broker is a structure head. type: boolean example: true role_structure: description: Indicates the role of the broker. type: string example: Tippgeber main_broker: description: Indicates if it is a main broker. type: boolean example: true Dto.Addresses: description: The addresses. type: object additionalProperties: false required: - home - company properties: home: description: The home address. title: Dto.Address nullable: true allOf: - $ref: "#/components/schemas/Dto.Address" company: description: The company address. title: Dto.Address nullable: true allOf: - $ref: "#/components/schemas/Dto.Address" Dto.AddressesUpdate: description: An addresses update. type: object additionalProperties: false properties: home: description: The home address. title: Dto.Address allOf: - $ref: "#/components/schemas/Dto.Address" company: description: The company address. title: Dto.Address allOf: - $ref: "#/components/schemas/Dto.Address" Dto.Address: type: object additionalProperties: false required: - street - postOfficeBox - postalCode - city - countryCode properties: street: description: The street address including house number. type: string nullable: true example: Riesstraße 25 postOfficeBox: description: The post office box number. type: string nullable: true example: "106438" postalCode: description: The postal code. type: string nullable: true example: "80992" city: description: The city or locality. type: string nullable: true example: München countryCode: description: | The country code. The country codes follow the standardised list of [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1) two-letter codes. type: string pattern: ^[A-Z]{2}$ nullable: true example: DE Dto.ContactDetails: description: The contact details. type: object additionalProperties: false required: - phone - mobile - fax - email - web properties: phone: description: The phone/landline number. type: string nullable: true example: "+49891588150" mobile: description: The mobile phone number. type: string nullable: true example: "+491791111111" fax: description: The fax number. type: string nullable: true example: "+49891588350" email: $ref: "#/components/schemas/DataType.Email" web: description: The web address. type: string nullable: true example: https://example.com Dto.ContactDetailsUpdate: description: A contact details update. type: object additionalProperties: false properties: phone: description: The phone/landline number. type: string example: "+49891588150" mobile: description: The mobile phone number. type: string example: "+491791111111" fax: description: The fax number. type: string example: "+49891588350" email: nullable: false allOf: - $ref: "#/components/schemas/DataType.Email" web: description: The web address. type: string example: https://example.com Dto.BankDetails: description: The bank details. type: object additionalProperties: false required: - accountHolder - iban - bic - bank properties: accountHolder: description: The account holder. type: string nullable: true example: Max Mustermann iban: description: The IBAN. type: string nullable: true example: DE89 3704 0044 0532 0130 00 bic: description: The BIC type: string nullable: true example: COBADEFFXXX bank: description: The bank name. type: string nullable: true example: Commerzbank Dto.RegionalDirector: description: A regional director. type: object required: - id - parentId - type - lastChangedAt - businessPartnerId - salutation - name - firstName - company - bankDetails - taxNumber - email - cluster - loyaltyProgram - commissionPercentage - demvContractValidFrom - demvContractValidUntil - demvExemptionAt properties: id: description: Fonds Finanz broker ID. type: string pattern: ^MAK\d{5,7}$ example: MAK10012 parentId: description: Reference to the superordinate broker. nullable: true type: string pattern: ^MAK\d{5,7}$ example: MAK10001 type: description: | The type of broker. * `RD`: RD (Regional Direktor) * `T`: TOP * `WT`: Standardmakler type: string nullable: false example: "RD" enum: - "RD" - "T" - "WT" lastChangedAt: description: The date broker's data last changed. type: string format: date-time nullable: false example: "2022-12-31T11:42:00Z" businessPartnerId: $ref: "#/components/schemas/DataType.BusinessPartnerId" salutation: $ref: "#/components/schemas/DataType.Salutation" name: $ref: "#/components/schemas/DataType.Name" firstName: $ref: "#/components/schemas/DataType.FirstName" company: $ref: "#/components/schemas/DataType.Company" bankDetails: $ref: "#/components/schemas/Dto.BankDetails" taxNumber: $ref: "#/components/schemas/DataType.TaxNumber" email: $ref: "#/components/schemas/DataType.Email" cluster: description: The cluster the regional director is in. type: string nullable: true example: RDCLUSTERC loyaltyProgram: $ref: "#/components/schemas/Dto.LoyaltyProgram" commissionPercentage: description: The commission percentage. type: string nullable: true example: "80.00" demvContractValidFrom: description: The date from which the contract is valid. type: string format: date-time nullable: false example: "2022-01-01T11:42:00Z" demvContractValidUntil: description: The date until which the contract is valid. type: string format: date-time nullable: false example: "2032-12-31T11:42:00Z" demvExemptionAt: description: The date from which the exemption for the DEMV contract is valid. type: string format: date-time nullable: false example: "2033-01-02T11:42:00Z" Dto.DefaultBrokerForRegionalDirectorStructures: description: A default broker for regional director structures. type: object required: - id - parentId - type - lastChangedAt - businessPartnerId - brokerConsentAt properties: id: $ref: "#/components/schemas/DataType.BrokerId" parentId: description: Reference to the superordinate broker. nullable: true type: string pattern: ^MAK\d{5,7}$ example: MAK10012 type: description: | The type of broker. * `RD`: RD (Regionaldirektor) * `T`: TOP * `WT`: Standardmakler type: string nullable: false example: "WT" enum: - "RD" - "T" - "WT" lastChangedAt: description: The date broker's data last changed. type: string format: date-time nullable: false example: "2022-12-31T11:42:00Z" businessPartnerId: $ref: "#/components/schemas/DataType.BusinessPartnerId" brokerConsentAt: description: The moment when the brokers gave their consent. type: string format: date-time nullable: false example: "2022-12-31T11:42:00Z" Dto.DefaultBrokerForIntroducerStructures: description: A default broker for introducer structures. type: object required: - id - parentId - type - role - contractValid - lastChangedAt - businessPartnerId properties: id: $ref: "#/components/schemas/DataType.BrokerId" parentId: description: Reference to the superordinate broker. nullable: true type: string pattern: ^MAK\d{5,7}$ example: MAK10012 type: description: | The type of broker. * `RD`: RD (Regionaldirektor) * `T`: TOP * `WT`: Standardmakler type: string nullable: false example: "WT" enum: - "RD" - "T" - "WT" role: description: | Indicates whether the broker is of role standard or introducer. * `ZUFUEHRER`: Introducer (Zuführer) * `STD`: Standard broker nullable: false type: string example: "STD" enum: - "ZUFUEHRER" - "STD" contractValid: description: Indicates whether the introducer contract is valid. type: boolean example: true lastChangedAt: description: The date broker's data last changed. type: string format: date-time nullable: false example: "2022-12-31T11:42:00Z" businessPartnerId: $ref: "#/components/schemas/DataType.BusinessPartnerId" Dto.Introducer: description: An introducer. type: object required: - id - parentId - type - role - contractValid - lastChangedAt - businessPartnerId - salutation - name - firstName - company - bankDetails - taxNumber - email - loyaltyProgram - commissionPercentage - demvContractValidFrom - demvContractValidUntil properties: id: description: Fonds Finanz broker ID. type: string pattern: ^MAK\d{5,7}$ example: MAK10012 parentId: description: Reference to the superordinate broker. nullable: true type: string pattern: ^MAK\d{5,7}$ example: MAK10001 type: description: | The type of broker. * `RD`: RD (Regional Direktor) * `T`: TOP * `WT`: Standardmakler type: string nullable: false example: "RD" enum: - "RD" - "T" - "WT" role: description: | Indicates whether the broker is of role standard or introducer. * `ZUFUEHRER`: Introducer (Zuführer) * `STD`: Standard broker nullable: false type: string example: "ZUFUEHRER" enum: - "ZUFUEHRER" - "STD" contractValid: description: Indicates whether the introducer contract is valid. type: boolean example: true lastChangedAt: description: The date broker's data last changed. type: string format: date-time nullable: false example: "2022-12-31T11:42:00Z" businessPartnerId: $ref: "#/components/schemas/DataType.BusinessPartnerId" salutation: $ref: "#/components/schemas/DataType.Salutation" name: $ref: "#/components/schemas/DataType.Name" firstName: $ref: "#/components/schemas/DataType.FirstName" company: $ref: "#/components/schemas/DataType.Company" bankDetails: $ref: "#/components/schemas/Dto.BankDetails" taxNumber: $ref: "#/components/schemas/DataType.TaxNumber" email: $ref: "#/components/schemas/DataType.Email" loyaltyProgram: $ref: "#/components/schemas/Dto.LoyaltyProgram" commissionPercentage: description: The commission percentage. type: string nullable: true example: "80.00" demvContractValidFrom: description: The date from which the introducer contract is valid. type: string format: date-time nullable: false example: "2022-01-01T11:42:00Z" demvContractValidUntil: description: The date until which the introducer contract is valid. type: string format: date-time nullable: false example: "2032-12-31T11:42:00Z" Dto.Permissions: description: The broker permissions/licenses. type: object additionalProperties: false required: - 34c - 34d - 34f - 34i - moneyLaunderingAct properties: 34c: description: Information about the broker's permission acccording to § 34c GewO. type: object additionalProperties: false required: - granted properties: granted: description: | Indicates whether the broker is permitted to arrange loan agreements according to § 34c GewO. type: boolean example: true 34d: description: Information about the broker's permission according to § 34d GewO. type: object additionalProperties: false required: - granted - registrationId properties: granted: description: | Indicates whether the broker is permitted to arrange insurance contracts according to § 34d GewO. type: boolean example: true registrationId: description: The broker's registration ID according to § 34d GewO. type: string nullable: true example: D-DJ15-X1S59-77 34f: description: Information about the broker's permission according to § 34f GewO. type: object additionalProperties: false required: - granted - realAssetsGranted - fundsGranted - othersGranted - registrationId properties: granted: description: | Indicates whether the broker is generally permitted to arrange financial investments according to § 34f GewO. type: boolean example: true realAssetsGranted: description: | Indicates whether the broker is permitted to arrange investments into real assets according to § 34f GewO. type: boolean example: true fundsGranted: description: | Indicates whether the broker is permitted to arrange investments into funds according to § 34f GewO. type: boolean example: true othersGranted: description: | Indicates whether the broker is permitted to arrange investments into other financial assets according to § 34f Gewo. type: boolean example: true registrationId: description: The broker's registration ID according to § 34f GewO. type: string nullable: true example: D-F-155-FERG-48 34i: description: Information about the broker's permission according to § 34i GewO. type: object additionalProperties: false required: - granted - registrationId properties: granted: description: | Indicates whether the broker is permitted to arrange real estate loans according to § 34i GewO. type: boolean example: true registrationId: description: The broker's registration ID according to § 34i GewO. type: string nullable: true example: D-W-155-XFAE-32 moneyLaunderingAct: description: Information about a broker's status regarding the money laundering act (GwG). type: object additionalProperties: false required: - status - expiresAt properties: status: $ref: "#/components/schemas/DataType.MoneyLaunderingActStatus" expiresAt: description: | The date when the broker's money laundring act certificate will expire. If the broker is not required to take a certification or he has not yet provided any certification (see `status`), `expiresAt` is `null`. type: string format: date-time nullable: true example: "2022-12-31T00:00:00Z" Dto.LoyaltyProgram: description: The loyalty program information. type: object additionalProperties: false required: - id - status properties: id: description: The loyalty program ID. type: string example: 3C-ID-003137 status: $ref: "#/components/schemas/DataType.LoyaltyProgramStatus" Dto.ConsultingContact: description: The contact information to be used in consulting contexts, e.g. in (third-party) comparison portals. type: object additionalProperties: false required: - salutation - name - firstName properties: salutation: $ref: "#/components/schemas/DataType.ConsultingContactSalutation" name: $ref: "#/components/schemas/DataType.Name" firstName: $ref: "#/components/schemas/DataType.FirstName" Dto.DpaApplication: description: A data processing agreement (DPA) application. type: object additionalProperties: false required: - uuid - version - createdAt - expiresAt - content properties: uuid: $ref: "#/components/schemas/DataType.Uuid" version: description: The DPA version information. type: string format: date example: "2022-09-07" createdAt: description: The DPA application's creation date. type: string format: date-time example: "2022-09-07T16:00:00Z" expiresAt: description: The DPA application's expiry date, i.e. when a generated DPA application will be invalidated type: string format: date-time example: "2022-09-07T18:00:00Z" content: description: The content of the DPA application personalized for the broker. type: string example: The DPA application content Dto.DpaStatus: description: The data processing agreement (DPA) status of a broker. type: object additionalProperties: false required: - valid - expiresAt - concludedVersion - latestVersion properties: valid: description: | Indicates whether a broker concluded/accepted the DPA. `valid` is `false` if a broker never concluded/accepted the DPA or if there exists a new DPA version and his DPA acceptance expired (see `expiresAt`). type: boolean example: true expiresAt: description: | If a broker has already accepted a DPA in the past (see `valid` and `concludedVersion`) and there exists a new DPA version (see `latestVersion`), this property defines the date when a broker's DPA acceptance will expire. After this date a broker's DPA acceptance will be invalidated (`valid` will be `false`) and he must be forced to conclude/accept the latest DPA version. If a broker has not yet concluded/accepted the DPA (`valid` is `false`) or there exists no new DPA version, `expiresAt` is `null`. type: string format: date-time nullable: true example: "2022-10-08T00:00:00Z" concludedVersion: description: | The DPA version the broker has concluded/accepted. If the broker has not yet concluded/accepted any DPA, `concludedVersion` is `null`. type: string format: date nullable: true example: "2022-09-07" latestVersion: description: The latest version of the DPA. type: string format: date example: "2022-10-07" Dto.Subbroker: description: A subbroker. type: object additionalProperties: false required: - id - uuid - name - firstName - company - birthdate - contractCount - organizationProtectionUntil properties: id: $ref: "#/components/schemas/DataType.BrokerId" uuid: $ref: "#/components/schemas/DataType.Uuid" name: description: The subbroker's name. type: string nullable: true example: Mustermann firstName: description: The subbroker's first name. type: string nullable: true example: Max company: description: The subbroker's company name. type: string nullable: true example: Max Mustermann GmbH birthdate: description: The subbroker's birthdate. type: string format: date nullable: true example: "1970-01-01" contractCount: description: The subbroker's number of contracts. type: integer minimum: 0 example: 150 organizationProtectionUntil: description: The date until which a broker is governed by the Fonds Finanz organization protection. type: string format: date nullable: true example: "2022-12-31" Dto.CollectionMeta: description: A collection response meta data. type: object additionalProperties: false required: - totalItems - totalPages - pageNumber - pageSize properties: totalItems: description: The total number of items for the collection. type: integer example: 140 totalPages: description: The total number of pages for the collection. type: integer example: 5 pageNumber: description: The page number. type: integer example: 2 pageSize: description: The page size. type: integer example: 30 Dto.Error: description: An error. type: object additionalProperties: false required: - message properties: message: description: | The error message. A human-readable representation of the error that occured. _Please note:_ This error message may be subject to change even without a version change of the API. Thus do not rely on it for deterministic processing of an error. Use the HTTP status code instead in order to identify an error in general and its error class. type: string Dto.ErrorMeta: description: An error response meta data. type: object additionalProperties: false required: - traceId properties: traceId: description: An ID that allows Fonds Finanz developers to trace an error. type: string minLength: 8 maxLength: 8 example: "string" Dto.ErrorResponse: description: An error response. type: object additionalProperties: false required: - error - meta properties: error: $ref: "#/components/schemas/Dto.Error" meta: $ref: "#/components/schemas/Dto.ErrorMeta" Dto.PartnerStatus: description: Indicates the status of partnership. type: string enum: - VOST - MABE - AKTIV - INAKTIV - GESP - FEUN - VPSTOP example: AKTIV x-enum-descriptions: VOST: Vollständig MABE: Maklerbeweis AKTIV: Aktiv INAKTIV: Inaktiv GESP: Gesperrt FEUN: Fehlende Unterlagen VPSTOP: Vollst. PROV.STOP Dto.PartnerCondition: description: Indicates the partner condition. type: string enum: - TOT - INSOLV - INKASS - PFAEND - KUENDFF - KUENDMAK - LEER - MAHN - AUSSERGERSCHULDBEREIN example: KUENDMAK x-enum-descriptions: TOT: verstorben INSOLV: insolvent INKASS: Inkasso Verfahren PFAEND: Pfändung KUENDFF: Kündigung seitens FF KUENDMAK: Kündigung seitens MAK LEER: kein Zustand MAHN: Mahnverfahren AUSSERGERSCHULDBEREIN: Außergerichtliches Schuldenbereinigungsverfahren Dto.PartnerType: description: Indicates the type of partnership. type: string enum: - INVSTMAK - BF - UNBK - BS - IM - GVV - VVME - VVMEB - VMME - FI - M - T - WT - OF - GF - RD - VG - DG - RK - BESTVERK - TIPPGBR - PROV200 - XXL - FFBEST - FFBESTRENT example: VMME x-enum-descriptions: INVSTMAK: Investmentmakler BF: Baufinanzierung UNBK: Unbekannt BS: Bausparkasse IM: Immobilien GVV: Geb. Versicherungsvertreter VVME: Versicherungsvertreter VVMEB: Versicherungsvertreter mit Erlaubnisbefreiung VMME: Versicherungsmakler FI: Finanzierungen M: Master T: TOP WT: Standardmakler OF: Offene Fonds GF: Geschlossene Fonds RD: RD VG: Versicherungsgesellschaft DG: Dummy Gesellschaft RK: Ratenkredit BESTVERK: Bestandsverkäufer TIPPGBR: Tippgeber PROV200: PROV-200 XXL: XXL FFBEST: FF Bestandsbetreuer FFBESTRENT: FF Bestandsbetreuer (Rente) requestBodies: AddressesUpdate: required: true description: An addresses update request. content: application/merge-patch+json: schema: $ref: "#/components/schemas/Dto.AddressesUpdate" ContactDetailsUpdate: required: true description: A contact details update request. content: application/merge-patch+json: schema: $ref: "#/components/schemas/Dto.ContactDetailsUpdate" ConsultingContactUpdate: required: true description: A consulting contact update request. content: application/json: schema: $ref: "#/components/schemas/Dto.ConsultingContact" PhonePasswordUpdate: required: true description: A phone password update request. content: application/json: schema: $ref: "#/components/schemas/Dto.PhonePasswordUpdate" responses: Broker: description: Broker data response. content: application/json: schema: title: Response.Broker type: object additionalProperties: false required: - data - meta properties: data: $ref: "#/components/schemas/Dto.Broker" meta: description: Response meta data. type: object additionalProperties: false default: {} SubbrokerCollection: description: Subbroker collection response. content: application/json: schema: title: Response.SubbrokerCollection type: object required: - data - meta properties: data: description: The subbrokers. type: array items: $ref: "#/components/schemas/Dto.Subbroker" meta: $ref: "#/components/schemas/Dto.CollectionMeta" RegionalDirectorsCollection: description: Regional directors collection response. content: application/json: schema: title: Response.RegionalDirectorsCollection type: object required: - data - meta properties: data: description: The regional directors. type: array items: oneOf: - $ref: "#/components/schemas/Dto.DefaultBrokerForRegionalDirectorStructures" - $ref: "#/components/schemas/Dto.RegionalDirector" meta: description: Response meta data. type: object additionalProperties: false default: { } IntroducersCollection: description: Introducers collection response. content: application/json: schema: title: Response.IntroducersCollection type: object required: - data - meta properties: data: description: The introducers. type: array items: oneOf: - $ref: "#/components/schemas/Dto.Introducer" - $ref: "#/components/schemas/Dto.DefaultBrokerForIntroducerStructures" meta: description: Response meta data. type: object additionalProperties: false default: { } DpaApplication: description: DPA application response. content: application/json: schema: title: Response.DpaApplication type: object additionalProperties: false required: - data - meta properties: data: $ref: "#/components/schemas/Dto.DpaApplication" meta: description: Response meta data. type: object additionalProperties: false default: {} BlankDpaApplication: description: Blank DPA application response. content: application/pdf: schema: type: string format: binary DpaStatus: description: DPA status response. content: application/json: schema: title: Response.DpaStatus type: object additionalProperties: false required: - data - meta properties: data: $ref: "#/components/schemas/Dto.DpaStatus" meta: description: Response meta data. type: object additionalProperties: false default: {} NoContent: description: No content. BadRequest: description: | Bad request response. Occurs if a request is semantically incorrect (e.g. path parameters, query parameters or request body). content: application/json: schema: title: Response.BadRequest allOf: - $ref: "#/components/schemas/Dto.ErrorResponse" Unauthorized: description: | Unauthorized response. Occurs if no or an insufficient authorization token is provided. content: application/json: schema: title: Response.Unauthorized allOf: - $ref: "#/components/schemas/Dto.ErrorResponse" NotFound: description: | Not found response. Occurs if a requested resource is not found. content: application/json: schema: title: Response.NotFound allOf: - $ref: "#/components/schemas/Dto.ErrorResponse" NotAcceptable: description: | Not acceptable response. Occurs if a response matching one of the acceptable MIME types cannot be produced. content: application/json: schema: title: Response.NotAcceptable allOf: - $ref: "#/components/schemas/Dto.ErrorResponse" Conflict: description: | Conflict response. Occurs if a request conflicts with the current state of the target resource. content: application/json: schema: title: Response.Conflict allOf: - $ref: "#/components/schemas/Dto.ErrorResponse" UnsupportedMediaType: description: | Unsupported media type response. Occurs if the request payload is in an unsupported format. content: application/json: schema: title: Response.UnsupportedMediaType allOf: - $ref: "#/components/schemas/Dto.ErrorResponse" InternalServerError: description: | Internal server error response. Occurs in case of an unexpected or fatal error. content: application/json: schema: title: Response.InternalServerError allOf: - $ref: "#/components/schemas/Dto.ErrorResponse" securitySchemes: JWT: type: oauth2 description: Fonds Finanz OAuth code flow flows: authorizationCode: authorizationUrl: https://auth.fondsfinanz.de/oauth2/authorize tokenUrl: https://auth.fondsfinanz.de/oauth2/token scopes: openid: Request an id token. offline_access: Request a refresh token. email: Request an email address. profile: Request profile data. JWT_permission: type: oauth2 description: Fonds Finanz OAuth permission flows: clientCredentials: tokenUrl: https://auth.fondsfinanz.de/oauth2/token scopes: target-entity:e60f95a4-fbb2-47bb-865f-56f2071de005: Target API. Must be selected to use this API. security: - JWT: - openid - offline_access - email - profile tags: - name: Broker - name: Data Processing Agreement (DPA) - name: Subbroker - name: Regional Director Structures - name: Introducers