{
  "openapi": "3.0.3",
  "info": {
    "title": "Flowcase API",
    "version": "0.1.1",
    "description": "The Flowcase API lets you synchronise user data, manage reference\nprojects and customers, automate proposals, and integrate Flowcase\ninto your existing systems. All endpoints require a Bearer token API\nkey passed in the `Authorization` header.\n\n# Flowcase API Guidance\n\n## Request Encoding\n\nAll request bodies must be encoded as UTF-8 and sent with `Content-Type: application/json`\n(except attachment uploads, which use `multipart/form-data`).\n\n## Unknown Fields Are Silently Ignored\n\nThe API ignores any unrecognised attributes in request bodies. This makes\nintegrations resilient to field deprecation, but it also means a misspelled\noptional field name (e.g. `\"Title\"` instead of `\"title\"`) will be silently\ndropped rather than returning a validation error. Double-check field names\nwhen a request appears to succeed but the expected value is not persisted.\n\n## Parsing Responses\n\nAPI responses may include fields beyond those defined in this specification.\nUse a JSON parser that ignores unknown fields so your client continues to\nwork as new fields are introduced. Do not rely on undocumented fields - they\nmay change without notice.\n\n## Request IDs\n\nEvery response includes an `x-request-id` header containing a unique\nidentifier for the request. Log this value in your application and include\nit when contacting Flowcase support to help diagnose issues.\n\n## Multilingual Field Updates\n\nMultilingual fields (e.g. `project_name`, `title`, `customer_description`)\nare updated as **complete objects**. You must include all language variants\nin the update - any language key omitted from the request will be removed.\n\nFor example, if a field currently contains three languages:\n\n```json\n{ \"int\": \"Cloud Migration\", \"no\": \"Skymigrering\", \"de\": \"Cloud-Migration\" }\n```\n\nSending only the changed language:\n\n```json\n{ \"int\": \"Cloud Migration Project\" }\n```\n\nwill **delete** the Norwegian and German translations. Always include every\nlanguage you want to keep.\n\n## Language Codes\n\nMultilingual fields use language code keys to identify each translation.\nBy default the API returns legacy codes (e.g. `int` for English,\n`se` for Swedish, `cn` for Chinese). Pass `?use_legacy_codes=false` on any\nrequest to use standard ISO 639-1 codes instead (e.g. `en`, `sv`, `zh`).\n\nNew integrations should use `use_legacy_codes=false`. The legacy codes\nexist for backward compatibility with older integrations.\n\nThe parameter affects both response serialisation and request parsing -\nlanguage keys in the request body must match the active mode. Keys that\nare invalid in the active mode are silently dropped.\n\n# Rate Limits\n\nRequests are rate-limited for each API key, and for each account across\nall of its API keys.\n\n| Scope | Requests per second | Requests per minute |\n|-------|---------------------|---------------------|\n| Each API key | 10 | 300 |\n| All API keys on an account combined | 20 | 600 |\n| `/api/v1/cvs/download` and `/api/v1/data_export`, all API keys on an account combined | 0.5 (1 every 2s) | 10 |\n\nA request must stay within every limit that applies to it, so several\nbusy integrations on the same account can rate-limit each other. Use a\nseparate API key for each integration.\n\nA request over a limit gets a `429 Too Many Requests` response with a\n`Retry-After` header giving the number of seconds to wait before\nretrying. If the header is missing, back off exponentially.\n\n# User Roles\n\nEach user has exactly one base role and may also have additional extra roles.\n\n## Base Roles\n\n| Role | Description |\n|------|-------------|\n| `external` | Can only edit and see their own CV. Logs in using their private email and password. |\n| `limited_access` | Same as `consultant`, but cannot read or download other users' CVs. |\n| `consultant` | Can edit their own CV, read other CVs, and read official reference projects. |\n| `internationalmanager` | Administrator. Can change company-wide settings. |\n\n## Extra Roles\n\n| Extra Role | Description |\n|------------|-------------|\n| `referencemanager` | Can change all reference projects in the account. |\n| `countrymanager` | Can change all CVs and users in their own country. |\n| `departmentmanager` | Can change all CVs and references within selected departments or custom tags. |\n\nWhen assigning the `departmentmanager` role, you must also provide\n`role_allowed_office_ids` and/or `role_allowed_tag_ids` to specify the\nscope of access. `role_allowed_tag_ids` allows assigning managers to users\nindependently of how they are organised into offices.\n"
  },
  "servers": [
    {
      "url": "https://{subdomain}.flowcase.com",
      "description": "Flowcase Tenant",
      "variables": {
        "subdomain": {
          "default": "your-company",
          "description": "Your Flowcase subdomain"
        }
      }
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Users",
      "description": "Operations for retrieving user profiles and related data."
    },
    {
      "name": "Customers",
      "description": "Operations for looking up reference customers."
    },
    {
      "name": "Custom Tags",
      "description": "Operations for managing custom tag categories and tags."
    },
    {
      "name": "Reference Projects",
      "description": "Operations for managing reference projects."
    }
  ],
  "paths": {
    "/api/v1/users": {
      "post": {
        "operationId": "createUser",
        "summary": "Create a new user",
        "description": "Creates a new user in the current account under the specified country and office. Requires the authenticated API key to have the `countrymanager` role (for their own country) or `internationalmanager` role (for any country). API keys with only the default `consultant` role cannot create users.\n\nThe request body should be wrapped in a `user` key. At minimum, `email`, `country_id`, and `office_id` are required.\n\nThe base `role` must be one of `external`, `limited_access`, `consultant`, or `internationalmanager`. Extra access roles (`countrymanager`, `departmentmanager`, `referencemanager`, `bidmanager`) are always layered on top of `consultant` and must be passed via `extra_roles`. The roles assignable are limited by the caller's own role level. When assigning `departmentmanager`, also provide `role_allowed_office_ids` (country-specific offices) and/or `role_allowed_tag_ids` (cross-country department modelling).\n\nIf `send_email` is set to `true`, a welcome email is sent to the new user. Omit or set to `false` to create the user without the email.\n\nBy default, the response uses legacy language codes (`int`, `se`, `cn`, `my`, `by`, etc.). Pass `?use_legacy_codes=false` to receive ISO 639-1 codes (`en`, `sv`, `zh`, `ms`, `be`, etc.) in `language_code`, `language_codes`, `ui_language_code`, `masterdata_languages`, and multilingual field keys (`title`, `nationality`). Language codes provided in the request body (such as `title` keys and `override_language_code`) must match the active mode; codes that are invalid in the active mode are silently dropped rather than returning an error.\n",
        "tags": [
          "Users"
        ],
        "parameters": [
          {
            "name": "use_legacy_codes",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "false"
              ]
            },
            "description": "Pass `use_legacy_codes=false` to receive ISO 639-1 language codes instead of the default legacy codes. Affects `language_code`, `language_codes`, `ui_language_code`, `masterdata_languages`, and multilingual field keys in the response. Also gates which language codes are accepted in request body fields. Codes not valid in the active mode are silently dropped.\n"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserCreateBody"
              },
              "examples": {
                "minimal": {
                  "summary": "Minimal required fields",
                  "value": {
                    "user": {
                      "email": "jane.smith@example.com",
                      "country_id": "629d0dbc878f992c53183f65",
                      "office_id": "629d0dd0878f992c53183f66",
                      "role": "consultant"
                    }
                  }
                },
                "allFields": {
                  "summary": "All common fields (legacy mode, default)",
                  "value": {
                    "user": {
                      "email": "jane.smith@example.com",
                      "country_id": "629d0dbc878f992c53183f65",
                      "office_id": "629d0dd0878f992c53183f66",
                      "role": "consultant",
                      "name": "Jane Smith",
                      "upn": "jane.smith@example.com",
                      "external_unique_id": "EMP-456",
                      "telephone": "+47 123 45 678",
                      "landline": "+47 987 65 432",
                      "born_year": 1990,
                      "title": {
                        "no": "Konsulent",
                        "int": "Consultant"
                      },
                      "nationality": {
                        "no": "Norsk",
                        "int": "Norwegian"
                      },
                      "send_email": false
                    }
                  }
                },
                "allFieldsIso": {
                  "summary": "All common fields (ISO mode, ?use_legacy_codes=false)",
                  "value": {
                    "user": {
                      "email": "jane.smith@example.com",
                      "country_id": "629d0dbc878f992c53183f65",
                      "office_id": "629d0dd0878f992c53183f66",
                      "role": "consultant",
                      "name": "Jane Smith",
                      "title": {
                        "no": "Konsulent",
                        "en": "Consultant"
                      },
                      "nationality": {
                        "no": "Norsk",
                        "en": "Norwegian"
                      },
                      "override_language_code": "en",
                      "send_email": false
                    }
                  }
                },
                "departmentManager": {
                  "summary": "Create a department manager",
                  "value": {
                    "user": {
                      "email": "manager@example.com",
                      "country_id": "629d0dbc878f992c53183f65",
                      "office_id": "629d0dd0878f992c53183f66",
                      "role": "consultant",
                      "extra_roles": [
                        "departmentmanager"
                      ],
                      "role_allowed_office_ids": [
                        "629d0ddb878f992c53183fb6"
                      ],
                      "role_allowed_tag_ids": [
                        "6634a28d92588400488179c3"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "User created successfully. Returns the full user object. Note: returns 200 (not 201) on successful creation.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "400": {
            "description": "Bad request. Returned when the `user` wrapper key is missing from the request body.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestError"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication.",
            "headers": {
              "WWW-Authenticate": {
                "description": "Always returns `Custom`.",
                "schema": {
                  "type": "string",
                  "example": "Custom"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. The authenticated API key does not have permission to create users in the specified country, or the API key is disabled.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "The specified `country_id` or `office_id` does not exist in the current account.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "415": {
            "description": "The `Content-Type` header is not `application/json`. All POST requests must set `Content-Type: application/json`.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                },
                "example": {
                  "error": "Unsupported Content-Type. Content-Type header must be 'application/json' for API PUT and POST requests"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed. Triggers include a duplicate `email` or `external_unique_id` already in use, and an email or UPN whose domain is not in the account's `valid_email_domains` whitelist. Error message strings in `details` are locale-dependent.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnprocessableEntityError"
                },
                "examples": {
                  "duplicateEmail": {
                    "summary": "Duplicate email",
                    "value": {
                      "error": "Unprocessable Entity",
                      "details": [
                        "Email Det finnes allerede en bruker med den eposten",
                        "Roles is too short (minimum is 1 character)"
                      ]
                    }
                  },
                  "emailDomainNotWhitelisted": {
                    "summary": "Email domain not in account whitelist",
                    "value": {
                      "error": "Unprocessable Entity",
                      "details": [
                        "Email E-postdomenet er ikke hvitelistet"
                      ]
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/users/find": {
      "get": {
        "operationId": "findUser",
        "summary": "Find a user by email, external ID, or UPN",
        "description": "Looks up a single user by exact match on `email`, `external_unique_id`, or `upn`. At least one query parameter is required; empty-string values are treated as absent. Multiple parameters are combined with AND logic and the user must match all provided criteria.\n\nReturns `400 { \"error\": \"Bad Request\" }` if no valid query parameters are provided. Returns `404 { \"error\": \"Not Found\" }` if no matching user is found in the current account. The success response body is the same shape as retrieving a user by ID.\n",
        "tags": [
          "Users"
        ],
        "parameters": [
          {
            "name": "email",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "email"
            },
            "description": "Filter by exact email address match.",
            "example": "jane.smith@example.com"
          },
          {
            "name": "external_unique_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by exact external unique ID match.",
            "example": "93"
          },
          {
            "name": "upn",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by exact User Principal Name match.",
            "example": "do.not.delete@example.com"
          },
          {
            "name": "use_legacy_codes",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "true"
            },
            "description": "Controls language and country code format in the response. Default is `\"true\"`, returning legacy codes (e.g. `int`, `se`, `cn`). Set to `\"false\"` for ISO 639-1 codes (e.g. `en`, `sv`, `zh`). Affects `language_code`, `language_codes`, `ui_language_code`, `override_language_code`, `masterdata_languages`, and `title` keys.\n"
          }
        ],
        "responses": {
          "200": {
            "description": "User found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "400": {
            "description": "No valid query parameters provided.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestError"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication.\n",
            "headers": {
              "WWW-Authenticate": {
                "description": "Always returns `Custom`.",
                "schema": {
                  "type": "string",
                  "example": "Custom"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. The authenticated user does not have permission to read the requested user, or the API key is disabled.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "No user matching the query exists in the current account.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/users/{id}": {
      "get": {
        "operationId": "getUser",
        "summary": "Get a user by ID",
        "description": "Retrieves a single user by their internal Flowcase ID. Returns the full user object including role, office, company, image, and language configuration fields.\n\nThe user must belong to the same account as the authenticated API key. Requesting an ID that belongs to a different account returns 404, not 403, so the caller cannot distinguish \"wrong account\" from \"does not exist.\"\n\nBy default, the response uses legacy language codes (`int`, `se`, `cn`, `my`, `by`, etc.). Pass `?use_legacy_codes=false` to receive ISO 639-1 codes (`en`, `sv`, `zh`, `ms`, `be`, etc.) in `language_code`, `language_codes`, `ui_language_code`, `masterdata_languages`, `override_language_code`, and multilingual field keys (`title`).\n",
        "tags": [
          "Users"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The internal Flowcase user ID.",
            "example": "629d0ddd878f992c53183fc3"
          },
          {
            "name": "use_legacy_codes",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "true"
            },
            "description": "Controls language and country code format in the response. Default is `\"true\"`, returning legacy codes (e.g. `int`, `se`, `cn`). Set to `\"false\"` for ISO 639-1 codes (e.g. `en`, `sv`, `zh`). Affects `language_code`, `language_codes`, `ui_language_code`, `override_language_code`, `masterdata_languages`, and `title` keys.\n"
          }
        ],
        "responses": {
          "200": {
            "description": "User found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication.",
            "headers": {
              "WWW-Authenticate": {
                "description": "Always returns `Custom`.",
                "schema": {
                  "type": "string",
                  "example": "Custom"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. The API key is invalid or disabled, or the authenticated user does not have read permission on the target user.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "No user with the given ID exists in the current account, or the ID format is invalid.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "put": {
        "operationId": "updateUser",
        "summary": "Update a user",
        "description": "Updates a user's profile fields. Only include the fields that should be changed. Omitted fields retain their current values.\n\nAlso used to deactivate a user (`\"deactivated\": true`) or reactivate a previously deactivated user (`\"deactivated\": false`). When reactivating, set `send_email` to `true` to send a welcome email.\n\nWhen changing the `office_id` (department), you must also provide the `country_id` for the country that the new office belongs to. Changing country or office requires elevated permissions (`internationalmanager` for country changes, `internationalmanager` or `countrymanager` for office changes within the same country).\n\nExtra access roles (`countrymanager`, `departmentmanager`, `referencemanager`, `bidmanager`) are always layered on top of the `consultant` base role and must be passed via `extra_roles`. When assigning `departmentmanager`, also include `role_allowed_office_ids` (country-specific offices) and/or `role_allowed_tag_ids` (cross-country department modelling).\n\nBy default, the response uses legacy language codes (`int`, `se`, `cn`, `my`, `by`, etc.). Pass `?use_legacy_codes=false` to receive ISO 639-1 codes (`en`, `sv`, `zh`, `ms`, `be`, etc.) in `language_code`, `language_codes`, `ui_language_code`, `masterdata_languages`, and multilingual field keys (`title`, `nationality`). Language codes provided in the request body (such as `title` keys and `override_language_code`) must match the active mode; codes that are invalid in the active mode are silently dropped rather than returning an error.\n",
        "tags": [
          "Users"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The internal Flowcase user ID.",
            "example": "629d0ddd878f992c53183fc3"
          },
          {
            "name": "use_legacy_codes",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "false"
              ]
            },
            "description": "Pass `use_legacy_codes=false` to receive ISO 639-1 language codes instead of the default legacy codes. Affects `language_code`, `language_codes`, `ui_language_code`, `masterdata_languages`, and multilingual field keys in the response. Also gates which language codes are accepted in request body fields. Codes not valid in the active mode are silently dropped.\n"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserUpdateBody"
              },
              "examples": {
                "updateName": {
                  "summary": "Update a single field",
                  "value": {
                    "user": {
                      "name": "Jane Smith"
                    }
                  }
                },
                "deactivate": {
                  "summary": "Deactivate a user",
                  "value": {
                    "user": {
                      "deactivated": true
                    }
                  }
                },
                "reactivate": {
                  "summary": "Reactivate a user",
                  "value": {
                    "user": {
                      "deactivated": false,
                      "send_email": false
                    }
                  }
                },
                "assignDepartmentManager": {
                  "summary": "Assign department manager role",
                  "value": {
                    "user": {
                      "role": "consultant",
                      "extra_roles": [
                        "departmentmanager"
                      ],
                      "role_allowed_office_ids": [
                        "629d0ddb878f992c53183fb6"
                      ],
                      "role_allowed_tag_ids": [
                        "6634a28d92588400488179c3"
                      ]
                    }
                  }
                },
                "isoMode": {
                  "summary": "Set title and language override (ISO mode, ?use_legacy_codes=false)",
                  "value": {
                    "user": {
                      "title": {
                        "no": "Utvikler",
                        "en": "Developer"
                      },
                      "override_language_code": "en"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "User updated successfully. Returns the full updated user object.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "400": {
            "description": "Bad request. Returned when the `user` wrapper key is missing from the request body.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestError"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication.",
            "headers": {
              "WWW-Authenticate": {
                "description": "Always returns `Custom`.",
                "schema": {
                  "type": "string",
                  "example": "Custom"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. The authenticated user does not have write permission on the target user, or the API key is invalid or disabled.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "No user with the given ID exists in the current account.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "415": {
            "description": "The `Content-Type` header is not `application/json`. All PUT requests must set `Content-Type: application/json`.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                },
                "example": {
                  "error": "Unsupported Content-Type. Content-Type header must be 'application/json' for API PUT and POST requests"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed. Triggers include a blank `email`, a duplicate `email` already in use by another user, and an email or UPN whose domain is not in the account's `valid_email_domains` whitelist. Error message strings in `details` are locale-dependent.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnprocessableEntityError"
                },
                "examples": {
                  "duplicateEmail": {
                    "summary": "Duplicate email",
                    "value": {
                      "error": "Unprocessable Entity",
                      "details": [
                        "Email Det finnes allerede en bruker med den eposten"
                      ]
                    }
                  },
                  "blankEmail": {
                    "summary": "Blank email",
                    "value": {
                      "error": "Unprocessable Entity",
                      "details": [
                        "Email må ha en verdi"
                      ]
                    }
                  },
                  "emailDomainNotWhitelisted": {
                    "summary": "Email or UPN domain not in account whitelist",
                    "value": {
                      "error": "Unprocessable Entity",
                      "details": [
                        "Email E-postdomenet er ikke hvitelistet",
                        "Upn UPN-domenet er ikke hvitelistet"
                      ]
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v2/company/cv/customers": {
      "post": {
        "operationId": "createCustomer",
        "summary": "Create a new customer",
        "description": "Creates a new reference customer in the current account. The request body must be wrapped in a `company_customer` key containing at least a `customer_name` with one language code entry.\n\nRequires the `referencemanager` or `internationalmanager` role. API keys without either of these roles receive 403.\n\nMultilingual fields (`customer_name`, `customer_description`, `customer_description_to_cvs`) use legacy language codes by default (e.g. `int` for international/English, `no` for Norwegian). Pass `use_legacy_codes=false` to use ISO 639-1 codes instead (e.g. `en`, `no`, `sv`). This affects both request parsing and response serialization.\n\nThe `customer_name` field is auto-populated: any company language codes not provided are filled with the first non-empty value from the supplied entries.\n\nReturns 200 (not 201) on successful creation.\n",
        "tags": [
          "Customers"
        ],
        "parameters": [
          {
            "name": "use_legacy_codes",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "true"
            },
            "description": "Controls language code format for all multilingual fields in both the request body and response. Default is `\"true\"`, using legacy codes (e.g. `int`, `no`, `se`). Set to `\"false\"` for ISO 639-1 codes (e.g. `en`, `no`, `sv`). Only the exact string `\"false\"` activates ISO mode.\n"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CustomerCreateBody"
              },
              "examples": {
                "minimal": {
                  "summary": "Minimal, just a name",
                  "value": {
                    "company_customer": {
                      "customer_name": {
                        "int": "Test Customer"
                      }
                    }
                  }
                },
                "allFields": {
                  "summary": "All fields populated",
                  "value": {
                    "company_customer": {
                      "customer_name": {
                        "int": "Test Customer",
                        "no": "Testkunde"
                      },
                      "customer_description": {
                        "int": "Description",
                        "no": "Beskrivelse"
                      },
                      "customer_description_to_cvs": {
                        "int": "CV description",
                        "no": "CV-beskrivelse"
                      },
                      "customer_url": "https://example.com",
                      "external_unique_id": "EXT-123",
                      "industry_id": "63b563fa0ff7255c26324ac5",
                      "customer_sensitivity": "anonymized"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Customer created successfully. Returns the customer object without `project_count` or `industry` fields. Note: returns 200 (not 201) on successful creation.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerCreateResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request. Returned when the request body is empty, the `company_customer` wrapper key is missing, or the wrapper is present but empty.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestError"
                },
                "examples": {
                  "missingWrapper": {
                    "summary": "Missing company_customer wrapper",
                    "value": {
                      "error": "Bad Request"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication.",
            "headers": {
              "WWW-Authenticate": {
                "description": "Always returns `Custom`.",
                "schema": {
                  "type": "string",
                  "example": "Custom"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. Returns `{ \"error\": \"Forbidden\" }` for invalid or disabled API keys, or an empty body when the authenticated user does not have the `referencemanager` or `internationalmanager` role required to create customers.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed. Returned when a field value fails validation — for example, `customer_sensitivity` set to a value outside the allowed set (`\"anonymized\"` or `\"confidential\"`). Error message strings in `details` are locale-dependent.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnprocessableEntityError"
                },
                "examples": {
                  "invalidSensitivity": {
                    "summary": "Invalid customer_sensitivity value",
                    "value": {
                      "error": "Unprocessable Entity",
                      "details": [
                        "Customer sensitivity er ikke en tillatt verdi"
                      ]
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v2/company/cv/customers/find": {
      "get": {
        "operationId": "findCustomer",
        "summary": "Find a customer by external unique ID",
        "description": "Looks up a single customer by exact match on `external_unique_id`. Intended for integrations that track customers by their own identifier rather than the Flowcase-assigned ID.\n\nThe `external_unique_id` parameter is required. Returns 404 with an empty body if no customer in the account matches. Returns 400 if the parameter is omitted, or if multiple customers share the same `external_unique_id` (the response includes a `duplicate_customer_ids` array listing the conflicting records).\n\nMultilingual fields (e.g. `customer_name`, `customer_description`) use legacy language codes by default (e.g. `int` for international/English, `no` for Norwegian). Pass `use_legacy_codes=false` to receive ISO 639-1 codes instead (e.g. `en`, `no`, `sv`). This affects all multilingual fields and nested objects (`custom_tags[].values`, `industry.values`, `industry.help_text`).\n\nCustomer logo image URLs are temporary and expire after approximately 20 minutes. Cache the image if you need to display it, or re-fetch the customer to obtain a fresh URL.\n",
        "tags": [
          "Customers"
        ],
        "parameters": [
          {
            "name": "external_unique_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Exact match on the customer's external unique identifier.",
            "example": "three-m"
          },
          {
            "name": "use_legacy_codes",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "true"
            },
            "description": "Controls language code format for all multilingual fields. Default is `\"true\"`, returning legacy codes (e.g. `int`, `no`, `se`). Set to `\"false\"` for ISO 639-1 codes (e.g. `en`, `no`, `sv`). Only the exact string `\"false\"` activates ISO mode; any other value uses legacy codes.\n"
          }
        ],
        "responses": {
          "200": {
            "description": "Customer found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Customer"
                }
              }
            }
          },
          "400": {
            "description": "Either the `external_unique_id` parameter is missing, or multiple customers share the same `external_unique_id`. The response shape differs between these two conditions: a missing parameter returns `{ \"error\": \"...\" }` only; a duplicate match returns `{ \"error\": \"...\", \"duplicate_customer_ids\": [...] }`. The `error` string is locale-dependent when duplicates are found.\n",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/AuthenticationError"
                    },
                    {
                      "$ref": "#/components/schemas/CustomerDuplicateError"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication.\n",
            "headers": {
              "WWW-Authenticate": {
                "description": "Always returns `Custom`.",
                "schema": {
                  "type": "string",
                  "example": "Custom"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. The API key is disabled or the authenticated user does not have permission to read customers for this company.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "No customer matching the `external_unique_id` exists in the current account. Empty body.\n"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v2/company/cv/customers/{customer_id}/custom_tags": {
      "put": {
        "operationId": "setCustomerCustomTags",
        "summary": "Set a customer's custom tags by category",
        "description": "Sets the tags in several categories in one request. Each listed category ends up with exactly the tags it lists, and an empty list removes them all. Categories left out keep their tags, so an integration can manage some categories while people manage the rest.\n\nCategories and tags are given by `id` or `external_unique_id`. Each category needs `can_be_used_for_customers: true`. Everything is checked before anything changes: if any part of the request is wrong, nothing is changed and the `422` lists every problem. Repeating a request changes nothing.\n\nWith `create_missing_tags: true`, tags given by `external_unique_id` that do not exist yet are created from their `values`. Categories are never created, and existing tags are not renamed.\n\nReturns the updated customer, as `POST` does.\n\n**Authorization:** Requires write permission on the customer. Categories with `lock_for_integrations: true` need an API user or the `internationalmanager` role. `create_missing_tags` needs the `internationalmanager` role.\n",
        "tags": [
          "Custom Tags"
        ],
        "parameters": [
          {
            "name": "customer_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the customer.",
            "example": "646cd381a205f30f4a8dab05"
          },
          {
            "name": "use_legacy_codes",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "true"
            },
            "description": "Language code format for `values` in the request and the response. Default `\"true\"`, using legacy codes such as `int`. Set to `\"false\"` for ISO 639-1 codes such as `en`.\n"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SetCustomTagsBody"
              },
              "examples": {
                "byId": {
                  "summary": "Set one category and clear another",
                  "value": {
                    "categories": [
                      {
                        "id": "64ba9d878e11ef0f45cc0768",
                        "custom_tags": [
                          {
                            "id": "64ba9f0f8e11ef0f48cc076b"
                          }
                        ]
                      },
                      {
                        "id": "64ba9d878e11ef0f45cc0770",
                        "custom_tags": []
                      }
                    ]
                  }
                },
                "createMissing": {
                  "summary": "Use external IDs and create a missing tag",
                  "value": {
                    "create_missing_tags": true,
                    "categories": [
                      {
                        "external_unique_id": "HR.FIELD.EMP_TYPE",
                        "custom_tags": [
                          {
                            "external_unique_id": "HR.FIELD.EMP_TYPE.FULL"
                          },
                          {
                            "external_unique_id": "HR.FIELD.EMP_TYPE.CONTRACT",
                            "values": {
                              "int": "Contractor",
                              "no": "Innleid"
                            }
                          }
                        ]
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tags set. Returns the updated customer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Customer"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication.",
            "headers": {
              "WWW-Authenticate": {
                "description": "Always returns `Custom`.",
                "schema": {
                  "type": "string",
                  "example": "Custom"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. An invalid or disabled API key returns `{\"error\": \"Forbidden\"}`. These return an empty body: no write permission on the customer, a category locked for integrations, or `create_missing_tags` without the `internationalmanager` role.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "The customer does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "409": {
            "description": "A concurrent request created the same tag, or attached the same tag, first. Nothing was changed. The request is safe to retry.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConflictError"
                }
              }
            }
          },
          "422": {
            "description": "The request body is invalid. Nothing was changed. `details` lists every problem, each prefixed with its place in the body.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnprocessableEntityError"
                },
                "examples": {
                  "invalid": {
                    "summary": "Unknown category and missing tag",
                    "value": {
                      "error": "Unprocessable Entity",
                      "details": [
                        "categories[1]: no custom tag category with external_unique_id HR.FIELD.SEC_LEVEL",
                        "categories[0].custom_tags[1]: no custom tag with external_unique_id HR.FIELD.EMP_TYPE.CONTRACT in custom tag category 64ba9d878e11ef0f45cc0768. Set create_missing_tags to create it"
                      ]
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/masterdata/custom_tags/custom_tag": {
      "get": {
        "operationId": "listCustomTags",
        "summary": "List custom tags by category",
        "description": "Retrieves custom tags filtered by category, with offset/limit pagination. Use this endpoint to browse or search for tags within a specific category. The `query` parameter enables case-insensitive substring searching across tag values.\n\nReturns a bare JSON array (no pagination envelope, no total count). Detect end-of-results by receiving fewer items than `limit`. An empty array is returned when no results match, when the category does not exist, or when `category_ids` is omitted. The endpoint does not return 404 in any of these cases.\n\nTag values support multiple languages via the `values` field. The key format in `values` objects is controlled by the `use_legacy_codes` parameter.\n",
        "tags": [
          "Custom Tags"
        ],
        "parameters": [
          {
            "name": "category_ids",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ID of the custom tag category to list tags from. Required for non-empty results. Omitting this parameter or providing a nonexistent ID returns an empty array. Despite the plural name, only a single category ID is accepted.\n",
            "example": "629d0dd1878f992c53183f68"
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            },
            "description": "Pagination offset. Number of items to skip before returning results.\n",
            "example": 0
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 100,
              "minimum": 0,
              "maximum": 100
            },
            "description": "Maximum number of items to return. The hard cap is 100. Requests with `limit` greater than 100 receive a `400 Bad Request` response.\n",
            "example": 100
          },
          {
            "name": "query",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Case-insensitive substring search on tag values. When used without `language_code`, searches across all language variants. When used with `language_code`, searches only the specified language variant.\n",
            "example": "Finance"
          },
          {
            "name": "language_code",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Specifies which language variant to search against (when combined with `query`) and controls the sort order of results. Falls back to the authenticated user's language code if omitted. When `use_legacy_codes` is true (default), use legacy codes (e.g. `int`, `no`); when false, use ISO 639-1 codes (e.g. `en`, `nb`).\n",
            "example": "int"
          },
          {
            "name": "use_legacy_codes",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "true"
            },
            "description": "Controls language code format in `values` objects. Default is `\"true\"`, returning legacy codes (e.g. `int`, `se`, `cn`). Set to `\"false\"` for ISO 639-1 codes (e.g. `en`, `sv`, `zh`).\n"
          }
        ],
        "responses": {
          "200": {
            "description": "List of custom tags matching the query. Returns an empty array when no tags match, the category does not exist, or `category_ids` is omitted.\n",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/CustomTag"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request. The `limit` parameter exceeds the maximum of 100. Empty body.\n"
          },
          "401": {
            "description": "Missing or invalid authentication.\n",
            "headers": {
              "WWW-Authenticate": {
                "description": "Always returns `Custom`.",
                "schema": {
                  "type": "string",
                  "example": "Custom"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. The API key is invalid or the authenticated user does not have permission to read masterdata. Empty body.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "createCustomTag",
        "summary": "Create a custom tag",
        "description": "Adds a new tag to a specified category. The tag can include multilingual name translations and an optional external unique ID for integration with external systems.\n\nThe request body must be wrapped in a `masterdata` key containing `category_ids` (an array with the target category ID). The `values` and `external_unique_id` fields are optional.\n\nRequires the `internationalmanager` role or higher. API keys with lower roles (e.g. `external`, `consultant`) receive a 403.\n\n**Note:** Returns 200 (not 201) on successful creation. Sending a request without the `masterdata` wrapper key results in a 500 Internal Server Error rather than a 400.\n",
        "tags": [
          "Custom Tags"
        ],
        "parameters": [
          {
            "name": "use_legacy_codes",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "true"
            },
            "description": "Controls language code format in `values` objects in both the request body and the response. Default is `\"true\"`, using legacy codes (e.g. `int`, `se`). Set to `\"false\"` for ISO 639-1 codes (e.g. `en`, `sv`).\n"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CustomTagCreateBody"
              },
              "examples": {
                "minimal": {
                  "summary": "Minimal, tag with a single language value",
                  "value": {
                    "masterdata": {
                      "values": {
                        "int": "Full time employee"
                      },
                      "category_ids": [
                        "629d0dd1878f992c53183f68"
                      ]
                    }
                  }
                },
                "withExternalId": {
                  "summary": "Tag with external ID",
                  "value": {
                    "masterdata": {
                      "values": {
                        "int": "Full time employee",
                        "no": "Fast ansatt"
                      },
                      "external_unique_id": "HR.FIELD.EMP_TYPE.FULL",
                      "category_ids": [
                        "629d0dd1878f992c53183f68"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tag created successfully. Returns the new tag. Note: returns 200, not 201.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomTag"
                }
              }
            }
          },
          "400": {
            "description": "Bad request. Two distinct shapes are returned depending on the cause.\n\n**Empty body:** Missing `category_ids`, empty `category_ids` array, or a nonexistent category ID.\n\n**`{error}` shape:** Invalid content type (e.g. form-encoded instead of JSON) returns `{\"error\": \"Bad Request\"}`.\n"
          },
          "401": {
            "description": "Missing or invalid authentication.",
            "headers": {
              "WWW-Authenticate": {
                "description": "Always returns `Custom`.",
                "schema": {
                  "type": "string",
                  "example": "Custom"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. The API key is invalid or the authenticated user does not have the `internationalmanager` role required for creating tags. Empty body.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed. Returned when a uniqueness or validation constraint is violated — for example, a duplicate `external_unique_id` already in use by another custom tag. Error message strings in `details` are locale-dependent.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnprocessableEntityError"
                },
                "examples": {
                  "duplicateExternalId": {
                    "summary": "Duplicate external_unique_id",
                    "value": {
                      "error": "Unprocessable Entity",
                      "details": [
                        "External unique må være unik"
                      ]
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Internal server error. Returned when the `masterdata` wrapper key is missing from the request body.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerError"
                },
                "examples": {
                  "missingMasterdata": {
                    "summary": "Missing masterdata wrapper key",
                    "value": {
                      "error": "Internal Server Error"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/masterdata/custom_tags/custom_tag/{id}": {
      "delete": {
        "operationId": "deleteCustomTag",
        "summary": "Delete a custom tag",
        "description": "Permanently removes a custom tag from the system. This also removes all associations between this tag and any entities (CVs, customers, projects). This operation cannot be undone.\n\nThe `category_ids` query parameter is required and must reference the category the tag belongs to. Despite the plural name, only a single category ID is accepted.\n\nRequires the `internationalmanager` role. API keys with lower roles (e.g. `external`, `consultant`) receive a 403.\n\nThe operation is **not idempotent**. Deleting an already-deleted tag returns `404`.\n",
        "tags": [
          "Custom Tags"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the custom tag to delete.",
            "example": "64188f6b226a6e239f8563dd"
          },
          {
            "name": "category_ids",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the category the tag belongs to. Despite the plural name, only a single category ID is accepted. Returns 400 if missing or if the category does not exist.\n",
            "example": "63b563c80ff7255c26324987"
          }
        ],
        "responses": {
          "204": {
            "description": "Tag deleted successfully. Empty body."
          },
          "400": {
            "description": "Bad request. The `category_ids` query parameter is missing or references a nonexistent category. Empty body.\n"
          },
          "401": {
            "description": "Missing or invalid authentication.\n",
            "headers": {
              "WWW-Authenticate": {
                "description": "Always returns `Custom`.",
                "schema": {
                  "type": "string",
                  "example": "Custom"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. Two causes:\n\n(1) Invalid or disabled API key — returns `{ \"error\": \"Forbidden\" }`.\n\n(2) The authenticated user does not have the `internationalmanager` role required for deleting tags — returns an empty body.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "Not found. The tag ID does not exist within the specified category. Also returned when the tag exists but belongs to a different category than the one specified in `category_ids`.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/masterdata/custom_tags/custom_tag_category": {
      "get": {
        "operationId": "listCustomTagCategories",
        "summary": "List all custom tag categories",
        "description": "Retrieves all available tag categories in your organization, with their associated tags nested inline. Use this endpoint to get an overview of how tags are organized and what restrictions apply to each category. Each category includes boolean flags (`can_be_used_for_cvs`, `can_be_used_for_references`, `can_be_used_for_customers`) that control which entity types the category's tags can be attached to, an `allow_filtering` flag that controls whether the category appears as a filter in the UI, and a `lock_for_integrations` flag that restricts tag management to API integrations only.\n\nReturns a bare JSON array (no pagination envelope). All categories for the authenticated account are returned in a single response. An empty array is returned when no categories exist. The endpoint does not return 404 in this case.\n\nBoth tags and categories support multiple language variants via the `values` field. The key format in `values` objects is controlled by the `use_legacy_codes` parameter.\n",
        "tags": [
          "Custom Tags"
        ],
        "parameters": [
          {
            "name": "language_code",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Controls the sort order of categories and tags. Results are ordered alphabetically by name in the specified language. Falls back to the authenticated user's language code if omitted. When `use_legacy_codes` is true (default), use legacy codes (e.g. `no`, `se`); when false, use ISO 639-1 codes (e.g. `nb`, `sv`).\n",
            "example": "no"
          },
          {
            "name": "use_legacy_codes",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "true"
            },
            "description": "Controls language code format in `values` objects across both categories and tags. Default is `\"true\"`, returning legacy codes (e.g. `int`, `se`, `cn`). Set to `\"false\"` for ISO 639-1 codes (e.g. `en`, `sv`, `zh`).\n"
          }
        ],
        "responses": {
          "200": {
            "description": "List of all custom tag categories with nested tags.\n",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/CustomTagCategory"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication.\n",
            "headers": {
              "WWW-Authenticate": {
                "description": "Always returns `Custom`.",
                "schema": {
                  "type": "string",
                  "example": "Custom"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. The API key is invalid or the authenticated user does not have permission to read masterdata.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "createCustomTagCategory",
        "summary": "Create a custom tag category",
        "description": "Creates a new category for organizing tags. You must specify which entity types (CVs, references, customers) can use tags from this category. The category can also have an external unique ID to link it with external systems.\n\nThe request body must be wrapped in a `masterdata` key. The `values` key is required (even if empty); all other fields are optional and default to sensible values.\n\nRequires the `internationalmanager` role or higher. API keys with lower roles (e.g. `external`, `consultant`) receive a 403.\n\n**Note:** Returns 200 (not 201) on successful creation. The response includes an empty `custom_tags` array since the category is new.\n",
        "tags": [
          "Custom Tags"
        ],
        "parameters": [
          {
            "name": "use_legacy_codes",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "true"
            },
            "description": "Controls language code format in `values` objects in both the request body and the response. Default is `\"true\"`, using legacy codes (e.g. `int`, `se`). Set to `\"false\"` for ISO 639-1 codes (e.g. `en`, `sv`).\n"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CustomTagCategoryCreateBody"
              },
              "examples": {
                "minimal": {
                  "summary": "Minimal, just a name",
                  "value": {
                    "masterdata": {
                      "values": {
                        "int": "Employment Type"
                      }
                    }
                  }
                },
                "allFields": {
                  "summary": "All fields specified",
                  "value": {
                    "masterdata": {
                      "values": {
                        "int": "Security Clearance",
                        "no": "Sikkerhetsklarering"
                      },
                      "external_unique_id": "HR.FIELD.SEC_LEVEL",
                      "can_be_used_for_cvs": true,
                      "can_be_used_for_references": false,
                      "can_be_used_for_customers": false,
                      "allow_filtering": true,
                      "lock_for_integrations": false
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Category created successfully. Returns the new category with an empty `custom_tags` array. Note: returns 200, not 201.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomTagCategory"
                }
              }
            }
          },
          "400": {
            "description": "Bad request. Returned for missing or malformed `masterdata` wrapper key.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestError"
                },
                "examples": {
                  "missingMasterdata": {
                    "summary": "Missing masterdata wrapper key",
                    "value": {
                      "error": "Bad Request"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication.",
            "headers": {
              "WWW-Authenticate": {
                "description": "Always returns `Custom`.",
                "schema": {
                  "type": "string",
                  "example": "Custom"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. The API key is invalid or the authenticated user does not have the `internationalmanager` role required for creating categories.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed. Returned when a uniqueness or validation constraint is violated — for example, a duplicate `external_unique_id` already in use by another category. Error message strings in `details` are locale-dependent.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnprocessableEntityError"
                },
                "examples": {
                  "duplicateExternalId": {
                    "summary": "Duplicate external_unique_id",
                    "value": {
                      "error": "Unprocessable Entity",
                      "details": [
                        "External unique må være unik"
                      ]
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/masterdata/custom_tags/custom_tag_category/{id}": {
      "delete": {
        "operationId": "deleteCustomTagCategory",
        "summary": "Delete a custom tag category",
        "description": "Permanently removes a tag category. **Warning:** This also deletes all tags in the category and removes all associations between those tags and any entities (CVs, customers, reference projects). This operation cannot be undone.\n\nRequires the `internationalmanager` role. API keys with lower roles (e.g. `external`, `consultant`) receive a 403.\n\nIf the category ID does not exist, has already been deleted, or is malformed, the endpoint returns a 500 error.\n",
        "tags": [
          "Custom Tags"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the custom tag category to delete.",
            "example": "63b563c80ff7255c26324987"
          }
        ],
        "responses": {
          "204": {
            "description": "Category deleted successfully. Empty body."
          },
          "401": {
            "description": "Missing or invalid authentication.\n",
            "headers": {
              "WWW-Authenticate": {
                "description": "Always returns `Custom`.",
                "schema": {
                  "type": "string",
                  "example": "Custom"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. Two causes:\n\n(1) Invalid or disabled API key — returns `{ \"error\": \"Forbidden\" }`.\n\n(2) The authenticated user does not have the `internationalmanager` role required for deleting categories — returns an empty body.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Internal server error. Returned when the category ID is not found.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v3/cvs/{user_id}/{cv_id}/custom_tags": {
      "post": {
        "operationId": "addTagToCv",
        "summary": "Add a custom tag to a CV",
        "description": "Attaches an existing custom tag to a specific CV (résumé). The tag's category should have `can_be_used_for_cvs: true` for the tag to appear in the response's `custom_tags` array, although the API does not enforce this on the write path.\n\nA CV can have multiple tags from the same category. The operation is idempotent. Adding a tag that is already attached returns the same response with no error or duplicate.\n\nFor master CVs, the tag is associated with the user (not the CV directly). For proposal CVs, the tag is associated with the proposal CV.\n\nReturns the full updated CV object including all sections, custom tags, and user metadata.\n\n**Authorization:** Requires write permission on the CV. If the tag's category has `lock_for_integrations: true`, only API users or users with the `internationalmanager` role can add tags from that category.\n",
        "tags": [
          "Custom Tags"
        ],
        "parameters": [
          {
            "name": "user_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the user who owns the CV.",
            "example": "69eb60e04e90c9ebbdc6edbb"
          },
          {
            "name": "cv_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the CV (master CV or proposal CV) to add the tag to.\n",
            "example": "69eb60e04e90c9ebbdc6edbc"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddTagToCvBody"
              },
              "examples": {
                "standard": {
                  "summary": "Add a tag to a CV",
                  "value": {
                    "custom_tag_category_id": "629d0dd1878f992c53183f68",
                    "custom_tag_id": "629d0dd1878f992c53183f69"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tag added successfully (or already present; idempotent). Returns the full updated CV object.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CvResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication.\n",
            "headers": {
              "WWW-Authenticate": {
                "description": "Always returns `Custom`.",
                "schema": {
                  "type": "string",
                  "example": "Custom"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. Two causes:\n\n(1) Invalid or disabled API key — returns `{ \"error\": \"Forbidden\" }`.\n\n(2) The authenticated user does not have write permission on the CV, or the tag's category has `lock_for_integrations: true` and the user is not an API user or `internationalmanager` — returns an empty body.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "Not found. Two distinct response shapes exist:\n**JSON body** `{\"error\": \"Not Found\"}`: The CV ID, category ID, or tag ID does not exist. Also returned when required body parameters are missing.\n**Empty body**: The `user_id` path parameter does not match the CV's owner.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "put": {
        "operationId": "setCvCustomTags",
        "summary": "Set a CV's custom tags by category",
        "description": "Sets the tags in several categories in one request. Each listed category ends up with exactly the tags it lists, and an empty list removes them all. Categories left out keep their tags, so an integration can manage some categories while people manage the rest.\n\nCategories and tags are given by `id` or `external_unique_id`. Each category needs `can_be_used_for_cvs: true`. Everything is checked before anything changes: if any part of the request is wrong, nothing is changed and the `422` lists every problem. Repeating a request changes nothing.\n\nWith `create_missing_tags: true`, tags given by `external_unique_id` that do not exist yet are created from their `values`. Categories are never created, and existing tags are not renamed.\n\nReturns the updated CV, as `POST` does. For a master CV the tags are held against the user, as with `POST`.\n\n**Authorization:** Requires write permission on the CV. Categories with `lock_for_integrations: true` need an API user or the `internationalmanager` role. `create_missing_tags` needs the `internationalmanager` role.\n",
        "tags": [
          "Custom Tags"
        ],
        "parameters": [
          {
            "name": "user_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the user who owns the CV.",
            "example": "69eb60e04e90c9ebbdc6edbb"
          },
          {
            "name": "cv_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the CV (master CV or proposal CV).",
            "example": "69eb60e04e90c9ebbdc6edbc"
          },
          {
            "name": "use_legacy_codes",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "true"
            },
            "description": "Language code format for `values` in the request and the response. Default `\"true\"`, using legacy codes such as `int`. Set to `\"false\"` for ISO 639-1 codes such as `en`.\n"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SetCustomTagsBody"
              },
              "examples": {
                "byId": {
                  "summary": "Set one category and clear another",
                  "value": {
                    "categories": [
                      {
                        "id": "64ba9d878e11ef0f45cc0768",
                        "custom_tags": [
                          {
                            "id": "64ba9f0f8e11ef0f48cc076b"
                          }
                        ]
                      },
                      {
                        "id": "64ba9d878e11ef0f45cc0770",
                        "custom_tags": []
                      }
                    ]
                  }
                },
                "createMissing": {
                  "summary": "Use external IDs and create a missing tag",
                  "value": {
                    "create_missing_tags": true,
                    "categories": [
                      {
                        "external_unique_id": "HR.FIELD.EMP_TYPE",
                        "custom_tags": [
                          {
                            "external_unique_id": "HR.FIELD.EMP_TYPE.FULL"
                          },
                          {
                            "external_unique_id": "HR.FIELD.EMP_TYPE.CONTRACT",
                            "values": {
                              "int": "Contractor",
                              "no": "Innleid"
                            }
                          }
                        ]
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tags set. Returns the updated CV.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CvResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication.",
            "headers": {
              "WWW-Authenticate": {
                "description": "Always returns `Custom`.",
                "schema": {
                  "type": "string",
                  "example": "Custom"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. An invalid or disabled API key returns `{\"error\": \"Forbidden\"}`. These return an empty body: no write permission on the CV, a category locked for integrations, or `create_missing_tags` without the `internationalmanager` role.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "Not found. Two distinct response shapes exist:\n**JSON body** `{\"error\": \"Not Found\"}`: The CV ID does not exist.\n**Empty body**: The `user_id` path parameter does not match the CV's owner.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "409": {
            "description": "A concurrent request created the same tag, or attached the same tag, first. Nothing was changed. The request is safe to retry.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConflictError"
                }
              }
            }
          },
          "422": {
            "description": "The request body is invalid. Nothing was changed. `details` lists every problem, each prefixed with its place in the body.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnprocessableEntityError"
                },
                "examples": {
                  "invalid": {
                    "summary": "Unknown category and missing tag",
                    "value": {
                      "error": "Unprocessable Entity",
                      "details": [
                        "categories[1]: no custom tag category with external_unique_id HR.FIELD.SEC_LEVEL",
                        "categories[0].custom_tags[1]: no custom tag with external_unique_id HR.FIELD.EMP_TYPE.CONTRACT in custom tag category 64ba9d878e11ef0f45cc0768. Set create_missing_tags to create it"
                      ]
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v3/cvs/{user_id}/{cv_id}/custom_tags/{custom_tag_id}": {
      "delete": {
        "operationId": "removeTagFromCv",
        "summary": "Remove a custom tag from a CV",
        "description": "Removes the association between a custom tag and a CV (résumé). This only removes the tag-CV relationship; the tag itself remains in the system and can be used with other entities.\n\nThe `custom_tag_id` can be found in the CV's `custom_tag_ids` array when reading the full CV, or as `id` in the CV's `custom_tags` array.\n\nFor master CVs, the tag is associated with the user (not the CV directly). For proposal CVs, the tag is associated with the proposal CV.\n\nReturns `204 No Content` with an empty body on success. The operation is **not idempotent**. Removing a tag that is not attached to the CV returns `404`.\n\n**Authorization:** Requires write permission on the CV. If the tag's category has `lock_for_integrations: true`, only API users or users with the `internationalmanager` role can remove tags from that category.\n",
        "tags": [
          "Custom Tags"
        ],
        "parameters": [
          {
            "name": "user_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the user who owns the CV.",
            "example": "69eb60e04e90c9ebbdc6edbb"
          },
          {
            "name": "cv_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the CV (master CV or proposal CV) to remove the tag from.\n",
            "example": "69eb60e04e90c9ebbdc6edbc"
          },
          {
            "name": "custom_tag_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the custom tag to remove. Can be found in the CV's `custom_tag_ids` array or as `id` in the `custom_tags` array.\n",
            "example": "629d0dd1878f992c53183f69"
          }
        ],
        "responses": {
          "204": {
            "description": "Tag removed successfully. Empty body."
          },
          "401": {
            "description": "Missing or invalid authentication.\n",
            "headers": {
              "WWW-Authenticate": {
                "description": "Always returns `Custom`.",
                "schema": {
                  "type": "string",
                  "example": "Custom"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. Three causes:\n\n(1) Invalid or disabled API key — returns `{ \"error\": \"Forbidden\" }`.\n\n(2) The authenticated user does not have write permission on the CV — returns an empty body.\n\n(3) The tag's category has `lock_for_integrations: true` and the user is not an API user or `internationalmanager` — returns an empty body.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "Not found. Two distinct response shapes exist:\n**JSON body** `{\"error\": \"Not Found\"}`: The CV ID or custom tag ID does not exist, or the tag is not currently attached to this CV.\n**Empty body**: The `user_id` path parameter does not match the CV's owner.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v2/company/cv/projects/find": {
      "get": {
        "operationId": "findProject",
        "summary": "Find a reference project by external unique ID",
        "description": "Looks up a single reference project by exact match on `external_unique_id`. Intended for integrations that track projects by their own identifier rather than the Flowcase-assigned ID.\n\nThe search is scoped to all reference projects across all customers in the authenticated account, so you do not need to know the parent customer ID.\n\nThe `external_unique_id` parameter is required. Returns `404 { \"error\": \"Not found\" }` (note lowercase \"found\") if no project matches. Returns `409 Conflict` if multiple projects share the same `external_unique_id` (the response includes a `duplicate_project_ids` array listing the conflicting records).\n\nThe response includes all project sections (challenges, solutions, value propositions, contacts, owners, links, skills, offices, attachments, images, and tags) by default.\n\nMultilingual fields (e.g. `project_name`, `project_description`) use legacy language codes by default (e.g. `int` for international/English, `no` for Norwegian). Pass `use_legacy_codes=false` to receive ISO 639-1 codes instead (e.g. `en`, `nb`, `sv`). This affects all multilingual fields and nested objects.\n\nImage and attachment URLs are temporary links that expire approximately 10 minutes after the response is generated. Re-fetch the resource if a fresh URL is needed.\n",
        "tags": [
          "Reference Projects"
        ],
        "parameters": [
          {
            "name": "external_unique_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Exact match on the project's external unique identifier.",
            "example": "SAP-1234"
          },
          {
            "name": "use_legacy_codes",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "true"
            },
            "description": "Controls language code format for all multilingual fields. Default is `\"true\"`, returning legacy codes (e.g. `int`, `no`, `se`). Set to `\"false\"` for ISO 639-1 codes (e.g. `en`, `nb`, `sv`). Only the exact string `\"false\"` activates ISO mode; any other value uses legacy codes.\n"
          },
          {
            "name": "include_custom_fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "false"
            },
            "description": "When set to `\"true\"`, includes the `custom_fields` array in the response. Only the exact string `\"true\"` activates this; any other value omits custom fields.\n"
          }
        ],
        "responses": {
          "200": {
            "description": "Project found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferenceProject"
                }
              }
            }
          },
          "400": {
            "description": "The required `external_unique_id` query parameter is missing or empty. The response includes the validation message in the `error` field.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestError"
                },
                "example": {
                  "error": "param is missing or the value is empty or invalid: external_unique_id"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication.\n",
            "headers": {
              "WWW-Authenticate": {
                "description": "Always returns `Custom`.",
                "schema": {
                  "type": "string",
                  "example": "Custom"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. The API key is disabled or the authenticated user does not have permission to read reference projects for this company.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "No project matching the `external_unique_id` exists in the current account. The `error` value is lowercase `\"Not found\"`, unlike most other 404 responses.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                },
                "example": {
                  "error": "Not found"
                }
              }
            }
          },
          "409": {
            "description": "Multiple projects share the same `external_unique_id` within the account. The response includes a `duplicate_project_ids` array listing the conflicting project IDs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectDuplicateError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v2/company/cv/customers/{customer_id}/projects": {
      "post": {
        "operationId": "createReferenceProject",
        "summary": "Create a reference project",
        "description": "Creates a new reference project under an existing customer. The request body must be wrapped in a `company_project` key with at least one field. Submitting an empty wrapper (`\"company_project\": {}`) returns 400. All fields are optional; omitting `project_name` creates a project with `project_name: {}`.\n\nRequires the `referencemanager` or `internationalmanager` role. API keys without one of these roles receive 403.\n\nSet top-level fields in the initial request. Additional details such as project challenges, solutions, customer contacts, owners, tags, and more can be added in subsequent requests after creating the initial project.\n\nMultilingual fields (`project_name`, `project_description`, etc.) use legacy language codes by default (e.g. `int` for English, `no` for Norwegian). Pass `use_legacy_codes=false` to use ISO 639-1 codes instead. This affects both request parsing and response serialization.\n\nThe `project_name` field is auto-populated: any company language codes not provided are filled with the first non-empty value from the supplied entries.\n\n**Custom fields** are an optional feature that must be enabled by your account representative or Flowcase support. Once enabled, values can be included in the `custom_fields` array to set custom field values on the project at creation time. Each entry references a custom field definition by `name`. See the `CustomFieldInput` schema for permitted parameters per field type and important notes on single select fields.\n\nOn creation, the system automatically creates one default empty entry in each of `customer_value_propositions`, `project_challenges`, `project_solutions`, and `customer_contacts`. The authenticated user's default office is also automatically assigned.\n\nReturns 200 (not 201) on successful creation.\n",
        "tags": [
          "Reference Projects"
        ],
        "parameters": [
          {
            "name": "customer_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the parent customer.",
            "example": "646cd381a205f30f4a8dab05"
          },
          {
            "name": "use_legacy_codes",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "true"
            },
            "description": "Controls language code format for all multilingual fields in both the request body and response. Default is `\"true\"`, using legacy codes (e.g. `int`, `no`, `se`). Set to `\"false\"` for ISO 639-1 codes (e.g. `en`, `no`, `sv`). Only the exact string `\"false\"` activates ISO mode.\n"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReferenceProjectCreateBody"
              },
              "examples": {
                "minimal": {
                  "summary": "Minimal (name only)",
                  "value": {
                    "company_project": {
                      "project_name": {
                        "int": "New Project"
                      }
                    }
                  }
                },
                "allFields": {
                  "summary": "All top-level fields populated",
                  "value": {
                    "company_project": {
                      "project_name": {
                        "int": "Full Project"
                      },
                      "project_description": {
                        "int": "Full description",
                        "no": "Full beskrivelse"
                      },
                      "project_introduction": {
                        "int": "Introduction text"
                      },
                      "project_notes": {
                        "int": "Some notes"
                      },
                      "project_skills_description": {
                        "int": "Skills description"
                      },
                      "type": {
                        "int": "Consulting"
                      },
                      "contract_type": {
                        "int": "Fixed Price"
                      },
                      "architect": "John Smith",
                      "area_amt": "500",
                      "building_owner": "ACME Corp",
                      "collaborating_partners": "Partner A, Partner B",
                      "extent": "Large",
                      "extent_amt": "1000000",
                      "extent_currency": "eur",
                      "extent_hours_new": "5000.5",
                      "total_extent_amt": "2000000",
                      "total_extent_currency": "nok",
                      "total_extent_hours": "10000.25",
                      "location_country_code": "no",
                      "month_from": "1",
                      "year_from": "2024",
                      "month_to": "12",
                      "year_to": "2025",
                      "project_address": "Oslo, Norway",
                      "workflow_stage": "draft",
                      "external_unique_id": "API-TEST-FULL-001",
                      "office_ids": [
                        "629d0dd0878f992c53183f66"
                      ]
                    }
                  }
                },
                "withCustomFields": {
                  "summary": "With custom fields (all types)",
                  "value": {
                    "company_project": {
                      "project_name": {
                        "int": "Custom Fields Project"
                      },
                      "custom_fields": [
                        {
                          "name": "phase_one_cost",
                          "amount": 2500000,
                          "currency": "nok"
                        },
                        {
                          "name": "workshare_hours",
                          "value": "1200"
                        },
                        {
                          "name": "test_quant",
                          "amount": "350",
                          "unit": "m^2"
                        },
                        {
                          "name": "us_state",
                          "value": "US-UT"
                        },
                        {
                          "name": "engineering_duration",
                          "from": "2024-01",
                          "to": "2025-06"
                        }
                      ]
                    }
                  }
                },
                "withCustomFieldSensitivity": {
                  "summary": "Custom field with sensitivity and anonymized value",
                  "value": {
                    "company_project": {
                      "project_name": {
                        "int": "Sensitive CF Project"
                      },
                      "custom_fields": [
                        {
                          "name": "workshare_hours",
                          "value": "500",
                          "sensitivity": "anonymized",
                          "anonymized": {
                            "int": "~500 hours"
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Project created successfully. Returns the full project object including auto-created default entries in `customer_value_propositions`, `project_challenges`, `project_solutions`, and `customer_contacts`. Note: returns 200 (not 201) on successful creation.\n\nWhen `custom_fields` are included in the request, the response includes a `custom_fields` array containing ALL custom field definitions for the company. The successfully saved values for the fields provided in the request are reflected in the response. Fields not provided in the request appear with `null` values.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferenceProject"
                }
              }
            }
          },
          "400": {
            "description": "Bad request. Two distinct response shapes are possible: (1) a generic error returned when the request body is empty or the `company_project` wrapper is missing/empty; (2) a validation message for invalid `office_ids`.\n",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/BadRequestError"
                    },
                    {
                      "$ref": "#/components/schemas/ValidationMessageError"
                    }
                  ]
                },
                "examples": {
                  "missingWrapper": {
                    "summary": "Missing or empty company_project wrapper",
                    "value": {
                      "error": "Bad Request"
                    }
                  },
                  "invalidOfficeIds": {
                    "summary": "Invalid office_ids",
                    "value": {
                      "valid": false,
                      "message": "One or more invalid office_ids used"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication.",
            "headers": {
              "WWW-Authenticate": {
                "description": "Always returns `Custom`.",
                "schema": {
                  "type": "string",
                  "example": "Custom"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. The API key is disabled, invalid, or the authenticated user does not have the `referencemanager` or `internationalmanager` role required to create projects.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "Not found. Returned when the customer specified by `customer_id` does not exist in the authenticated user's company, or when `custom_fields` references a nonexistent custom field name.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable entity. Returned for field-level validation failures — for example, invalid `workflow_stage`, `month_from` out of range, unrecognised `area_unit`, uppercase currency codes in `currency_amount` fields (must be lowercase, e.g. `\"nok\"` not `\"NOK\"`), invalid `external_unique_id` values for `single_select` custom fields, and unrecognised `unit` values for `quantity` custom fields. Error message strings in `details` are locale-dependent.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnprocessableEntityError"
                },
                "examples": {
                  "invalidWorkflowStage": {
                    "summary": "Invalid workflow_stage value",
                    "value": {
                      "error": "Unprocessable Entity",
                      "details": [
                        "Workflow stage er ikke en tillatt verdi"
                      ]
                    }
                  },
                  "invalidAreaUnit": {
                    "summary": "Unrecognised area_unit value",
                    "value": {
                      "error": "Unprocessable Entity",
                      "details": [
                        "Area unit er ikke en tillatt verdi"
                      ]
                    }
                  },
                  "invalidMonth": {
                    "summary": "month_from / month_to out of range",
                    "value": {
                      "error": "Unprocessable Entity",
                      "details": [
                        "Month from må være mindre enn eller lik 12"
                      ]
                    }
                  },
                  "invalidCurrencyCode": {
                    "summary": "Uppercase currency code",
                    "value": {
                      "error": "Unprocessable Entity",
                      "details": [
                        "Extent currency er ikke en tillatt verdi"
                      ]
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v2/company/cv/customers/{customer_id}/projects/{project_id}": {
      "get": {
        "operationId": "getReferenceProject",
        "summary": "Get a reference project by ID",
        "description": "Retrieves a single reference project by its ID, scoped under a customer. Returns the full project object including all nested sections: challenges, solutions, value propositions, customer contacts, project owners, skills, links, images, attachments, offices, and custom tags.\n\nThe response is large, and a fully populated project can exceed 20 KB. Nested section arrays (challenges, solutions, etc.) are included by default. New projects created via the API include one default empty entry in `customer_value_propositions`, `project_challenges`, `project_solutions`, and `customer_contacts`.\n\nImage URLs in the response are temporary links that expire after approximately 10 minutes.\n\nAuthorization depends on the project's `workflow_stage`:\n- `live` and `archived` projects are readable by most roles\n  (consultant, limited_access, proposal, referencemanager, etc.)\n\n- `draft` and `ready_for_review` projects are only readable by\n  project owners, admin roles (referencemanager,\n  internationalmanager, countrymanager), or department managers\n  for the project's assigned department\n",
        "tags": [
          "Reference Projects"
        ],
        "parameters": [
          {
            "name": "customer_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the parent customer.",
            "example": "6943cf1a81e6048fcaa3b17c"
          },
          {
            "name": "project_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the reference project.",
            "example": "6943cf1e81e6048fcaa3b19d"
          },
          {
            "name": "include_custom_fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "false"
            },
            "description": "When `\"true\"`, includes a `custom_fields` array in the response with all custom field values defined for the company. Custom fields are polymorphic, so different field types (`currency_amount`, `numeric`, `quantity`, `single_select`, `year_month_range`) include different value properties.\n"
          },
          {
            "name": "include_full_options",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "false"
            },
            "description": "When `\"true\"`, nested objects include full data instead of referencing by unique ID.\n"
          },
          {
            "name": "include_project_sections",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "true"
            },
            "description": "When `\"false\"`, omits nested section arrays (challenges, solutions, value propositions, contacts, etc.) from the response. Useful for lightweight lookups.\n"
          }
        ],
        "responses": {
          "200": {
            "description": "Reference project found. Returns the full project object with all nested sections.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferenceProject"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication.",
            "headers": {
              "WWW-Authenticate": {
                "description": "Always returns `Custom`.",
                "schema": {
                  "type": "string",
                  "example": "Custom"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. The API key is disabled, invalid, or the authenticated user lacks permission to read this project (e.g. draft project and user is not an owner or admin). Empty body.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "Not found. The customer or project does not exist, or the project belongs to a different customer.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "put": {
        "operationId": "updateReferenceProject",
        "summary": "Update a reference project",
        "description": "Updates an existing reference project. Only the fields included in the request body are changed; omitted fields retain their current values. The request body must be wrapped in a `company_project` key and must contain at least one field. An empty wrapper returns 400.\n\nMultilingual fields (objects keyed by language code) are fully replaced, not merged. For example, updating `project_name` with `{\"int\": \"New\"}` removes any existing `no` key.\n\n**Custom fields** are an optional feature that must be enabled by your account representative or Flowcase support. Once enabled, values can be included in the `custom_fields` array to create or update custom field values on the project. Include only the fields you want to change. Omitted custom fields retain their values. Each entry references a custom field definition by `name`. See the `CustomFieldInput` schema for permitted parameters per field type.\n\nSetting `workflow_stage` to `live` or `archived` requires the `publish` permission. Project owners with only the `consultant` or `limited_access` role can update other fields but cannot publish or archive.\n\nThe `version` field in the response auto-increments on each successful update.\n\nUnlike the create endpoint, `office_ids` is not accepted on update. Use the dedicated office add/remove endpoints to manage project offices.\n",
        "tags": [
          "Reference Projects"
        ],
        "parameters": [
          {
            "name": "customer_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the parent customer.",
            "example": "6943cf1a81e6048fcaa3b17c"
          },
          {
            "name": "project_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the reference project to update.",
            "example": "6943cf1e81e6048fcaa3b19d"
          },
          {
            "name": "use_legacy_codes",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "true"
            },
            "description": "Controls language code format. By default uses legacy codes (e.g. `int`, `no`, `se`). Set to `\"false\"` for ISO 639-1 codes.\n"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReferenceProjectUpdateBody"
              },
              "examples": {
                "updateCustomFields": {
                  "summary": "Update custom field values",
                  "value": {
                    "company_project": {
                      "custom_fields": [
                        {
                          "name": "workshare_hours",
                          "value": "1500"
                        },
                        {
                          "name": "total_cost",
                          "amount": 9000000,
                          "currency": "eur"
                        },
                        {
                          "name": "test_quant",
                          "amount": "420",
                          "unit": "kWh"
                        }
                      ]
                    }
                  }
                },
                "updateWithSensitivity": {
                  "summary": "Set custom field with sensitivity",
                  "value": {
                    "company_project": {
                      "custom_fields": [
                        {
                          "name": "workshare_hours",
                          "value": "500",
                          "sensitivity": "anonymized",
                          "anonymized": {
                            "int": "~500 hours"
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Project updated successfully. Returns the full project object including all nested sections.\n\nWhen `custom_fields` are included in the request, the response includes a `custom_fields` array with all custom field definitions for the company, populated with their current values (including the just-updated ones).\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferenceProject"
                }
              }
            }
          },
          "400": {
            "description": "Bad request. The `company_project` wrapper is missing or the body is malformed.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestError"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication.",
            "headers": {
              "WWW-Authenticate": {
                "description": "Always returns `Custom`.",
                "schema": {
                  "type": "string",
                  "example": "Custom"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. The API key is disabled, invalid, or the authenticated user lacks write permission on this project. Also returned when a user without the `publish` permission attempts to set `workflow_stage` to `live` or `archived`. Empty body.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "Not found. The customer or project does not exist within the authenticated user's company, or `custom_fields` references a nonexistent custom field name.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable entity. Returned for field-level validation failures — for example, invalid `workflow_stage`, `month_from` outside 1–12, unrecognised `area_unit`, uppercase currency codes in `currency_amount` fields, invalid `external_unique_id` for `single_select` custom fields, or an unrecognised `unit` value for `quantity` custom fields. Error message strings in `details` are locale-dependent.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnprocessableEntityError"
                },
                "examples": {
                  "invalidWorkflowStage": {
                    "summary": "Invalid workflow_stage value",
                    "value": {
                      "error": "Unprocessable Entity",
                      "details": [
                        "Workflow stage er ikke en tillatt verdi"
                      ]
                    }
                  },
                  "invalidAreaUnit": {
                    "summary": "Unrecognised area_unit value",
                    "value": {
                      "error": "Unprocessable Entity",
                      "details": [
                        "Area unit er ikke en tillatt verdi"
                      ]
                    }
                  },
                  "invalidCountryCode": {
                    "summary": "Invalid location_country_code",
                    "value": {
                      "error": "Unprocessable Entity",
                      "details": [
                        "Location country code er ikke en tillatt verdi"
                      ]
                    }
                  },
                  "invalidCurrencyCode": {
                    "summary": "Uppercase currency code",
                    "value": {
                      "error": "Unprocessable Entity",
                      "details": [
                        "Extent currency er ikke en tillatt verdi"
                      ]
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v2/company/cv/customers/{customer_id}/projects/{project_id}/custom_tags": {
      "post": {
        "operationId": "addTagToReferenceProject",
        "summary": "Add a custom tag to a reference project",
        "description": "Attaches an existing custom tag to a reference project. The request body includes `custom_tag_category_id` and `custom_tag_id`.\n\nThe tag's category should have `can_be_used_for_references: true` for the tag to appear in the response's `custom_tags` array, although the API does not enforce this on the write path. A tag from any category can be added, but only qualifying tags appear in the response.\n\nUnlike the equivalent CV endpoint, this operation is **not idempotent**. Adding a tag that is already attached returns `422 Unprocessable Entity` with `details: [\"Custom tag må være unik\"]`.\n\nReturns the full updated reference project object including all sections.\n\n**Authorization:** Requires write permission on the reference project. If the tag's category has `lock_for_integrations: true`, only API users or users with the `internationalmanager` role can add tags from that category.\n",
        "tags": [
          "Custom Tags"
        ],
        "parameters": [
          {
            "name": "customer_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the parent customer that owns the project.",
            "example": "646cd381a205f30f4a8dab05"
          },
          {
            "name": "project_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the reference project.",
            "example": "6878e97ca0ab68003d274eae"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddTagToCvBody"
              },
              "examples": {
                "standard": {
                  "summary": "Add a tag to a reference project",
                  "value": {
                    "custom_tag_category_id": "64ba9d878e11ef0f45cc0768",
                    "custom_tag_id": "64ba9f0f8e11ef0f48cc076b"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tag added successfully. Returns the full updated reference project object.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferenceProject"
                }
              }
            }
          },
          "400": {
            "description": "Bad request. Returned for malformed bodies that fail parsing before reaching field-level validation.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestError"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication.\n",
            "headers": {
              "WWW-Authenticate": {
                "description": "Always returns `Custom`.",
                "schema": {
                  "type": "string",
                  "example": "Custom"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. Three causes:\n\n(1) Invalid or disabled API key — returns `{ \"error\": \"Forbidden\" }`.\n\n(2) The authenticated user does not have write permission on the reference project — returns an empty body.\n\n(3) The tag's category has `lock_for_integrations: true` and the user is not an API user or `internationalmanager` — returns an empty body.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "Not found. The customer ID, project ID, category ID, or tag ID does not exist. Also returned when required body parameters are missing.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed. Returned when a uniqueness constraint is violated — for example, the same tag is already attached to the reference project. Error message strings in `details` are locale-dependent.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnprocessableEntityError"
                },
                "examples": {
                  "duplicateTag": {
                    "summary": "Tag is already on this project",
                    "value": {
                      "error": "Unprocessable Entity",
                      "details": [
                        "Custom tag må være unik"
                      ]
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "put": {
        "operationId": "setReferenceProjectCustomTags",
        "summary": "Set a reference project's custom tags by category",
        "description": "Sets the tags in several categories in one request. Each listed category ends up with exactly the tags it lists, and an empty list removes them all. Categories left out keep their tags, so an integration can manage some categories while people manage the rest.\n\nCategories and tags are given by `id` or `external_unique_id`. Each category needs `can_be_used_for_references: true`. Everything is checked before anything changes: if any part of the request is wrong, nothing is changed and the `422` lists every problem. Repeating a request changes nothing.\n\nWith `create_missing_tags: true`, tags given by `external_unique_id` that do not exist yet are created from their `values`. Categories are never created, and existing tags are not renamed.\n\nReturns the updated reference project, as `POST` does.\n\n**Authorization:** Requires write permission on the reference project. Categories with `lock_for_integrations: true` need an API user or the `internationalmanager` role. `create_missing_tags` needs the `internationalmanager` role.\n",
        "tags": [
          "Custom Tags"
        ],
        "parameters": [
          {
            "name": "customer_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the parent customer that owns the project.",
            "example": "646cd381a205f30f4a8dab05"
          },
          {
            "name": "project_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the reference project.",
            "example": "6878e97ca0ab68003d274eae"
          },
          {
            "name": "use_legacy_codes",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "true"
            },
            "description": "Language code format for `values` in the request and the response. Default `\"true\"`, using legacy codes such as `int`. Set to `\"false\"` for ISO 639-1 codes such as `en`.\n"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SetCustomTagsBody"
              },
              "examples": {
                "byId": {
                  "summary": "Set one category and clear another",
                  "value": {
                    "categories": [
                      {
                        "id": "64ba9d878e11ef0f45cc0768",
                        "custom_tags": [
                          {
                            "id": "64ba9f0f8e11ef0f48cc076b"
                          }
                        ]
                      },
                      {
                        "id": "64ba9d878e11ef0f45cc0770",
                        "custom_tags": []
                      }
                    ]
                  }
                },
                "createMissing": {
                  "summary": "Use external IDs and create a missing tag",
                  "value": {
                    "create_missing_tags": true,
                    "categories": [
                      {
                        "external_unique_id": "HR.FIELD.EMP_TYPE",
                        "custom_tags": [
                          {
                            "external_unique_id": "HR.FIELD.EMP_TYPE.FULL"
                          },
                          {
                            "external_unique_id": "HR.FIELD.EMP_TYPE.CONTRACT",
                            "values": {
                              "int": "Contractor",
                              "no": "Innleid"
                            }
                          }
                        ]
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tags set. Returns the updated reference project.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferenceProject"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication.",
            "headers": {
              "WWW-Authenticate": {
                "description": "Always returns `Custom`.",
                "schema": {
                  "type": "string",
                  "example": "Custom"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. An invalid or disabled API key returns `{\"error\": \"Forbidden\"}`. These return an empty body: no write permission on the reference project, a category locked for integrations, or `create_missing_tags` without the `internationalmanager` role.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "The customer or project does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "409": {
            "description": "A concurrent request created the same tag, or attached the same tag, first. Nothing was changed. The request is safe to retry.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConflictError"
                }
              }
            }
          },
          "422": {
            "description": "The request body is invalid. Nothing was changed. `details` lists every problem, each prefixed with its place in the body.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnprocessableEntityError"
                },
                "examples": {
                  "invalid": {
                    "summary": "Unknown category and missing tag",
                    "value": {
                      "error": "Unprocessable Entity",
                      "details": [
                        "categories[1]: no custom tag category with external_unique_id HR.FIELD.SEC_LEVEL",
                        "categories[0].custom_tags[1]: no custom tag with external_unique_id HR.FIELD.EMP_TYPE.CONTRACT in custom tag category 64ba9d878e11ef0f45cc0768. Set create_missing_tags to create it"
                      ]
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v2/company/cv/customers/{customer_id}/projects/{project_id}/custom_tags/{custom_tag_id}": {
      "delete": {
        "operationId": "removeTagFromReferenceProject",
        "summary": "Remove a custom tag from a reference project",
        "description": "Removes the association between a custom tag and a reference project. This only affects the specific project-tag relationship; the tag remains available for use with other projects.\n\nThe `custom_tag_id` can be found as `id` in the project's `custom_tags` array when reading the full reference project.\n\nReturns `204 No Content` with an empty body on success. The operation is **not idempotent**. Removing a tag that is not attached to the project returns `404`.\n\n**Authorization:** Requires write permission on the reference project. If the tag's category has `lock_for_integrations: true`, only API users or users with the `internationalmanager` role can remove tags from that category.\n",
        "tags": [
          "Custom Tags"
        ],
        "parameters": [
          {
            "name": "customer_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the parent customer that owns the project.",
            "example": "646cd381a205f30f4a8dab05"
          },
          {
            "name": "project_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the reference project.",
            "example": "6878e97ca0ab68003d274eae"
          },
          {
            "name": "custom_tag_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the custom tag to remove. Can be found as `id` in the project's `custom_tags` array.\n",
            "example": "64ba9f0f8e11ef0f48cc076b"
          }
        ],
        "responses": {
          "204": {
            "description": "Tag removed successfully. Empty body."
          },
          "401": {
            "description": "Missing or invalid authentication.\n",
            "headers": {
              "WWW-Authenticate": {
                "description": "Always returns `Custom`.",
                "schema": {
                  "type": "string",
                  "example": "Custom"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. Three causes:\n\n(1) Invalid or disabled API key — returns `{ \"error\": \"Forbidden\" }`.\n\n(2) The authenticated user does not have write permission on the reference project — returns an empty body.\n\n(3) The tag's category has `lock_for_integrations: true` and the user is not an API user or `internationalmanager` — returns an empty body.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "Not found. The customer ID, project ID, or custom tag ID does not exist, or the tag is not currently attached to this project.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v2/company/cv/customers/{customer_id}/projects/{project_id}/company_project_skills": {
      "post": {
        "operationId": "addSkillToReferenceProject",
        "summary": "Add a skill to a reference project",
        "description": "Adds a skill entry to an existing reference project. Skills represent competencies used or acquired during the project and support multiple entries per project.\n\nThe request body must be wrapped in a `company_project_skill` key. The `tags` field is a multilingual object mapping language codes to the skill name. Both `tags` and `order` are optional. Omitting `tags` creates a skill with an empty name.\n\nMultilingual fields use legacy language codes by default (e.g. `int` for English, `no` for Norwegian). Pass `use_legacy_codes=false` to use ISO 639-1 codes instead. Language codes not enabled for the company are silently dropped from `tags`.\n\nRequires write access to the reference project. Users with the `referencemanager` or `internationalmanager` role can write to any project in their company. Project owners and users with matching office/department roles may also have write access. Read-only API keys receive 403.\n\nReturns 200 (not 201) on successful creation.\n",
        "tags": [
          "Reference Projects"
        ],
        "parameters": [
          {
            "name": "customer_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the parent customer.",
            "example": "646cd381a205f30f4a8dab05"
          },
          {
            "name": "project_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the reference project to add the skill to.",
            "example": "69f07366b16e4e65aa5ef4b3"
          },
          {
            "name": "use_legacy_codes",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "true"
            },
            "description": "Controls language code format for multilingual fields in both the request body and response. Default is `\"true\"`, using legacy codes (e.g. `int`, `no`, `se`). Set to `\"false\"` for ISO 639-1 codes (e.g. `en`, `nb`, `sv`). Only the exact string `\"false\"` activates ISO mode.\n"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReferenceProjectSkillCreateBody"
              },
              "examples": {
                "minimal": {
                  "summary": "Single language tag",
                  "value": {
                    "company_project_skill": {
                      "tags": {
                        "int": "Project management"
                      }
                    }
                  }
                },
                "multilingual": {
                  "summary": "Multiple language tags",
                  "value": {
                    "company_project_skill": {
                      "tags": {
                        "int": "Project management",
                        "no": "Prosjektledelse"
                      }
                    }
                  }
                },
                "withOrder": {
                  "summary": "With explicit ordering",
                  "value": {
                    "company_project_skill": {
                      "tags": {
                        "int": "Ordered skill"
                      },
                      "order": 5
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Skill created successfully. Returns the skill object with a server-assigned `id`. Note: returns 200 (not 201) on successful creation.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferenceProjectSkill"
                }
              }
            }
          },
          "400": {
            "description": "Bad request. Returned when the request body is missing or does not contain the required `company_project_skill` wrapper key.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestError"
                },
                "example": {
                  "error": "Bad Request"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication.",
            "headers": {
              "WWW-Authenticate": {
                "description": "Always returns `Custom`.",
                "schema": {
                  "type": "string",
                  "example": "Custom"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. The authenticated user does not have write access to this reference project. Read-only API keys and users without the appropriate role receive this response. Empty body.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "Not found. Returned when `customer_id` does not exist in the authenticated user's company or `project_id` does not exist under that customer.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v2/company/cv/customers/{customer_id}/projects/{project_id}/company_project_skills/{project_skill_id}": {
      "put": {
        "operationId": "updateSkillOnReferenceProject",
        "summary": "Update a skill on a reference project",
        "description": "Updates an existing skill entry on a reference project. Skills represent competencies used or acquired during the project.\n\nThe `project_skill_id` can be found as `id` when creating the skill or when reading the full reference project.\n\nSupports partial updates: only the fields provided in the request body are changed. Omitting `tags` preserves the current skill name; omitting `order` preserves the current sort position. However, the `tags` field itself is replaced entirely, so individual language keys within `tags` cannot be patched independently. Sending `{\"tags\": {}}` clears all language entries.\n\nThe request body must be wrapped in a `company_project_skill` key.\n\nMultilingual fields use legacy language codes by default (e.g. `int` for English, `no` for Norwegian). Pass `use_legacy_codes=false` to use ISO 639-1 codes instead.\n\nRequires write access to the reference project. Users with the `referencemanager` or `internationalmanager` role can write to any project in their company. Project owners and users with matching office/department roles may also have write access. Read-only API keys receive 403.\n",
        "tags": [
          "Reference Projects"
        ],
        "parameters": [
          {
            "name": "customer_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the parent customer.",
            "example": "646cd381a205f30f4a8dab05"
          },
          {
            "name": "project_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the reference project containing the skill.",
            "example": "69f07366b16e4e65aa5ef4b3"
          },
          {
            "name": "project_skill_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the skill to update. Can be found as `id` when creating the skill or in the project's `company_project_skills` array.\n",
            "example": "69f358e35d5c0ddd44ec8b4b"
          },
          {
            "name": "use_legacy_codes",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "true"
            },
            "description": "Controls language code format for multilingual fields in both the request body and response. Default is `\"true\"`, using legacy codes (e.g. `int`, `no`, `se`). Set to `\"false\"` for ISO 639-1 codes (e.g. `en`, `nb`, `sv`). Only the exact string `\"false\"` activates ISO mode.\n"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReferenceProjectSkillUpdateBody"
              },
              "examples": {
                "updateTags": {
                  "summary": "Update skill name only",
                  "value": {
                    "company_project_skill": {
                      "tags": {
                        "int": "Updated skill name"
                      }
                    }
                  }
                },
                "updateOrder": {
                  "summary": "Update display order only",
                  "value": {
                    "company_project_skill": {
                      "order": 3
                    }
                  }
                },
                "updateBoth": {
                  "summary": "Update both tags and order",
                  "value": {
                    "company_project_skill": {
                      "tags": {
                        "int": "Project management",
                        "no": "Prosjektledelse"
                      },
                      "order": 5
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Skill updated successfully. Returns the full skill object with the updated fields and an incremented `version`.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferenceProjectSkill"
                }
              }
            }
          },
          "400": {
            "description": "Bad request. Returned when the request body is missing or does not contain the required `company_project_skill` wrapper key.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestError"
                },
                "example": {
                  "error": "Bad Request"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication.",
            "headers": {
              "WWW-Authenticate": {
                "description": "Always returns `Custom`.",
                "schema": {
                  "type": "string",
                  "example": "Custom"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. The authenticated user does not have write access to this reference project. Read-only API keys and users without the appropriate role receive this response. Empty body.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "Not found. Returned when `customer_id` does not exist in the authenticated user's company, `project_id` does not exist under that customer, or `project_skill_id` does not exist on the project.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v2/company/cv/customers/{customer_id}/projects/{project_id}/customer_contacts": {
      "post": {
        "operationId": "addCustomerContactToReferenceProject",
        "summary": "Add a customer contact to a reference project",
        "description": "Adds a customer contact entry to an existing reference project. Customer contacts store contact information, customer quotes, and notes for reference project testimonials. Each project supports multiple contact entries.\n\nContact, quote, and use in reference need to be approved by setting `disabled`, `hide_contact_details`, and `hide_quote` to `false`. All three default to `true` (not approved). Note that setting these to `false` on creation does **not** populate the approver tracking fields (`name_approver_*`, `contact_details_approver_*`, `quote_approver_*`). Those fields are only set when toggling from `true` to `false` via the update endpoint.\n\nThe request body must be wrapped in a `customer_contact` key. At least one field must be provided in the wrapper — an empty object returns 400.\n\nMultilingual fields (`label`, `quote`, `notes`) use legacy language codes by default (e.g. `int` for English, `no` for Norwegian). Pass `use_legacy_codes=false` to use ISO 639-1 codes instead.\n\nRequires write access to the reference project. Users with the `referencemanager` or `internationalmanager` role can write to any project in their company. Project owners and users with matching office/department roles may also have write access. Read-only API keys receive 403.\n\nReturns 200 (not 201) on successful creation.\n",
        "tags": [
          "Reference Projects"
        ],
        "parameters": [
          {
            "name": "customer_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the parent customer.",
            "example": "646cd381a205f30f4a8dab05"
          },
          {
            "name": "project_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the reference project to add the contact to.",
            "example": "69f07366b16e4e65aa5ef4b3"
          },
          {
            "name": "use_legacy_codes",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "true"
            },
            "description": "Controls language code format for multilingual fields in both the request body and response. Default is `\"true\"`, using legacy codes (e.g. `int`, `no`, `se`). Set to `\"false\"` for ISO 639-1 codes (e.g. `en`, `nb`, `sv`). Only the exact string `\"false\"` activates ISO mode.\n"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReferenceProjectContactCreateBody"
              },
              "examples": {
                "full": {
                  "summary": "Full contact with all fields",
                  "value": {
                    "customer_contact": {
                      "name": "John Doe",
                      "label": {
                        "int": "Project Manager",
                        "no": "Prosjektleder"
                      },
                      "email": "john.doe@example.com",
                      "phone": "+1234567890",
                      "disabled": true,
                      "hide_contact_details": true,
                      "hide_quote": true,
                      "quote": {
                        "int": "Great working with this team.",
                        "no": "Flott å jobbe med dette teamet."
                      },
                      "notes": {
                        "int": "10 years experience in project management.",
                        "no": "10 års erfaring innen prosjektledelse."
                      }
                    }
                  }
                },
                "minimal": {
                  "summary": "Name only",
                  "value": {
                    "customer_contact": {
                      "name": "Test Contact"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Contact created successfully. Returns the contact object with a server-assigned `id`. Note: returns 200 (not 201) on successful creation. Approval tracking fields (`*_approved_at`, `*_approver_id`, `*_approver_name`) are always `null` on creation.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferenceProjectContact"
                }
              }
            }
          },
          "400": {
            "description": "Bad request. Returned when the request body is missing, does not contain the required `customer_contact` wrapper key, or the wrapper object is empty.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestError"
                },
                "example": {
                  "error": "Bad Request"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication.",
            "headers": {
              "WWW-Authenticate": {
                "description": "Always returns `Custom`.",
                "schema": {
                  "type": "string",
                  "example": "Custom"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. The authenticated user does not have write access to this reference project. Read-only API keys and users without the appropriate role receive this response. Empty body.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "Not found. Returned when `customer_id` does not exist in the authenticated user's company or `project_id` does not exist under that customer.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v2/company/cv/customers/{customer_id}/projects/{project_id}/customer_contacts/{customer_contact_id}": {
      "put": {
        "operationId": "updateCustomerContactOnReferenceProject",
        "summary": "Update a customer contact on a reference project",
        "description": "Updates an existing customer contact entry on a reference project. Customer contacts store contact information, customer quotes, and notes for reference project testimonials.\n\nThe `customer_contact_id` can be found as `id` when creating the contact or when reading the full reference project.\n\nSupports partial updates: only the fields provided in the request body are changed. Omitted fields retain their current value. However, multilingual fields (`label`, `quote`, `notes`) overwrite the entire language object, so individual language keys cannot be patched independently. For example, updating `{\"label\": {\"int\": \"New\"}}` replaces the entire label, removing any other language entries that were previously set.\n\nThe request body must be wrapped in a `customer_contact` key. At least one field must be provided in the wrapper — an empty object returns 400.\n\nWhen an approval toggle (`disabled`, `hide_contact_details`, `hide_quote`) is changed from `true` to `false`, the API records who approved and when on the corresponding `*_approver_id`, `*_approver_name`, and `*_approved_at` fields. Revoking approval (setting back to `true`) does **not** clear these fields, and the last approver's information is retained.\n\nMultilingual fields use legacy language codes by default (e.g. `int` for English, `no` for Norwegian). Pass `use_legacy_codes=false` to use ISO 639-1 codes instead.\n\nRequires write access to the reference project. Users with the `referencemanager` or `internationalmanager` role can write to any project in their company. Project owners and users with matching office/department roles may also have write access. Read-only API keys receive 403.\n",
        "tags": [
          "Reference Projects"
        ],
        "parameters": [
          {
            "name": "customer_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the parent customer.",
            "example": "646cd381a205f30f4a8dab05"
          },
          {
            "name": "project_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the reference project containing the contact.",
            "example": "69f07366b16e4e65aa5ef4b3"
          },
          {
            "name": "customer_contact_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the customer contact to update. Can be found as `id` when creating the contact or in the project's `customer_contacts` array.\n",
            "example": "69f0bebeca51b16f82469cb6"
          },
          {
            "name": "use_legacy_codes",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "true"
            },
            "description": "Controls language code format for multilingual fields in both the request body and response. Default is `\"true\"`, using legacy codes (e.g. `int`, `no`, `se`). Set to `\"false\"` for ISO 639-1 codes (e.g. `en`, `nb`, `sv`). Only the exact string `\"false\"` activates ISO mode.\n"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReferenceProjectContactUpdateBody"
              },
              "examples": {
                "partialName": {
                  "summary": "Update name only",
                  "value": {
                    "customer_contact": {
                      "name": "Updated Name"
                    }
                  }
                },
                "approveAll": {
                  "summary": "Approve contact for use in references",
                  "value": {
                    "customer_contact": {
                      "disabled": false,
                      "hide_contact_details": false,
                      "hide_quote": false
                    }
                  }
                },
                "updateMultilingual": {
                  "summary": "Update multilingual label",
                  "value": {
                    "customer_contact": {
                      "label": {
                        "int": "Senior Project Manager",
                        "no": "Senior Prosjektleder"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Contact updated successfully. Returns the full contact object with the updated fields and an incremented `version`. When approval toggles change from `true` to `false`, the corresponding approver fields are populated in the response.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferenceProjectContact"
                }
              }
            }
          },
          "400": {
            "description": "Bad request. Returned when the request body is missing, does not contain the required `customer_contact` wrapper key, or the wrapper object is empty.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestError"
                },
                "example": {
                  "error": "Bad Request"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. The authenticated user does not have write access to this reference project. Read-only API keys and users without the appropriate role receive this response. Empty body.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "Not found. Returned when `customer_id` does not exist in the authenticated user's company, `project_id` does not exist under that customer, or `customer_contact_id` does not exist on the project.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v2/company/cv/customers/{customer_id}/projects/{project_id}/project_owners": {
      "post": {
        "operationId": "addProjectOwners",
        "summary": "Add project owners to a reference project",
        "description": "Adds one or more project owners to an existing reference project. Project owners have additional access rights, enabling them to edit the project without needing admin or reference manager roles. This allows regular or limited users to collaborate effectively without requiring full administrative access.\n\nThe request body accepts a `user_ids` array of Flowcase user IDs. You can add multiple users in a single request. Each user must exist in the same company as the project. To find user IDs, use the Find Users endpoint.\n\nUnlike other reference project sub-resource endpoints, this endpoint does **not** use a wrapper key. Instead, `user_ids` is at the top level of the request body. It also returns the **full reference project** (with all sections) rather than just the created sub-resource.\n\nSending an empty `user_ids` array succeeds with no changes, returning the project unchanged. Adding a user who is already an owner returns `422 Unprocessable Entity` with `details: [\"User må være unik\"]`.\n\n**Deactivated users may be added as owners.** User lookup matches by ID regardless of the user's `deactivated` flag. The deactivated owner appears in the response's `project_owners` array with `deactivated: true` and `deactivated_at` populated. If the integration should not assign deactivated users, filter them out client-side before calling this endpoint.\n\nRequires write access to the reference project and read access to each user being added. Users with the `referencemanager` or `internationalmanager` role can write to any project in their company. Project owners and users with matching office/department roles may also have write access. Read-only API keys receive 403.\n\nReturns 200 (not 201) on success.\n",
        "tags": [
          "Reference Projects"
        ],
        "parameters": [
          {
            "name": "customer_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the parent customer.",
            "example": "646cd381a205f30f4a8dab05"
          },
          {
            "name": "project_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the reference project to add owners to.",
            "example": "69f0c273ca51b16f82469cb9"
          },
          {
            "name": "use_legacy_codes",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "true"
            },
            "description": "Controls language code format for multilingual fields in the response. Default is `\"true\"`, using legacy codes (e.g. `int`, `no`, `se`). Set to `\"false\"` for ISO 639-1 codes (e.g. `en`, `nb`, `sv`). Only the exact string `\"false\"` activates ISO mode.\n"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddProjectOwnersBody"
              },
              "examples": {
                "single": {
                  "summary": "Add a single owner",
                  "value": {
                    "user_ids": [
                      "69eb60e04e90c9ebbdc6edbb"
                    ]
                  }
                },
                "multiple": {
                  "summary": "Add multiple owners at once",
                  "value": {
                    "user_ids": [
                      "63b6c4bcb6973e0f7ae9b092",
                      "629d0dd4878f992c53183f80"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Owners added successfully. Returns the full reference project with all sections, including the updated `project_owners` array. Note: returns 200 (not 201) on success.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferenceProject"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication.",
            "headers": {
              "WWW-Authenticate": {
                "description": "Always returns `Custom`.",
                "schema": {
                  "type": "string",
                  "example": "Custom"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. The authenticated user does not have write access to this reference project, or does not have read access to one of the users being added. Read-only API keys and users without the appropriate role receive this response. Empty body.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "Not found. Returned when `customer_id` does not exist in the authenticated user's company, `project_id` does not exist under that customer, any user ID in `user_ids` does not exist, or `user_ids` is missing from the request body.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed. Returned when a uniqueness constraint is violated — for example, a user already listed as a project owner is added again. Error message strings in `details` are locale-dependent.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnprocessableEntityError"
                },
                "examples": {
                  "duplicateOwner": {
                    "summary": "User is already a project owner",
                    "value": {
                      "error": "Unprocessable Entity",
                      "details": [
                        "User må være unik"
                      ]
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v2/company/cv/customers/{customer_id}/projects/{project_id}/project_owners/sync_by_email": {
      "put": {
        "operationId": "syncProjectOwnersByEmail",
        "summary": "Sync project owners by email",
        "description": "Syncs the project owners on a reference project against a list of email addresses. Use this when integrating with an external identity source where the canonical reference is an email rather than a Flowcase user ID.\n\nThe `replace` flag controls the sync mode:\n- `replace: false` (default) — **merge**: the provided emails are\n  added to the existing owners (set union). No existing owners are\n  removed. Idempotent on already-present owners.\n\n- `replace: true` — **replace**: the resulting owners list is\n  exactly the users resolved from `emails`. Current owners not\n  present in the new list are removed.\n\n\nEmails are normalised before lookup: lowercased, whitespace-trimmed, blank entries dropped, and duplicates removed. Email lookup is scoped to the authenticated user's company.\n\nThe operation is **all-or-nothing**: if any email in the request does not match a user in the company, the entire request fails with `422 Unprocessable Entity` and no owners are modified. The final owners list must contain at least one user — sending `replace: true` with an empty (or all-blank) `emails` array returns `422 Unprocessable Entity`.\n\n**Deactivated users may be synced as owners.** Email lookup matches by email regardless of the user's `deactivated` flag. The deactivated owner appears in the response's `project_owners` array with `deactivated: true` and `deactivated_at` populated.\n\n**The project's `updated_at` and `version` do NOT change when only owners are synced.** Owners live in a join table; the project record itself is not modified. To detect whether the owner list changed, compare the `project_owners` array before and after.\n\nReturns the full reference project with all sections, reflecting the updated `project_owners` array. Returns `200` (not `201`) on success.\n\n**Authorization:** Requires write access to the reference project, read access to every user being added (newly resolved from `emails`), and read access to every user being removed (existing owner not present in the new list when `replace: true`). Users with the `referencemanager` or `internationalmanager` role can write to any project in their company. Read-only API keys receive `403`.\n",
        "tags": [
          "Reference Projects"
        ],
        "parameters": [
          {
            "name": "customer_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the parent customer.",
            "example": "646cd381a205f30f4a8dab05"
          },
          {
            "name": "project_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the reference project to sync owners on.",
            "example": "69f0c273ca51b16f82469cb9"
          },
          {
            "name": "use_legacy_codes",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "true"
            },
            "description": "Controls language code format for multilingual fields in the response. Default is `\"true\"`, using legacy codes (e.g. `int`, `no`, `se`). Set to `\"false\"` for ISO 639-1 codes (e.g. `en`, `nb`, `sv`). Only the exact string `\"false\"` activates ISO mode.\n"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SyncProjectOwnersByEmailBody"
              },
              "examples": {
                "mergeSingle": {
                  "summary": "Merge a single new owner (default)",
                  "value": {
                    "emails": [
                      "alice@example.com"
                    ]
                  }
                },
                "mergeMultiple": {
                  "summary": "Merge multiple new owners",
                  "value": {
                    "emails": [
                      "alice@example.com",
                      "bob@example.com"
                    ]
                  }
                },
                "replaceWholesale": {
                  "summary": "Replace the owners list wholesale",
                  "value": {
                    "emails": [
                      "alice@example.com"
                    ],
                    "replace": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Owners synced successfully. Returns the full reference project with all sections, including the updated `project_owners` array. Returns `200` (not `201`) on success. Note that the project's own `updated_at` and `version` are NOT bumped by owner sync — owners live in a join table.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferenceProject"
                }
              }
            }
          },
          "400": {
            "description": "Bad request. Two distinct shapes are possible:\n- `{\"error\":\"emails must be an array\"}` when `emails` is missing,\n  `null`, or not a JSON array.\n\n- `{\"error\":\"Bad Request\"}` when `replace` is present but not a\n  valid boolean.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestError"
                },
                "examples": {
                  "emailsNotArray": {
                    "summary": "emails is not an array (missing, null, or string)",
                    "value": {
                      "error": "emails must be an array"
                    }
                  },
                  "invalidReplace": {
                    "summary": "replace is not a valid boolean",
                    "value": {
                      "error": "Bad Request"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication.",
            "headers": {
              "WWW-Authenticate": {
                "description": "Always returns `Custom`.",
                "schema": {
                  "type": "string",
                  "example": "Custom"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. Two causes: (1) the authenticated user does not have write permission on the reference project; (2) the authenticated user does not have read permission on a user being added or removed. Read-only API keys receive this response. Note: some 403 responses (CanCanCan `head 403`) have an empty body rather than the JSON shape documented here.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "Not found. The `customer_id` does not exist in the authenticated user's company, or the `project_id` does not exist under that customer.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed. Two cases:\n- One or more emails could not be resolved to users in the\n  company. The `details` array contains a single string listing\n  all unresolved emails in square brackets. The sync is\n  all-or-nothing; no owners are modified.\n\n- The resulting owners list would be empty (sending\n  `replace: true` with an empty or all-blank `emails` array). A\n  project must always have at least one owner.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnprocessableEntityError"
                },
                "examples": {
                  "emailNotFound": {
                    "summary": "One or more emails are not in the company",
                    "value": {
                      "error": "Unprocessable Entity",
                      "details": [
                        "Could not find Users by emails: [ghost@example.com]"
                      ]
                    }
                  },
                  "replaceWithEmpty": {
                    "summary": "replace=true with no resolvable emails",
                    "value": {
                      "error": "Unprocessable Entity",
                      "details": [
                        "A project must have at least one owner"
                      ]
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v2/company/cv/customers/{customer_id}/projects/{project_id}/project_owners/{user_id}": {
      "delete": {
        "operationId": "removeProjectOwner",
        "summary": "Remove a project owner from a reference project",
        "description": "Removes a single project owner from an existing reference project. Project owners have additional access rights, enabling them to edit the project without needing admin or reference manager roles. Removing a user as a project owner revokes these additional editing permissions, though they may retain access through other roles.\n\nThe `user_id` path parameter identifies the user to remove, and can be found in the `project_owners` array when reading the full reference project.\n\nReturns `204 No Content` with an empty body on success.\n\n**Warning:** The endpoint is **not idempotent**. Attempting to remove a user who is not currently an owner of the project (including repeating a successful removal) returns `500 Internal Server Error` rather than `404` or `204`.\n\n**Authorization:** Requires write access to the reference project and read access to the user being removed. Users with the `referencemanager` or `internationalmanager` role can write to any project in their company. Project owners and users with matching office/department roles may also have write access. Read-only API keys receive `403`.\n",
        "tags": [
          "Reference Projects"
        ],
        "parameters": [
          {
            "name": "customer_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the parent customer.",
            "example": "646cd381a205f30f4a8dab05"
          },
          {
            "name": "project_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the reference project.",
            "example": "69f0c273ca51b16f82469cb9"
          },
          {
            "name": "user_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the user to remove as project owner. Can be found as `id` in the project's `project_owners` array when reading the full reference project.\n",
            "example": "629d0dd4878f992c53183f80"
          }
        ],
        "responses": {
          "204": {
            "description": "Owner removed successfully. Empty body."
          },
          "401": {
            "description": "Missing or invalid authentication.",
            "headers": {
              "WWW-Authenticate": {
                "description": "Always returns `Custom`.",
                "schema": {
                  "type": "string",
                  "example": "Custom"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. Returns an empty body. Two causes: (1) the authenticated user does not have write permission on the reference project, or (2) the authenticated user does not have read permission on the user being removed. Read-only API keys receive this response.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "Not found. The customer ID does not exist in the authenticated user's company, the project ID does not exist under that customer, or the user ID does not exist in the company.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Internal server error. Returned when the specified user is not currently an owner of this project. This includes repeat calls after a successful removal.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/company/cv/customers/{customer_id}/projects/{project_id}/offices": {
      "post": {
        "operationId": "addOfficeToProject",
        "summary": "Add an office to a reference project",
        "description": "Associates an office (department) with an existing reference project. The office is identified by `office_id` together with the `country_id` of the country it belongs to; both are required and sent at the top level of the request body (there is no wrapper key).\n\nThe office must belong to the country identified by `country_id`. If the office does not exist, the country does not exist, or the office belongs to a different country, the request returns `404 Not Found` — there is no distinct validation error for a malformed `office_id`.\n\nAdding an office that is already associated with the project returns `422 Unprocessable Entity` with `details: [\"Office må være unik\"]`. Error message strings in `details` are locale-dependent.\n\nRequires write access to the reference project. Users with the `referencemanager` or `internationalmanager` role can write to any project in their company; project owners and users with matching office/department roles may also have write access. Read-only API keys receive 403.\n\nOn success, returns the **full reference project** (with all sections, including the updated `offices` array) rather than just the added office. Returns 200 (not 201).\n",
        "tags": [
          "Reference Projects"
        ],
        "parameters": [
          {
            "name": "customer_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the parent customer.",
            "example": "629d0e34878f992c531841bb"
          },
          {
            "name": "project_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the reference project to add the office to.",
            "example": "629d0e34878f992c531841c4"
          },
          {
            "name": "use_legacy_codes",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "true"
            },
            "description": "Controls language code format for multilingual fields in the response. Default is `\"true\"`, using legacy codes (e.g. `int`, `no`, `se`). Set to `\"false\"` for ISO 639-1 codes (e.g. `en`, `nb`, `sv`). Only the exact string `\"false\"` activates ISO mode.\n"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddOfficeBody"
              },
              "examples": {
                "addOffice": {
                  "summary": "Add an office to a project",
                  "value": {
                    "country_id": "64023c9f47db6bbadf29cde8",
                    "office_id": "64023d01441b770f46ad5daf"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Office added successfully. Returns the full reference project with all sections, including the updated `offices` array. Note: returns 200 (not 201) on success.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferenceProject"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication.",
            "headers": {
              "WWW-Authenticate": {
                "description": "Always returns `Custom`.",
                "schema": {
                  "type": "string",
                  "example": "Custom"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. The authenticated user does not have write access to this reference project. Read-only API keys and users without the appropriate role receive this response. An invalid or disabled API key returns `{\"error\": \"Forbidden\"}`; a valid key that simply lacks write access (e.g. a read-only role) returns an empty body.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "Not found. Returned when `customer_id` does not exist in the authenticated user's company, `project_id` does not exist under that customer, `country_id` does not exist, or `office_id` does not exist within that country. Also returned when `country_id` or `office_id` is missing from the request body.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed. Returned when a uniqueness constraint is violated — for example, an office already associated with the project is added again. Error message strings in `details` are locale-dependent.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnprocessableEntityError"
                },
                "examples": {
                  "duplicateOffice": {
                    "summary": "Office is already associated with the project",
                    "value": {
                      "error": "Unprocessable Entity",
                      "details": [
                        "Office må være unik"
                      ]
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "required": [
          "user_id",
          "id",
          "company_id",
          "company_name",
          "company_subdomains",
          "company_group_ids",
          "email",
          "external_unique_id",
          "upn",
          "deactivated",
          "deactivated_at",
          "created_at",
          "updated_at",
          "role",
          "roles",
          "role_allowed_office_ids",
          "role_allowed_tag_ids",
          "office_id",
          "office_name",
          "country_id",
          "country_code",
          "language_code",
          "language_codes",
          "ui_language_code",
          "title",
          "international_toggle",
          "preferred_download_format",
          "masterdata_languages",
          "expand_proposals_toggle",
          "selected_office_ids",
          "include_officeless_reference_projects",
          "selected_tag_ids",
          "override_language_code",
          "default_cv_template_id",
          "image",
          "name",
          "telephone",
          "default_cv_id",
          "is_authenticated_by_password"
        ],
        "properties": {
          "user_id": {
            "type": "string",
            "description": "User ID. Same value as `id`.",
            "example": "629d0ddd878f992c53183fc3"
          },
          "id": {
            "type": "string",
            "description": "Primary user identifier.",
            "example": "629d0ddd878f992c53183fc3"
          },
          "company_id": {
            "type": "string",
            "description": "Identifier of the company this user belongs to.",
            "example": "629d0db2878f992c53183f64"
          },
          "company_name": {
            "type": "string",
            "description": "Name of the company this user belongs to.",
            "example": "Acme Consulting AS"
          },
          "company_subdomains": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Subdomains associated with the user's company.",
            "example": [
              "acme-consulting"
            ]
          },
          "company_group_ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Company group identifiers.",
            "example": [
              "629d0e58878f992c5318429e"
            ]
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "The user's email address.",
            "example": "jane.smith@example.com"
          },
          "external_unique_id": {
            "type": "string",
            "nullable": true,
            "description": "External identifier used for integration with third-party systems. Null if not set.",
            "example": "93"
          },
          "upn": {
            "type": "string",
            "nullable": true,
            "description": "User Principal Name. Null if not set.",
            "example": "do.not.delete@example.com"
          },
          "deactivated": {
            "type": "boolean",
            "description": "Whether the user is deactivated.",
            "example": false
          },
          "deactivated_at": {
            "description": "Boolean `false` when the user is active. ISO 8601 datetime string indicating when deactivation occurred when the user is deactivated.\n",
            "oneOf": [
              {
                "type": "boolean"
              },
              {
                "type": "string",
                "format": "date-time"
              }
            ],
            "example": false
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the user was created.",
            "example": "2022-06-05T20:11:09.000Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the user was last updated.",
            "example": "2024-12-11T13:42:31.820Z"
          },
          "role": {
            "type": "string",
            "description": "The user's primary base role. One of `external`, `limited_access`, `consultant`, or `internationalmanager`. Extra access roles (`countrymanager`, `departmentmanager`, `referencemanager`, `bidmanager`) are always layered on top of `consultant` and appear only in `roles`, not here.\n",
            "example": "consultant"
          },
          "roles": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Full list of roles assigned to the user. Includes the base role plus any extra access roles (`countrymanager`, `departmentmanager`, `referencemanager`, `bidmanager`). Extra access roles always appear alongside `consultant`.\n",
            "example": [
              "consultant"
            ]
          },
          "role_allowed_office_ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Office IDs this user is allowed to manage. Relevant for the departmentmanager role.\n"
          },
          "role_allowed_tag_ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Custom tag IDs this user is allowed to manage as a departmentmanager. Used to model an office/department that spans multiple countries, as an alternative to role_allowed_office_ids which is scoped to a single country's office.\n"
          },
          "office_id": {
            "type": "string",
            "nullable": true,
            "description": "Identifier of the user's office (department). Null if no office assigned.",
            "example": "629d0ddb878f992c53183fb6"
          },
          "office_name": {
            "type": "string",
            "nullable": true,
            "description": "Name of the user's office (department). Null if no office assigned.",
            "example": "Bergen"
          },
          "country_id": {
            "type": "string",
            "nullable": true,
            "description": "Identifier of the country derived from the user's office. Null if no office assigned.",
            "example": "629d0dbc878f992c53183f65"
          },
          "country_code": {
            "type": "string",
            "nullable": true,
            "description": "Country code derived from the user's office. Null if no office assigned. Affected by the `use_legacy_codes` parameter.\n",
            "example": "no"
          },
          "language_code": {
            "type": "string",
            "description": "Primary language code for the user. Uses legacy codes by default (`int`, `se`, `cn`, etc.); uses ISO 639-1 codes (`en`, `sv`, `zh`, etc.) when `?use_legacy_codes=false` is passed. When `override_language_code` is set, this field returns the override value rather than the office default.\n",
            "example": "int"
          },
          "language_codes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "All language codes available to the user. Uses legacy codes by default; uses ISO 639-1 codes when `?use_legacy_codes=false` is passed. When `override_language_code` is set, that code is placed first in the list; all other codes follow in their natural order.\n"
          },
          "ui_language_code": {
            "type": "string",
            "description": "UI language preference. Uses legacy codes by default; uses ISO 639-1 codes when `?use_legacy_codes=false` is passed. Tracks `override_language_code` when set; otherwise reflects the office default.\n",
            "example": "int"
          },
          "title": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Multilingual job title. Keys are language codes in legacy format by default (`int`, `no`, `se`, etc.), or ISO 639-1 (`en`, `no`, `sv`, etc.) when `?use_legacy_codes=false` is passed. Values are title strings. May be empty (`{}`). Keys not valid in the active mode are filtered out on creation.\n",
            "example": {
              "int": "Senior Consultant",
              "no": "Seniorkonsulent"
            }
          },
          "international_toggle": {
            "type": "string",
            "description": "Controls international CV section visibility.",
            "example": "expand"
          },
          "preferred_download_format": {
            "type": "string",
            "description": "The user's preferred CV download format.",
            "example": "pdf-from-word"
          },
          "masterdata_languages": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Language codes available to the user. Contains the same values as `language_codes`, in the same order. Affected by the `use_legacy_codes` parameter.\n"
          },
          "expand_proposals_toggle": {
            "type": "boolean",
            "example": true
          },
          "selected_office_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "include_officeless_reference_projects": {
            "type": "boolean",
            "example": false
          },
          "selected_tag_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "override_language_code": {
            "type": "string",
            "nullable": true,
            "description": "Language code override. Null if not set. When set, this value is placed first in `language_codes` and `masterdata_languages`, and also determines `language_code` and `ui_language_code`. Uses legacy codes by default; uses ISO 639-1 codes when `?use_legacy_codes=false` is passed. A code that is not valid in the active mode is silently dropped (field returns null) rather than returning an error.\n",
            "example": "int"
          },
          "default_cv_template_id": {
            "type": "string",
            "nullable": true,
            "description": "Default CV template identifier derived from the user's office. Null if no office or no default template.",
            "example": "65e077696a22740052cbd1e1"
          },
          "image": {
            "$ref": "#/components/schemas/UserImage"
          },
          "name": {
            "type": "string",
            "description": "Display name. Falls back to the user's email if the name is blank.",
            "example": "Jane Smith"
          },
          "telephone": {
            "type": "string",
            "description": "Telephone number. Empty string if not set.",
            "example": "+47 123 45 678"
          },
          "default_cv_id": {
            "type": "string",
            "description": "Identifier of the user's master (default) CV. Always present for every user.\n",
            "example": "629d0ddd878f992c53183fc4"
          },
          "is_authenticated_by_password": {
            "type": "boolean",
            "description": "Whether the user authenticates with a password.",
            "example": true
          }
        }
      },
      "UserImage": {
        "type": "object",
        "required": [
          "url",
          "thumb",
          "fit_thumb",
          "large",
          "small_thumb"
        ],
        "properties": {
          "url": {
            "type": "string",
            "nullable": true,
            "format": "uri",
            "description": "Full-size image URL. Temporary URL that expires after approximately 10 minutes. Null if no image uploaded."
          },
          "thumb": {
            "$ref": "#/components/schemas/UserImageVersion"
          },
          "fit_thumb": {
            "$ref": "#/components/schemas/UserImageVersion"
          },
          "large": {
            "$ref": "#/components/schemas/UserImageVersion"
          },
          "small_thumb": {
            "$ref": "#/components/schemas/UserImageVersion"
          }
        }
      },
      "UserImageVersion": {
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "nullable": true,
            "format": "uri",
            "description": "Image URL for this version. Temporary URL that expires after approximately 10 minutes. Null if no image uploaded."
          }
        }
      },
      "CustomTagCategory": {
        "type": "object",
        "required": [
          "id",
          "values",
          "external_unique_id",
          "can_be_used_for_cvs",
          "can_be_used_for_references",
          "can_be_used_for_customers",
          "allow_filtering",
          "lock_for_integrations"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the custom tag category.",
            "example": "629d0dd1878f992c53183f68"
          },
          "values": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "external_unique_id": {
            "type": "string",
            "nullable": true,
            "description": "Optional identifier for linking this category with an external system. Can be `null` or an empty string when not set.\n",
            "example": "HR.FIELD.EMP_TYPE"
          },
          "can_be_used_for_cvs": {
            "type": "boolean",
            "description": "Whether tags in this category can be attached to CVs / résumés.",
            "example": true
          },
          "can_be_used_for_references": {
            "type": "boolean",
            "description": "Whether tags in this category can be attached to reference projects.",
            "example": true
          },
          "can_be_used_for_customers": {
            "type": "boolean",
            "description": "Whether tags in this category can be attached to customers.",
            "example": true
          },
          "allow_filtering": {
            "type": "boolean",
            "description": "Whether this category is available as a filter option in the UI.",
            "example": false
          },
          "lock_for_integrations": {
            "type": "boolean",
            "description": "Whether this category is locked for integration use.",
            "example": false
          },
          "custom_tags": {
            "type": "array",
            "description": "The custom tags belonging to this category.",
            "items": {
              "$ref": "#/components/schemas/CustomTag"
            }
          }
        }
      },
      "CustomTag": {
        "type": "object",
        "required": [
          "id",
          "values",
          "external_unique_id",
          "custom_tag_category_id",
          "category_ids"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the custom tag.",
            "example": "629d0dd1878f992c53183f69"
          },
          "values": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "external_unique_id": {
            "type": "string",
            "nullable": true,
            "description": "Optional identifier for linking this tag with an external system. Can be `null` or an empty string when not set.\n",
            "example": "HR.FIELD.EMP_TYPE.FULL"
          },
          "custom_tag_category_id": {
            "type": "string",
            "description": "ID of the category this tag belongs to.",
            "example": "629d0dd1878f992c53183f68"
          },
          "category_ids": {
            "type": "array",
            "description": "Array containing the parent category ID. Always a single-element array, since tags belong to exactly one category.\n",
            "items": {
              "type": "string"
            },
            "example": [
              "629d0dd1878f992c53183f68"
            ]
          },
          "custom_tag_category": {
            "description": "Embedded category details. Present when tags are returned as part of a reference project; absent in standalone tag listings.\n",
            "$ref": "#/components/schemas/CustomTagCategory"
          }
        }
      },
      "MultilingualValues": {
        "type": "object",
        "description": "A map of language codes to translated strings. Keys are language codes whose format depends on the `use_legacy_codes` parameter. The default format uses legacy codes (e.g. `int`, `se`, `cn`), or ISO 639-1 codes (e.g. `en`, `sv`, `zh`) when `use_legacy_codes=false`. Not all languages need to be present; the object may be empty.\n",
        "additionalProperties": {
          "type": "string"
        },
        "example": {
          "int": "Department",
          "no": "Avdeling",
          "se": "Avdeling"
        }
      },
      "AuthenticationError": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable error message.",
            "example": "You are not authorized to access this page"
          }
        }
      },
      "ValidationError": {
        "type": "object",
        "required": [
          "valid",
          "errors"
        ],
        "properties": {
          "valid": {
            "type": "boolean",
            "description": "Always `false` for validation errors.",
            "example": false
          },
          "errors": {
            "type": "object",
            "additionalProperties": true,
            "description": "Map of field names to error details. Most fields map to an array of locale-dependent message strings. The `ensure_unique_custom_tag_ids_by_category` field maps to an object with `not_found_category_ids`, `not_found_tag_ids`, and `tags` arrays. Message strings are locale-dependent and should not be used for programmatic error handling.\n",
            "example": {
              "email": [
                "has been taken"
              ]
            }
          }
        }
      },
      "NotFoundError": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable error description.",
            "example": "Not Found"
          }
        }
      },
      "UserCreateBody": {
        "type": "object",
        "properties": {
          "user": {
            "type": "object",
            "required": [
              "email",
              "country_id",
              "office_id"
            ],
            "description": "Fields for the new user. At minimum, `email`, `country_id`, and `office_id` are required. The user is created under the account associated with the authenticated API key.\n",
            "properties": {
              "email": {
                "type": "string",
                "format": "email",
                "description": "The user's email address. Must be unique within the account. Automatically lowercased and trimmed. The email domain must be in the account's whitelist unless the user is given the `external` role.\n"
              },
              "country_id": {
                "type": "string",
                "description": "Identifier of the country to create the user in. The API key must have `create_user` permission for this country (`countrymanager` for their own country, `internationalmanager` for any country).\n",
                "example": "629d0dbc878f992c53183f65"
              },
              "office_id": {
                "type": "string",
                "description": "Identifier of the office (department) within the specified country. Must belong to the country identified by `country_id`.\n",
                "example": "629d0dd0878f992c53183f66"
              },
              "role": {
                "type": "string",
                "description": "Base role for the user. The roles that can be assigned depend on the caller's own role level. Extra access roles (`countrymanager`, `departmentmanager`, `referencemanager`, `bidmanager`) should be passed via `extra_roles` instead, as they are always layered on top of `consultant`.\n",
                "enum": [
                  "external",
                  "limited_access",
                  "consultant",
                  "internationalmanager"
                ],
                "example": "consultant"
              },
              "extra_roles": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "countrymanager",
                    "departmentmanager",
                    "referencemanager",
                    "bidmanager"
                  ]
                },
                "description": "Extra access roles granted on top of the `consultant` base role. When including `departmentmanager`, also provide `role_allowed_office_ids` and/or `role_allowed_tag_ids`.\n",
                "example": [
                  "departmentmanager"
                ]
              },
              "role_allowed_office_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Office IDs the user can manage. Only applied when the user's roles include `departmentmanager`.\n",
                "example": [
                  "629d0ddb878f992c53183fb6"
                ]
              },
              "role_allowed_tag_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Custom tag IDs the user can manage as a departmentmanager. Models an office/department that spans multiple countries, as an alternative to `role_allowed_office_ids` which is scoped to a single country's office.\n",
                "example": [
                  "6634a28d92588400488179c3"
                ]
              },
              "upn": {
                "type": "string",
                "description": "User Principal Name. Must be unique within the account if provided. Automatically lowercased and trimmed.\n"
              },
              "external_unique_id": {
                "type": "string",
                "description": "External system identifier (e.g. employee ID). Must be unique within the account if provided.\n"
              },
              "name": {
                "type": "string",
                "description": "Display name. Falls back to the email address if not provided.",
                "example": "Jane Smith"
              },
              "telephone": {
                "type": "string",
                "description": "Phone number.",
                "example": "+47 123 45 678"
              },
              "landline": {
                "type": "string",
                "description": "Landline number.",
                "example": "+47 987 65 432"
              },
              "born_year": {
                "type": "integer",
                "description": "Birth year.",
                "example": 1990
              },
              "override_language_code": {
                "type": "string",
                "nullable": true,
                "description": "Language code override for this user. When set, this code is placed first in `language_codes` / `masterdata_languages` and becomes the value of `language_code` and `ui_language_code`. Must be a valid code in the active mode (legacy by default, ISO 639-1 when `?use_legacy_codes=false`). Codes not valid in the active mode are silently dropped. Send `null` to explicitly clear a previously set override.\n",
                "example": "int"
              },
              "title": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Multilingual job title. Keys are language codes (legacy by default, e.g. `int`, `no`; ISO 639-1 when `?use_legacy_codes=false`, e.g. `en`, `no`). Values are title strings. Keys not valid in the active mode are silently dropped. Keys with null values are also silently dropped (e.g. `{\"no\":\"Utvikler\",\"en\":null}` → `{\"no\":\"Utvikler\"}`).\n",
                "example": {
                  "no": "Konsulent",
                  "int": "Consultant"
                }
              },
              "nationality": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Multilingual nationality. Same shape and language code rules as `title`.\n",
                "example": {
                  "no": "Norsk",
                  "int": "Norwegian"
                }
              },
              "name_multilang": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Multilingual display name. Same shape and language code rules as `title`. Not returned in the user response.\n",
                "example": {
                  "no": "Jane Smith",
                  "int": "Jane Smith"
                }
              },
              "place_of_residence": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Multilingual place of residence. Same shape and language code rules as `title`. Not returned in the user response.\n",
                "example": {
                  "no": "Oslo",
                  "int": "Oslo"
                }
              },
              "deactivated": {
                "type": "boolean",
                "description": "Create the user in a deactivated state. When `true`, `deactivated_at` in the response is set to the creation timestamp (an ISO 8601 datetime string) rather than `false`.\n",
                "default": false,
                "example": false
              },
              "navn": {
                "type": "string",
                "description": "Legacy alias for `name`. If both `name` and `navn` are provided, `navn` takes precedence.\n",
                "example": "Jane Smith"
              },
              "telefon": {
                "type": "string",
                "description": "Legacy alias for `telephone`. If both `telephone` and `telefon` are provided, `telefon` takes precedence.\n",
                "example": "+47 123 45 678"
              },
              "ensure_unique_custom_tag_ids_by_category": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Map of custom tag category ID to custom tag ID. Adds the specified tag and removes any other tag the user has within that category. Use the `id` values returned by the API, not `external_unique_id` values. Returns 400 if any referenced category or tag ID does not exist in the account.\n",
                "example": {
                  "63b563c80ff7255c26324987": "6880cd8b706ad10046c515df"
                }
              },
              "send_email": {
                "type": "boolean",
                "description": "If `true`, sends a welcome email to the new user. Omit or set to `false` to create the user without sending an email.\n",
                "default": false,
                "example": false
              }
            }
          }
        }
      },
      "UserUpdateBody": {
        "type": "object",
        "required": [
          "user"
        ],
        "properties": {
          "user": {
            "type": "object",
            "description": "Fields to update on the user. Only include fields that should be changed; omitted fields remain as they are.\n",
            "properties": {
              "email": {
                "type": "string",
                "format": "email",
                "description": "The user's email address. Must be unique within the account."
              },
              "upn": {
                "type": "string",
                "description": "User Principal Name. Must be unique within the account if provided."
              },
              "external_unique_id": {
                "type": "string",
                "description": "External system identifier (e.g. employee ID). Must be unique within the account if provided."
              },
              "name": {
                "type": "string",
                "description": "Display name.",
                "example": "Jane Smith"
              },
              "telephone": {
                "type": "string",
                "description": "Phone number.",
                "example": "+47 123 45 678"
              },
              "landline": {
                "type": "string",
                "description": "Landline number.",
                "example": "+47 987 65 432"
              },
              "born_year": {
                "type": "integer",
                "description": "Birth year.",
                "example": 1990
              },
              "role": {
                "type": "string",
                "description": "Base role. Extra access roles (`countrymanager`, `departmentmanager`, `referencemanager`, `bidmanager`) should be passed via `extra_roles` instead, as they are always layered on top of `consultant`.\n",
                "enum": [
                  "external",
                  "limited_access",
                  "consultant",
                  "internationalmanager"
                ],
                "example": "consultant"
              },
              "extra_roles": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "countrymanager",
                    "departmentmanager",
                    "referencemanager",
                    "bidmanager"
                  ]
                },
                "description": "Extra access roles granted on top of the `consultant` base role. When assigning `departmentmanager`, also include `role_allowed_office_ids` and/or `role_allowed_tag_ids`.\n",
                "example": [
                  "departmentmanager"
                ]
              },
              "role_allowed_office_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Office IDs the user can manage. Required when `extra_roles` includes `departmentmanager`.\n",
                "example": [
                  "629d0ddb878f992c53183fb6"
                ]
              },
              "role_allowed_tag_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Custom tag IDs the user can manage as a departmentmanager. Models an office/department that spans multiple countries, as an alternative to `role_allowed_office_ids` which is scoped to a single country's office.\n",
                "example": [
                  "6634a28d92588400488179c3"
                ]
              },
              "country_id": {
                "type": "string",
                "description": "Country identifier. Required when changing `office_id` and must be the country that the new office belongs to.\n",
                "example": "629d0dbc878f992c53183f65"
              },
              "office_id": {
                "type": "string",
                "description": "Office (department) identifier. When changing the office, you must also provide `country_id` for the country that the new office belongs to.\n",
                "example": "629d0ddb878f992c53183fb6"
              },
              "override_language_code": {
                "type": "string",
                "nullable": true,
                "description": "Language code override for this user. When set, this code is placed first in `language_codes` / `masterdata_languages` and becomes the value of `language_code` and `ui_language_code`. Must be a valid code in the active mode (legacy by default, ISO 639-1 when `?use_legacy_codes=false`). Codes not valid in the active mode are silently dropped. Send `null` to explicitly clear a previously set override.\n",
                "example": "int"
              },
              "deactivated": {
                "type": "boolean",
                "description": "Set to `true` to deactivate the user, `false` to reactivate.\n",
                "example": false
              },
              "title": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Multilingual job title. Keys are language codes (legacy by default, e.g. `int`, `no`; ISO 639-1 when `?use_legacy_codes=false`, e.g. `en`, `no`). Values are title strings. Keys not valid in the active mode are silently dropped.\n",
                "example": {
                  "no": "Konsulent",
                  "int": "Consultant"
                }
              },
              "nationality": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Multilingual nationality. Same shape and language code rules as `title`.\n",
                "example": {
                  "no": "Norsk",
                  "int": "Norwegian"
                }
              },
              "ensure_unique_custom_tag_ids_by_category": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Map of custom tag category ID to custom tag ID. Adds the specified tag and removes any other tag the user has within that category. Use the `id` values returned by the API, not `external_unique_id` values. Returns 400 if any referenced category or tag ID does not exist in the account.\n",
                "example": {
                  "63b563c80ff7255c26324987": "6880cd8b706ad10046c515df"
                }
              },
              "send_email": {
                "type": "boolean",
                "description": "If `true`, sends an email notification to the user. When reactivating a user, set to `true` to send a welcome email. Omit or set to `false` to suppress the email.\n",
                "default": false,
                "example": false
              }
            }
          }
        }
      },
      "Customer": {
        "type": "object",
        "required": [
          "id",
          "company_id",
          "created_at",
          "updated_at",
          "version",
          "customer_name",
          "customer_name_anonymized",
          "customer_description",
          "customer_description_anonymized",
          "customer_description_to_cvs",
          "customer_sensitivity",
          "customer_url",
          "external_unique_id",
          "image",
          "image_height",
          "image_width",
          "masterdata_industry_id",
          "project_count",
          "custom_tags",
          "industry"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Customer identifier.",
            "example": "646cd381a205f30f4a8dab05"
          },
          "company_id": {
            "type": "string",
            "description": "Identifier of the company that owns this customer.",
            "example": "629d0db2878f992c53183f64"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the customer was created.",
            "example": "2023-05-23T14:53:53.679Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the customer was last updated.",
            "example": "2026-04-24T15:31:22.196Z"
          },
          "version": {
            "type": "integer",
            "description": "Version counter. Increments on each update.",
            "example": 62
          },
          "customer_name": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Multilingual customer name. Keys are language codes in legacy format by default (e.g. `int`, `no`, `se`), or ISO 639-1 when `use_legacy_codes=false` (e.g. `en`, `no`, `sv`). On creation, any company language codes not provided are auto-populated with the first non-empty value supplied.\n",
            "example": {
              "int": "3M",
              "no": "3M"
            }
          },
          "customer_name_anonymized": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Anonymised version of the customer name. Same structure as `customer_name`. Empty object if not set. Only available on accounts with anonymisation enabled — contact support to enable.\n",
            "example": {}
          },
          "customer_description": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Multilingual customer description. Keys are language codes affected by `use_legacy_codes`. Empty object if not set.\n",
            "example": {
              "int": "A multinational conglomerate company."
            }
          },
          "customer_description_anonymized": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Anonymised version of the customer description. Empty object if not set. Only available on accounts with anonymisation enabled — contact support to enable.\n",
            "example": {}
          },
          "customer_description_to_cvs": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Multilingual description shown on CVs when this customer is referenced. Keys are language codes affected by `use_legacy_codes`. Empty object if not set.\n",
            "example": {
              "int": "A multinational conglomerate company."
            }
          },
          "customer_sensitivity": {
            "type": "string",
            "nullable": true,
            "description": "Sensitivity classification. `\"confidential\"` hides the customer name in public views. `\"anonymized\"` replaces the name with the anonymised variant. `null` when not classified.\n",
            "example": null
          },
          "customer_url": {
            "type": "string",
            "nullable": true,
            "description": "Customer website URL. Null if not set.",
            "example": "https://www.3m.co.uk/"
          },
          "external_unique_id": {
            "type": "string",
            "nullable": true,
            "description": "External identifier used to link this customer to an external system. This is the lookup key for the find endpoint. Null if not set.\n",
            "example": "three-m"
          },
          "image": {
            "$ref": "#/components/schemas/UserImage"
          },
          "image_height": {
            "type": "integer",
            "nullable": true,
            "description": "Height of the customer logo image in pixels. Null if no image has been uploaded.\n",
            "example": 48
          },
          "image_width": {
            "type": "integer",
            "nullable": true,
            "description": "Width of the customer logo image in pixels. Null if no image has been uploaded.\n",
            "example": 79
          },
          "masterdata_industry_id": {
            "type": "string",
            "nullable": true,
            "description": "Identifier of the industry masterdata record associated with this customer. Null if no industry has been assigned. See also the `industry` field for the full expanded object.\n",
            "example": "63b563fa0ff7255c26324ac5"
          },
          "project_count": {
            "type": "integer",
            "description": "Number of reference projects associated with this customer.",
            "example": 13
          },
          "custom_tags": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CustomerCustomTag"
            },
            "description": "Custom tags applied to this customer from categories configured for customer use. Empty array if no tags have been applied.\n"
          },
          "industry": {
            "nullable": true,
            "allOf": [
              {
                "$ref": "#/components/schemas/CustomerIndustry"
              }
            ],
            "description": "Expanded industry masterdata object. Null if no industry has been assigned. The `masterdata_industry_id` field contains the same value as a plain string identifier.\n"
          }
        }
      },
      "CustomerIndustry": {
        "type": "object",
        "required": [
          "id",
          "section_type",
          "field_name",
          "values",
          "external_unique_id",
          "help_text"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Industry identifier.",
            "example": "63b563fa0ff7255c26324ac5"
          },
          "section_type": {
            "type": "string",
            "description": "The CV section type this industry belongs to.",
            "example": "project_experiences"
          },
          "field_name": {
            "type": "string",
            "description": "The field name within the section type.",
            "example": "industry"
          },
          "values": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Multilingual industry name. Keys are legacy language codes (e.g. `int` for international/English). Values are localised name strings.\n",
            "example": {
              "int": "Transport"
            }
          },
          "external_unique_id": {
            "type": "string",
            "nullable": true,
            "description": "External identifier for this industry entry. Null if not set."
          },
          "help_text": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Multilingual help text for this industry field. Empty object if not set.\n",
            "example": {}
          }
        }
      },
      "CustomerCustomTag": {
        "type": "object",
        "required": [
          "id",
          "values",
          "external_unique_id",
          "custom_tag_category_id",
          "category_ids"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Custom tag identifier.",
            "example": "64ba9ea58e11ef0f4ecc0768"
          },
          "values": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Multilingual tag label. Keys are legacy language codes (e.g. `int` for international/English). Values are localised label strings.\n",
            "example": {
              "int": "Production"
            }
          },
          "external_unique_id": {
            "type": "string",
            "nullable": true,
            "description": "External identifier for this tag. Empty string `\"\"` when not set (not null); may also be null in some cases.\n",
            "example": ""
          },
          "custom_tag_category_id": {
            "type": "string",
            "description": "Identifier of the category this tag belongs to.",
            "example": "64ba9d878e11ef0f45cc0768"
          },
          "category_ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of category IDs for this tag. In practice contains the single `custom_tag_category_id` value.\n",
            "example": [
              "64ba9d878e11ef0f45cc0768"
            ]
          }
        }
      },
      "CustomerCreateBody": {
        "type": "object",
        "required": [
          "company_customer"
        ],
        "properties": {
          "company_customer": {
            "type": "object",
            "required": [
              "customer_name"
            ],
            "description": "Customer fields. At minimum, `customer_name` with at least one language code entry is required. Submitting an empty wrapper (`\"company_customer\": {}`) returns 400.\n",
            "properties": {
              "customer_name": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Multilingual customer name. Keys are language codes in legacy format by default (e.g. `int`, `no`, `se`), or ISO 639-1 when `use_legacy_codes=false` (e.g. `en`, `no`, `sv`). Any company language codes not provided are auto-populated with the first non-empty value.\n",
                "example": {
                  "int": "Test customer",
                  "no": "Test customer"
                }
              },
              "customer_name_anonymized": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Anonymised version of the customer name. Same language code rules as `customer_name`. Unlike `customer_name`, missing language codes are NOT auto-populated. Only available on accounts with anonymisation enabled — contact support to enable.\n",
                "example": {
                  "int": "Redacted Customer"
                }
              },
              "customer_description": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Multilingual customer description. Same language code rules as `customer_name`.\n",
                "example": {
                  "int": "Description",
                  "no": "Description"
                }
              },
              "customer_description_anonymized": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Anonymised version of the customer description. Same language code rules as `customer_name`. Only available on accounts with anonymisation enabled — contact support to enable.\n",
                "example": {
                  "int": "Redacted description"
                }
              },
              "customer_description_to_cvs": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Multilingual description shown on CVs when this customer is referenced. Same language code rules as `customer_name`.\n",
                "example": {
                  "int": "Description",
                  "no": "Description"
                }
              },
              "customer_url": {
                "type": "string",
                "description": "Customer website URL. Must be a valid `http://` or `https://` URL. Invalid URLs are stored as an empty string.\n",
                "example": "https://example.com"
              },
              "external_unique_id": {
                "type": "string",
                "description": "External system identifier for linking this customer to external systems. This is the lookup key used by the find endpoint.\n",
                "example": "1234"
              },
              "industry_id": {
                "type": "string",
                "description": "Identifier of an industry to associate with this customer. Must be a valid industry ID in the account.\n",
                "example": "63b563fa0ff7255c26324ac5"
              },
              "customer_sensitivity": {
                "type": "string",
                "enum": [
                  "anonymized",
                  "confidential"
                ],
                "description": "Sensitivity classification. `\"anonymized\"` replaces the customer name with the anonymised variant in applicable views. `\"confidential\"` hides the customer name. Invalid values return a 400 validation error.\n"
              }
            }
          }
        }
      },
      "CustomerCreateResponse": {
        "description": "Customer object as returned by the create endpoint. This shape omits the `project_count` and `industry` fields that are present in read endpoints (find, show, list, update).\n",
        "type": "object",
        "required": [
          "id",
          "company_id",
          "created_at",
          "updated_at",
          "version",
          "customer_name",
          "customer_name_anonymized",
          "customer_description",
          "customer_description_anonymized",
          "customer_description_to_cvs",
          "customer_sensitivity",
          "customer_url",
          "external_unique_id",
          "image",
          "image_height",
          "image_width",
          "masterdata_industry_id",
          "custom_tags"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Customer identifier.",
            "example": "69f068bbb7c50ee6045ef4a7"
          },
          "company_id": {
            "type": "string",
            "description": "Identifier of the company that owns this customer.",
            "example": "629d0db2878f992c53183f64"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the customer was created.",
            "example": "2026-04-28T07:58:51.703Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the customer was last updated.",
            "example": "2026-04-28T07:58:51.703Z"
          },
          "version": {
            "type": "integer",
            "description": "Version counter. Always `1` for newly created customers.",
            "example": 1
          },
          "customer_name": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Multilingual customer name. Keys are language codes in legacy format by default (e.g. `int`, `no`, `se`), or ISO 639-1 when `use_legacy_codes=false` (e.g. `en`, `no`, `sv`). On creation, any company language codes not provided are auto-populated with the first non-empty value.\n",
            "example": {
              "int": "Acme Corporation",
              "no": "Acme Corporation"
            }
          },
          "customer_name_anonymized": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Anonymised version of the customer name. Same structure as `customer_name`. Empty object if not set. Only available on accounts with anonymisation enabled — contact support to enable.\n",
            "example": {}
          },
          "customer_description": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Multilingual customer description. Keys are language codes affected by `use_legacy_codes`. Empty object if not set.\n",
            "example": {}
          },
          "customer_description_anonymized": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Anonymised version of the customer description. Empty object if not set. Only available on accounts with anonymisation enabled — contact support to enable.\n",
            "example": {}
          },
          "customer_description_to_cvs": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Multilingual description shown on CVs when this customer is referenced. Keys are language codes affected by `use_legacy_codes`. Empty object if not set.\n",
            "example": {}
          },
          "customer_sensitivity": {
            "type": "string",
            "nullable": true,
            "description": "Sensitivity classification. `\"confidential\"` hides the customer name in public views. `\"anonymized\"` replaces the name with the anonymised variant. `null` when not classified.\n",
            "example": null
          },
          "customer_url": {
            "type": "string",
            "nullable": true,
            "description": "Customer website URL. Null if not set. Empty string `\"\"` if an invalid URL was provided.\n",
            "example": "https://example.com"
          },
          "external_unique_id": {
            "type": "string",
            "nullable": true,
            "description": "External identifier used to link this customer to an external system. Null if not set.\n",
            "example": "CRM-10042"
          },
          "image": {
            "$ref": "#/components/schemas/UserImage"
          },
          "image_height": {
            "type": "integer",
            "nullable": true,
            "description": "Height of the customer logo image in pixels. Null if no image has been uploaded (always null for newly created customers).\n",
            "example": null
          },
          "image_width": {
            "type": "integer",
            "nullable": true,
            "description": "Width of the customer logo image in pixels. Null if no image has been uploaded (always null for newly created customers).\n",
            "example": null
          },
          "masterdata_industry_id": {
            "type": "string",
            "nullable": true,
            "description": "Identifier of the industry masterdata record associated with this customer. Null if no industry was specified via `industry_id` in the request.\n",
            "example": "63b563fa0ff7255c26324ac5"
          },
          "custom_tags": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CustomerCustomTag"
            },
            "description": "Custom tags applied to this customer. Always an empty array for newly created customers.\n"
          }
        }
      },
      "CustomerDuplicateError": {
        "type": "object",
        "required": [
          "error",
          "duplicate_customer_ids"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable error message. The message text is locale-dependent (returned in the account's configured language). Do not rely on the message text for detection. Instead, use the HTTP 400 status and the presence of `duplicate_customer_ids` to detect this condition.\n",
            "example": "More than one customer was found when looking up by external_unique_id"
          },
          "duplicate_customer_ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "IDs of the customers that share the same `external_unique_id` within the account.\n",
            "example": [
              "646cd3a1a205f30f4a8dabf7",
              "65b0fee20e6acb003a1dfde9"
            ]
          }
        }
      },
      "CustomTagCreateBody": {
        "type": "object",
        "required": [
          "masterdata"
        ],
        "properties": {
          "masterdata": {
            "type": "object",
            "required": [
              "category_ids"
            ],
            "description": "Fields for the new custom tag. The `category_ids` field is required; all other fields are optional.\n",
            "properties": {
              "values": {
                "$ref": "#/components/schemas/MultilingualValues"
              },
              "external_unique_id": {
                "type": "string",
                "description": "Optional identifier for linking this tag with an external system. Must be unique within the category if provided. Multiple tags may omit this field.\n",
                "example": "HR.FIELD.EMP_TYPE.FULL"
              },
              "category_ids": {
                "type": "array",
                "description": "Array containing the ID of the category to create this tag in. Despite the plural name, only the first element is used because tags belong to exactly one category.\n",
                "items": {
                  "type": "string"
                },
                "minItems": 1,
                "example": [
                  "629d0dd1878f992c53183f68"
                ]
              }
            }
          }
        }
      },
      "CustomTagCategoryCreateBody": {
        "type": "object",
        "required": [
          "masterdata"
        ],
        "properties": {
          "masterdata": {
            "type": "object",
            "required": [
              "values"
            ],
            "description": "Fields for the new custom tag category. The `values` key is required (even if empty). All other fields are optional and have sensible defaults.\n",
            "properties": {
              "values": {
                "$ref": "#/components/schemas/MultilingualValues"
              },
              "external_unique_id": {
                "type": "string",
                "description": "Optional identifier for linking this category with an external system. Must be unique within the account if provided. Multiple categories may omit this field.\n",
                "example": "HR.FIELD.EMP_TYPE"
              },
              "can_be_used_for_cvs": {
                "type": "boolean",
                "description": "Whether tags in this category can be attached to CVs / résumés.",
                "default": true,
                "example": true
              },
              "can_be_used_for_references": {
                "type": "boolean",
                "description": "Whether tags in this category can be attached to reference projects.",
                "default": true,
                "example": true
              },
              "can_be_used_for_customers": {
                "type": "boolean",
                "description": "Whether tags in this category can be attached to customers.",
                "default": true,
                "example": true
              },
              "allow_filtering": {
                "type": "boolean",
                "description": "Whether this category is available as a filter option.",
                "default": false,
                "example": false
              },
              "lock_for_integrations": {
                "type": "boolean",
                "description": "Whether to lock this category for integration use.",
                "default": false,
                "example": false
              }
            }
          }
        }
      },
      "BadRequestError": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable error description. Typically the HTTP status reason phrase.\n",
            "example": "Bad Request"
          }
        }
      },
      "InternalServerError": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable error description. Typically the HTTP status reason phrase.\n",
            "example": "Internal Server Error"
          }
        }
      },
      "CvResponse": {
        "type": "object",
        "description": "Full CV (résumé) object as returned by write operations on the V3 CV endpoint. This is a large response containing all CV sections, user metadata, custom tags, and template settings.\n",
        "required": [
          "bruker_id",
          "user_id",
          "name",
          "navn",
          "name_multilang",
          "default",
          "created_at",
          "updated_at",
          "version",
          "company_id",
          "email",
          "country_code",
          "language_code",
          "language_codes",
          "telephone",
          "technologies",
          "custom_tags",
          "custom_tag_ids",
          "updated_ago",
          "template_document_type",
          "highlighted_roles",
          "image",
          "can_write"
        ],
        "properties": {
          "bruker_id": {
            "type": "string",
            "description": "User ID. Legacy field; identical to `user_id`.\n",
            "example": "69eb60e04e90c9ebbdc6edbb"
          },
          "user_id": {
            "type": "string",
            "description": "ID of the user who owns this CV.",
            "example": "69eb60e04e90c9ebbdc6edbb"
          },
          "tilbud_id": {
            "type": "string",
            "nullable": true,
            "description": "Proposal ID. Null for master CVs; set for proposal CVs.\n",
            "example": null
          },
          "name": {
            "type": "string",
            "nullable": true,
            "description": "Display name of the CV owner. `null` when the user has no display name configured.\n",
            "example": "Jane Smith"
          },
          "navn": {
            "type": "string",
            "nullable": true,
            "description": "Display name. Legacy field; identical to `name`.\n",
            "example": "Jane Smith"
          },
          "name_multilang": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "title": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "telefon": {
            "type": "string",
            "nullable": true,
            "description": "Telephone number. Legacy field; identical to `telephone`.\n",
            "example": "+47 123 45 678"
          },
          "landline": {
            "type": "string",
            "nullable": true,
            "description": "Landline telephone number.",
            "example": "+47 987 65 432"
          },
          "twitter": {
            "type": "string",
            "nullable": true,
            "description": "Twitter/X handle.",
            "example": "@janesmith"
          },
          "level": {
            "type": "string",
            "nullable": true,
            "description": "Seniority level.",
            "example": "Senior"
          },
          "born_day": {
            "type": "integer",
            "description": "Always 1 (day of birth is not exposed).",
            "example": 1
          },
          "born_month": {
            "type": "integer",
            "description": "Always 1 (month of birth is not exposed).",
            "example": 1
          },
          "born_year": {
            "type": "integer",
            "nullable": true,
            "description": "Year of birth. Null if not set.",
            "example": 1990
          },
          "default": {
            "type": "boolean",
            "description": "True for master CVs, false for proposal CVs.\n",
            "example": true
          },
          "nationality": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "place_of_residence": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "status": {
            "type": "string",
            "nullable": true,
            "description": "Proposal CV status. Null for master CVs.\n",
            "example": null
          },
          "order": {
            "type": "integer",
            "nullable": true,
            "description": "Sort order for proposal CVs. Null for master CVs.\n",
            "example": null
          },
          "owner_updated_at": {
            "type": "string",
            "nullable": true,
            "format": "date-time",
            "description": "When the CV owner last updated the CV."
          },
          "owner_updated_at_significant": {
            "type": "string",
            "nullable": true,
            "format": "date-time",
            "description": "When the CV owner last made a significant update."
          },
          "imported_date": {
            "type": "string",
            "nullable": true,
            "description": "Import date string (`YYYY-MM-DD`). Null for proposal CVs or if not imported.\n",
            "example": null
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the CV was created.",
            "example": "2026-04-24T12:24:00.912Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the CV was last updated.",
            "example": "2026-04-24T12:24:00.912Z"
          },
          "version": {
            "type": "integer",
            "description": "CV version number.",
            "example": 1
          },
          "modifier_id": {
            "type": "string",
            "nullable": true,
            "description": "Reserved for future use. Always null.",
            "example": null
          },
          "company_id": {
            "type": "string",
            "description": "ID of the company the CV owner belongs to.",
            "example": "629d0db2878f992c53183f64"
          },
          "external_unique_id": {
            "type": "string",
            "nullable": true,
            "description": "External identifier for the CV owner.",
            "example": "EMP-12345"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Email address of the CV owner.",
            "example": "jane.smith@example.com"
          },
          "country_code": {
            "type": "string",
            "nullable": true,
            "description": "Country code derived from the user's office.",
            "example": "no"
          },
          "language_code": {
            "type": "string",
            "description": "Primary language code for this CV.",
            "example": "no"
          },
          "language_codes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "All language codes available for this CV.",
            "example": [
              "no",
              "int",
              "se"
            ]
          },
          "proposal": {
            "type": "object",
            "nullable": true,
            "description": "Proposal metadata. Null for master CVs.\n",
            "example": null
          },
          "telephone": {
            "type": "string",
            "nullable": true,
            "description": "Telephone number.",
            "example": "+47 123 45 678"
          },
          "technologies": {
            "type": "array",
            "description": "Technology/skill category sections.",
            "items": {
              "$ref": "#/components/schemas/CvTechnologySection"
            }
          },
          "cv_roles": {
            "type": "array",
            "description": "CV roles.",
            "items": {
              "type": "object"
            }
          },
          "project_experiences": {
            "type": "array",
            "description": "Project experience sections.",
            "items": {
              "type": "object"
            }
          },
          "educations": {
            "type": "array",
            "description": "Education sections.",
            "items": {
              "type": "object"
            }
          },
          "certifications": {
            "type": "array",
            "description": "Certification sections.",
            "items": {
              "type": "object"
            }
          },
          "courses": {
            "type": "array",
            "description": "Course sections.",
            "items": {
              "type": "object"
            }
          },
          "blogs": {
            "type": "array",
            "description": "Blog/publication sections.",
            "items": {
              "type": "object"
            }
          },
          "custom_tags": {
            "type": "array",
            "description": "Custom tags attached to this CV. Only includes tags whose category has `can_be_used_for_cvs: true`. Sorted by tag ID.\n",
            "items": {
              "$ref": "#/components/schemas/CvCustomTag"
            }
          },
          "custom_tag_ids": {
            "type": "array",
            "description": "IDs of custom tags attached to this CV. Same filter as `custom_tags` and includes only tags from categories with `can_be_used_for_cvs: true`.\n",
            "items": {
              "type": "string"
            },
            "example": [
              "629d0dd1878f992c53183f69"
            ]
          },
          "updated_ago": {
            "type": "string",
            "description": "Always returns `\"N/A\"` via the API. This field is only meaningful in the web UI.",
            "example": "N/A"
          },
          "template_document_type": {
            "type": "string",
            "nullable": true,
            "description": "Default document template type.",
            "example": "doc"
          },
          "default_word_template_id": {
            "type": "string",
            "nullable": true,
            "example": "66d1cd708219d300454efff4"
          },
          "default_word_json_template_id": {
            "type": "string",
            "nullable": true,
            "example": null
          },
          "default_ppt_template_id": {
            "type": "string",
            "nullable": true,
            "example": "65dc8e94497f7e00456fc945"
          },
          "default_indesign_template_id": {
            "type": "string",
            "nullable": true,
            "example": "66fbe566d61e96572fe0048c"
          },
          "master_cv_id": {
            "type": "string",
            "description": "Master CV ID. Only present for proposal CVs.\n"
          },
          "highlighted_roles": {
            "type": "array",
            "description": "Starred/highlighted CV roles.",
            "items": {
              "type": "object"
            }
          },
          "office": {
            "nullable": true,
            "allOf": [
              {
                "$ref": "#/components/schemas/CvOffice"
              }
            ],
            "description": "Office (department) of the CV owner. Null if the user has no office assigned.\n"
          },
          "image": {
            "$ref": "#/components/schemas/UserImage"
          },
          "can_write": {
            "type": "boolean",
            "description": "Whether the authenticated user has write permission on this CV.\n",
            "example": true
          }
        }
      },
      "CvCustomTag": {
        "type": "object",
        "description": "Custom tag as returned in CV responses, with the parent category embedded. Only tags whose category has `can_be_used_for_cvs: true` appear in the CV's `custom_tags` array.\n",
        "required": [
          "id",
          "values",
          "external_unique_id",
          "custom_tag_category_id",
          "category_ids",
          "custom_tag_category"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the custom tag.",
            "example": "629d0dd1878f992c53183f69"
          },
          "values": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "external_unique_id": {
            "type": "string",
            "nullable": true,
            "description": "Optional identifier for linking this tag with an external system. Can be `null` or an empty string when not set.\n",
            "example": "HR.FIELD.EMP_TYPE.FULL"
          },
          "custom_tag_category_id": {
            "type": "string",
            "description": "ID of the category this tag belongs to.",
            "example": "629d0dd1878f992c53183f68"
          },
          "category_ids": {
            "type": "array",
            "description": "Array containing the parent category ID. Always a single-element array, since tags belong to exactly one category.\n",
            "items": {
              "type": "string"
            },
            "example": [
              "629d0dd1878f992c53183f68"
            ]
          },
          "custom_tag_category": {
            "$ref": "#/components/schemas/CvCustomTagCategory"
          }
        }
      },
      "CvCustomTagCategory": {
        "type": "object",
        "description": "Custom tag category as embedded in CV custom tag objects. Unlike the standalone CustomTagCategory schema, this does not include the nested `custom_tags` array.\n",
        "required": [
          "id",
          "values",
          "external_unique_id",
          "can_be_used_for_cvs",
          "can_be_used_for_references",
          "can_be_used_for_customers",
          "allow_filtering",
          "lock_for_integrations"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the custom tag category.",
            "example": "629d0dd1878f992c53183f68"
          },
          "values": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "external_unique_id": {
            "type": "string",
            "nullable": true,
            "description": "Optional identifier for linking this category with an external system. Can be `null` or an empty string when not set.\n",
            "example": "HR.FIELD.EMP_TYPE"
          },
          "can_be_used_for_cvs": {
            "type": "boolean",
            "description": "Whether tags in this category can be attached to CVs / résumés.",
            "example": true
          },
          "can_be_used_for_references": {
            "type": "boolean",
            "description": "Whether tags in this category can be attached to reference projects.",
            "example": true
          },
          "can_be_used_for_customers": {
            "type": "boolean",
            "description": "Whether tags in this category can be attached to customers.",
            "example": true
          },
          "allow_filtering": {
            "type": "boolean",
            "description": "Whether this category is available as a filter option in the UI.",
            "example": true
          },
          "lock_for_integrations": {
            "type": "boolean",
            "description": "When true, only administrators and API integrations can add or remove tags from this category.\n",
            "example": false
          }
        }
      },
      "CvOffice": {
        "type": "object",
        "description": "Office (department) as embedded in CV responses.",
        "required": [
          "id",
          "name",
          "selected",
          "default_word_template_id",
          "default_word_json_template_id",
          "default_ppt_template_id",
          "default_indesign_template_id",
          "country_id",
          "country_code",
          "override_language_code"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the office.",
            "example": "629d0dd0878f992c53183f66"
          },
          "name": {
            "type": "string",
            "description": "Office name.",
            "example": "Oslo"
          },
          "selected": {
            "type": "boolean",
            "example": false
          },
          "default_word_template_id": {
            "type": "string",
            "nullable": true,
            "example": null
          },
          "default_word_json_template_id": {
            "type": "string",
            "nullable": true,
            "example": null
          },
          "default_ppt_template_id": {
            "type": "string",
            "nullable": true,
            "example": null
          },
          "default_indesign_template_id": {
            "type": "string",
            "nullable": true,
            "example": null
          },
          "country_id": {
            "type": "string",
            "description": "ID of the country this office belongs to.",
            "example": "629d0dbc878f992c53183f65"
          },
          "country_code": {
            "type": "string",
            "description": "Country code for this office.",
            "example": "no"
          },
          "override_language_code": {
            "type": "string",
            "nullable": true,
            "description": "Language code override for this office. Null if not set.",
            "example": null
          }
        }
      },
      "CvTechnologySection": {
        "type": "object",
        "description": "A technology/skill category section within a CV.",
        "properties": {
          "category": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-04-24T12:24:00.912Z"
          },
          "disabled": {
            "type": "boolean",
            "example": true
          },
          "diverged_from_master": {
            "type": "boolean",
            "example": false
          },
          "exclude_tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "external_unique_id": {
            "type": "string",
            "nullable": true
          },
          "modifier_id": {
            "type": "string",
            "nullable": true
          },
          "order": {
            "type": "integer",
            "example": 0
          },
          "origin_id": {
            "type": "string",
            "nullable": true
          },
          "owner_updated_at": {
            "type": "string",
            "nullable": true,
            "format": "date-time"
          },
          "recently_added": {
            "type": "boolean",
            "example": false
          },
          "starred": {
            "type": "boolean",
            "example": false
          },
          "uncategorized": {
            "type": "boolean",
            "example": true
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-04-24T12:24:00.912Z"
          },
          "version": {
            "type": "integer",
            "example": 1
          }
        }
      },
      "AddTagToCvBody": {
        "type": "object",
        "required": [
          "custom_tag_category_id",
          "custom_tag_id"
        ],
        "properties": {
          "custom_tag_category_id": {
            "type": "string",
            "description": "ID of the custom tag category. Must belong to the authenticated user's company.\n",
            "example": "629d0dd1878f992c53183f68"
          },
          "custom_tag_id": {
            "type": "string",
            "description": "ID of the custom tag to attach. Must belong to the specified category.\n",
            "example": "629d0dd1878f992c53183f69"
          }
        }
      },
      "ReferenceProject": {
        "type": "object",
        "description": "A reference project with all sections. Returned by endpoints that modify reference projects (add tag, update, etc.).\n",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the reference project.",
            "example": "6878e97ca0ab68003d274eae"
          },
          "company_project_id": {
            "type": "string",
            "description": "Alias for `id`.",
            "example": "6878e97ca0ab68003d274eae"
          },
          "architect": {
            "type": "string",
            "nullable": true
          },
          "area_amt": {
            "type": "string",
            "nullable": true,
            "description": "Area amount as a string.",
            "example": "300"
          },
          "area_unit": {
            "type": "string",
            "nullable": true,
            "description": "Unit for area amount (e.g. FTE, m2).",
            "example": "FTE"
          },
          "area_anonymized": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "area_sensitivity": {
            "type": "string",
            "nullable": true,
            "example": "confidential"
          },
          "building_owner": {
            "type": "string",
            "nullable": true
          },
          "collaborating_partners": {
            "type": "string",
            "nullable": true
          },
          "company_customer_id": {
            "type": "string",
            "description": "ID of the parent reference customer.",
            "example": "646cd381a205f30f4a8dab05"
          },
          "contract_type": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2025-07-17T12:15:56.652Z"
          },
          "customer_name": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "duration_anonymized": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "duration_sensitivity": {
            "type": "string",
            "nullable": true,
            "example": "confidential"
          },
          "extent": {
            "type": "string",
            "nullable": true,
            "description": "Free-text project cost description."
          },
          "extent_amt": {
            "type": "string",
            "nullable": true,
            "example": "5000000"
          },
          "extent_currency": {
            "type": "string",
            "nullable": true,
            "description": "Currency code.",
            "example": "nok"
          },
          "extent_currency_amt_anonymized": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "extent_currency_amt_sensitivity": {
            "type": "string",
            "nullable": true,
            "example": "confidential"
          },
          "extent_hours": {
            "type": "string",
            "nullable": true
          },
          "extent_hours_new": {
            "type": "string",
            "nullable": true,
            "description": "Floating point number as string."
          },
          "extent_hours_new_anonymized": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "extent_hours_new_sensitivity": {
            "type": "string",
            "nullable": true,
            "example": "confidential"
          },
          "external_unique_id": {
            "type": "string",
            "nullable": true,
            "description": "Object ID from an external source system.",
            "example": "1000"
          },
          "location_country_code": {
            "type": "string",
            "nullable": true,
            "description": "Country code for project location.",
            "example": "bs"
          },
          "location_country_code_anonymized": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "location_country_code_sensitivity": {
            "type": "string",
            "nullable": true
          },
          "month_from": {
            "type": "string",
            "nullable": true,
            "example": ""
          },
          "month_to": {
            "type": "string",
            "nullable": true,
            "example": ""
          },
          "project_address": {
            "type": "string",
            "nullable": true,
            "example": "sesame street"
          },
          "project_address_anonymized": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "project_address_sensitivity": {
            "type": "string",
            "nullable": true
          },
          "project_description": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "project_introduction": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "project_name": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "project_name_anonymized": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "project_name_sensitivity": {
            "type": "string",
            "nullable": true
          },
          "project_notes": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "project_skills_description": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "total_extent_amt": {
            "type": "string",
            "nullable": true,
            "example": "90000"
          },
          "total_extent_currency": {
            "type": "string",
            "nullable": true,
            "example": "nok"
          },
          "total_extent_currency_amt_anonymized": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "total_extent_currency_amt_sensitivity": {
            "type": "string",
            "nullable": true,
            "example": "confidential"
          },
          "total_extent_hours": {
            "type": "string",
            "nullable": true
          },
          "total_extent_hours_anonymized": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "total_extent_hours_sensitivity": {
            "type": "string",
            "nullable": true,
            "example": "confidential"
          },
          "type": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "example": "2025-11-06T14:34:15.154Z"
          },
          "version": {
            "type": "integer",
            "example": 42
          },
          "workflow_stage": {
            "type": "string",
            "description": "Current workflow stage. One of `draft`, `ready_for_review`, `live`, or `archived`.\n",
            "example": "ready_for_review"
          },
          "year_from": {
            "type": "string",
            "nullable": true,
            "example": "2025"
          },
          "year_to": {
            "type": "string",
            "nullable": true,
            "example": "2025"
          },
          "attachments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReferenceProjectAttachment"
            }
          },
          "company_project_skills": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReferenceProjectSkill"
            }
          },
          "custom_tags": {
            "type": "array",
            "description": "Custom tags attached to this project. Only tags whose category has `can_be_used_for_references: true` appear in this array.\n",
            "items": {
              "$ref": "#/components/schemas/CustomTag"
            }
          },
          "customer_value_propositions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReferenceProjectSection"
            }
          },
          "customer_value_propositions_images": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReferenceProjectImageEntry"
            }
          },
          "customer_contacts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReferenceProjectContact"
            }
          },
          "offices": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CvOffice"
            }
          },
          "project_challenges": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReferenceProjectSection"
            }
          },
          "project_challenges_images": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReferenceProjectImageEntry"
            }
          },
          "project_introduction_images": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReferenceProjectImageEntry"
            }
          },
          "project_owners": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/User"
            }
          },
          "project_links": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReferenceProjectLink"
            }
          },
          "project_solutions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReferenceProjectSection"
            }
          },
          "project_solutions_images": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReferenceProjectImageEntry"
            }
          },
          "has_linked_project_experiences": {
            "type": "boolean",
            "description": "Whether this reference project is linked to any user CV project experiences. Only present on the GET detail endpoint.\n",
            "example": false
          },
          "custom_fields": {
            "type": "array",
            "description": "Custom field values for all company-defined custom fields. Present when `include_custom_fields=true` is set on GET endpoints, or when `custom_fields` are included in a create/update request body. In create and update responses, custom field values are returned as `null`. To retrieve the stored values, use a subsequent GET request with `include_custom_fields=true`.\n",
            "items": {
              "$ref": "#/components/schemas/ReferenceProjectCustomField"
            }
          }
        }
      },
      "ReferenceProjectSection": {
        "type": "object",
        "description": "A content section within a reference project (challenge, solution, or value proposition). All three share the same shape.\n",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for this section entry.",
            "example": "6878e97ca0ab68003d274eb4"
          },
          "reference_project_id": {
            "type": "string",
            "description": "ID of the parent reference project.",
            "example": "6878e97ca0ab68003d274eae"
          },
          "label": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "value": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "disabled": {
            "type": "boolean",
            "description": "When `true`, this entry is excluded from published references.\n",
            "example": false
          },
          "version": {
            "type": "integer",
            "example": 1
          }
        }
      },
      "ReferenceProjectSkill": {
        "type": "object",
        "description": "A skill associated with a reference project.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for this skill entry.",
            "example": "6878eb0ba0ab68003d274ec2"
          },
          "tags": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "order": {
            "type": "integer",
            "example": 0
          },
          "version": {
            "type": "integer",
            "example": 1
          }
        }
      },
      "ReferenceProjectLink": {
        "type": "object",
        "description": "An external link attached to a reference project.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for this link entry.",
            "example": "6878eb3fa0ab68003b274eae"
          },
          "label": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "url": {
            "type": "string",
            "description": "Full URL of the external link.",
            "example": "https://www.youtube.com/watch?v=BqY2VviSPNw"
          },
          "disabled": {
            "type": "boolean",
            "description": "When `true`, this link is excluded from published references.\n",
            "example": false
          },
          "version": {
            "type": "integer",
            "example": 1
          }
        }
      },
      "ReferenceProjectContact": {
        "type": "object",
        "description": "A customer contact on a reference project, with approval tracking for name, contact details, and quote.\n",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for this contact entry.",
            "example": "6878e97ca0ab68003d274eb8"
          },
          "reference_project_id": {
            "type": "string",
            "description": "ID of the parent reference project.",
            "example": "6878e97ca0ab68003d274eae"
          },
          "name": {
            "type": "string",
            "description": "Contact person's name.",
            "example": "John Doe"
          },
          "label": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "email": {
            "type": "string",
            "description": "Contact email address.",
            "example": "john.doe@example.com"
          },
          "phone": {
            "type": "string",
            "description": "Contact phone number.",
            "example": "+1234567890"
          },
          "disabled": {
            "type": "boolean",
            "description": "Whether this contact is excluded from references. When `false`, the contact is approved for use.\n",
            "example": false
          },
          "name_approved_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "example": "2025-09-11T08:22:11.000Z"
          },
          "name_approver_id": {
            "type": "string",
            "nullable": true,
            "example": "629d0dd0878f992c53183f67"
          },
          "name_approver_name": {
            "type": "string",
            "nullable": true,
            "example": "Jane Smith"
          },
          "hide_contact_details": {
            "type": "boolean",
            "description": "Whether contact details are hidden. When `false`, the customer's contact details are approved for use.\n",
            "example": false
          },
          "contact_details_approved_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "example": "2025-09-11T08:22:21.000Z"
          },
          "contact_details_approver_id": {
            "type": "string",
            "nullable": true,
            "example": "629d0dd0878f992c53183f67"
          },
          "contact_details_approver_name": {
            "type": "string",
            "nullable": true,
            "example": "Jane Smith"
          },
          "hide_quote": {
            "type": "boolean",
            "description": "Whether the quote is hidden. When `false`, the quote is approved for use.\n",
            "example": true
          },
          "quote": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "quote_approved_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "example": null
          },
          "quote_approver_id": {
            "type": "string",
            "nullable": true,
            "example": null
          },
          "quote_approver_name": {
            "type": "string",
            "nullable": true,
            "example": null
          },
          "notes": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "order": {
            "type": "integer",
            "example": 0
          },
          "version": {
            "type": "integer",
            "example": 6
          }
        }
      },
      "ReferenceProjectImageEntry": {
        "type": "object",
        "description": "An image entry within a reference project section (challenge, solution, introduction, or value proposition images).\n",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for this image entry.",
            "example": "6878eb00a0ab68003d274ec0"
          },
          "image_id": {
            "type": "string",
            "description": "ID of the underlying image resource.",
            "example": "6878eaffc3734fb8ad15a9fc"
          },
          "caption": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "order": {
            "type": "integer",
            "example": 0
          },
          "image": {
            "$ref": "#/components/schemas/ReferenceProjectImage"
          }
        }
      },
      "ReferenceProjectImage": {
        "type": "object",
        "description": "Image with multiple size variants. URLs are temporary links that expire after approximately 10 minutes.\n",
        "properties": {
          "id": {
            "type": "string",
            "example": "6878eaffc3734fb8ad15a9fc"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Original image URL (temporary signed link)."
          },
          "scaled": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "format": "uri"
              }
            }
          },
          "for_templates": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "format": "uri"
              }
            }
          },
          "for_projects": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "format": "uri"
              }
            }
          },
          "thumb": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "format": "uri"
              }
            }
          },
          "fit_thumb": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "format": "uri"
              }
            }
          },
          "small_thumb": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      },
      "ReferenceProjectAttachment": {
        "type": "object",
        "description": "A file attachment on a reference project.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for this attachment.",
            "example": "63f5f235a1e8f70fd3723b63"
          },
          "label": {
            "type": "string",
            "description": "Display label for the attachment.",
            "example": "A thing"
          },
          "file": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "format": "uri",
                "description": "Temporary signed download URL. Expires after approximately 10 minutes."
              },
              "extension": {
                "type": "string",
                "description": "File extension (without dot).",
                "example": "docx"
              }
            }
          }
        }
      },
      "ReferenceProjectCustomField": {
        "type": "object",
        "description": "A custom field value on a reference project. The shape varies by `type`, and different types include different value fields. All types share `name`, `sensitivity`, `anonymized`, and `type`.\n",
        "properties": {
          "name": {
            "type": "string",
            "description": "Custom field name.",
            "example": "phase_one_cost"
          },
          "type": {
            "type": "string",
            "description": "Custom field type. Determines which value fields are present.\n",
            "enum": [
              "currency_amount",
              "numeric",
              "quantity",
              "single_select",
              "year_month_range"
            ],
            "example": "currency_amount"
          },
          "sensitivity": {
            "type": "string",
            "nullable": true,
            "description": "Sensitivity level. One of `anonymized`, `confidential`, or null.\n",
            "example": null
          },
          "anonymized": {
            "$ref": "#/components/schemas/MultilingualValues"
          },
          "value": {
            "nullable": true,
            "description": "Value field. Present for `numeric` and `single_select` types. For `numeric`, this is a string (e.g. `\"12112.0\"`) or null. For `single_select`, this is an object with `id`, `external_unique_id`, and `name` (multilingual) properties.\n",
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "external_unique_id": {
                    "type": "string",
                    "nullable": true
                  },
                  "name": {
                    "$ref": "#/components/schemas/MultilingualValues"
                  }
                }
              }
            ],
            "example": null
          },
          "amount": {
            "nullable": true,
            "description": "Amount field. Present for `currency_amount` and `quantity` types. For `currency_amount`, this is an integer. For `quantity`, this is a string (e.g. `\"56.0\"`).\n",
            "oneOf": [
              {
                "type": "integer"
              },
              {
                "type": "string"
              }
            ],
            "example": null
          },
          "currency": {
            "type": "string",
            "nullable": true,
            "description": "Currency code. Present for `currency_amount` type only.\n",
            "example": null
          },
          "unit": {
            "type": "string",
            "nullable": true,
            "description": "Unit of measurement. Present for `quantity` type only.\n",
            "example": null
          },
          "from": {
            "type": "string",
            "nullable": true,
            "description": "Range start (year-month). Present for `year_month_range` type only.\n",
            "example": null
          },
          "to": {
            "type": "string",
            "nullable": true,
            "description": "Range end (year-month). Present for `year_month_range` type only.\n",
            "example": null
          }
        }
      },
      "ReferenceProjectCreateBody": {
        "type": "object",
        "required": [
          "company_project"
        ],
        "properties": {
          "company_project": {
            "type": "object",
            "description": "Project fields. The wrapper must contain at least one field. Submitting an empty wrapper (`\"company_project\": {}`) returns 400. All individual fields are optional and can be omitted; additional details such as challenges, solutions, contacts, owners, and tags are added in subsequent requests after creating the initial project.\n",
            "properties": {
              "project_name": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Multilingual project name. Keys are language codes in legacy format by default (e.g. `int`, `no`, `se`), or ISO 639-1 when `use_legacy_codes=false`. Any company language codes not provided are auto-populated with the first non-empty value.\n",
                "example": {
                  "int": "Project name"
                }
              },
              "project_description": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Multilingual project description.",
                "example": {
                  "int": "Official project description for CVs",
                  "no": "Offisiell prosjektbeskrivelse for CV-er"
                }
              },
              "project_introduction": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Multilingual long text field for project introduction.",
                "example": {
                  "int": "Project introduction text block"
                }
              },
              "project_notes": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Multilingual project notes.",
                "example": {
                  "int": "Project notes long text field"
                }
              },
              "project_skills_description": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Multilingual long form description of skills used or acquired during the project.\n",
                "example": {
                  "int": "Skills used during project."
                }
              },
              "type": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Multilingual project type.",
                "example": {
                  "int": "Consulting"
                }
              },
              "contract_type": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Multilingual contract type.",
                "example": {
                  "int": "Fixed Price"
                }
              },
              "external_unique_id": {
                "type": "string",
                "description": "Object ID from an external source system.",
                "example": "SAP-1234"
              },
              "architect": {
                "type": "string",
                "description": "Architect info.",
                "example": "4"
              },
              "area_amt": {
                "type": "string",
                "description": "Area amount as a numeric string.",
                "example": "2564"
              },
              "area_unit": {
                "type": "string",
                "description": "Unit for area amount. Must be one of the accepted unit values (e.g. `FTE`).\n",
                "example": "FTE"
              },
              "building_owner": {
                "type": "string",
                "example": "Building owner"
              },
              "collaborating_partners": {
                "type": "string",
                "example": "Royal Dutch Shell PLC - 302964 - 60%"
              },
              "extent": {
                "type": "string",
                "description": "Project cost as free text.",
                "example": "Project cost (free text)"
              },
              "extent_amt": {
                "type": "string",
                "description": "Extent amount as a numeric string (validated as integer).",
                "example": "2354"
              },
              "extent_currency": {
                "type": "string",
                "description": "Currency code. Stored and returned in lowercase.\n",
                "example": "eur"
              },
              "extent_hours_new": {
                "type": "string",
                "description": "Floating point number as string.",
                "example": "2456.44"
              },
              "total_extent_amt": {
                "type": "string",
                "description": "Total extent amount as a numeric string.",
                "example": "54000000"
              },
              "total_extent_currency": {
                "type": "string",
                "description": "Currency code for total extent. Stored and returned in lowercase.\n",
                "example": "nok"
              },
              "total_extent_hours": {
                "type": "string",
                "description": "Total hours as a numeric string.",
                "example": "6.564577"
              },
              "location_country_code": {
                "type": "string",
                "description": "ISO 3166-1 alpha-2 country code. Empty string is treated as null.\n",
                "example": "pt"
              },
              "month_from": {
                "type": "string",
                "description": "Start month (1–12).",
                "example": "9"
              },
              "year_from": {
                "type": "string",
                "description": "Start year.",
                "example": "2020"
              },
              "month_to": {
                "type": "string",
                "description": "End month (1–12).",
                "example": "09"
              },
              "year_to": {
                "type": "string",
                "description": "End year.",
                "example": "2022"
              },
              "project_address": {
                "type": "string",
                "example": "Bergen"
              },
              "workflow_stage": {
                "type": "string",
                "description": "Workflow stage for the project. Defaults to `draft` if omitted.\n",
                "enum": [
                  "draft",
                  "ready_for_review",
                  "live",
                  "archived"
                ],
                "default": "draft"
              },
              "office_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Office IDs to assign to the project. Validated against the company's offices; invalid IDs return 400. Note: the authenticated user's default office is automatically assigned even when this field is omitted.\n",
                "example": [
                  "629d0dd0878f992c53183f66"
                ]
              },
              "custom_fields": {
                "type": "array",
                "description": "Custom field values to set on the project. Each entry must reference an existing custom field definition by `name`. See `CustomFieldInput` for permitted parameters per field type.\n",
                "items": {
                  "$ref": "#/components/schemas/CustomFieldInput"
                }
              },
              "area_sensitivity": {
                "type": "string",
                "enum": [
                  "anonymized",
                  "confidential"
                ]
              },
              "duration_sensitivity": {
                "type": "string",
                "enum": [
                  "anonymized",
                  "confidential"
                ]
              },
              "extent_currency_amt_sensitivity": {
                "type": "string",
                "enum": [
                  "anonymized",
                  "confidential"
                ]
              },
              "extent_hours_new_sensitivity": {
                "type": "string",
                "enum": [
                  "anonymized",
                  "confidential"
                ]
              },
              "location_country_code_sensitivity": {
                "type": "string",
                "enum": [
                  "anonymized",
                  "confidential"
                ]
              },
              "project_address_sensitivity": {
                "type": "string",
                "enum": [
                  "anonymized",
                  "confidential"
                ]
              },
              "project_name_sensitivity": {
                "type": "string",
                "enum": [
                  "anonymized",
                  "confidential"
                ]
              },
              "total_extent_currency_amt_sensitivity": {
                "type": "string",
                "enum": [
                  "anonymized",
                  "confidential"
                ]
              },
              "total_extent_hours_sensitivity": {
                "type": "string",
                "enum": [
                  "anonymized",
                  "confidential"
                ]
              },
              "area_anonymized": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Multilingual anonymized alternative for area."
              },
              "duration_anonymized": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              },
              "extent_currency_amt_anonymized": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              },
              "extent_hours_new_anonymized": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              },
              "location_country_code_anonymized": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              },
              "project_address_anonymized": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              },
              "project_name_anonymized": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              },
              "total_extent_currency_amt_anonymized": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              },
              "total_extent_hours_anonymized": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "ReferenceProjectUpdateBody": {
        "type": "object",
        "required": [
          "company_project"
        ],
        "properties": {
          "company_project": {
            "type": "object",
            "description": "Project fields to update. The wrapper must contain at least one field. Submitting an empty wrapper (`\"company_project\": {}`) returns 400. Only the fields you provide are changed; omitted fields retain their current values. Multilingual fields (objects keyed by language code) replace the entire value, so partial language-key merges are not supported.\n",
            "properties": {
              "project_name": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Multilingual project name. Keys are language codes in legacy format by default (e.g. `int`, `no`, `se`), or ISO 639-1 when `use_legacy_codes=false`. Replaces the entire multilingual object.\n",
                "example": {
                  "int": "Project name"
                }
              },
              "project_description": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Multilingual project description.",
                "example": {
                  "int": "Official project description for CVs",
                  "no": "Offisiell prosjektbeskrivelse for CV-er"
                }
              },
              "project_introduction": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Multilingual long text field for project introduction.",
                "example": {
                  "int": "Project introduction text block"
                }
              },
              "project_notes": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Multilingual project notes.",
                "example": {
                  "int": "Project notes long text field"
                }
              },
              "project_skills_description": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Multilingual long form description of skills used or acquired during the project.\n",
                "example": {
                  "int": "Skills used during project."
                }
              },
              "type": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Multilingual project type.",
                "example": {
                  "int": "Consulting"
                }
              },
              "contract_type": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Multilingual contract type.",
                "example": {
                  "int": "Fixed Price"
                }
              },
              "external_unique_id": {
                "type": "string",
                "description": "Object ID from an external source system.",
                "example": "SAP-1234"
              },
              "architect": {
                "type": "string",
                "description": "Architect info.",
                "example": "4"
              },
              "area_amt": {
                "type": "string",
                "description": "Area amount as a numeric string.",
                "example": "2564"
              },
              "area_unit": {
                "type": "string",
                "description": "Unit for area amount. Validated against an allowed list of values.\n",
                "example": "FTE"
              },
              "building_owner": {
                "type": "string",
                "example": "Building owner"
              },
              "collaborating_partners": {
                "type": "string",
                "example": "Royal Dutch Shell PLC - 302964 - 60%"
              },
              "extent": {
                "type": "string",
                "description": "Project cost as free text.",
                "example": "Project cost (free text)"
              },
              "extent_amt": {
                "type": "string",
                "description": "Extent amount as a numeric string (validated as integer).",
                "example": "2354"
              },
              "extent_currency": {
                "type": "string",
                "description": "Currency code. Stored and returned in lowercase.\n",
                "example": "eur"
              },
              "extent_hours_new": {
                "type": "string",
                "description": "Floating point number as string.",
                "example": "2456.44"
              },
              "total_extent_amt": {
                "type": "string",
                "description": "Total extent amount as a numeric string.",
                "example": "54000000"
              },
              "total_extent_currency": {
                "type": "string",
                "description": "Currency code for total extent. Stored and returned in lowercase.\n",
                "example": "nok"
              },
              "total_extent_hours": {
                "type": "string",
                "description": "Total hours as a numeric string.",
                "example": "6.564577"
              },
              "location_country_code": {
                "type": "string",
                "description": "ISO 3166-1 alpha-2 country code. Empty string is treated as null.\n",
                "example": "pt"
              },
              "month_from": {
                "type": "string",
                "description": "Start month (1–12).",
                "example": "9"
              },
              "year_from": {
                "type": "string",
                "description": "Start year.",
                "example": "2020"
              },
              "month_to": {
                "type": "string",
                "description": "End month (1–12).",
                "example": "09"
              },
              "year_to": {
                "type": "string",
                "description": "End year.",
                "example": "2022"
              },
              "project_address": {
                "type": "string",
                "example": "Bergen"
              },
              "workflow_stage": {
                "type": "string",
                "description": "Workflow stage for the project. Setting this to `live` or `archived` requires the `publish` permission. Project owners with only the `consultant` or `limited_access` role can update other fields but cannot publish or archive.\n",
                "enum": [
                  "draft",
                  "ready_for_review",
                  "live",
                  "archived"
                ]
              },
              "custom_fields": {
                "type": "array",
                "description": "Custom field values to create or update on the project. Include only the custom fields you want to set; omitted fields retain their current values. Each entry must reference an existing custom field definition by `name`. See `CustomFieldInput` for permitted parameters per type.\n",
                "items": {
                  "$ref": "#/components/schemas/CustomFieldInput"
                }
              },
              "area_sensitivity": {
                "type": "string",
                "enum": [
                  "anonymized",
                  "confidential"
                ]
              },
              "duration_sensitivity": {
                "type": "string",
                "enum": [
                  "anonymized",
                  "confidential"
                ]
              },
              "extent_currency_amt_sensitivity": {
                "type": "string",
                "enum": [
                  "anonymized",
                  "confidential"
                ]
              },
              "extent_hours_new_sensitivity": {
                "type": "string",
                "enum": [
                  "anonymized",
                  "confidential"
                ]
              },
              "location_country_code_sensitivity": {
                "type": "string",
                "enum": [
                  "anonymized",
                  "confidential"
                ]
              },
              "project_address_sensitivity": {
                "type": "string",
                "enum": [
                  "anonymized",
                  "confidential"
                ]
              },
              "project_name_sensitivity": {
                "type": "string",
                "enum": [
                  "anonymized",
                  "confidential"
                ]
              },
              "total_extent_currency_amt_sensitivity": {
                "type": "string",
                "enum": [
                  "anonymized",
                  "confidential"
                ]
              },
              "total_extent_hours_sensitivity": {
                "type": "string",
                "enum": [
                  "anonymized",
                  "confidential"
                ]
              },
              "area_anonymized": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Multilingual anonymized alternative for area."
              },
              "duration_anonymized": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              },
              "extent_currency_amt_anonymized": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              },
              "extent_hours_new_anonymized": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              },
              "location_country_code_anonymized": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              },
              "project_address_anonymized": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              },
              "project_name_anonymized": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              },
              "total_extent_currency_amt_anonymized": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              },
              "total_extent_hours_anonymized": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "ReferenceProjectSkillCreateBody": {
        "type": "object",
        "description": "Request body for adding a skill to a reference project.\n",
        "properties": {
          "company_project_skill": {
            "type": "object",
            "description": "Wrapper object containing the skill fields.",
            "properties": {
              "tags": {
                "$ref": "#/components/schemas/MultilingualValues"
              },
              "order": {
                "type": "integer",
                "description": "Controls display ordering. Default is 0.",
                "example": 0
              }
            }
          }
        }
      },
      "ReferenceProjectSkillUpdateBody": {
        "type": "object",
        "description": "Request body for updating a skill on a reference project. Supports partial updates; only the fields provided are changed, and omitted fields retain their current value. Note that `tags` overwrites the entire multilingual object (individual language keys cannot be patched).\n",
        "properties": {
          "company_project_skill": {
            "type": "object",
            "description": "Wrapper object containing the skill fields to update.",
            "properties": {
              "tags": {
                "$ref": "#/components/schemas/MultilingualValues"
              },
              "order": {
                "type": "integer",
                "description": "Controls display ordering.",
                "example": 3
              }
            }
          }
        }
      },
      "ReferenceProjectContactCreateBody": {
        "type": "object",
        "description": "Request body for adding a customer contact to a reference project.\n",
        "properties": {
          "customer_contact": {
            "type": "object",
            "description": "Wrapper object containing the contact fields.",
            "properties": {
              "name": {
                "type": "string",
                "description": "Contact person's name.",
                "example": "John Doe"
              },
              "label": {
                "$ref": "#/components/schemas/MultilingualValues"
              },
              "email": {
                "type": "string",
                "description": "Contact email address.",
                "example": "john.doe@example.com"
              },
              "phone": {
                "type": "string",
                "description": "Contact phone number.",
                "example": "+1234567890"
              },
              "disabled": {
                "type": "boolean",
                "description": "Whether this contact is excluded from references. When `false`, the contact is approved for use. Defaults to `true`.\n",
                "default": true,
                "example": true
              },
              "hide_contact_details": {
                "type": "boolean",
                "description": "Whether contact details are hidden. When `false`, the customer's contact details are approved for use. Defaults to `true`.\n",
                "default": true,
                "example": true
              },
              "hide_quote": {
                "type": "boolean",
                "description": "Whether the quote is hidden. When `false`, the quote is approved for use. Defaults to `true`.\n",
                "default": true,
                "example": true
              },
              "quote": {
                "$ref": "#/components/schemas/MultilingualValues"
              },
              "notes": {
                "$ref": "#/components/schemas/MultilingualValues"
              }
            }
          }
        }
      },
      "ReferenceProjectContactUpdateBody": {
        "type": "object",
        "description": "Request body for updating a customer contact on a reference project. Supports partial updates; only the fields provided are changed, and omitted fields retain their current value. Multilingual fields (`label`, `quote`, `notes`) overwrite the entire language object, so individual language keys cannot be patched independently. At least one field must be provided in the wrapper.\n",
        "properties": {
          "customer_contact": {
            "type": "object",
            "description": "Wrapper object containing the contact fields to update.",
            "properties": {
              "name": {
                "type": "string",
                "description": "Contact person's name.",
                "example": "John Doe"
              },
              "label": {
                "$ref": "#/components/schemas/MultilingualValues"
              },
              "email": {
                "type": "string",
                "description": "Contact email address.",
                "example": "john.doe@example.com"
              },
              "phone": {
                "type": "string",
                "description": "Contact phone number.",
                "example": "+1234567890"
              },
              "disabled": {
                "type": "boolean",
                "description": "Whether this contact is excluded from references. When `false`, the contact is approved for use. Changing from `true` to `false` records the approver's identity and timestamp on `name_approver_*` fields.\n",
                "example": false
              },
              "hide_contact_details": {
                "type": "boolean",
                "description": "Whether contact details are hidden. When `false`, the customer's contact details are approved for use. Changing from `true` to `false` records the approver's identity and timestamp on `contact_details_approver_*` fields.\n",
                "example": false
              },
              "hide_quote": {
                "type": "boolean",
                "description": "Whether the quote is hidden. When `false`, the quote is approved for use. Changing from `true` to `false` records the approver's identity and timestamp on `quote_approver_*` fields.\n",
                "example": false
              },
              "quote": {
                "$ref": "#/components/schemas/MultilingualValues"
              },
              "notes": {
                "$ref": "#/components/schemas/MultilingualValues"
              }
            }
          }
        }
      },
      "ProjectDuplicateError": {
        "type": "object",
        "required": [
          "error",
          "duplicate_project_ids"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable error message. The message is always in English: \"More than one project found when looking up by external_unique_id\".\n",
            "example": "More than one project found when looking up by external_unique_id"
          },
          "duplicate_project_ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "IDs of the projects that share the same `external_unique_id` within the account.\n",
            "example": [
              "629d0e34878f992c531841c2",
              "629d0e34878f992c531841c3"
            ]
          }
        }
      },
      "ValidationMessageError": {
        "type": "object",
        "required": [
          "valid",
          "message"
        ],
        "properties": {
          "valid": {
            "type": "boolean",
            "description": "Always `false` for validation errors.",
            "example": false
          },
          "message": {
            "type": "string",
            "description": "Human-readable error message describing the validation failure.\n",
            "example": "One or more invalid office_ids used"
          }
        }
      },
      "AddProjectOwnersBody": {
        "type": "object",
        "required": [
          "user_ids"
        ],
        "properties": {
          "user_ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Flowcase user IDs to add as project owners. All users must exist in the same company as the reference project. To find user IDs, use the Find Users endpoint.\n",
            "example": [
              "69eb60e04e90c9ebbdc6edbb"
            ]
          }
        }
      },
      "AddOfficeBody": {
        "type": "object",
        "required": [
          "country_id",
          "office_id"
        ],
        "properties": {
          "country_id": {
            "type": "string",
            "description": "ID of the country the office belongs to. Must be a country in the authenticated user's company. Use the Countries and Departments API to look up country IDs.\n",
            "example": "64023c9f47db6bbadf29cde8"
          },
          "office_id": {
            "type": "string",
            "description": "ID of the office to add to the reference project. The office must belong to the country identified by `country_id`; if it belongs to a different country (or does not exist), the request returns 404.\n",
            "example": "64023d01441b770f46ad5daf"
          }
        }
      },
      "ForbiddenError": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable error description.",
            "example": "Forbidden"
          }
        }
      },
      "UnprocessableEntityError": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable error description. Typically the HTTP status reason phrase.\n",
            "example": "Unprocessable Entity"
          },
          "details": {
            "type": "array",
            "description": "Validation messages describing why the request was rejected. Message language depends on the account's configured locale.\n",
            "items": {
              "type": "string"
            },
            "example": [
              "Email has already been taken"
            ]
          }
        }
      },
      "SetCustomTagsTag": {
        "type": "object",
        "description": "A tag in its category. Give either `id` or `external_unique_id`, not both.\n",
        "properties": {
          "id": {
            "type": "string",
            "description": "ID of the custom tag.",
            "example": "64ba9f0f8e11ef0f48cc076b"
          },
          "external_unique_id": {
            "type": "string",
            "description": "External unique ID of the custom tag within its category.",
            "example": "HR.FIELD.EMP_TYPE.FULL"
          },
          "values": {
            "type": "object",
            "description": "The tag name per language code. Used only to create a missing tag with `create_missing_tags`, and then required. Keys are legacy language codes unless `use_legacy_codes=false`. Existing tags are not renamed, but `values` is checked on every request, so an unknown language code is a `422` even when the tag exists.\n",
            "additionalProperties": {
              "type": "string"
            },
            "example": {
              "int": "Full time employee",
              "no": "Fast ansatt"
            }
          }
        }
      },
      "SetCustomTagsCategory": {
        "type": "object",
        "description": "A category and the tags it should hold. Give either `id` or `external_unique_id`, not both.\n",
        "required": [
          "custom_tags"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "ID of the custom tag category.",
            "example": "64ba9d878e11ef0f45cc0768"
          },
          "external_unique_id": {
            "type": "string",
            "description": "External unique ID of the custom tag category.",
            "example": "HR.FIELD.EMP_TYPE"
          },
          "custom_tags": {
            "type": "array",
            "description": "The tags the category should hold. An empty array removes every tag in the category.\n",
            "items": {
              "$ref": "#/components/schemas/SetCustomTagsTag"
            }
          }
        }
      },
      "SetCustomTagsBody": {
        "type": "object",
        "required": [
          "categories"
        ],
        "properties": {
          "categories": {
            "type": "array",
            "description": "The categories to set. Each one ends up with exactly the tags it lists. Categories left out keep their tags.\n",
            "items": {
              "$ref": "#/components/schemas/SetCustomTagsCategory"
            }
          },
          "create_missing_tags": {
            "type": "boolean",
            "default": false,
            "description": "Create tags that are given by `external_unique_id` and do not exist in their category yet, using their `values`. Needs the `internationalmanager` role, whether or not any tag is missing.\n"
          }
        }
      },
      "ConflictError": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "example": "Conflict"
          },
          "details": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "A concurrent request changed the same custom tags. The request is safe to retry."
            ]
          }
        }
      },
      "CustomFieldInput": {
        "type": "object",
        "description": "Custom field value to set on a reference project when creating or updating via the inline reference project API. The `name` field is always required. Which other fields to include depends on the custom field definition's type, so see each property description for details. Unknown `name` values return 404. The `value_id` parameter is not accepted through this endpoint.\n",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Required for all types. The `field_name` from the custom field definition. Must match an existing definition for the company; unknown names return 404.\n",
            "example": "phase_one_cost"
          },
          "value": {
            "type": "string",
            "nullable": true,
            "description": "Used for `numeric` and `single_select` types. For `numeric`, pass a numeric string (e.g. `\"1200\"`). The API stores and returns it as a decimal string like `\"1200.0\"`. For `single_select`, pass the option's `external_unique_id`, not the option's UUID (`id`) and not the display name. Invalid `external_unique_id` values return 422.\n\nPass `null` to clear a `single_select` value. Clearing it with `value_id: null` instead returns 422.\n",
            "example": "1200"
          },
          "amount": {
            "description": "Used for `currency_amount` and `quantity` types. For `currency_amount`, pass an integer, which is stored and returned as an integer (e.g. `2500000`). For `quantity`, pass a numeric string, which is stored and returned as a decimal string (e.g. `\"350.0\"`).\n",
            "example": 2500000
          },
          "unit": {
            "type": "string",
            "description": "Used for `quantity` type only. Optional unit of measurement. Must be one of the supported unit codes (e.g. `\"m^2\"`, `\"kWh\"`, `\"FTE\"`, `\"kg\"`). Invalid values return 422.\n",
            "example": "m^2"
          },
          "currency": {
            "type": "string",
            "description": "Used for `currency_amount` type only. Must be lowercase (e.g. `\"nok\"`, `\"eur\"`). Uppercase codes return 422.\n",
            "example": "nok"
          },
          "from": {
            "type": "string",
            "description": "Used for `year_month_range` type only. Range start in `YYYY-MM` format.\n",
            "example": "2024-01"
          },
          "to": {
            "type": "string",
            "description": "Used for `year_month_range` type only. Range end in `YYYY-MM` format.\n",
            "example": "2025-06"
          },
          "sensitivity": {
            "type": "string",
            "description": "Optional for all types. Controls field visibility.\n",
            "enum": [
              "anonymized",
              "confidential"
            ]
          },
          "anonymized": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Optional for all types. Multilingual anonymized display values. Keys are language codes (legacy codes by default, or ISO 639-1 when `use_legacy_codes=false`).\n",
            "example": {
              "int": "~500 hours"
            }
          }
        }
      },
      "SyncProjectOwnersByEmailBody": {
        "type": "object",
        "required": [
          "emails"
        ],
        "properties": {
          "emails": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of user emails to sync as project owners. Emails are normalised before lookup: lowercased, whitespace-trimmed, blank entries dropped, and duplicates removed. Every remaining email must resolve to an active or deactivated user in the authenticated company — unknown emails cause the entire request to fail with `422 Unprocessable Entity` (no partial sync).\n",
            "example": [
              "alice@example.com",
              "bob@example.com"
            ]
          },
          "replace": {
            "type": "boolean",
            "default": false,
            "description": "Controls sync semantics. When `false` (default), the provided emails are merged with the project's existing owners (set union) — no existing owners are removed. When `true`, the resulting owners list is exactly the resolved users from `emails`; any current owners not present in the new list are removed. The resulting owners list must contain at least one user — sending `replace: true` with an empty (or all-blank) `emails` array returns `422 Unprocessable Entity`.\n",
            "example": false
          }
        }
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key authentication via the Authorization header. Send as: `Authorization: Bearer <your-api-key>`. The API also accepts `Authorization: Token token=\"<your-api-key>\"`.\n"
      }
    },
    "responses": {
      "RateLimited": {
        "description": "Rate limit exceeded for the API key or the account. Wait for the number of seconds in the `Retry-After` header, then retry.\n"
      }
    }
  }
}