{
  "openapi": "3.1.0",
  "info": {
    "title": "Tax & Relax API",
    "version": "0.1.0"
  },
  "paths": {
    "/v1/clients": {
      "post": {
        "tags": [
          "v1"
        ],
        "summary": "Create Client",
        "description": "Create a client in your Tax & Relax account.\n\nWith an `Idempotency-Key`, the same key and the same body within 24 hours answer with the\nclient the first call created, as it is stored now, and `Idempotent-Replayed: true`; the\nsame key with another body is refused with `409 idempotency_key_reused`. After 24 hours\nthe key counts as new.",
        "operationId": "createClient",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ],
              "minLength": 1,
              "maxLength": 128,
              "title": "Idempotency-Key"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ClientCreateV1"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClientV1"
                }
              }
            }
          },
          "401": {
            "description": "No valid API key: missing, malformed, unknown or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "`idempotency_key_reused`: the key came before with another body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "422": {
            "description": "The body or a header did not parse.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiValidationError"
                }
              }
            }
          },
          "500": {
            "description": "An error on our side.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ApiError": {
        "properties": {
          "code": {
            "type": "string",
            "title": "Code"
          },
          "detail": {
            "type": "string",
            "title": "Detail"
          }
        },
        "type": "object",
        "required": [
          "code",
          "detail"
        ],
        "title": "ApiError",
        "description": "Every answer under `/v1` that is not a success: a stable `code` and an English sentence."
      },
      "ApiValidationError": {
        "properties": {
          "code": {
            "type": "string",
            "title": "Code"
          },
          "detail": {
            "type": "string",
            "title": "Detail"
          },
          "errors": {
            "items": {
              "additionalProperties": true,
              "type": "object"
            },
            "type": "array",
            "title": "Errors"
          }
        },
        "type": "object",
        "required": [
          "code",
          "detail",
          "errors"
        ],
        "title": "ApiValidationError",
        "description": "A request that did not parse; `errors` lists each problem as FastAPI reports it."
      },
      "ClientCreateV1": {
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 255,
            "minLength": 1,
            "title": "Name",
            "description": "The client's full name."
          },
          "profile_modifiers": {
            "items": {
              "$ref": "#/components/schemas/ProfileModifier"
            },
            "type": "array",
            "title": "Profile Modifiers",
            "description": "What you already know about the client's tax situation; leave out what you do not know.\n\n- `joint_filing`: married or in a civil partnership and assessed jointly\n- `rental_income`: income from letting property\n- `capital_income`: income from investments\n- `pension_income`: income from pensions\n- `foreign_income`: income from abroad\n- `vat_liable`: a business that charges VAT\n- `kleinunternehmer`: a small business that charges no VAT (§ 19 UStG)\n- `employees`: a business with employees",
            "default": []
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "format": "email",
            "title": "Email",
            "description": "The client's email address."
          },
          "phone": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 50,
            "title": "Phone",
            "description": "The client's phone number."
          },
          "client_number": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 64,
            "title": "Client Number",
            "description": "Your own reference for the client, returned as sent. It is not checked for uniqueness: two requests with the same number create two clients."
          },
          "notes": {
            "type": [
              "string",
              "null"
            ],
            "title": "Notes",
            "description": "Free text stored with the client."
          },
          "locale": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "de",
              "en",
              null
            ],
            "title": "Locale",
            "description": "The language Tax & Relax uses with the client: `de` German, `en` English. It sets the language of the client's emails and of their account until they choose one themselves. Without it, German."
          }
        },
        "type": "object",
        "required": [
          "name"
        ],
        "title": "ClientCreateV1",
        "description": "A new client: always a natural person."
      },
      "ClientV1": {
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id",
            "description": "Tax & Relax's id for the client."
          },
          "name": {
            "type": "string",
            "title": "Name",
            "description": "The client's full name."
          },
          "profile_modifiers": {
            "items": {
              "$ref": "#/components/schemas/ProfileModifier"
            },
            "type": "array",
            "title": "Profile Modifiers",
            "description": "What you already know about the client's tax situation; leave out what you do not know.\n\n- `joint_filing`: married or in a civil partnership and assessed jointly\n- `rental_income`: income from letting property\n- `capital_income`: income from investments\n- `pension_income`: income from pensions\n- `foreign_income`: income from abroad\n- `vat_liable`: a business that charges VAT\n- `kleinunternehmer`: a small business that charges no VAT (§ 19 UStG)\n- `employees`: a business with employees"
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "title": "Email",
            "description": "The client's email address."
          },
          "phone": {
            "type": [
              "string",
              "null"
            ],
            "title": "Phone",
            "description": "The client's phone number."
          },
          "client_number": {
            "type": [
              "string",
              "null"
            ],
            "title": "Client Number",
            "description": "Your own reference for the client, returned as sent. It is not checked for uniqueness: two requests with the same number create two clients."
          },
          "internal_number": {
            "type": "integer",
            "title": "Internal Number",
            "description": "Tax & Relax's own number for the client, assigned on creation."
          },
          "notes": {
            "type": [
              "string",
              "null"
            ],
            "title": "Notes",
            "description": "Free text stored with the client."
          },
          "locale": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "de",
              "en",
              null
            ],
            "title": "Locale",
            "description": "The language Tax & Relax uses with the client: `de` German, `en` English. It sets the language of the client's emails and of their account until they choose one themselves. Without it, German."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "title": "Created At",
            "description": "When the client was created."
          }
        },
        "type": "object",
        "required": [
          "id",
          "name",
          "profile_modifiers",
          "email",
          "phone",
          "client_number",
          "internal_number",
          "notes",
          "locale",
          "created_at"
        ],
        "title": "ClientV1",
        "description": "The client, as stored."
      },
      "ProfileModifier": {
        "type": "string",
        "enum": [
          "joint_filing",
          "rental_income",
          "capital_income",
          "pension_income",
          "foreign_income",
          "vat_liable",
          "kleinunternehmer",
          "employees"
        ],
        "title": "ProfileModifier"
      }
    },
    "securitySchemes": {
      "ApiKey": {
        "type": "http",
        "description": "Your API key, issued by Tax & Relax.",
        "scheme": "bearer"
      }
    }
  },
  "servers": [
    {
      "url": "https://app.taxnrelax.de/api"
    }
  ]
}