> ## Documentation Index
> Fetch the complete documentation index at: https://docs.intermezzo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Employee Tax Details

> Create new tax details for an employee.



## OpenAPI

````yaml /api-reference/preview.json post /organizations/{organization_id}/employees/{employee_id}/tax-details
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers: []
security: []
paths:
  /organizations/{organization_id}/employees/{employee_id}/tax-details:
    post:
      tags:
        - Core
        - Employees
        - Tax Details
      summary: Create Employee Tax Details
      description: Create new tax details for an employee.
      operationId: >-
        create_employee_tax_details_organizations__organization_id__employees__employee_id__tax_details_post
      parameters:
        - name: organization_id
          in: path
          required: true
          schema:
            anyOf:
              - type: string
              - type: string
                format: uuid
            title: Organization Id
        - name: employee_id
          in: path
          required: true
          schema:
            anyOf:
              - type: string
              - type: string
                format: uuid
            title: Employee Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/DETaxDetails'
                - $ref: '#/components/schemas/GBTaxDetails'
              discriminator:
                propertyName: employment_country
                mapping:
                  DE:
                    $ref: '#/components/schemas/DETaxDetails'
                  GB:
                    $ref: '#/components/schemas/GBTaxDetails'
              title: Tax Details
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/DETaxDetailsResponse'
                  - $ref: '#/components/schemas/GBTaxDetailsResponse'
                discriminator:
                  propertyName: employment_country
                  mapping:
                    DE:
                      $ref: '#/components/schemas/DETaxDetailsResponse'
                    GB:
                      $ref: '#/components/schemas/GBTaxDetailsResponse'
                title: >-
                  Response Create Employee Tax Details Organizations 
                  Organization Id  Employees  Employee Id  Tax Details Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - BearerToken: []
components:
  schemas:
    DETaxDetails:
      properties:
        employment_country:
          type: string
          const: DE
          title: Employment Country
          default: DE
        tax_id:
          type: string
          maxLength: 11
          minLength: 11
          title: Tax Id
          description: 'Steuerliche Identifikationsnummer (11 digits) - ELSTAM: steuerid'
        tax_class:
          $ref: '#/components/schemas/TaxClassType'
          description: 'Steuerklasse (1-6) - ELSTAM: steuerklasse'
        child_allowances:
          anyOf:
            - type: number
              multipleOf: 0.5
              maximum: 9
              minimum: 0
            - type: string
              pattern: >-
                ^(?!^[-+.]*$)[+-]?0*(?:\d{0,1}|(?=[\d.]{1,3}0*$)\d{0,1}\.\d{0,1}0*$)
          title: Child Allowances
          description: 'Kinderfreibeträge - ELSTAM: kinderfreibetrag'
          default: '0.0'
        church_confession:
          anyOf:
            - $ref: '#/components/schemas/ChurchTaxConfession'
            - type: 'null'
          description: 'Konfession für Kirchensteuer - ELSTAM: kirchensteuer'
        church_confession_partner:
          anyOf:
            - $ref: '#/components/schemas/ChurchTaxConfession'
            - type: 'null'
          description: 'Konfession des Partners - ELSTAM: kirchensteuer_partner'
        factor_procedure:
          type: boolean
          title: Factor Procedure
          description: Faktorverfahren
          default: false
        factor:
          anyOf:
            - type: integer
              maximum: 999
              minimum: 0
            - type: 'null'
          title: Factor
          description: Factor Percent as Integer (0-999)
        tax_allowance_amount:
          anyOf:
            - type: number
              minimum: 0
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$
            - type: 'null'
          title: Tax Allowance Amount
          description: 'Steuerfreibetrag - ELSTAM: freibetrag monat'
        additional_taxable_amount:
          anyOf:
            - type: number
              minimum: 0
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$
            - type: 'null'
          title: Additional Taxable Amount
          description: 'Hinzurechnungsbetrag - ELSTAM: hinzurechnungsbetrag monat'
        valid_from:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Valid From
          description: 'Gültig ab Datum - ELSTAM: gueltig_ab'
        valid_to:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Valid To
          description: 'EN: Valid to date | DE: Gültig bis Datum'
        church_member:
          type: boolean
          title: Church Member
          description: Kirchensteuerpflichtig
          default: false
        church_tax_state:
          anyOf:
            - $ref: '#/components/schemas/payroll__de__payroll_types__DEStates'
            - type: 'null'
          description: Bundesland for church tax
      additionalProperties: true
      type: object
      required:
        - tax_id
        - tax_class
      title: DETaxDetails
      description: >-
        German-specific tax data with comprehensive validation aligned with
        ELSTAM API
    GBTaxDetails:
      properties:
        employment_country:
          type: string
          const: GB
          title: Employment Country
          default: GB
        rti_id:
          anyOf:
            - type: string
              maxLength: 35
              minLength: 1
            - type: 'null'
          title: Rti Id
          description: >-
            RTI Payroll ID — unique identifier for this employee in HMRC
            submissions
        tax_code:
          $ref: '#/components/schemas/TaxCode-Input'
          description: HMRC Tax code (e.g., '1257L', 'K475', 'BR')
        student_loan_type:
          anyOf:
            - $ref: '#/components/schemas/StudentLoanPlanType'
            - type: 'null'
          description: Student loan type
        postgraduate_loan:
          type: boolean
          title: Postgraduate Loan
          description: Postgraduate loan?
          default: false
        p45_gross_pay:
          anyOf:
            - type: number
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: P45 Gross Pay
          description: P45 gross pay
          default: '0.00'
        p45_tax_amount:
          anyOf:
            - type: number
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: P45 Tax Amount
          description: P45 tax amount
          default: '0.00'
        valid_from:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Valid From
        valid_to:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Valid To
      additionalProperties: true
      type: object
      required:
        - tax_code
      title: GBTaxDetails
    DETaxDetailsResponse:
      properties:
        employee_id:
          type: string
          title: Employee Id
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        id:
          anyOf:
            - type: string
            - type: string
              format: uuid
          title: Id
        employment_country:
          type: string
          const: DE
          title: Employment Country
          default: DE
        tax_id:
          type: string
          maxLength: 11
          minLength: 11
          title: Tax Id
        tax_class:
          $ref: '#/components/schemas/TaxClassType'
        child_allowances:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*(?:\d{0,1}|(?=[\d.]{1,3}0*$)\d{0,1}\.\d{0,1}0*$)
          title: Child Allowances
          default: '0.0'
        church_confession:
          anyOf:
            - $ref: '#/components/schemas/ChurchTaxConfession'
            - type: 'null'
        church_confession_partner:
          anyOf:
            - $ref: '#/components/schemas/ChurchTaxConfession'
            - type: 'null'
          description: 'Konfession des Partners - ELSTAM: kirchensteuer_partner'
        factor_procedure:
          type: boolean
          title: Factor Procedure
          default: false
        factor:
          anyOf:
            - type: integer
            - type: 'null'
          title: Factor
        tax_allowance_amount:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Tax Allowance Amount
          default: '0.00'
        additional_taxable_amount:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Additional Taxable Amount
          default: '0.00'
        valid_from:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Valid From
          description: 'Gültig ab Datum - ELSTAM: gueltig_ab'
        valid_to:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Valid To
          description: 'EN: Valid to date | DE: Gültig bis Datum'
        church_member:
          type: boolean
          title: Church Member
          default: false
        church_tax_state:
          anyOf:
            - $ref: '#/components/schemas/payroll__de__payroll_types__DEStates'
            - type: 'null'
      additionalProperties: true
      type: object
      required:
        - employee_id
        - created_at
        - updated_at
        - id
        - tax_id
        - tax_class
      title: DETaxDetailsResponse
      description: Response model for tax details with metadata fields.
    GBTaxDetailsResponse:
      properties:
        employee_id:
          type: string
          title: Employee Id
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created At
        updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updated At
        id:
          anyOf:
            - type: string
            - type: string
              format: uuid
          title: Id
        employment_country:
          type: string
          const: GB
          title: Employment Country
          default: GB
        rti_id:
          type: string
          title: Rti Id
        tax_code:
          $ref: '#/components/schemas/TaxCode-Output'
        student_loan_type:
          anyOf:
            - $ref: '#/components/schemas/StudentLoanPlanType'
            - type: 'null'
        postgraduate_loan:
          type: boolean
          title: Postgraduate Loan
          default: false
        p45_gross_pay:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: P45 Gross Pay
          default: '0.00'
        p45_tax_amount:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: P45 Tax Amount
          default: '0.00'
        valid_from:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Valid From
        valid_to:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Valid To
      additionalProperties: true
      type: object
      required:
        - employee_id
        - created_at
        - updated_at
        - id
        - rti_id
        - tax_code
      title: GBTaxDetailsResponse
      description: Response model for tax details with metadata fields.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TaxClassType:
      type: string
      enum:
        - '1'
        - '2'
        - '3'
        - '4'
        - '5'
        - '6'
      title: TaxClassType
      description: Steuerklasse (STKL)
    ChurchTaxConfession:
      type: string
      enum:
        - AK
        - EV
        - FA
        - FB
        - FG
        - FM
        - FR
        - FS
        - IB
        - IH
        - IL
        - IS
        - IW
        - JD
        - JH
        - LT
        - RF
        - RK
        - NA
        - KEINE
      title: ChurchTaxConfession
      description: German church tax confessions as defined in ELSTAM API
    payroll__de__payroll_types__DEStates:
      type: string
      enum:
        - Baden-Württemberg
        - Bayern
        - Berlin
        - Brandenburg
        - Bremen
        - Hamburg
        - Hessen
        - Mecklenburg-Vorpommern
        - Niedersachsen
        - Nordrhein-Westfalen
        - Rheinland-Pfalz
        - Saarland
        - Sachsen
        - Sachsen-Anhalt
        - Schleswig-Holstein
        - Thüringen
      title: DEStates
      description: German states (Bundesländer) with their official names
    TaxCode-Input:
      properties:
        original_code:
          type: string
          title: Original Code
        personal_allowance:
          anyOf:
            - type: number
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Personal Allowance
          default: '0'
        prefix:
          anyOf:
            - type: string
            - type: 'null'
          title: Prefix
        prefix_meaning:
          anyOf:
            - type: string
            - type: 'null'
          title: Prefix Meaning
        suffix:
          anyOf:
            - type: string
            - type: 'null'
          title: Suffix
        suffix_meaning:
          anyOf:
            - type: string
            - type: 'null'
          title: Suffix Meaning
        emergency:
          type: boolean
          title: Emergency
          default: false
        region:
          $ref: '#/components/schemas/Region'
          default: England/NI
      type: object
      required:
        - original_code
      title: TaxCode
      description: Represents a parsed UK HMRC tax code
    StudentLoanPlanType:
      type: string
      enum:
        - Plan1
        - Plan2
        - Plan4
      title: StudentLoanPlanType
      description: Types of student loan plans
    TaxCode-Output:
      properties:
        original_code:
          type: string
          title: Original Code
        personal_allowance:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Personal Allowance
          default: '0'
        prefix:
          anyOf:
            - type: string
            - type: 'null'
          title: Prefix
        prefix_meaning:
          anyOf:
            - type: string
            - type: 'null'
          title: Prefix Meaning
        suffix:
          anyOf:
            - type: string
            - type: 'null'
          title: Suffix
        suffix_meaning:
          anyOf:
            - type: string
            - type: 'null'
          title: Suffix Meaning
        emergency:
          type: boolean
          title: Emergency
          default: false
        region:
          $ref: '#/components/schemas/Region'
          default: England/NI
      type: object
      required:
        - original_code
      title: TaxCode
      description: Represents a parsed UK HMRC tax code
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    Region:
      type: string
      enum:
        - England/NI
        - Scotland
        - Wales
      title: Region
      description: UK Tax Regions
  securitySchemes:
    BearerToken:
      type: oauth2
      flows:
        password:
          scopes:
            read:all: Read all
            write:all: Write all
            read:health_check: Read health check
            write:health_check: Write health check
            read:wage_types: Read wage types
            write:wage_types: Write wage types
          tokenUrl: >-
            https://auth-preview.intermezzo.ai/authorize?audience=api-preview.intermezzo.ai

````