# Tax Membership Histories

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

## Get Tax Membership History

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

```json
{"openapi":"3.0.0","info":{"title":"CATAPA API","version":"1.0.0"},"tags":[{"name":"tax-membership-history","description":"These endpoints let you manage(retrieve and update) tax membership histories for employees.\n"}],"servers":[{"url":"https://api.catapa.com","description":"Production server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication header of the form `Bearer <token>`."}}},"paths":{"/core/v1/employees/{employeeId}/tax-membership-histories":{"get":{"tags":["tax-membership-history"],"summary":"Get Tax Membership History","description":"Get tax membership history for a specific employee for a given year and month","parameters":[{"in":"path","name":"employeeId","schema":{"type":"string"},"required":true,"description":"Unique identifier for the employee"},{"in":"query","name":"year","schema":{"type":"integer","minimum":1970},"required":true,"description":"Year for which to get tax membership history"},{"in":"query","name":"month","schema":{"type":"integer","minimum":1,"maximum":12,"default":12},"required":false,"description":"Month for which to get tax membership history (defaults to December)"}],"responses":{"200":{"description":"Tax membership history returned successfully","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the tax membership"},"foreignTaxObject":{"type":"boolean","description":"Whether this is a foreign tax object"},"kppId":{"type":"string","description":"Tax office (KPP) identifier"},"linkToPayroll":{"type":"boolean","description":"Whether this tax membership is linked to payroll"},"membershipEndPeriod":{"allOf":[{"type":"object","properties":{"month":{"type":"integer","minimum":1,"maximum":12,"description":"Month of membership start period"},"year":{"type":"integer","minimum":1970,"description":"Year of membership start period"}}}],"description":"Period when tax membership ends"},"membershipStartPeriod":{"allOf":[{"type":"object","properties":{"month":{"type":"integer","minimum":1,"maximum":12,"description":"Month of membership start period"},"year":{"type":"integer","minimum":1970,"description":"Year of membership start period"}}}],"description":"Period when tax membership starts"},"effectiveEndPeriod":{"allOf":[{"type":"object","properties":{"month":{"type":"integer","minimum":1,"maximum":12,"description":"Month of membership start period"},"year":{"type":"integer","minimum":1970,"description":"Year of membership start period"}}}],"description":"Period when tax effectiveness ends"},"effectiveStartPeriod":{"allOf":[{"type":"object","properties":{"month":{"type":"integer","minimum":1,"maximum":12,"description":"Month of membership start period"},"year":{"type":"integer","minimum":1970,"description":"Year of membership start period"}}}],"description":"Period when tax becomes effective"},"method":{"type":"string","enum":["GROSS","NETTO","GROSS_UP","MIX","MIX_GROSS_NETTO","MIX_NETTO_GROSS","MIX_GROSS_UP_GROSS"],"description":"PPh21 calculation method"},"moreThanOneEmployer":{"type":"boolean","description":"Whether employee has more than one employer"},"npwpAddress":{"type":"string","description":"Address registered with NPWP"},"npwpNumber":{"type":"string","pattern":"^$|^\\d+$","description":"NPWP (Tax ID) number - can be empty or contain only digits"},"tin":{"type":"string","description":"Tax Identification Number"},"previousNetIncome":{"type":"number","format":"double","minimum":0,"description":"Previous net income amount"},"previousPaidPph":{"type":"number","format":"double","minimum":0,"description":"Previous paid PPh amount"},"ptkpCategoryId":{"type":"string","description":"PTKP (Personal Tax Free Income) category identifier"},"taxObject":{"type":"string","enum":["PERMANENT","TEMPORARY","MULTI_LEVEL_DISTRIBUTOR","INSURANCE_AGENT","MERCHANT_GOODS","EXPERT_CONTINUOUS","EXPERT_NON_CONTINUOUS","CONTINUOUS","NON_CONTINUOUS","COMMISSIONER","FORMER_EMPLOYEE","EVENT_PARTICIPANT","EXPATRIATE","EXPERT","MEETING_PARTICIPANT","COMMITTEE_PARTICIPANT","EDUCATION_PARTICIPANT","OTHER_PARTICIPANT","ADVISOR_LECTURER","AUTHOR_RESEARCHER","SERVICE_PROVIDER","ADVERTISING_AGENT","PROJECT_MANAGER","INTERMEDIARY","ARTIST","ATHLETE","TEMPORARY_MONTHLY","COMPETITION_PARTICIPANT"],"description":"Type of tax object for the employee"},"useRecommendedPeriod":{"type":"boolean"},"taxDependents":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Name of the tax dependent"},"ptkpRelationType":{"type":"string","enum":["SPOUSE","CHILD","PARENT"],"description":"Relationship type for PTKP calculation"},"dateOfBirth":{"type":"string","format":"date","description":"Date of birth of the tax dependent"},"job":{"type":"string","description":"Job or occupation of the tax dependent"}}},"description":"List of tax dependents for PTKP calculation"}}},{"type":"object","properties":{"employee":{"type":"object","properties":{"id":{"type":"string"},"identificationNumber":{"type":"string"},"name":{"type":"string"}}}}}]}}}},"400":{"description":"Bad Request - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Error message"},"status":{"type":"integer","description":"HTTP status code"},"timestamp":{"type":"string","description":"Timestamp when the error occurred"}}}}}},"404":{"description":"Employee or tax membership history not found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Error message"},"status":{"type":"integer","description":"HTTP status code"},"timestamp":{"type":"string","description":"Timestamp when the error occurred"}}}}}}}}}}}
```

## Get Tax Membership History by Id

> Get a specific tax membership history record by its unique identifier

```json
{"openapi":"3.0.0","info":{"title":"CATAPA API","version":"1.0.0"},"tags":[{"name":"tax-membership-history","description":"These endpoints let you manage(retrieve and update) tax membership histories for employees.\n"}],"servers":[{"url":"https://api.catapa.com","description":"Production server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication header of the form `Bearer <token>`."}}},"paths":{"/core/v1/tax-membership-histories/{id}":{"get":{"tags":["tax-membership-history"],"summary":"Get Tax Membership History by Id","description":"Get a specific tax membership history record by its unique identifier","parameters":[{"in":"path","name":"id","schema":{"type":"string"},"required":true,"description":"Unique identifier for the tax membership history record"}],"responses":{"200":{"description":"Tax membership history returned successfully","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the tax membership"},"foreignTaxObject":{"type":"boolean","description":"Whether this is a foreign tax object"},"kppId":{"type":"string","description":"Tax office (KPP) identifier"},"linkToPayroll":{"type":"boolean","description":"Whether this tax membership is linked to payroll"},"membershipEndPeriod":{"allOf":[{"type":"object","properties":{"month":{"type":"integer","minimum":1,"maximum":12,"description":"Month of membership start period"},"year":{"type":"integer","minimum":1970,"description":"Year of membership start period"}}}],"description":"Period when tax membership ends"},"membershipStartPeriod":{"allOf":[{"type":"object","properties":{"month":{"type":"integer","minimum":1,"maximum":12,"description":"Month of membership start period"},"year":{"type":"integer","minimum":1970,"description":"Year of membership start period"}}}],"description":"Period when tax membership starts"},"effectiveEndPeriod":{"allOf":[{"type":"object","properties":{"month":{"type":"integer","minimum":1,"maximum":12,"description":"Month of membership start period"},"year":{"type":"integer","minimum":1970,"description":"Year of membership start period"}}}],"description":"Period when tax effectiveness ends"},"effectiveStartPeriod":{"allOf":[{"type":"object","properties":{"month":{"type":"integer","minimum":1,"maximum":12,"description":"Month of membership start period"},"year":{"type":"integer","minimum":1970,"description":"Year of membership start period"}}}],"description":"Period when tax becomes effective"},"method":{"type":"string","enum":["GROSS","NETTO","GROSS_UP","MIX","MIX_GROSS_NETTO","MIX_NETTO_GROSS","MIX_GROSS_UP_GROSS"],"description":"PPh21 calculation method"},"moreThanOneEmployer":{"type":"boolean","description":"Whether employee has more than one employer"},"npwpAddress":{"type":"string","description":"Address registered with NPWP"},"npwpNumber":{"type":"string","pattern":"^$|^\\d+$","description":"NPWP (Tax ID) number - can be empty or contain only digits"},"tin":{"type":"string","description":"Tax Identification Number"},"previousNetIncome":{"type":"number","format":"double","minimum":0,"description":"Previous net income amount"},"previousPaidPph":{"type":"number","format":"double","minimum":0,"description":"Previous paid PPh amount"},"ptkpCategoryId":{"type":"string","description":"PTKP (Personal Tax Free Income) category identifier"},"taxObject":{"type":"string","enum":["PERMANENT","TEMPORARY","MULTI_LEVEL_DISTRIBUTOR","INSURANCE_AGENT","MERCHANT_GOODS","EXPERT_CONTINUOUS","EXPERT_NON_CONTINUOUS","CONTINUOUS","NON_CONTINUOUS","COMMISSIONER","FORMER_EMPLOYEE","EVENT_PARTICIPANT","EXPATRIATE","EXPERT","MEETING_PARTICIPANT","COMMITTEE_PARTICIPANT","EDUCATION_PARTICIPANT","OTHER_PARTICIPANT","ADVISOR_LECTURER","AUTHOR_RESEARCHER","SERVICE_PROVIDER","ADVERTISING_AGENT","PROJECT_MANAGER","INTERMEDIARY","ARTIST","ATHLETE","TEMPORARY_MONTHLY","COMPETITION_PARTICIPANT"],"description":"Type of tax object for the employee"},"useRecommendedPeriod":{"type":"boolean"},"taxDependents":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Name of the tax dependent"},"ptkpRelationType":{"type":"string","enum":["SPOUSE","CHILD","PARENT"],"description":"Relationship type for PTKP calculation"},"dateOfBirth":{"type":"string","format":"date","description":"Date of birth of the tax dependent"},"job":{"type":"string","description":"Job or occupation of the tax dependent"}}},"description":"List of tax dependents for PTKP calculation"}}},{"type":"object","properties":{"employee":{"type":"object","properties":{"id":{"type":"string"},"identificationNumber":{"type":"string"},"name":{"type":"string"}}}}}]}}}},"400":{"description":"Bad Request - Invalid ID format","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Error message"},"status":{"type":"integer","description":"HTTP status code"},"timestamp":{"type":"string","description":"Timestamp when the error occurred"}}}}}},"404":{"description":"Tax membership history not found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Error message"},"status":{"type":"integer","description":"HTTP status code"},"timestamp":{"type":"string","description":"Timestamp when the error occurred"}}}}}}}}}}}
```

## Update Tax Membership History Tax Subject

> Update tax subject information for a specific tax membership history record

```json
{"openapi":"3.0.0","info":{"title":"CATAPA API","version":"1.0.0"},"tags":[{"name":"tax-membership-history","description":"These endpoints let you manage(retrieve and update) tax membership histories for employees.\n"}],"servers":[{"url":"https://api.catapa.com","description":"Production server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication header of the form `Bearer <token>`."}}},"paths":{"/core/v1/tax-membership-histories/{id}/tax-subjects":{"put":{"tags":["tax-membership-history"],"summary":"Update Tax Membership History Tax Subject","description":"Update tax subject information for a specific tax membership history record","parameters":[{"in":"path","name":"id","schema":{"type":"string"},"required":true,"description":"Unique identifier for the tax membership history record"}],"responses":{"200":{"description":"Tax membership history tax subject updated successfully","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the tax membership"},"foreignTaxObject":{"type":"boolean","description":"Whether this is a foreign tax object"},"kppId":{"type":"string","description":"Tax office (KPP) identifier"},"linkToPayroll":{"type":"boolean","description":"Whether this tax membership is linked to payroll"},"membershipEndPeriod":{"allOf":[{"type":"object","properties":{"month":{"type":"integer","minimum":1,"maximum":12,"description":"Month of membership start period"},"year":{"type":"integer","minimum":1970,"description":"Year of membership start period"}}}],"description":"Period when tax membership ends"},"membershipStartPeriod":{"allOf":[{"type":"object","properties":{"month":{"type":"integer","minimum":1,"maximum":12,"description":"Month of membership start period"},"year":{"type":"integer","minimum":1970,"description":"Year of membership start period"}}}],"description":"Period when tax membership starts"},"effectiveEndPeriod":{"allOf":[{"type":"object","properties":{"month":{"type":"integer","minimum":1,"maximum":12,"description":"Month of membership start period"},"year":{"type":"integer","minimum":1970,"description":"Year of membership start period"}}}],"description":"Period when tax effectiveness ends"},"effectiveStartPeriod":{"allOf":[{"type":"object","properties":{"month":{"type":"integer","minimum":1,"maximum":12,"description":"Month of membership start period"},"year":{"type":"integer","minimum":1970,"description":"Year of membership start period"}}}],"description":"Period when tax becomes effective"},"method":{"type":"string","enum":["GROSS","NETTO","GROSS_UP","MIX","MIX_GROSS_NETTO","MIX_NETTO_GROSS","MIX_GROSS_UP_GROSS"],"description":"PPh21 calculation method"},"moreThanOneEmployer":{"type":"boolean","description":"Whether employee has more than one employer"},"npwpAddress":{"type":"string","description":"Address registered with NPWP"},"npwpNumber":{"type":"string","pattern":"^$|^\\d+$","description":"NPWP (Tax ID) number - can be empty or contain only digits"},"tin":{"type":"string","description":"Tax Identification Number"},"previousNetIncome":{"type":"number","format":"double","minimum":0,"description":"Previous net income amount"},"previousPaidPph":{"type":"number","format":"double","minimum":0,"description":"Previous paid PPh amount"},"ptkpCategoryId":{"type":"string","description":"PTKP (Personal Tax Free Income) category identifier"},"taxObject":{"type":"string","enum":["PERMANENT","TEMPORARY","MULTI_LEVEL_DISTRIBUTOR","INSURANCE_AGENT","MERCHANT_GOODS","EXPERT_CONTINUOUS","EXPERT_NON_CONTINUOUS","CONTINUOUS","NON_CONTINUOUS","COMMISSIONER","FORMER_EMPLOYEE","EVENT_PARTICIPANT","EXPATRIATE","EXPERT","MEETING_PARTICIPANT","COMMITTEE_PARTICIPANT","EDUCATION_PARTICIPANT","OTHER_PARTICIPANT","ADVISOR_LECTURER","AUTHOR_RESEARCHER","SERVICE_PROVIDER","ADVERTISING_AGENT","PROJECT_MANAGER","INTERMEDIARY","ARTIST","ATHLETE","TEMPORARY_MONTHLY","COMPETITION_PARTICIPANT"],"description":"Type of tax object for the employee"},"useRecommendedPeriod":{"type":"boolean"},"taxDependents":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Name of the tax dependent"},"ptkpRelationType":{"type":"string","enum":["SPOUSE","CHILD","PARENT"],"description":"Relationship type for PTKP calculation"},"dateOfBirth":{"type":"string","format":"date","description":"Date of birth of the tax dependent"},"job":{"type":"string","description":"Job or occupation of the tax dependent"}}},"description":"List of tax dependents for PTKP calculation"}}},{"type":"object","properties":{"employee":{"type":"object","properties":{"id":{"type":"string"},"identificationNumber":{"type":"string"},"name":{"type":"string"}}}}}]}}}},"400":{"description":"Bad Request - Invalid input data","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Error message"},"status":{"type":"integer","description":"HTTP status code"},"timestamp":{"type":"string","description":"Timestamp when the error occurred"}}}}}},"404":{"description":"Tax membership history not found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Error message"},"status":{"type":"integer","description":"HTTP status code"},"timestamp":{"type":"string","description":"Timestamp when the error occurred"}}}}}},"422":{"description":"Unprocessable Entity - Business logic validation failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"details":{"type":"array","items":{"type":"string"},"description":"Business validation errors"}}}}}}},"requestBody":{"required":true,"description":"Tax subject information to update for the history record","content":{"application/json":{"schema":{"type":"object","properties":{"npwpAddress":{"type":"string","description":"Address registered with NPWP"},"npwpNumber":{"type":"string","pattern":"^$|^\\d+$","description":"NPWP (Tax ID) number - can be empty or contain only digits"},"idTku":{"type":"string","description":"TKU (Tax Knowledge Unit) identifier"},"tin":{"type":"string","description":"Tax Identification Number"},"kppId":{"type":"string","description":"Tax office (KPP) identifier"},"ptkpCategoryId":{"type":"string","description":"PTKP (Personal Tax Free Income) category identifier"},"taxDependents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the tax dependent"},"name":{"type":"string","maxLength":100,"description":"Name of the tax dependent"},"ptkpRelationType":{"type":"string","enum":["CHILD","SPOUSE","PARENT"],"description":"Relationship type for PTKP calculation"},"dateOfBirth":{"type":"string","format":"date","description":"Date of birth of the tax dependent (YYYY-MM-DD)."},"job":{"type":"string","maxLength":100,"description":"Job or occupation of the tax dependent"}},"required":["name","ptkpRelationType","dateOfBirth"]},"description":"List of tax dependents for PTKP calculation"}},"required":["npwpAddress"],"additionalProperties":false}}}}}}}}
```
