---
updatedAt: 2026-07-03T12:40:57.000Z
agentTools:
  projectIndex: https://developer.xentral.com/llms.txt
---

# 🔒 Create tax account mapping

This endpoint is currently in Beta and available for testing. It may contain bugs, and breaking changes can occur at any time without prior notice. We do not recommend using Beta endpoints in production environments. Should you choose to use it in production, you assume full responsibility for any resulting issues.

Creates a single tax account mapping.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Xentral API",
    "version": "v0.1",
    "description": "Xentral is an ERP platform.",
    "contact": {
      "name": "Xentral",
      "url": "https://xentral.com",
      "email": "api@xentral.com"
    }
  },
  "tags": [
    {
      "name": "Tax Account Mapping",
      "description": "Tax Account Mapping configurations"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Bearer token obtained in POST /tokens endpoint or pregenerated in the system."
      }
    }
  },
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "servers": [
    {
      "url": "https://{xentralId}.xentral.biz",
      "description": "Your Xentral Instance",
      "variables": {
        "xentralId": {
          "default": "xentral"
        }
      }
    },
    {
      "url": "https://{domain}",
      "description": "Xentral at a custom domain",
      "variables": {
        "domain": {
          "default": "xentral.com"
        }
      }
    }
  ],
  "x-readme": {
    "samples-languages": []
  },
  "paths": {
    "/api/v1/taxAccountMapping": {
      "post": {
        "tags": [
          "Tax Account Mapping"
        ],
        "operationId": "taxAccountMapping.create.v1",
        "summary": "🔒 Create tax account mapping",
        "description": "This endpoint is currently in Beta and available for testing. It may contain bugs, and breaking changes can occur at any time without prior notice. We do not recommend using Beta endpoints in production environments. Should you choose to use it in production, you assume full responsibility for any resulting issues.\n\nCreates a single tax account mapping.",
        "requestBody": {
          "description": "Create a tax account mapping object",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true,
                "required": [
                  "accountId"
                ],
                "properties": {
                  "accountId": {
                    "type": "string"
                  },
                  "countryCode": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 2
                  },
                  "region": {
                    "type": "string",
                    "maxLength": 100
                  },
                  "zipCode": {
                    "type": "string",
                    "maxLength": 10
                  },
                  "isActive": {
                    "type": "boolean"
                  }
                }
              },
              "examples": {
                "tax account mapping": {
                  "value": {
                    "accountId": "1",
                    "countryCode": "DE",
                    "region": "",
                    "zipCode": "",
                    "isActive": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true,
                  "description": "Tax account mapping entry",
                  "properties": {
                    "id": {
                      "description": "Tax account mapping ID",
                      "type": "string",
                      "example": "1"
                    },
                    "name": {
                      "description": "Name of the mapping",
                      "type": "string",
                      "example": ""
                    },
                    "account": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "Account entry",
                      "properties": {
                        "id": {
                          "description": "Account ID",
                          "type": "string",
                          "example": "1"
                        },
                        "accountNumber": {
                          "description": "Account number",
                          "type": "string",
                          "example": "1000"
                        },
                        "accountType": {
                          "description": "Account type",
                          "type": "string",
                          "maxLength": 50,
                          "example": "asset"
                        },
                        "name": {
                          "description": "Account name",
                          "type": "string",
                          "maxLength": 100,
                          "example": "Cash Account"
                        },
                        "description": {
                          "description": "Account description",
                          "type": "string",
                          "maxLength": 255,
                          "example": "Main cash account for daily operations"
                        },
                        "isStandard": {
                          "description": "Is standard account",
                          "type": "boolean",
                          "example": false
                        },
                        "deletedAt": {
                          "description": "Deleted at timestamp",
                          "type": "string",
                          "format": "date-time",
                          "nullable": true,
                          "example": null
                        },
                        "createdAt": {
                          "description": "Created at timestamp",
                          "type": "string",
                          "format": "date-time",
                          "example": "2022-01-01T00:00:00Z"
                        },
                        "updatedAt": {
                          "description": "Updated at timestamp",
                          "type": "string",
                          "format": "date-time",
                          "example": "2022-01-01T00:00:00Z"
                        }
                      },
                      "example": {
                        "id": "1",
                        "accountNumber": "1000",
                        "accountType": "asset",
                        "name": "Cash Account",
                        "description": "Main cash account for daily operations",
                        "isStandard": false,
                        "deletedAt": null,
                        "createdAt": "2022-01-01T00:00:00Z",
                        "updatedAt": "2022-01-01T00:00:00Z"
                      }
                    },
                    "taxType": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "Tax type entry",
                      "properties": {
                        "id": {
                          "description": "Tax type ID",
                          "type": "string",
                          "example": "1"
                        },
                        "name": {
                          "description": "Tax type name",
                          "type": "string",
                          "maxLength": 50,
                          "example": "custom_tax_type"
                        },
                        "description": {
                          "description": "Tax type description",
                          "type": "string",
                          "maxLength": 255,
                          "nullable": true,
                          "example": "Custom tax type for testing"
                        },
                        "isStandard": {
                          "description": "Is standard tax type",
                          "type": "boolean",
                          "example": false
                        },
                        "createdAt": {
                          "description": "Created at timestamp",
                          "type": "string",
                          "format": "date-time",
                          "example": "2022-01-01T00:00:00Z"
                        },
                        "updatedAt": {
                          "description": "Updated at timestamp",
                          "type": "string",
                          "format": "date-time",
                          "example": "2022-01-01T00:00:00Z"
                        }
                      },
                      "example": {
                        "id": "1",
                        "name": "custom_tax_type",
                        "description": "Custom tax type for testing",
                        "isStandard": false,
                        "createdAt": "2022-01-01T00:00:00Z",
                        "updatedAt": "2022-01-01T00:00:00Z"
                      }
                    },
                    "countryCode": {
                      "description": "Country code in ISO 3166-1 alpha-2 format",
                      "type": "string",
                      "example": "DE"
                    },
                    "region": {
                      "description": "Region",
                      "type": "string",
                      "nullable": true,
                      "example": ""
                    },
                    "zipCode": {
                      "description": "ZIP code",
                      "type": "string",
                      "nullable": true,
                      "example": ""
                    },
                    "isActive": {
                      "description": "Is active",
                      "type": "boolean",
                      "example": true
                    },
                    "createdAt": {
                      "description": "Created at timestamp",
                      "type": "string",
                      "format": "date-time",
                      "example": "2022-01-01T00:00:00Z"
                    },
                    "updatedAt": {
                      "description": "Updated at timestamp",
                      "type": "string",
                      "format": "date-time",
                      "example": "2022-01-01T00:00:00Z"
                    }
                  },
                  "example": {
                    "id": "2",
                    "name": "",
                    "account": {
                      "id": "3",
                      "accountNumber": "1776",
                      "accountType": "tax",
                      "name": "VAT Standard",
                      "description": "VAT 19%",
                      "isStandard": true,
                      "deletedAt": null,
                      "createdAt": "2025-08-13T09:02:39.808Z",
                      "updatedAt": "2025-08-13T09:02:39.808Z"
                    },
                    "taxType": {
                      "id": "1",
                      "name": "standard",
                      "description": "Standard",
                      "isStandard": true,
                      "createdAt": "2025-11-26T08:08:53.640784Z",
                      "updatedAt": "2025-11-26T08:08:53.640784Z"
                    },
                    "countryCode": "DE",
                    "region": "",
                    "zipCode": "",
                    "isActive": true,
                    "createdAt": "2022-01-01T00:00:00Z",
                    "updatedAt": "2022-01-01T00:00:00Z"
                  }
                }
              }
            }
          },
          "400": {
            "description": "XGL Problem",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "description": "XGL Problem specification",
                  "properties": {
                    "type": {
                      "type": "string",
                      "description": "URL of the problem",
                      "example": "https://api.xentral.biz/problems/xgl-error"
                    },
                    "title": {
                      "type": "string",
                      "description": "title of the error. It should be always XGL Error",
                      "example": "XGL Error"
                    },
                    "errorCode": {
                      "type": "integer",
                      "description": "Error code regarding the request failure",
                      "enum": [
                        1,
                        2,
                        3,
                        4,
                        5,
                        6,
                        7,
                        8,
                        9,
                        10,
                        11,
                        12
                      ],
                      "example": 1
                    },
                    "message": {
                      "type": "string",
                      "description": "General description about the failed request",
                      "enum": [
                        "Error listing tax obligations",
                        "Error creating tax obligation",
                        "Error listing taxes",
                        "Error getting account information",
                        "Error getting account mapping information",
                        "Error listing account mappings",
                        "Error creating account mapping",
                        "Error updating account mapping",
                        "Error deleting account mapping",
                        "Error creating tax",
                        "Error updating tax",
                        "Error getting general ledger"
                      ],
                      "example": "Error getting account information"
                    },
                    "details": {
                      "type": "object",
                      "description": "Object containing the fields and their specifications",
                      "additionalProperties": {
                        "type": "string"
                      },
                      "example": {
                        "field": "Additional error detail"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unable to authenticate the client",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "description": "Error message explaining why the request failed.",
                      "example": "Missing required scopes: customer:create."
                    }
                  }
                },
                "example": {
                  "message": "Missing required scopes: customer:create."
                }
              },
              "text/html": {
                "schema": {
                  "type": "string",
                  "example": "Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Unable to authorize the client"
          },
          "409": {
            "description": "IETF RFC 9457 Problem API compliant response",
            "content": {
              "application/problem+json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "type",
                        "title",
                        "violations"
                      ],
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "https://api.xentral.biz/problems/request-validation"
                          ]
                        },
                        "title": {
                          "type": "string",
                          "minLength": 1,
                          "example": "Request payload validation failed."
                        },
                        "violations": {
                          "oneOf": [
                            {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "example": {
                                  "username": [
                                    "This value should not be blank."
                                  ],
                                  "email": [
                                    "This value is not a valid email address."
                                  ]
                                }
                              },
                              "description": "This field will be a mirrored request payload with only invalid fields and values replaced by error messages."
                            },
                            {
                              "type": "object",
                              "example": {
                                "_": [
                                  "This value should contain at most `9` elements."
                                ]
                              },
                              "description": "This field will be a mirrored request payload with only invalid fields and values replaced by error messages."
                            }
                          ]
                        }
                      }
                    },
                    {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "type",
                        "title",
                        "messages"
                      ],
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "https://api.xentral.biz/problems/generic-validation"
                          ]
                        },
                        "title": {
                          "type": "string",
                          "minLength": 1
                        },
                        "messages": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "type",
                        "title",
                        "messages"
                      ],
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "https://api.xentral.biz/problems/conflict"
                          ]
                        },
                        "title": {
                          "type": "string",
                          "minLength": 1
                        },
                        "messages": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "type",
                        "title",
                        "items"
                      ],
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "https://api.xentral.biz/problems/conflictItems"
                          ]
                        },
                        "title": {
                          "type": "string",
                          "minLength": 1
                        },
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": false,
                            "required": [
                              "id",
                              "title",
                              "messages"
                            ],
                            "properties": {
                              "id": {
                                "type": "integer"
                              },
                              "title": {
                                "type": "string",
                                "minLength": 1
                              },
                              "messages": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "type",
                        "title",
                        "scopes"
                      ],
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "https://developer.xentral.com/reference/problems#token-scopes"
                          ]
                        },
                        "title": {
                          "type": "string",
                          "minLength": 1
                        },
                        "scopes": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "type",
                        "title",
                        "messages"
                      ],
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "https://api.xentral.biz/problems/generic-validation"
                          ]
                        },
                        "title": {
                          "type": "string",
                          "minLength": 1
                        },
                        "messages": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "415": {
            "description": "Resource representation send in the request is not supported."
          },
          "429": {
            "description": "Too many API calls made."
          },
          "500": {
            "description": "XGL Problem",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "description": "XGL Problem specification",
                  "properties": {
                    "type": {
                      "type": "string",
                      "description": "URL of the problem",
                      "example": "https://api.xentral.biz/problems/xgl-error"
                    },
                    "title": {
                      "type": "string",
                      "description": "title of the error. It should be always XGL Error",
                      "example": "XGL Error"
                    },
                    "errorCode": {
                      "type": "integer",
                      "description": "Error code regarding the request failure",
                      "enum": [
                        1,
                        2,
                        3,
                        4,
                        5,
                        6,
                        7,
                        8,
                        9,
                        10,
                        11,
                        12
                      ],
                      "example": 1
                    },
                    "message": {
                      "type": "string",
                      "description": "General description about the failed request",
                      "enum": [
                        "Error listing tax obligations",
                        "Error creating tax obligation",
                        "Error listing taxes",
                        "Error getting account information",
                        "Error getting account mapping information",
                        "Error listing account mappings",
                        "Error creating account mapping",
                        "Error updating account mapping",
                        "Error deleting account mapping",
                        "Error creating tax",
                        "Error updating tax",
                        "Error getting general ledger"
                      ],
                      "example": "Error getting account information"
                    },
                    "details": {
                      "type": "object",
                      "description": "Object containing the fields and their specifications",
                      "additionalProperties": {
                        "type": "string"
                      },
                      "example": {
                        "field": "Additional error detail"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```