Management API v2 (Current) (2.0)

Creates a new organization entry in the system hierarchy. The organization will be placed under the specified owner Organization and can contain other organizational units and companies.

🔒 Permissions: ManageCompany permission on the Organization identified via ownerOrganizationId in the request body.

🔴 Required Fields:

• parentEntityId: ID of the parent Organization (minimum value: 2)

• name: Organization name (2-1000 characters)

🔵 Optional Fields:

• address: Street address (max 1000 characters)

• city: City name (max 1000 characters)

• zip: Postal code (max 50 characters)

• countryCode: ISO-2 country code (exactly 2 characters, e.g., "DE", "AT", "FR")

• invoiceEmailAddress: Email for invoice notifications (valid email format, max 100 characters)

• userComment: Custom description (max 2000 characters)

• state: Organization state - "Productive" (default) or "Test"

📝 Important Notes:

• Valid states: "Productive", "Test"
• Organization will be created with "Productive" state by default
• If created under a Test organization, it will automatically be set to "Test" state
• State changes from "Productive" to "Test" are irreversible
• Address fields are primarily used for billing and invoicing purposes
• The organization will be assigned a unique ID and creation timestamp

Updates the existing organization properties. This is a full update operation - all properties should be included in the request as missing properties may cause validation errors or unexpected behavior.

🔒 Permissions: ManageCompany on the organization to update.

🔴 Required Fields:

• name: Organization name (2-1000 characters)

🔵 Optional Fields:

• address: Street address (max 1000 characters)

• city: City name (max 1000 characters)

• zip: Postal code (max 50 characters)

• countryCode: ISO-2 country code (exactly 2 characters, e.g., "DE", "AT", "FR")

• invoiceEmailAddress: Email for invoice notifications (valid email format, max 100 characters)

• userComment: Custom description (max 2000 characters)

• state: Organization state - "Productive", "Test", or "Deactivated"

📝 Important Notes:

• All properties should be included in the request as missing properties may cause validation errors
• Address fields are primarily used for billing and invoicing purposes
• Some properties may be restricted based on the organization's current state
• State changes from "Productive" to "Test" are irreversible and cannot be undone
• State changes from "Test" to "Productive" are not allowed
• The organization's change timestamp will be updated automatically

Retrieves a single organization by its unique identifier. 🔒 Permissions: ReadCompany permission on the organization identified via the given ID.

📝 Important Notes:

• If the organization is not found, a 404 error will be returned
• The response includes the organization's current state and all associated metadata

Performs a filtered search across organizations based on the provided search criteria. Multiple search parameters can be combined to narrow down results. Supports pagination, sorting, and various filtering options.

🔒 Permissions: ReadCompany permission is required for each organization to appear in the search results.

📝 Search Parameters:

• parentEntityId: Filter by parent Organization (optional, minimum value: 2)

• createdAfter: Filter by creation date (optional, ISO-8601 format)

• hasUserComment: Filter by presence of user comments (optional, boolean)

• hasDeactivateAfterTimestamp: Filter by deactivation date presence (optional, boolean)

• searchText: Text search across name, comment, and other fields (optional, max 1000 characters)

• state: Filter by organization state - "Productive", "Test", or "Deactivated" (optional)

• orderByField: Sort field name (optional, default: "name")

• orderDescending: Sort direction (optional, default: false for ascending)

• offset: Number of items to skip for pagination (optional, minimum: 0)

• limit: Number of items to return (optional, range: 0-250, default: 100)

📝 Important Notes:

• Maximum 250 results per request, default limit is 100 if not specified
• If parentEntityId is provided, only direct children of that Organization are returned
• State filtering supports: "Productive", "Test", "Deactivated"
• Search is case-insensitive for text fields
• Results include pagination metadata (total count, offset, limit)
• Empty search criteria will return all accessible organizations (up to limit)

Creates a new company entry in the system hierarchy. The company will be placed under the specified organization and can contain locations, registers, and other business entities.

🔒 Permissions: ManageCompany permission on the organization identified via parentEntityId in the request body.

🔴 Required Fields:

• parentEntityId: ID of the parent organization (minimum value: 2)

• name: Company name (2-1000 characters)

• taxId: EU tax ID/ECI (4-40 characters, e.g., "DE999999999")

• address: Street address (max 1000 characters)

• city: City name (max 1000 characters)

• zip: Postal code (max 50 characters)

• countryCode: ISO-2 country code (exactly 2 characters, e.g., "DE", "AT", "FR")

🔵 Optional Fields:

• invoiceEmailAddress: Email for invoice notifications (valid email format, max 100 characters)

• userComment: Custom description (max 2000 characters)

• state: Company state - "Productive" (default) or "Test"

• ignoreTaxId: If set to true, the validation of the TaxId will be skipped. The TaxId will still be saved.

• countryProperties: Additional country-specific company data (e.g. DE_WIdNr for the German Wirtschafts-Identifikationsnummer). See "PublicCompanyCountryProperties" for available fields.

📝 Important Notes:

• Valid states: "Productive", "Test"
• Company will be created with "Productive" state by default
• If created under a Test organization, it will automatically be set to "Test" state
• State changes from "Productive" to "Test" are irreversible
• Address fields are primarily used for billing and invoicing purposes
• The company will be assigned a unique ID and creation timestamp
• the field DE_WIdNr in the countryProperties is mandatory for DE companies as of 01.01.2027 until then it is optional

Updates the existing company properties. This is a full update operation - all properties should be included in the request as missing properties may cause validation errors or unexpected behavior.

🔒 Permissions: ManageCompany permission on the company to update.

🔴 Required Fields:

• name: Company name (2-1000 characters)

• address: Street address (max 1000 characters)

• city: City name (max 1000 characters)

• zip: Postal code (max 50 characters)

• countryCode: ISO-2 country code (exactly 2 characters)

🔵 Optional Fields:

• invoiceEmailAddress: Email for invoice notifications (valid email format, max 100 characters)

• userComment: Custom description (max 2000 characters)

• state: Company state - "Productive", "Test", or "Deactivated"

• taxId: EU tax ID/ECI (4-40 characters, e.g., "DE999999999") - Can only be changed if the company's IgnoreEci flag is set to true in the database

• countryProperties: Additional country-specific company data (e.g. DE_WIdNr for the German Wirtschafts-Identifikationsnummer). See "PublicCompanyCountryProperties" for available fields.

📝 Important Notes:

• All company fields should be provided as the update replaces the entire entity
• Changes are automatically synchronized to all locations and registers
• State changes from "Productive" to "Test" are irreversible and cannot be undone
• State changes from "Test" to "Productive" are not allowed
• The company's change timestamp will be updated automatically
• the field DE_WIdNr in the countryProperties is mandatory for DE companies as of 01.01.2027 until then it is optional
• The Tax ID can only be changed if the company's IgnoreEci flag is set to true. In normal cases of company renaming (rebranding), a new company must be created. See FAQs.

Retrieves a single company by its unique identifier. Returns complete company information

🔒 Permissions: ReadCompany permission on the company identified via the given ID.

📝 Important Notes:

• If the company is not found, a 404 error will be returned
• The response includes the company's current state and all associated metadata

Deactivates a company and all its subordinate entities including registers, locations, and fiscal units. The process executes in a specific order to ensure proper shutdown of all connected systems.

🔒 Permissions: ManageCompany permission required for the specified company.

📝 Deactivation Process:

• Immediate deactivation: If no year specified, company is deactivated immediately

• Scheduled deactivation: If year specified, deactivation occurs on December 31st at 23:59:59

• Subordinate entities: All locations, registers, and fiscal units are deactivated

• Fiscal units: Terminated after notice period (unless forceSubDeactivation is true)

📝 Important Notes:

• Process is irreversible once completed
• All subordinate entities will be deactivated
• Scheduled deactivation year must be current year or later
• Fiscal Units will be terminated after notice period (unless forced)
• Force sub-deactivation bypasses normal notice periods

Performs a filtered search across companies based on the provided search criteria. Multiple search parameters can be combined to narrow down results. Supports pagination, sorting, and various filtering options.

🔒 Permissions: ReadCompany permission is required for each company to appear in the search results.

📝 Search Parameters:

• ParentEntityId: Filter by parent organization (optional, minimum value: 2)

• createdAfter: Filter by creation date (optional, ISO-8601 format)

• hasUserComment: Filter by presence of user comments (optional, boolean)

• hasDeactivateAfterTimestamp: Filter by deactivation date presence (optional, boolean)

• searchText: Text search across name, comment, and other fields (optional, max 1000 characters)

• state: Filter by company state - "Productive", "Test", or "Deactivated" (optional)

• countryCode: Filter by ISO-2 country code (optional, exactly 2 characters, e.g., "DE", "AT", "FR")

• orderByField: Sort field name (optional, default: "name")

• orderDescending: Sort direction (optional, default: false for ascending)

• offset: Number of items to skip for pagination (optional, minimum: 0)

• limit: Number of items to return (optional, range: 0-250, default: 100)

📝 Important Notes:

• Maximum 250 results per request, default limit is 100 if not specified
• If ParentEntityId is provided, only direct children of that organization are returned
• State filtering supports: "Productive" (10), "Test" (9), "Deactivated" (8)
• Search is case-insensitive for text fields
• Results include pagination metadata (total count, offset, limit)
• Empty search criteria will return all accessible companies (up to limit)

Loads all available notifications for registers of a company and all related locations. These notifications contain warnings from the efsta Portal escalation system and describe issues and potential problems with registers.

🔒 Permissions: ReadCompany permission required for the specified company.

📝 Returned Data:

• Register information: RegisterNumber, EventCode, DescriptionShort

• Event details: DescriptionLong, CurrentLevel, InitialTimestamp

• Company context: parentEntityId, CompanyName, CompanyType

📝 Important Notes:

• Language code defaults to "en-US" if not provided
• Only Works on Productive Companies
• Only active notifications are returned
• Notifications are localized based on the provided language code

Creates a new contact person for a company. Contact persons are used for automated notifications and communication purposes.

🔒 Permissions: ManageCompany permission required for the company specified in the request.

🔴 Required Fields:

• companyId: ID of the company to add the contact to (minimum value: 2)

• contactName: Contact person's full name (2-500 characters)

• emailAddress: Contact person's email address (valid email format, max 500 characters)

• contactType: Type of contact role (see Contact Types below)

👤 Contact Types:

• InvoiceContact: Responsible for invoice-related communications

• TechnicalContact: Responsible for technical support and system issues

• CommercialContact: Responsible for commercial and business matters

• ElsterContact: Responsible for fiscal authority communications (Germany)

📝 Important Notes:

• Email addresses must be unique within the company
• Contact information is used for automated notifications
• Multiple contacts of the same type are allowed
• The contact will be assigned a unique ID upon creation

Gets a list of all the different contacts added to the Company. Returns complete contact information including roles, verification status, and communication preferences.

🔒 Permissions: ReadCompany permission required for the specified company.

📝 Returned Information:

• Contact person details: Name, Email,

• Role and responsibility assignments: ContactType

• Company context: CompanyId

👤 Contact Types:

• InvoiceContact: Responsible for invoice-related communications

• TechnicalContact: Responsible for technical support and system issues

• CommercialContact: Responsible for commercial and business matters

• ElsterContact: Responsible for fiscal authority communications (Germany)

📝 Important Notes:

• Only contacts for the specified company are returned
• If the company is not found, a 404 error will be returned
• Contact information includes all available metadata
• Verification status is particularly relevant for German fiscal contacts

Creates a new location entry in the system hierarchy. The location will be placed under the specified company and can contain registers and process transactions.

🔒 Permissions: ManageCompany permission on the company identified via parentEntityId in the request body.

🔴 Required Fields:

• parentEntityId: ID of the parent company (minimum value: 2)

• name: Location name (2-1000 characters)

• address: Street address (max 1000 characters)

• city: City name (max 1000 characters)

• zip: Postal code (max 50 characters)

• countryCode: ISO-2 country code (exactly 2 characters, e.g., "DE", "AT", "FR")

• locationIdentification: Unique identifier within the company (1-1000 characters, alphanumeric and special characters )

🔵 Optional Fields

• invoiceEmailAddress: Email for invoice notifications (valid email format, max 100 characters)

• userComment: Custom description (max 2000 characters)

• state: Location state - "Productive" (default) or "Test"

📝 Important Notes:

• Valid states: "Productive", "Test"
• Location will be created with "Productive" state by default
• If created under a Test company, it will automatically be set to "Test" state
• State changes from "Productive" to "Test" are irreversible
• Address fields are primarily used for billing and invoicing purposes
• The location will be assigned a unique ID and creation timestamp
• Location name should be unique within the parent company for better organization

Updates the existing location properties. This is a full update operation - all properties should be included in the request as missing properties may cause validation errors or unexpected behavior.

🔒 Permissions: ManageCompany permission on the location to update.

🔴 Required Fields:

• parentEntityId: ID of the parent company (minimum value: 2)

• name: Location name (2-1000 characters)

• address: Street address (max 1000 characters)

• city: City name (max 1000 characters)

• zip: Postal code (max 50 characters)

• countryCode: ISO-2 country code (exactly 2 characters)

• locationIdentification: Unique identifier within the company (1-1000 characters, alphanumeric and special characters )

🔵 Optional Fields:

• invoiceEmailAddress: Email for invoice notifications (valid email format, max 100 characters)

• userComment: Custom description (max 2000 characters)

• state: Location state - "Productive", "Test", or "Deactivated"

📝 Important Notes:

• All properties should be included in the request to avoid validation errors
• Missing properties may be cleared or cause validation failures
• State changes from "Productive" to "Test" are irreversible and cannot be undone
• State changes from "Test" to "Productive" are not allowed
• The location's change timestamp will be updated automatically

Retrieves a single location by its unique identifier.

🔒 Permissions: ReadCompany permission on the location identified via the given ID.

Deactivates a location and all its subordinate entities including registers and fiscal units. The process executes in a specific order to ensure proper shutdown of all connected systems.

🔒 Permissions: ManageCompany permission required for the specified location.

📝 Deactivation Process:

• Immediate deactivation: If no year specified, location is deactivated immediately

• Scheduled deactivation: If year specified, deactivation occurs on December 31st at 23:59:59

• Subordinate entities: All registers and fiscal units are deactivated

• Fiscal units: Terminated after notice period (unless forceSubDeactivation is true)

📝 Important Notes:

• Process is irreversible once completed
• All subordinate entities will be deactivated
• Scheduled deactivation year must be current year or later
• Fiscal Units will be terminated after notice period (unless forced)
• Force sub-deactivation bypasses normal notice periods

Performs a filtered search across locations based on the provided search criteria. Multiple search parameters can be combined to narrow down results. Supports pagination, sorting, and various filtering options.

🔒 Permissions: ReadCompany permission is required for each location to appear in the search results.

📝 Search Parameters:

• parentEntityId: Filter by parent company (optional, minimum value: 2)

• createdAfter: Filter by creation date (optional, ISO-8601 format)

• hasUserComment: Filter by presence of user comments (optional, boolean)

• hasDeactivateAfterTimestamp: Filter by deactivation date presence (optional, boolean)

• searchText: Text search across name, comment, and other fields (optional, max 1000 characters)

• state: Filter by location state - "Productive", "Test", or "Deactivated" (optional)

• countryCode: Filter by ISO-2 country code (optional, exactly 2 characters, e.g., "DE", "AT", "FR")

• orderByField: Sort field name (optional, default: "name")

• orderDescending: Sort direction (optional, default: false for ascending)

• offset: Number of items to skip for pagination (optional, minimum: 0)

• limit: Number of items to return (optional, range: 0-250, default: 100)

📝 Important Notes:

• Maximum 250 results per request, default limit is 100 if not specified
• If parentEntityId is provided, only direct children of that company are returned
• State filtering supports: "Productive", "Test", "Deactivated"
• Search is case-insensitive for text fields
• Results include pagination metadata (total count, offset, limit)
• Empty search criteria will return all accessible locations (up to limit)

Retrieves a single register by its unique register number. Returns complete register information.

🔒 Permissions: ReadRegister permission on the company that owns the register.

📝 Important Notes:

• Register numbers are typically 11 digits long

Performs a filtered search across registers based on the provided search criteria. Multiple search parameters can be combined to narrow down results. Supports pagination, sorting, and various filtering options.

🔒 Permissions: ReadRegister permission is required for each register to appear in the search results.

📝 Search Parameters:

• parentEntityId: Filter by parent company (optional, minimum value: 2)

• createdAfter: Filter by creation date (optional, ISO-8601 format)

• hasUserComment: Filter by presence of user comments (optional, boolean)

• hasDeactivateAfterTimestamp: Filter by deactivation date presence (optional, boolean)

• state: Filter by RegisterState (optional, Productive|Test|Deactivated)

• searchText: Text search across register properties (optional, max 1000 characters)

• orderByField: Sort field name (optional, default: "registerNumber")

• orderDescending: Sort direction (optional, default: false for ascending)

• offset: Number of items to skip for pagination (optional, minimum: 0)

• limit: Number of items to return (optional, range: 0-250, default: 100)

📝 Important Notes:

• Maximum 250 results per request, default limit is 100 if not specified
• If pFarentEntityId is provided, only registers of that company are returned
• Search text filtering is applied across register properties
• Results include pagination metadata (total count, offset, limit)
• Empty search criteria will return all accessible registers (up to limit)

Deactivates a register by changing state to "Discharged". This operation can be immediate or scheduled for a future date.

🔒 Permissions: ManageRegister permission required for the company that owns the register.

📝 Important Notes:

• Register must not be in "DATA_PENDING" state to be deactivated
• Registers with active subregisters cannot be deactivated
• Registers still active with fiscal authorities cannot be deactivated
• Already deactivated registers cannot be reanimated
• Scheduled deactivation year must be current year or later

Updates the software release version assigned to a register. The operation is performed asynchronously in the background.

🔒 Permissions: ManageRegister permission required for the company that owns the register.

📝 Update Process:

• Compatibility check: Target release must be compatible with register's platform and architecture

• Background processing: Update is initiated asynchronously via messaging system

• Version validation: Software version compatibility is verified

• Platform restrictions: Cross-platform updates have specific limitations

📝 Important Notes:

• Register must exist and be accessible to the user
• Target release must be compatible with the register's platform and architecture
• Cross-platform updates have restrictions (e.g., Windows-only for major version changes)
• Downgrade to version 1.x is not supported
• EFR version 1.x is only available for ia32 architecture on Linux
• Multiple target releases for the same parameters are not allowed
• Update process runs in the background and may take time to complete

⚡ Error Codes:

• 01: No register found to update

• 02: No assignment found to update

• 03: Multiple target releases found

• 04: No target release found

• 06: Main releases different - downgrade not possible or cross update only available for Windows

Returns a list of all products available for purchase by the company. Products are filtered based on company state, assignment type, and purchase mode restrictions.

🔒 Permissions: Purchase permission on the specified company.

📝 Returned Data:

• Product information: ID, Name, DescriptionShort, DescriptionLong

• Pricing details: PriceOnce, PriceReoccurring (may be hidden based on purchase mode)

• Product details: WarningText, ImageLink, Supplier, AmountLimit

• Localization: CountryCode, AmountSelectionType

📝 Important Notes:

• Products are filtered by state (Production/Test)
• Efsta-only products are excluded from results
• Purchase mode restrictions may hide prices or entire products
• Results are ordered by CountryCode and Supplier
• Language code defaults to "en" if not provided or invalid
• Only active products are returned

Returns a comprehensive overview of all purchases made by the company within the specified date range. Results include purchase details, pricing information, and product information.

🔒 Permissions: Purchase permission on the specified company.

📝 Important Notes:

• Results are ordered by purchase date (newest first)
• Date format must be yyyyMMdd (e.g., "20230101" for January 1, 2023)
• If fromDate is after tillDate, a validation error will be returned
• Purchase mode restrictions may hide pricing information
• Test orders are clearly marked in the results
• Results include translated product names when available

Creates a new purchase order in the system. The purchase will be processed according to the company's payment method and billing preferences. All validation checks are performed before order creation.

🔒 Permissions: Purchase permission required for all companies involved in the purchase (companyId, invoiceCompanyId, shippingCompanyId if provided).

🔴 Required Fields:

• companyId: ID of the company making the purchase (minimum value: 1)

• invoiceCompanyId: ID of the company to invoice (minimum value: 1)

• items: List of products to purchase with amounts and assignments

• recipientEmailAddress: Email address for order notifications (valid email format)

🔵 Optional Fields:

• shippingCompanyId: ID of the company for shipping (if different from companyId)

• shippingName: Name for shipping address (max 200 characters)

• shippingStreet: Street address for shipping (max 200 characters)

• shippingCity: City for shipping address (max 200 characters)

• shippingZip: Postal code for shipping (max 20 characters)

• shippingCountryCode: ISO-2 country code for shipping (exactly 2 characters)

• recipientEmailRealName: Real name of the recipient (max 200 characters)

• customerReference: Customer reference information (max 200 characters)

📝 Important Notes:

• Request must not be empty and must pass validation
• All specified companies must be accessible with Purchase permission
• Products must be available and valid for the company
• Order processing is initiated asynchronously
• Collective invoice is automatically enabled
• Language is set based on user's language code or defaults to "en-US"