openapi: 3.0.3 info: title: Customer API description: API to retrieve information about a broker's customers managed by Fonds Finanz makler pool. contact: name: Fonds Finanz Maklerservice GmbH url: https://www.fondsfinanz.de/ email: development@fondsfinanz.de version: 1.1.0 servers: - url: https://api.fondsfinanz.de description: Production paths: /brokers/{brokerId}/customers: get: tags: - Customer summary: List broker customers description: > List broker customers that are managed by Fonds Finanz.
If no result is found with the provided filters, an empty array is returned. operationId: customers.list parameters: - $ref: "#/components/parameters/brokerId" - name: filter[id] in: query description: Filter the customers by Fonds Finanz partner/customer ID. allowEmptyValue: false style: form explode: false schema: type: array items: $ref: "#/components/schemas/DataType.PartnerId" minItems: 1 uniqueItems: true - name: filter[uuid] in: query description: Filter the customers by UUID. allowEmptyValue: false style: form explode: false schema: type: array items: $ref: "#/components/schemas/DataType.Uuid" minItems: 1 uniqueItems: true - name: filter[lastChangedAt.le] in: query description: Filter customers by lastChangedAt, i.e. list all customers with a lastChangedAt before (less than or equal) the given date. allowEmptyValue: false style: form schema: type: string format: date-time example: "2023-09-01T00:51:14Z" - name: filter[lastChangedAt.ge] in: query description: Filter the customers by lastChangedAt, i.e. list all customers with a lastChangedAt after (greater than or equal) the given date. allowEmptyValue: false style: form schema: type: string format: date-time example: "2021-12-31T00:51:14Z" - name: filter[anonymous] in: query description: Filter for anonymous customers. An anonymous customer is not a real customer, but a customer used for pre-enquiries. allowEmptyValue: false style: form explode: false schema: type: boolean example: true - name: filter[deceased] in: query description: Filter the customers by their deceased status. allowEmptyValue: false style: form schema: type: boolean example: "false" - name: page[number] in: query description: | The page number. If the page number exceeds the total number of pages, 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 customers 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/CustomerCollection" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalServerError" /brokers/{brokerId}/customers/{customerUuid}: patch: tags: - Customer summary: Update a customer's data description: Update a customer's data. parameters: - $ref: "#/components/parameters/brokerId" - $ref: "#/components/parameters/customerUuid" requestBody: $ref: "#/components/requestBodies/PartnerUpdate" 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" delete: tags: - Customer summary: Delete customer description: Delete a customer parameters: - $ref: "#/components/parameters/brokerId" - $ref: "#/components/parameters/customerUuid" responses: "204": $ref: "#/components/responses/NoContent" "400": $ref: "#/components/responses/BadRequest" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalServerError" /brokers/{brokerId}/customers/{customerUuid}/address-changes: post: tags: - Customer summary: Create an address change description: Create an address change request for a customer. parameters: - $ref: "#/components/parameters/brokerId" - $ref: "#/components/parameters/customerUuid" requestBody: $ref: "#/components/requestBodies/AddressChange" 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}/customers/{customerUuid}/contact-details: patch: tags: - Customer summary: Create a contact change description: Create a contact change for a customer. parameters: - $ref: "#/components/parameters/brokerId" - $ref: "#/components/parameters/customerUuid" requestBody: $ref: "#/components/requestBodies/ContactChange" 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}/customer-events: get: tags: - Customer summary: List customer events description: List a broker's customer events. parameters: - $ref: "#/components/parameters/brokerId" - name: filter[type] in: query description: Filter the customer events by type. allowEmptyValue: false style: form explode: false schema: type: array items: $ref: "#/components/schemas/DataType.CustomerEventType" minItems: 1 uniqueItems: true - name: filter[publishedAt.ge] in: query description: | Filter the customer events by publish date. i.e. list all customer events that were published on or after the provided date. A response with status code 400 "Bad Request" will be returned if the date specified for the filter `filter[publishedAt.ge]` is not before a potential date for `filter[publishedAt.le]`. allowEmptyValue: false style: form schema: type: string format: date-time example: "2021-12-31T12:00:00Z" - name: filter[publishedAt.le] in: query description: | Filter the customer events by publish date, i.e. list all contract events that where published before or on the provided date. A response with status code 400 "Bad Request" will be returned if the date specified for the filter `filter[publishedAt.le]` is not after a potential date for `filter[publishedAt.le]`. allowEmptyValue: false style: form schema: type: string format: date-time example: "2021-12-31T08:30:00Z" - name: page[number] in: query description: | The page number. If the page number exceeds the total number of pages, 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 customer events 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/CustomerEventCollection" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalServerError" /brokers/{brokerId}/customers/{primaryId}/merge: parameters: - schema: type: string name: brokerId in: path required: true - schema: type: string description: The UUID of the customer the duplicate customers will be merged into. The customer must not be deleted. name: primaryId in: path required: true post: summary: Merge Customers operationId: post-brokers-brokerId-merge responses: 200: $ref: "#/components/responses/CustomerMerged" 400: $ref: "#/components/responses/BadRequest" 404: $ref: "#/components/responses/NotFound" tags: - Customer requestBody: $ref: "#/components/requestBodies/MergeCustomers" description: Merge one or multiple customers into another customer. Customers must not be deleted. components: parameters: brokerId: name: brokerId in: path description: The ID of the broker. required: true schema: $ref: "#/components/schemas/DataType.BrokerId" customerUuid: name: customerUuid in: path description: The UUID of the customer. required: true schema: $ref: "#/components/schemas/DataType.Uuid" schemas: 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.BrokerId: description: Fonds Finanz broker ID. type: string pattern: ^MAK\d{5,7}$ example: MAK12345 DataType.CustomerNo: description: Fonds Finanz number of the broker customer. Not to be confused with the PartnerId! type: string pattern: ^\d{5}$ example: "00002" DataType.PartnerId: description: Fonds Finanz partner/customer (i.e. person or legal entity) ID. type: string pattern: ^MAK\d{5,7}\/\d{5}$ example: MAK12345/00001 DataType.AddressType: description: | Address type. * `PA`: Home address * `FA`: Company address * `NA`: Secondary/alternative address * `NN`: Additional address type: string enum: - PA - FA - NA - NN example: PA DataType.CustomerEventType: description: The customer event type. type: string enum: - ERASED - DELETED - RESTORED - MERGED example: DELETED DataType.Salutation: description: | Salutation (see BiPRO salutation keys) * `0`: Without salutation * `1`: Mr * `2`: Ms * `3`: Company * `4`: Mr and Mrs * `5`: Miss * `6`: Association * `7`: Ladies * `8`: Gentlemen type: string enum: - "0" - "1" - "2" - "3" - "4" - "5" - "6" - "7" - "8" example: "2" Dto.Address: description: | An address. Address can be either of type StreetAddress or PostOfficeBoxAddress. This means that either the field "street" or "postOfficeBox" must be set. oneOf: - $ref: "#/components/schemas/Dto.StreetAddress" - $ref: "#/components/schemas/Dto.PostOfficeBoxAddress" Dto.StreetAddress: description: A street address. type: object additionalProperties: false required: - type - street - postalCode - city - countryCode properties: type: $ref: "#/components/schemas/DataType.AddressType" street: description: The street address including house number. type: string nullable: false example: Riesstraße 25 postOfficeBox: type: string nullable: true example: null 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.PostOfficeBoxAddress: description: A post office box address. type: object additionalProperties: false required: - type - postOfficeBox - postalCode - city - countryCode properties: type: $ref: "#/components/schemas/DataType.AddressType" street: type: string nullable: true example: null postOfficeBox: description: The post office box number. type: string nullable: false 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 properties: phone: description: The phone/landline number. type: string nullable: false example: +49 891588150 mobile: description: The mobile phone number. type: string nullable: false example: +49 1791111111 fax: description: The fax number. type: string nullable: false example: +49 89 1588350 email: description: The email address. type: string nullable: false example: max.mustermann@example.com web: description: The web address. type: string nullable: false example: https://example.com Dto.Partner: description: A partner. discriminator: propertyName: type mapping: PERSON: "#/components/schemas/Dto.Person" LEGAL_ENTITY: "#/components/schemas/Dto.LegalEntity" oneOf: - $ref: "#/components/schemas/Dto.Person" - $ref: "#/components/schemas/Dto.LegalEntity" Dto.PartnerBase: type: object required: - id - uuid - salutation - addresses - contactDetails - lastChangedAt properties: id: $ref: "#/components/schemas/DataType.PartnerId" uuid: $ref: "#/components/schemas/DataType.Uuid" salutation: $ref: "#/components/schemas/DataType.Salutation" addresses: description: The partner's addresses. type: array items: $ref: "#/components/schemas/Dto.Address" contactDetails: $ref: "#/components/schemas/Dto.ContactDetails" lastChangedAt: description: The last changed date of the customer. type: string pattern: date-time example: "2015-01-11T00:51:14Z" Dto.Person: allOf: - $ref: "#/components/schemas/Dto.PartnerBase" description: A (natural) person. required: - type - name - firstName - birthdate properties: type: description: The type of partner that distiguishes the schema of a (natural) person from a legal entity. type: string enum: - PERSON default: PERSON name: description: The person's (last) name. type: string nullable: true example: Mustermann firstName: description: The person's first name. type: string nullable: true example: Max birthdate: description: The person's birthdate. type: string format: date nullable: true example: "1970-01-01" Dto.LegalEntity: allOf: - $ref: "#/components/schemas/Dto.PartnerBase" description: A legal entity. required: - type - name properties: type: description: The type of partner that distinguishes the schema of a legal entity from a (natural) person. type: string enum: - LEGAL_ENTITY default: LEGAL_ENTITY name: description: The legal entity's name (e.g. company name). type: string nullable: true example: Musterfirma GmbH Dto.PartnerUpdate: description: A partner update. discriminator: propertyName: type mapping: PERSON: "#/components/schemas/Dto.PersonUpdate" oneOf: - $ref: "#/components/schemas/Dto.PersonUpdate" Dto.PartnerBaseUpdate: type: object properties: salutation: $ref: "#/components/schemas/DataType.Salutation" Dto.PersonUpdate: allOf: - $ref: "#/components/schemas/Dto.PartnerBaseUpdate" description: A (natural) person update. properties: birthdate: description: The person's birthdate. type: string format: date nullable: false example: "1970-01-01" Dto.AddressChange: description: An address change. type: object additionalProperties: false required: - address properties: address: oneOf: - $ref: "#/components/schemas/Dto.StreetAddress" - $ref: "#/components/schemas/Dto.PostOfficeBoxAddress" Dto.CustomerEvent: oneOf: - $ref: "#/components/schemas/Dto.CustomerErasedEvent" - $ref: "#/components/schemas/Dto.CustomerDeletedEvent" - $ref: "#/components/schemas/Dto.CustomerRestoredEvent" - $ref: "#/components/schemas/Dto.CustomerMergedEvent" discriminator: propertyName: type mapping: ERASED: "#/components/schemas/Dto.CustomerErasedEvent" DELETED: "#/components/schemas/Dto.CustomerDeletedEvent" RESTORED: "#/components/schemas/Dto.CustomerRestoredEvent" MERGED: "#/components/schemas/Dto.CustomerMergedEvent" Dto.CustomerEventBase: type: object required: - publishedAt - customerUuid properties: publishedAt: description: The date/timestamp when the customer event was published. type: string format: date-time example: "2022-07-18T12:00:00Z" customerUuid: allOf: - $ref: "#/components/schemas/DataType.Uuid" description: The UUID (version 4) of the customer the event was recorded for. Dto.CustomerErasedEvent: allOf: - $ref: "#/components/schemas/Dto.CustomerEventBase" description: A customer erased event. required: - type properties: type: description: The type of event that distinguishes the schemas of the different event types. type: string enum: - ERASED default: ERASED example: ERASED Dto.CustomerDeletedEvent: allOf: - $ref: "#/components/schemas/Dto.CustomerEventBase" description: A customer deleted event. required: - type properties: type: description: The type of event that distinguishes the schemas of the different event types. type: string enum: - DELETED default: DELETED example: DELETED Dto.CustomerRestoredEvent: allOf: - $ref: "#/components/schemas/Dto.CustomerEventBase" description: A customer restored event. required: - type properties: type: description: The type of event that distinguishes the schemas of the different event types. type: string enum: - RESTORED default: RESTORED example: RESTORED Dto.CustomerMergedEvent: allOf: - $ref: "#/components/schemas/Dto.CustomerEventBase" description: A contract merged event. required: - type - newCustomerUuid properties: type: description: The type of event that distinguishes the schemas of the different event types. type: string enum: - MERGED default: MERGED example: MERGED newCustomerUuid: allOf: - $ref: "#/components/schemas/DataType.Uuid" description: | The new UUID the customer is identified by starting from the date the event was published. The data of the customer originally identified by `customerUuid` was merged with the data of the customer referenced by `newCustomerUuid` and can be found there now. 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.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.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" requestBodies: PartnerUpdate: required: true description: A customer update request. content: application/merge-patch+json: schema: $ref: "#/components/schemas/Dto.PartnerUpdate" AddressChange: required: true description: | An address change request. Address can be either of type StreetAddress or PostOfficeBoxAddress. This means that either the field "street" or "postOfficeBox" must be set. content: application/json: schema: title: Request.AddressChange description: The address changes. type: array items: $ref: "#/components/schemas/Dto.AddressChange" minItems: 1 ContactChange: required: true description: | A contact change request. Contact can be either of type phone, mobile, fax, email or web. This means that one of the fields "phone","mobile","fax","email" or "web" must be set. content: application/merge-patch+json: schema: $ref: "#/components/schemas/Dto.ContactDetails" MergeCustomers: content: application/json: schema: type: object properties: duplicateCustomerUuids: type: array description: List of customer UUIDs which will be merged into the primary customer. minItems: 1 items: $ref: "#/components/schemas/DataType.Uuid" required: - duplicateCustomerUuids responses: CustomerCollection: description: A customer collection response. content: application/json: schema: title: Response.CustomerCollection type: object additionalProperties: false required: - data - meta properties: data: description: The customers. type: array items: $ref: "#/components/schemas/Dto.Partner" meta: $ref: "#/components/schemas/Dto.CollectionMeta" CustomerEventCollection: description: Customer event collection response. content: application/json: schema: title: Response.CustomerEventCollection type: object additionalProperties: false required: - data - meta properties: data: description: The customer events. type: array items: $ref: "#/components/schemas/Dto.CustomerEvent" meta: $ref: "#/components/schemas/Dto.CollectionMeta" NoContent: description: No content. BadRequest: description: | Bad request response. It 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. It 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. It occurs if a requested resource is not found. content: application/json: schema: title: Response.NotFound allOf: - $ref: "#/components/schemas/Dto.ErrorResponse" UnsupportedMediaType: description: | Unsupported media type response. It occurs if the request payload is in an unsupported format. content: application/json: schema: title: Response.UnsupportedMediaType allOf: - $ref: "#/components/schemas/Dto.ErrorResponse" NotAcceptable: description: | Not acceptable response. It occurs if a reponse matching one of the acceptable MIME types cannot be produced. content: application/json: schema: $ref: "#/components/schemas/Dto.ErrorResponse" InternalServerError: description: | Internal server error response. It occurs in case of an unexpected or fatal error. content: application/json: schema: title: Response.InternalServerError allOf: - $ref: "#/components/schemas/Dto.ErrorResponse" CustomerMerged: description: | The response of a successful merge operation. The response contains the UUID of the primary customer, the UUIDs of the customers that were successfully merged into the primary customer and the UUIDs of the customers that could not be merged. content: application/json: schema: type: object properties: primaryCustomerUUID: $ref: "#/components/schemas/DataType.Uuid" successfulMerges: type: array items: $ref: "#/components/schemas/DataType.Uuid" failedMerges: type: array items: $ref: "#/components/schemas/DataType.Uuid" required: - primaryCustomerUUID - successfulMerges - failedMerges securitySchemes: JWT: type: oauth2 flows: clientCredentials: tokenUrl: https://auth.fondsfinanz.de/oauth2/token scopes: target-entity:d92e4b75-5584-4989-a6af-560106595026: Target API. Must be selected to use this API. security: - JWT: [ target-entity:d92e4b75-5584-4989-a6af-560106595026 ] tags: - name: Customer