Masterdata Matching Service

Purpose

This docker image provides a REST API service for managing master data (Business Units, Suppliers, Addresses) and includes fuzzy matching functionality for searching and linking records.

Features:

• Manage company entities (Business Units)
• Manage suppliers and link them to business units
• Manage addresses for business units
• Fuzzy matching to identify business units and suppliers based on inexact attribute data

System requirements

To run the Masterdata Matching Service, Docker must be installed on your system.

• You can find installation instructions for Docker on the official website: Get Docker
• Make sure that Docker and, if necessary, Docker Compose are installed in a current version.
• Verify your installation with:

docker --version
docker compose version

Deployment

You can run the masterdata matching service using Docker Compose for easy deployment.

Create a file named .env in the project root directory with the following content:

API_TOKEN=changeme-secure-token
BU_THRESHOLD=90
SUPPLIER_THRESHOLD=80
# New in version 1.0.3
MATCH_WEIGHT_NAME=0.5
MATCH_WEIGHT_ADDRESS=0.15
MATCH_WEIGHT_CITY=0.1
MATCH_WEIGHT_POSTAL=0.05
MATCH_WEIGHT_TAXID=0.1
MATCH_WEIGHT_IBAN=0.1

info

Results below the threshold are ignored. The total weight must be 1.

An API token can be generated with the following command.

openssl rand -base64 32

If OpenSSL is not installed, proceed as follows:

• Open the terminal and select PowerShell in VS Code.

• Use the following command to generate a cryptographically secure key using RNGCryptoServiceProvider.

• After generating the key, add it to the .env file without quotation marks.

$bytes = New-Object byte[] 32
$rng = New-Object System.Security.Cryptography.RNGCryptoServiceProvider
$rng.GetBytes($bytes)
$rng.Dispose()
[Convert]::ToBase64String($bytes)

Create a file named docker-compose.yml in the project root directory with the following content:

services:
  masterdata-matching-service:
    image: triumphadler/masterdata-matching-service:latest
    container_name: masterdata-matching-service
    ports:
      - "8001:8000"
    environment:
      - PYTHONUNBUFFERED=1
      - API_TOKEN=${API_TOKEN}
      - BU_THRESHOLD=${BU_THRESHOLD}
      - SUPPLIER_THRESHOLD=${SUPPLIER_THRESHOLD}
      - MATCH_WEIGHT_NAME=${MATCH_WEIGHT_NAME}
      - MATCH_WEIGHT_ADDRESS=${MATCH_WEIGHT_ADDRESS}
      - MATCH_WEIGHT_CITY=${MATCH_WEIGHT_CITY}
      - MATCH_WEIGHT_POSTAL=${MATCH_WEIGHT_POSTAL}
      - MATCH_WEIGHT_TAXID=${MATCH_WEIGHT_TAXID}
      - MATCH_WEIGHT_IBAN=${MATCH_WEIGHT_IBAN}
    volumes:
      - masterdata_data:/app/db
volumes:
  masterdata_data:

The API docs will be available on http://localhost:8001/docs. The database will be stored in a Docker volume (masterdata_data), which persists data across container restarts.

Start Service

docker compose up -d

Stop Service

docker compose down

API Endpoints

Business Units

Method	Endpoint	Description
GET	/business-units/	Get all business units
GET	/business-units/{business_unit_id}	Get a business unit by ID
POST	/business-units/	Create a new business unit
PUT	/business-units/{business_unit_id}	Update a business unit by ID
DELETE	/business-units/{business_unit_id}	Delete a business unit including all related addresses and suppliers
GET	/business-units/{business_unit_id}/addresses/	Get all addresses for a business unit
POST	/business-units/{business_unit_id}/addresses/	Add an address to a business unit
DELETE	/business-units/{business_unit_id}/addresses/{address_id}	Delete an address from a business unit

Addresses

Method	Endpoint	Description
GET	/addresses/	Get all addresses
GET	/addresses/{address_id}	Get an address by ID
PUT	/addresses/{address_id}	Update an address by ID

Suppliers

Method	Endpoint	Description
GET	/suppliers/	Get all suppliers
GET	/suppliers/{supplier_id}	Get a supplier by ID
POST	/suppliers/	Add a new supplier
DELETE	/suppliers/{supplier_id}	Delete a supplier

Matching

Method	Endpoint	Description
POST	/match/	Find business unit and supplier match

Admin

Method	Endpoint	Description
DELETE	/suppliers/purge/	Deletes all suppliers
DELETE	/addresses/purge/	Deletes all addresses
DELETE	/business-units/purge/	Deletes all business units, addresses, and suppliers

Changelog

Version	Date	Description
1.0.3-rc2	6. Feb. 2026	Feat Configure matching weights Reset autoincrement counter after delete suppliers, addresses and business-units Add PUT method to endpoints Update a business-unit by ID Update an address by ID Update a supplier by ID Add GET-by-ID endpoints Get business-unit by ID Get address by ID Please recreate the Docker volume for changes to the DB schema.
v1.0.2 / latest	4. Feb. 2026	Feat Add pagination to endpoints Get all business units Get all addresses Get all suppliers
v1.0.1	4. Feb. 2026	Feat New endpoints: Get all addresses Get a supplier by ID Delete all addresses