Tax API

Self-Employed Basics

1. When to use 💡

This route enables you to perform basic tax calculations for self-employed persons. Basic tax calculations include a calculation from gross revenue to net income.

2. Simple use case 👇

For a simple gross to net calculation we suggest using the following steps.

Step 1: Determine if the calulation is for a director or a one-man business owner.

The tax treatment of both is very similar but the fixed costs (if applicable) are calculated with a different percentage. Set selfEmployedType = "director" or selfEmployedType = "oneManBusiness".

Provide the grossIncome and the actualCost of the user. If you want to use fixed costs instead of actual costs, use the fixedCostChoice = true option.

Step 2 (optional): Add other information more specific about the user such as:

numberOfChildDependents
selfEmployedStatus
employeeTaxableIncome

3. Request 📤

The API only consumes POST requests with a valid JSON body. Your request header needs to contain your API-key as a x-api-key field.

3.1. Example request

POST Request
Endpoint: tax-api.aeco.cloud/api/models/selfEmployedBasics
HEADER: {
  x-api-key: YOUR API KEY
}
BODY: {
  "grossIncome": 60000,
  "actualCost": 10000,
  "selfEmployedType": "oneManBusiness",
  "selfEmployedStatus": "primary",
  "employeeTaxableIncome": 0,
  "numberOfChildDependents": 2,
  "selfEmployedSocialSecurityContributionAdministrationCostConstant": 3056.99886,
  "selfEmployedSocialSecurityContributionAdministrationCostRate":  0.0305
}

3.2. Method

It should be a POST request.

3.3. Endpoint

The request should be sent to tax-api.aeco.cloud/api/models/selfEmployedBasics.

Developer requests should be sent to tax-api-develop.aeco.cloud/api/models/selfEmployedBasics.

3.4. Header

Field	Value
x-api-key	aeco-authentication

3.5. Body Parameters

Parameter	Type	Default	Description	Required
grossIncome	number	/	The yearly gross revenue of a self-employed person.	yes
actualCost	number	0	The yearly actual costs incurred by a self-employed person.	no
fixedCostChoice	boolean	false	The choice to use fixed costs in the calculation of the self-employed basics.	no
selfEmployedType	"director/"oneManBusiness"	"oneManBusiness"	The type of self-employed person.	no
numberOfChildDependents	integer	0	The number of child dependents a person has.	no
selfEmployedSocialSecurityContribution	number	/	The social contribution of a self-employed person. The route will calculate the optimal selfEmployedSocialSecurityContribution if this is not included in the body. As such, default behaviour is not to include this parameter.	no
selfEmployedStatus	"primary"/"secondary"	"primary	The status of the self-employed person. A self-employed person is either a self-employed person as its primary activity or as a secondary activity.	no
employeeTaxableIncome	number	0	The yearly net taxable income of an self-employed person who is also an employee in a second job. This should only be used if the person is both an employee and a self-employed person.	no
selfEmployedSocialSecurityContributionAdministrationCostConstant	number	3056.99886	The administration cost constant is equal to the minimum yearly contribution a person has to pay at a payroll enterprise (NL: de sociale secretariaten). This is sligthly different for the different payroll enterprises mainly due to rounding differences. The default value used is the cheapest one in the Belgian market.	no
selfEmployedSocialSecurityContributionAdministrationCostRate	number	0.0305	Payroll companies use their own administration cost rate which a person has to pay on top of their social contributions.	no

4. Response 📥

4.1. Response parameters

An object with the following parameters, depending on which type of self-employed person the user is:

selfEmployedType = oneManBusiness

Parameter	type
oneManBusinessGrossIncome	number
selfEmployedGrossIncome	number
oneManBusinessActualCost	number
selfEmployedActualCost	number
oneManBusinessFixedCost	number
selfEmployedFixedCost	number
selfEmployedCost	number
selfEmployedSocialSecurityContribution	number
selfEmployedTaxableIncome	number
employeeTaxableIncome	number
professionalTaxableIncome	number
globallyTaxedTaxableIncome	number
personalIncomeTaxFreeAllowance	number
personalIncomeTaxFreeAllowanceTax	number
globallyTaxedIncomeTax	number
personalIncomeTaxMunicipalTax	number
personalIncomeTax	number
personalNetIncome	number

selfEmployedType = director

Parameter	type
directorGrossIncome	number
selfEmployedGrossIncome	number
directorActualCost	number
selfEmployedActualCost	number
directorFixedCost	number
selfEmployedFixedCost	number
selfEmployedCost	number
selfEmployedSocialSecurityContribution	number
selfEmployedTaxableIncome	number
employeeTaxableIncome	number
professionalTaxableIncome	number
globallyTaxedTaxableIncome	number
personalIncomeTaxFreeAllowance	number
personalIncomeTaxFreeAllowanceTax	number
globallyTaxedIncomeTax	number
personalIncomeTaxMunicipalTax	number
personalIncomeTax	number
personalNetIncome	number

4.2. Response type

type SelfEmployedBasicsResponse = {
  directorGrossIncome?: number | undefined;
  oneManBusinessGrossIncome?: number | undefined;
  directorActualCost?: number | undefined;
  oneManBusinessActualCost?: number | undefined;
  directorFixedCost?: number | undefined;
  oneManBusinessFixedCost?: number | undefined;
  selfEmployedGrossIncome: number;
  selfEmployedActualCost: number;
  selfEmployedSocialSecurityContribution: number;
  selfEmployedFixedCost: number;
  selfEmployedCost: number;
  selfEmployedTaxableIncome: number;
  employeeTaxableIncome: number;
  professionalTaxableIncome: number;
  globallyTaxedTaxableIncome: number;
  personalIncomeTaxFreeAllowance: number;
  personalIncomeTaxFreeAllowanceTax: number;
  globallyTaxedIncomeTax: number;
  personalIncomeTaxMunicipalTax: number;
  personalIncomeTax: number;
  personalNetIncome: number;
};

4.3. Response example

{
    "oneManBusinessGrossIncome": 60000,
    "selfEmployedGrossIncome": 60000,
    "oneManBusinessActualCost": 10000,
    "selfEmployedActualCost": 10000,
    "oneManBusinessFixedCost": 0,
    "selfEmployedFixedCost": 0,
    "selfEmployedCost": 10000,
    "selfEmployedSocialSecurityContribution": 8720.413894064475,
    "selfEmployedTaxableIncome": 41279.57725501225,
    "employeeTaxableIncome": 0,
    "professionalTaxableIncome": 41279.57725501225,
    "globallyTaxedTaxableIncome": 41279.57725501225,
    "personalIncomeTaxFreeAllowance": 14940,
    "personalIncomeTaxFreeAllowanceTax": 4146,
    "globallyTaxedIncomeTax": 11203.809764755511,
    "personalIncomeTaxMunicipalTax": 784.2666835328858,
    "personalIncomeTax": 11988.076448288397,
    "personalNetIncome": 29291.509657647126
}