Tax Membership Histories

These endpoints let you manage(retrieve and update) tax membership histories for employees.

Get Tax Membership History

get

Get tax membership history for a specific employee for a given year and month

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

employeeIdstringRequired

Unique identifier for the employee

Example: 0ab1c2d3-e4f5-6789-0123-456789abcdef

Query parameters

yearinteger · min: 1970Required

Year for which to get tax membership history

Example: 2024

monthinteger · min: 1 · max: 12Optional

Month for which to get tax membership history (defaults to December)

Default: 12Example: 1

Responses

200

Tax membership history returned successfully

application/json

idstringOptional

Unique identifier for the tax membership

foreignTaxObjectbooleanOptional

Whether this is a foreign tax object

kppIdstringOptional

Tax office (KPP) identifier

linkToPayrollbooleanOptional

Whether this tax membership is linked to payroll

methodstring · enumOptional

PPh21 calculation method

Possible values:

moreThanOneEmployerbooleanOptional

Whether employee has more than one employer

npwpAddressstringOptional

Address registered with NPWP

npwpNumberstringOptional

NPWP (Tax ID) number - can be empty or contain only digits

Pattern: ^$|^\d+$

tinstringOptional

Tax Identification Number

previousNetIncomenumber · doubleOptional

Previous net income amount

previousPaidPphnumber · doubleOptional

Previous paid PPh amount

ptkpCategoryIdstringOptional

PTKP (Personal Tax Free Income) category identifier

taxObjectstring · enumOptional

Type of tax object for the employee

Possible values:

useRecommendedPeriodbooleanOptional

400

Bad Request - Invalid request parameters

application/json

404

Employee or tax membership history not found

application/json

get

/core/v1/employees/{employeeId}/tax-membership-histories

cURLPython SDK

curl -X GET \
  "https://api.catapa.com/core/v1/employees/0ab1c2d3-e4f5-6789-0123-456789abcdef/tax-membership-histories?year=2024&month=12" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Tenant: your-tenant-id"

{
  "foreignTaxObject": false,
  "id": "string",
  "kppId": "string",
  "linkToPayroll": true,
  "membershipEndPeriod": {
    "month": 1,
    "year": 1970
  },
  "membershipStartPeriod": {
    "month": 1,
    "year": 1970
  },
  "effectiveStartPeriod": {
    "month": 1,
    "year": 1970
  },
  "effectiveEndPeriod": {
    "month": 1,
    "year": 1970
  },
  "method": "GROSS",
  "moreThanOneEmployer": true,
  "npwpAddress": "string",
  "npwpNumber": "1234567890",
  "tin": "string",
  "previousNetIncome": 0,
  "previousPaidPph": 0,
  "ptkpCategoryId": "string",
  "taxObject": "PERMANENT",
  "useRecommendedPeriod": true,
  "taxDependents": [],
  "employee": {
    "id": "string",
    "identificationNumber": "string",
    "name": "string"
  }
}

Get Tax Membership History by Id

get

Get a specific tax membership history record by its unique identifier

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

Unique identifier for the tax membership history record

Example: f47ac10b-58cc-4372-a567-0e02b2c3d479

Responses

200

Tax membership history returned successfully

application/json

idstringOptional

Unique identifier for the tax membership

foreignTaxObjectbooleanOptional

Whether this is a foreign tax object

kppIdstringOptional

Tax office (KPP) identifier

linkToPayrollbooleanOptional

Whether this tax membership is linked to payroll

methodstring · enumOptional

PPh21 calculation method

Possible values:

moreThanOneEmployerbooleanOptional

Whether employee has more than one employer

npwpAddressstringOptional

Address registered with NPWP

npwpNumberstringOptional

NPWP (Tax ID) number - can be empty or contain only digits

Pattern: ^$|^\d+$

tinstringOptional

Tax Identification Number

previousNetIncomenumber · doubleOptional

Previous net income amount

previousPaidPphnumber · doubleOptional

Previous paid PPh amount

ptkpCategoryIdstringOptional

PTKP (Personal Tax Free Income) category identifier

taxObjectstring · enumOptional

Type of tax object for the employee

Possible values:

useRecommendedPeriodbooleanOptional

400

Bad Request - Invalid ID format

application/json

404

Tax membership history not found

application/json

get

/core/v1/tax-membership-histories/{id}

cURLPython SDK

curl -X GET \
  "https://api.catapa.com/core/v1/tax-membership-histories/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Tenant: your-tenant-id"

{
  "id": "history-12345",
  "taxObject": "PERMANENT",
  "membershipStartPeriod": {
    "month": 1,
    "year": 2024
  },
  "membershipEndPeriod": {
    "month": 12,
    "year": 2024
  },
  "effectiveStartPeriod": {
    "month": 1,
    "year": 2024
  },
  "effectiveEndPeriod": {
    "month": 12,
    "year": 2024
  },
  "method": "GROSS",
  "npwpNumber": "123456789012345",
  "npwpAddress": "Jakarta Selatan, DKI Jakarta",
  "tin": "TIN123456",
  "linkToPayroll": true,
  "moreThanOneEmployer": false,
  "foreignTaxObject": false,
  "previousNetIncome": 100000000,
  "previousPaidPph": 5000000,
  "kppId": "kpp-jakarta-selatan",
  "ptkpCategoryId": "ptkp-tk-1",
  "taxDependents": [
    {
      "id": "dep-1",
      "name": "Jane Doe",
      "ptkpRelationType": "SPOUSE",
      "dateOfBirth": "1990-05-15",
      "job": "Teacher"
    }
  ],
  "employee": {
    "id": "emp-12345",
    "identificationNumber": "EMP001234",
    "name": "John Doe"
  }
}

Update Tax Membership History Tax Subject

put

Update tax subject information for a specific tax membership history record

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

Unique identifier for the tax membership history record

Example: f47ac10b-58cc-4372-a567-0e02b2c3d479

Body

application/json

npwpAddressstringRequired

Address registered with NPWP

npwpNumberstringOptional

NPWP (Tax ID) number - can be empty or contain only digits

Pattern: ^$|^\d+$

idTkustringOptional

TKU (Tax Knowledge Unit) identifier

tinstringOptional

Tax Identification Number

kppIdstringOptional

Tax office (KPP) identifier

ptkpCategoryIdstringOptional

PTKP (Personal Tax Free Income) category identifier

Responses

200

Tax membership history tax subject updated successfully

application/json

idstringOptional

Unique identifier for the tax membership

foreignTaxObjectbooleanOptional

Whether this is a foreign tax object

kppIdstringOptional

Tax office (KPP) identifier

linkToPayrollbooleanOptional

Whether this tax membership is linked to payroll

methodstring · enumOptional

PPh21 calculation method

Possible values:

moreThanOneEmployerbooleanOptional

Whether employee has more than one employer

npwpAddressstringOptional

Address registered with NPWP

npwpNumberstringOptional

NPWP (Tax ID) number - can be empty or contain only digits

Pattern: ^$|^\d+$

tinstringOptional

Tax Identification Number

previousNetIncomenumber · doubleOptional

Previous net income amount

previousPaidPphnumber · doubleOptional

Previous paid PPh amount

ptkpCategoryIdstringOptional

PTKP (Personal Tax Free Income) category identifier

taxObjectstring · enumOptional

Type of tax object for the employee

Possible values:

useRecommendedPeriodbooleanOptional

400

Bad Request - Invalid input data

application/json

404

Tax membership history not found

application/json

422

Unprocessable Entity - Business logic validation failed

application/json

put

/core/v1/tax-membership-histories/{id}/tax-subjects

cURLPython SDK

curl -X PUT \
  "https://api.catapa.com/core/v1/tax-membership-histories/f47ac10b-58cc-4372-a567-0e02b2c3d479/tax-subjects" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Tenant: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
  "npwpAddress": "Jakarta Selatan, DKI Jakarta",
  "npwpNumber": "123456789012345",
  "idTku": "TKU123456",
  "tin": "TIN123456",
  "kppId": "kpp-jakarta-selatan",
  "ptkpCategoryId": "ptkp-tk-1",
  "taxDependents": [
    {
      "id": "dep-1",
      "name": "Jane Doe",
      "ptkpRelationType": "SPOUSE",
      "dateOfBirth": "1990-05-15",
      "job": "Teacher"
    },
    {
      "id": "dep-2",
      "name": "John Doe Jr",
      "ptkpRelationType": "CHILD",
      "dateOfBirth": "2015-03-20",
      "job": "Student"
    }
  ]
}'

{
  "id": "history-12345",
  "taxObject": "PERMANENT",
  "membershipStartPeriod": {
    "month": 1,
    "year": 2024
  },
  "membershipEndPeriod": {
    "month": 12,
    "year": 2024
  },
  "effectiveStartPeriod": {
    "month": 1,
    "year": 2024
  },
  "effectiveEndPeriod": {
    "month": 12,
    "year": 2024
  },
  "method": "GROSS",
  "npwpNumber": "123456789012345",
  "npwpAddress": "Jakarta Selatan, DKI Jakarta",
  "tin": "TIN123456",
  "linkToPayroll": true,
  "moreThanOneEmployer": false,
  "foreignTaxObject": false,
  "previousNetIncome": 100000000,
  "previousPaidPph": 5000000,
  "kppId": "kpp-jakarta-selatan",
  "ptkpCategoryId": "ptkp-tk-1",
  "taxDependents": [
    {
      "id": "dep-1",
      "name": "Jane Doe",
      "ptkpRelationType": "SPOUSE",
      "dateOfBirth": "1990-05-15",
      "job": "Teacher"
    }
  ],
  "employee": {
    "id": "emp-12345",
    "identificationNumber": "EMP001234",
    "name": "John Doe"
  }
}