--- title: "Yuki Platform API Prod" url: "https://developer.yukisoftware.com/apis/yuki-platform-api-prod-1/versions/9cdc452d-fd77-4e06-8797-f61e76134ec9" --- # Yuki Platform API Prod OpenAPI specification document. ```json {"openapi":"3.0.0","info":{"title":"Yuki Platform API Prod","description":"Unified API specification for all Yuki Platform services. This specification includes 5 APIs with 15 total endpoints.","version":"1.0.77"},"servers":[{"url":"https://apirest.yukiworks.be/api/v1"}],"paths":{"/domains/{domain-id}/companies/{company-id}":{"get":{"x-environments":["development","pilot","production"],"x-portal-visibility":["internal","trusted","prod"],"x-required-roles":[{"any-of":["AccountantManagement","Accountant"],"scope":"portal"}],"summary":"Get Company by ID","description":"Retrieves detailed information about a specific company using its unique identifier. You should have the **openid** and **yukiapi:domain:companies:read** scopes to access this endpoint.\n\n\n\n**Authorization**\n\nCalled with a **Portal User** token - an employee of an accounting portal.\n\nThe caller must hold at least one of these roles in the portal: `AccountantManagement`, `Accountant`.\n\n","operationId":"getCompanyById","tags":["Company"],"parameters":[{"$ref":"#/components/parameters/AuthorizationHeader"},{"$ref":"#/components/parameters/DomainIdPath"},{"$ref":"#/components/parameters/CompanyIdPath"}],"security":[{"vismaConnectPortalUser":["openid","yukiapi:domain:companies:read"]}],"responses":{"200":{"$ref":"#/components/responses/GetCompanyResponse"},"400":{"$ref":"#/components/responses/BadRequestResponse"},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}}},"put":{"x-environments":["development","pilot","production"],"x-portal-visibility":["internal","trusted","prod"],"x-required-roles":[{"any-of":["AccountantManagement","Accountant"],"scope":"portal"}],"summary":"Update Company","description":"This endpoint allows the modification of an existing company's details. Ensure you have the necessary permissions before attempting to update a company. You should have the **openid** and **yukiapi:domain:companies:update** scopes to access this endpoint.\n\n\n\n**Authorization**\n\nCalled with a **Portal User** token - an employee of an accounting portal.\n\nThe caller must hold at least one of these roles in the portal: `AccountantManagement`, `Accountant`.\n\n","operationId":"updateCompany","tags":["Company"],"parameters":[{"$ref":"#/components/parameters/AuthorizationHeader"},{"$ref":"#/components/parameters/DomainIdPath"},{"$ref":"#/components/parameters/CompanyIdPath"}],"security":[{"vismaConnectPortalUser":["openid","yukiapi:domain:companies:update"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCompany"}}}},"responses":{"204":{"description":"Company updated successfully."},"400":{"$ref":"#/components/responses/BadRequestResponse"},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}}}},"/domains/{domain-id}/companies/{company-id}/settings/peppol":{"patch":{"x-environments":["development","pilot","production"],"x-portal-visibility":["internal","trusted","prod"],"x-required-roles":[{"any-of":["AccountantManagement","Accountant"],"scope":"portal","note":"Checked before any Peppol eligibility check, so a caller who lacks these roles gets 403 rather than a 422 about Peppol."}],"summary":"Patch Company Peppol Settings","description":"Partially updates a company's Peppol settings, registering the company on the Peppol network, updating its registration, or removing it when both flags are set to false. You should have the **openid** and **yukiapi:domain:companies:update** scopes to access this endpoint - the gateway requires both together. Peppol must be enabled for the portal and licensed for the company's domain, and sending over Peppol is only possible with a Small bundle or higher. A request that asks for more than the portal or the domain is entitled to is rejected with 422, not with a permissions error - errorCode peppol:portal_not_enabled when Peppol is not enabled for the portal, peppol:domain_not_eligible when the company's domain is not licensed for Peppol, and peppol:sending_not_eligible when enableSending is requested for a domain that may receive over Peppol but not send.\n\n\n\n**Authorization**\n\nCalled with a **Portal User** token - an employee of an accounting portal.\n\nThe caller must hold at least one of these roles in the portal: `AccountantManagement`, `Accountant`.\n\nChecked before any Peppol eligibility check, so a caller who lacks these roles gets 403 rather than a 422 about Peppol.\n\n","operationId":"patchCompanyPeppolSettings","tags":["Company"],"parameters":[{"$ref":"#/components/parameters/AuthorizationHeader"},{"$ref":"#/components/parameters/DomainIdPath"},{"$ref":"#/components/parameters/CompanyIdPath"}],"security":[{"vismaConnectPortalUser":["openid","yukiapi:domain:companies:update"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchPeppolSettingsRequest"}}}},"responses":{"204":{"description":"Company Peppol settings patched successfully."},"400":{"$ref":"#/components/responses/BadRequestResponse"},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"409":{"$ref":"#/components/responses/ConflictResponse"},"422":{"$ref":"#/components/responses/UnprocessableEntityResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"},"502":{"$ref":"#/components/responses/BadGatewayResponse"}}}},"/domains/{domain-id}/companies":{"get":{"x-environments":["development","pilot","production"],"x-portal-visibility":["internal","trusted","prod"],"x-required-roles":[{"any-of":["AccountantManagement","Accountant"],"scope":"portal"}],"summary":"Get All Companies","description":"Retrieves a paginated list of all companies within the specified domain. Use offset and limit parameters for pagination through large result sets. You should have the **openid** and **yukiapi:domain:companies:read** scopes to access this endpoint.\n\n\n\n**Authorization**\n\nCalled with a **Portal User** token - an employee of an accounting portal.\n\nThe caller must hold at least one of these roles in the portal: `AccountantManagement`, `Accountant`.\n\n","operationId":"getAllCompanies","tags":["Company"],"parameters":[{"$ref":"#/components/parameters/AuthorizationHeader"},{"$ref":"#/components/parameters/DomainIdPath"},{"$ref":"#/components/parameters/OffsetQuery"},{"$ref":"#/components/parameters/LimitQuery"}],"security":[{"vismaConnectPortalUser":["openid","yukiapi:domain:companies:read"]}],"responses":{"200":{"$ref":"#/components/responses/GetCompanyPagedResponse"},"400":{"$ref":"#/components/responses/BadRequestResponse"},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}}}},"/portals/{portal-id}/domains":{"post":{"x-environments":["development","pilot","production"],"x-portal-visibility":["internal","trusted","prod"],"x-required-roles":[{"any-of":["AccountantManagement","Accountant"],"scope":"portal"}],"summary":"Create Domain","description":"This endpoint allows the creation of a new domain. Ensure you have the necessary permissions before attempting to create a domain. You should have the **openid** scope together with one of **yukiapi:domain:domains:create** or **yukiapi:domain:domains:write** to access this endpoint. The portal must be registered as a Yuki Partner and be allowed to create new administrations; otherwise the request is rejected with 403. Returns domains:already_exists (409) if a domain with that name already exists or the name is reserved, domains:validation_failed (400) if the domain cannot be created from the data supplied, or domains:creation_failed (500) if the domain and its default administration could not be created.\n\n\n\n**Authorization**\n\nCalled with a **Portal User** token - an employee of an accounting portal.\n\nThe caller must hold at least one of these roles in the portal: `AccountantManagement`, `Accountant`.\n\n","operationId":"createDomain","tags":["Domain"],"parameters":[{"$ref":"#/components/parameters/AuthorizationHeader"},{"$ref":"#/components/parameters/PortalIdPath"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDomain"}}}},"security":[{"vismaConnectPortalUser":["openid","yukiapi:domain:domains:create"]},{"vismaConnectPortalUser":["openid","yukiapi:domain:domains:write"]}],"responses":{"201":{"$ref":"#/components/responses/CreateDomainResponse"},"400":{"$ref":"#/components/responses/BadRequestResponse"},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"409":{"$ref":"#/components/responses/ConflictResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}}},"get":{"x-environments":["development","pilot","production"],"x-portal-visibility":["internal","trusted","prod"],"x-required-roles":[{"any-of":["AccountantManagement","Accountant"],"scope":"portal"}],"summary":"Get All Domains for a Portal","description":"This endpoint allows the retrieval of all domains belonging to a Portal. Ensure you have the necessary permissions before attempting to retrieve the domains list. You should have the **openid** and **yukiapi:domain:domains:read** scopes to access this endpoint.\n\n\n\n**Authorization**\n\nCalled with a **Portal User** token - an employee of an accounting portal.\n\nThe caller must hold at least one of these roles in the portal: `AccountantManagement`, `Accountant`.\n\n","operationId":"getAllDomains","tags":["Domain"],"parameters":[{"$ref":"#/components/parameters/AuthorizationHeader"},{"$ref":"#/components/parameters/PortalIdPath"},{"$ref":"#/components/parameters/OffsetQuery"},{"$ref":"#/components/parameters/LimitQuery"}],"security":[{"vismaConnectPortalUser":["openid","yukiapi:domain:domains:read"]}],"responses":{"200":{"$ref":"#/components/responses/GetDomainsPagedResponse"},"204":{"description":"No Content, with an empty body and no problem+json document, returned when the domain query cannot be read from the database. There is no errorCode to branch on, so treat it as a server-side failure and retry. A portal with no domains is a 200 with totalItems 0, not a 204.\n"},"400":{"$ref":"#/components/responses/BadRequestResponse"},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}}}},"/portals/{portal-id}/domains/{domain-id}":{"get":{"x-environments":["development","pilot","production"],"x-portal-visibility":["internal","trusted","prod"],"x-required-roles":[{"any-of":["AccountantManagement","Accountant"],"scope":"portal"}],"summary":"Get Domain by ID","description":"Retrieves detailed information about a specific domain using its unique identifier. This includes domain metadata and configuration details. You should have the **openid** and **yukiapi:domain:domains:read** scopes to access this endpoint. Returns domains:not_found (404) if this portal has no domain with that id.\n\n\n\n**Authorization**\n\nCalled with a **Portal User** token - an employee of an accounting portal.\n\nThe caller must hold at least one of these roles in the portal: `AccountantManagement`, `Accountant`.\n\n","operationId":"getDomainById","tags":["Domain"],"parameters":[{"$ref":"#/components/parameters/AuthorizationHeader"},{"$ref":"#/components/parameters/PortalIdPath"},{"$ref":"#/components/parameters/DomainIdPath"}],"security":[{"vismaConnectPortalUser":["openid","yukiapi:domain:domains:read"]}],"responses":{"200":{"$ref":"#/components/responses/GetDomainResponse"},"204":{"description":"No Content, with an empty body and no problem+json document, returned when the domain query cannot be read from the database. There is no errorCode to branch on, so treat it as a server-side failure and retry. A domain that does not exist is a 404 with errorCode domains:not_found, not a 204.\n"},"400":{"$ref":"#/components/responses/BadRequestResponse"},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}}},"put":{"x-environments":["development","pilot","production"],"x-portal-visibility":["internal","trusted","prod"],"x-required-roles":[{"any-of":["AccountantManagement","Accountant"],"scope":"portal"},{"any-of":["BackofficeManager","BackofficeController","AccountantManagement"],"note":"Enforced at the back-office security level and back-office functions layer."}],"summary":"Update Domain by ID","description":"This endpoint allows the modification of an existing domain's details by its ID. Ensure you have the necessary permissions before attempting to update a domain. You should have the **openid** scope together with one of **yukiapi:domain:domains:write** or **yukiapi:domain:domains:update** to access this endpoint. Returns domains:not_found (404) if this portal has no domain with that id, or domains:update_failed (500) if the domain was found but the back-office change could not be written.\n\n\n\n**Authorization**\n\nCalled with a **Portal User** token - an employee of an accounting portal.\n\nThe caller must hold at least one role from **each** of the following groups:\n\n- In the portal: `AccountantManagement`, `Accountant`\n- `BackofficeManager`, `BackofficeController`, `AccountantManagement` - Enforced at the back-office security level and back-office functions layer.\n\n","operationId":"updateDomainById","tags":["Domain"],"parameters":[{"$ref":"#/components/parameters/AuthorizationHeader"},{"$ref":"#/components/parameters/PortalIdPath"},{"$ref":"#/components/parameters/DomainIdPath"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDomain"}}}},"security":[{"vismaConnectPortalUser":["openid","yukiapi:domain:domains:write"]},{"vismaConnectPortalUser":["openid","yukiapi:domain:domains:update"]}],"responses":{"204":{"description":"Domain updated successfully."},"400":{"$ref":"#/components/responses/BadRequestResponse"},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}}}},"/domains/{domain-id}/users":{"get":{"x-environments":["development","pilot","production"],"x-portal-visibility":["internal","trusted","prod"],"x-required-roles":[{"any-of":["AccountantManagement","Accountant"],"scope":"portal"}],"summary":"Get All Domain Users","description":"This endpoint allows retrieving all users within a specific domain. Returns a list of all users with their details including name, email, roles, and language preferences. Users attempting to perform this operation need to ensure they possess the necessary permissions. You should have the **openid** and **yukiapi:domain:users:read** scopes to access this endpoint.\n\n\n\n**Authorization**\n\nCalled with a **Portal User** token - an employee of an accounting portal.\n\nThe caller must hold at least one of these roles in the portal: `AccountantManagement`, `Accountant`.\n\n","operationId":"getAllDomainUsers","tags":["Domain User"],"parameters":[{"$ref":"#/components/parameters/AuthorizationHeader"},{"$ref":"#/components/parameters/DomainIdPath"},{"$ref":"#/components/parameters/OffsetQuery"},{"$ref":"#/components/parameters/LimitQuery"}],"security":[{"vismaConnectPortalUser":["openid","yukiapi:domain:users:read"]}],"responses":{"200":{"$ref":"#/components/responses/DomainUsersPagedResultResponse"},"400":{"$ref":"#/components/responses/BadRequestResponse"},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}}},"post":{"x-environments":["development","pilot","production"],"x-portal-visibility":["internal","trusted","prod"],"x-required-roles":[{"any-of":["AccountantManagement","Accountant"],"scope":"portal"}],"summary":"Create Domain User","description":"This endpoint allows creating a new user for a specific domain. The user can be added with basic information including name, email, language preference, roles, and an optional message. Users attempting to perform this operation need to ensure they possess the necessary permissions. You should have the **openid** and **yukiapi:domain:users:write** scopes to access this endpoint. Returns domains:user_already_exists (409) if a user with the given email already has access to the domain, or domains:validation_failed (400) if a companiesIds entry is not on the domain, no role could be resolved, or the invitation could not be sent. A domain id the caller's portal does not own — whether unknown or belonging to another portal — answers 403.\n\n\n\n**Authorization**\n\nCalled with a **Portal User** token - an employee of an accounting portal.\n\nThe caller must hold at least one of these roles in the portal: `AccountantManagement`, `Accountant`.\n\n","operationId":"createDomainUser","tags":["Domain User"],"parameters":[{"$ref":"#/components/parameters/AuthorizationHeader"},{"$ref":"#/components/parameters/DomainIdPath"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDomainUser"}}}},"security":[{"vismaConnectPortalUser":["openid","yukiapi:domain:users:write"]}],"responses":{"201":{"$ref":"#/components/responses/CreateDomainUserResponse"},"400":{"$ref":"#/components/responses/BadRequestResponse"},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"409":{"$ref":"#/components/responses/ConflictResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}}}},"/domains/{domain-id}/users/search":{"get":{"x-environments":["development","pilot","production"],"x-portal-visibility":["internal","trusted","prod"],"x-required-roles":[{"any-of":["AccountantManagement","Accountant"],"scope":"portal"}],"summary":"Search Domain Users","description":"This endpoint allows searching for users within a specific domain by email address. Returns the user details if a match is found. Users attempting to perform this operation need to ensure they possess the necessary permissions. You should have the **openid** and **yukiapi:domain:users:read** scopes to access this endpoint. Returns domains:user_not_found (404) if no user on this domain carries that address.\n\n\n\n**Authorization**\n\nCalled with a **Portal User** token - an employee of an accounting portal.\n\nThe caller must hold at least one of these roles in the portal: `AccountantManagement`, `Accountant`.\n\n","operationId":"searchDomainUsers","tags":["Domain User"],"parameters":[{"$ref":"#/components/parameters/AuthorizationHeader"},{"$ref":"#/components/parameters/DomainIdPath"},{"$ref":"#/components/parameters/EmailQuery"}],"security":[{"vismaConnectPortalUser":["openid","yukiapi:domain:users:read"]}],"responses":{"200":{"$ref":"#/components/responses/DomainUserResponse"},"400":{"$ref":"#/components/responses/BadRequestResponse"},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}}}},"/domains/{domain-id}/users/byEmail":{"delete":{"x-environments":["development","pilot","production"],"x-portal-visibility":["internal","trusted","prod"],"x-required-roles":[{"any-of":["AccountantManagement","Accountant"],"scope":"portal"}],"summary":"Delete Domain User","description":"This endpoint allows deleting a user from a specific domain by email. Users attempting to perform this operation need to ensure they possess the necessary permissions. Once deleted, the user information cannot be recovered. You should have the **openid** and **yukiapi:domain:users:delete** scopes to access this endpoint. Returns domains:user_not_found (404) if no user on this domain carries that address.\n\n\n\n**Authorization**\n\nCalled with a **Portal User** token - an employee of an accounting portal.\n\nThe caller must hold at least one of these roles in the portal: `AccountantManagement`, `Accountant`.\n\n","operationId":"deleteDomainUser","tags":["Domain User"],"parameters":[{"$ref":"#/components/parameters/AuthorizationHeader"},{"$ref":"#/components/parameters/DomainIdPath"},{"$ref":"#/components/parameters/EmailQuery"}],"security":[{"vismaConnectPortalUser":["openid","yukiapi:domain:users:delete"]}],"responses":{"204":{"description":"Domain user successfully deleted"},"400":{"$ref":"#/components/responses/BadRequestResponse"},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}}}},"/portals/{portal-id}":{"get":{"x-environments":["development","pilot","production"],"x-portal-visibility":["internal","trusted","prod"],"x-required-roles":[{"any-of":["AccountantManagement","Accountant"],"scope":"portal"}],"summary":"Get Portal info","description":"This endpoint retrieves information about a portal using its unique portal ID. Ensure you have the necessary permissions before accessing this endpoint. You should have the **openid** and **yukiapi:portal:portals:read** scopes to access this endpoint. Returns portals:not_found (404) if no portal has that id.\n\n\n\n**Authorization**\n\nCalled with a **Portal User** token - an employee of an accounting portal.\n\nThe caller must hold at least one of these roles in the portal: `AccountantManagement`, `Accountant`.\n\n","operationId":"getPortal","tags":["Portal"],"parameters":[{"$ref":"#/components/parameters/AuthorizationHeader"},{"$ref":"#/components/parameters/PortalIdPath"}],"security":[{"vismaConnectPortalUser":["openid","yukiapi:portal:portals:read"]}],"responses":{"200":{"$ref":"#/components/responses/PortalResponse"},"400":{"$ref":"#/components/responses/BadRequestResponse"},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}}}},"/portals/{portal-id}/companies/search/byCustomerCode":{"get":{"x-environments":["development","pilot","production"],"x-portal-visibility":["internal","trusted","prod"],"x-required-roles":[{"any-of":["AccountantManagement","Accountant"],"scope":"portal"}],"summary":"Search Company by Customer Code","description":"This endpoint allows searching for a company within a specific portal by its internal customer code. Returns the company details if a match is found. Users attempting to perform this operation need to ensure they possess the necessary permissions. You should have the **openid** and **yukiapi:portal:portals:read** scopes to access this endpoint.\n\n\n\n**Authorization**\n\nCalled with a **Portal User** token - an employee of an accounting portal.\n\nThe caller must hold at least one of these roles in the portal: `AccountantManagement`, `Accountant`.\n\n","operationId":"searchCompanyByCustomerCode","tags":["Company"],"parameters":[{"$ref":"#/components/parameters/AuthorizationHeader"},{"$ref":"#/components/parameters/PortalIdPath"},{"$ref":"#/components/parameters/CustomerCodeQuery"}],"security":[{"vismaConnectPortalUser":["openid","yukiapi:portal:portals:read"]}],"responses":{"200":{"$ref":"#/components/responses/GetCompanyResponse"},"400":{"$ref":"#/components/responses/BadRequestResponse"},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}}}},"/portals/{portal-id}/companies/search/byCompanyId":{"get":{"x-environments":["development","pilot","production"],"x-portal-visibility":["internal","trusted","prod"],"x-required-roles":[{"any-of":["AccountantManagement","Accountant"],"scope":"portal"}],"summary":"Search Company by Company ID","description":"This endpoint allows searching for a company within a specific portal by its company ID. Returns the company details if a match is found. Users attempting to perform this operation need to ensure they possess the necessary permissions. You should have the **openid** and **yukiapi:portal:portals:read** scopes to access this endpoint.\n\n\n\n**Authorization**\n\nCalled with a **Portal User** token - an employee of an accounting portal.\n\nThe caller must hold at least one of these roles in the portal: `AccountantManagement`, `Accountant`.\n\n","operationId":"searchCompanyByCompanyId","tags":["Company"],"parameters":[{"$ref":"#/components/parameters/AuthorizationHeader"},{"$ref":"#/components/parameters/PortalIdPath"},{"$ref":"#/components/parameters/CompanyIdQuery"}],"security":[{"vismaConnectPortalUser":["openid","yukiapi:portal:portals:read"]}],"responses":{"200":{"$ref":"#/components/responses/GetCompanyResponse"},"400":{"$ref":"#/components/responses/BadRequestResponse"},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}}}},"/portals/{portal-id}/users":{"get":{"x-environments":["development","pilot","production"],"x-portal-visibility":["internal","trusted","prod"],"x-required-roles":[{"any-of":["AccountantManagement","Accountant"],"scope":"portal"}],"summary":"Get All Portal Users","description":"This endpoint retrieves basic information about users by Portal id. You should have the **openid** and **yukiapi:portal:users:read** scopes to access this endpoint.\n\n\n\n**Authorization**\n\nCalled with a **Portal User** token - an employee of an accounting portal.\n\nThe caller must hold at least one of these roles in the portal: `AccountantManagement`, `Accountant`.\n\n","operationId":"getUsersByPortalId","tags":["Portal User"],"parameters":[{"$ref":"#/components/parameters/AuthorizationHeader"},{"$ref":"#/components/parameters/PortalIdPath"},{"$ref":"#/components/parameters/OffsetQuery"},{"$ref":"#/components/parameters/LimitQuery"}],"security":[{"vismaConnectPortalUser":["openid","yukiapi:portal:users:read"]}],"responses":{"200":{"$ref":"#/components/responses/PortalUsersPagedResultResponse"},"400":{"$ref":"#/components/responses/BadRequestResponse"},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}}},"post":{"x-environments":["development","pilot","production"],"x-portal-visibility":["internal","trusted","prod"],"x-required-roles":[{"any-of":["AccountantManagement"],"scope":"portal"}],"summary":"Create Portal User","description":"This endpoint allows the creation of a user in the portal. Ensure the user has the necessary permissions before attempting to create a user. You should have the **openid** and **yukiapi:portal:users:write** scopes to access this endpoint. Returns portals:user_already_exists (409) if that address is already a user of this portal, or portals:validation_failed (400) if the portal refuses the user for another reason.\n\n\n\n**Authorization**\n\nCalled with a **Portal User** token - an employee of an accounting portal.\n\nThe caller must hold the `AccountantManagement` role in the portal.\n\n","operationId":"createUser","tags":["Portal User"],"parameters":[{"$ref":"#/components/parameters/AuthorizationHeader"},{"$ref":"#/components/parameters/PortalIdPath"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePortalUser"}}}},"security":[{"vismaConnectPortalUser":["openid","yukiapi:portal:users:write"]}],"responses":{"201":{"$ref":"#/components/responses/PortalUserCreateResponse"},"400":{"$ref":"#/components/responses/BadRequestResponse"},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"409":{"$ref":"#/components/responses/ConflictResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}}}},"/portals/{portal-id}/users/search":{"get":{"x-environments":["development","pilot","production"],"x-portal-visibility":["internal","trusted","prod"],"x-required-roles":[{"any-of":["AccountantManagement","Accountant"],"scope":"portal"}],"summary":"Search Portal Users","description":"This endpoint allows searching for users within a specific portal by email address. Returns the user details if a match is found. Users attempting to perform this operation need to ensure they possess the necessary permissions. You should have the **openid** and **yukiapi:portal:users:read** scopes to access this endpoint. Returns portals:user_not_found (404) if no user in this portal carries that address.\n\n\n\n**Authorization**\n\nCalled with a **Portal User** token - an employee of an accounting portal.\n\nThe caller must hold at least one of these roles in the portal: `AccountantManagement`, `Accountant`.\n\n","operationId":"searchPortalUsers","tags":["Portal User"],"parameters":[{"$ref":"#/components/parameters/AuthorizationHeader"},{"$ref":"#/components/parameters/PortalIdPath"},{"$ref":"#/components/parameters/EmailQuery"}],"security":[{"vismaConnectPortalUser":["openid","yukiapi:portal:users:read"]}],"responses":{"200":{"$ref":"#/components/responses/PortalUsersResponse"},"400":{"$ref":"#/components/responses/BadRequestResponse"},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}}}},"/portals/{portal-id}/users/byEmail":{"delete":{"x-environments":["development","pilot","production"],"x-portal-visibility":["internal","trusted","prod"],"x-required-roles":[{"any-of":["AccountantManagement"],"scope":"portal"}],"summary":"Delete Portal User by Email","description":"This endpoint allows deleting a user from a specific portal by their email address. Users attempting to perform this operation need to ensure they possess the necessary permissions. Once deleted, the user information cannot be recovered. You should have the **openid** and **yukiapi:portal:users:delete** scopes to access this endpoint. Returns portals:user_not_found (404) if no user in this portal carries that address, or portals:user_update_failed (500) if the user was found but the deletion could not be written.\n\n\n\n**Authorization**\n\nCalled with a **Portal User** token - an employee of an accounting portal.\n\nThe caller must hold the `AccountantManagement` role in the portal.\n\n","operationId":"deletePortalUserByEmail","tags":["Portal User"],"parameters":[{"$ref":"#/components/parameters/AuthorizationHeader"},{"$ref":"#/components/parameters/PortalIdPath"},{"$ref":"#/components/parameters/EmailQuery"}],"security":[{"vismaConnectPortalUser":["openid","yukiapi:portal:users:delete"]}],"responses":{"204":{"description":"Portal user successfully deleted"},"400":{"$ref":"#/components/responses/BadRequestResponse"},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}}},"put":{"x-environments":["development","pilot","production"],"x-portal-visibility":["internal","trusted","prod"],"x-required-roles":[{"any-of":["AccountantManagement"],"scope":"portal"}],"summary":"Update Portal User","description":"This endpoint allows updating a user's information in the portal using the specified user email and portal ID. The update can modify the user's name, language preference, and roles. Users attempting to perform this operation need to ensure they possess the necessary permissions. You should have the **openid** scope together with one of **yukiapi:portal:users:write** or **yukiapi:portal:users:update** to access this endpoint. Returns portals:user_not_found (404) if no user in this portal carries that address, portals:validation_failed (400) if the portal refuses the change, for instance removing the last portal manager, or portals:user_update_failed (500) if the user was found but the change could not be written.\n\n\n\n**Authorization**\n\nCalled with a **Portal User** token - an employee of an accounting portal.\n\nThe caller must hold the `AccountantManagement` role in the portal.\n\n","operationId":"updateUser","tags":["Portal User"],"parameters":[{"$ref":"#/components/parameters/AuthorizationHeader"},{"$ref":"#/components/parameters/PortalIdPath"},{"$ref":"#/components/parameters/EmailQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePortalUser"}}}},"security":[{"vismaConnectPortalUser":["openid","yukiapi:portal:users:write"]},{"vismaConnectPortalUser":["openid","yukiapi:portal:users:update"]}],"responses":{"204":{"description":"User successfully updated"},"400":{"$ref":"#/components/responses/BadRequestResponse"},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}}}},"/portals/{portal-id}/users/{user-id}":{"get":{"x-environments":["development","pilot","production"],"x-portal-visibility":["internal","trusted","prod"],"x-required-roles":[{"any-of":["AccountantManagement","Accountant"],"scope":"portal"}],"summary":"Get Portal User","description":"This endpoint enables the retrieval of a single user's information from the specified portal by the user's id. Users need to confirm they have the required permissions before attempting to access this information. The operation helps in fetching critical user data for administrative or auditing purposes. You should have the **openid** and **yukiapi:portal:users:read** scopes to access this endpoint. Returns portals:user_not_found (404) if this portal has no user with that id.\n\n\n\n**Authorization**\n\nCalled with a **Portal User** token - an employee of an accounting portal.\n\nThe caller must hold at least one of these roles in the portal: `AccountantManagement`, `Accountant`.\n\n","operationId":"getUser","tags":["Portal User"],"parameters":[{"$ref":"#/components/parameters/AuthorizationHeader"},{"$ref":"#/components/parameters/PortalIdPath"},{"$ref":"#/components/parameters/GetUserIdPath"}],"security":[{"vismaConnectPortalUser":["openid","yukiapi:portal:users:read"]}],"responses":{"200":{"$ref":"#/components/responses/PortalUsersResponse"},"400":{"$ref":"#/components/responses/BadRequestResponse"},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}}}}},"components":{"schemas":{"CompanyAddress":{"type":"object","properties":{"address":{"type":"string","nullable":true,"description":"Street name and number.","example":"Main Street 123"},"address2":{"type":"string","nullable":true,"description":"Additional address information.","example":"Suite 456"},"postalCode":{"type":"string","nullable":true,"description":"Postal code.","example":"1234AB"},"city":{"type":"string","nullable":true,"description":"City name.","example":"Amsterdam"}},"description":"Address information object."},"LegalForm":{"type":"string","enum":["Unknown","SolePartnership","PrivateLimited","PublicLimited","GeneralPartnership","LimitedPartnership","Partnership","Association","Foundation","Cooperative"],"description":"Legal form of the company. \\\nBE: Unknown, SolePartnership, PrivateLimited, PublicLimited, GeneralPartnership, LimitedPartnership, Partnership, Association, Foundation, Cooperative. \\\nNL: values to be added later\n","example":"PrivateLimited"},"MixedOrPartialLiable":{"type":"string","nullable":true,"enum":["No","Mixed","Partial"],"description":"Mixed or partial liable indicator. \"No\" is stored as the absence of the setting, so sending \"No\" and reading the value back returns null; only \"Mixed\" and \"Partial\" are persisted as values.","example":"No"},"ICPFrequency":{"type":"string","nullable":true,"enum":["None","Yearly","Quarterly","Monthly"],"description":"ICP frequency indicator.","example":"Monthly"},"VATFrequency":{"type":"string","nullable":true,"enum":["None","Yearly","Quarterly","Monthly"],"description":"VAT frequency indicator.","example":"Monthly"},"PettyCashOption":{"type":"string","nullable":true,"enum":["Unknown","Regularly","Petty","None"],"description":"Cash usage option: Unknown, Regularly, Petty, None\n","example":"Regularly"},"CompanyFinancials":{"type":"object","properties":{"vatNumber":{"type":"string","nullable":true,"description":"VAT number, normalised to the notation of the country its prefix declares. Belgian numbers are returned grouped (BE0531.247.818), Dutch numbers ungrouped (NL123456782B01), so this can differ from the value that was submitted.","example":"NL123456782B01"},"fiscalNumber":{"type":"string","nullable":true,"description":"Fiscal number.","example":"123456789"},"payrollTaxNumber":{"type":"string","nullable":true,"description":"Payroll tax number.","example":"987654321"},"vatLiable":{"type":"boolean","nullable":true,"description":"VAT liable indicator.","example":true},"mixedOrPartialLiable":{"$ref":"#/components/schemas/MixedOrPartialLiable"},"icpFrequency":{"$ref":"#/components/schemas/ICPFrequency"},"autoICPDeclaration":{"type":"boolean","nullable":true,"description":"Whether to automatically generate ICP declaration.","example":false},"vatFrequency":{"$ref":"#/components/schemas/VATFrequency"},"showVatReturn":{"type":"boolean","nullable":true,"description":"Whether to show VAT return.","example":true},"pettyCash":{"$ref":"#/components/schemas/PettyCashOption"},"financialYearFollowsCalendarMonths":{"type":"boolean","description":"Whether the financial year follows calendar months.","example":true},"yukiStartKeepingFinancialRecordsYear":{"type":"string","description":"The year when Yuki started keeping financial records.","example":"2023"},"yukiStartKeepingFinancialRecordsDate":{"type":"string","format":"date-time","description":"The date when Yuki started keeping financial records.","example":"2023-01-01T00:00:00Z"}},"description":"Financial object containing financial-related settings."},"PeppolConfiguration":{"type":"object","required":["enableSending","enableReceiving"],"properties":{"enableSending":{"type":"boolean","description":"Whether Peppol sending is enabled for this company. Defaults to false when the company is not registered on Peppol.","default":false},"enableReceiving":{"type":"boolean","description":"Whether Peppol receiving is enabled for this company. Defaults to false when the company is not registered on Peppol.","default":false}},"description":"Peppol configuration object containing Peppol-related settings."},"Company":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the company.","example":"123e4567-e89b-12d3-a456-426614174000"},"companyName":{"type":"string","description":"The name of the company.","example":"Example Corp"},"companyDescription":{"type":"string","description":"A brief description of the company.","example":"Example Corp is a leading provider of innovative solutions."},"address":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CompanyAddress"}]},"mailingAddress":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CompanyAddress"}]},"country":{"type":"string","nullable":true,"description":"Country ISO code.","example":"NL"},"emailAddress":{"type":"string","description":"Back-office mailbox of the company, always on Yuki's own mail domain. Only the part before the \"@\" is stored when the company is updated, so this is not the company's own email address.","example":"backoffice@yukiworks.be"},"phone":{"type":"string","description":"Phone number.","example":"+31 20 123 4567"},"website":{"type":"string","description":"Company website (optional).","example":"https://example.com"},"legalForm":{"$ref":"#/components/schemas/LegalForm"},"cocNumber":{"type":"string","description":"Chamber of Commerce number.","example":"12345678"},"internalCustomerCode":{"type":"string","description":"Internal customer code (optional).","example":"CUST001"},"accountingStartingDate":{"type":"string","format":"date","description":"Accounting starting date.","example":"2024-01-01"},"financial":{"$ref":"#/components/schemas/CompanyFinancials"},"peppolConfiguration":{"$ref":"#/components/schemas/PeppolConfiguration"},"domainId":{"type":"string","format":"uuid","description":"The unique identifier of the domain where the company belongs.","example":"456e5678-f90c-23e4-b567-537725285111"}},"required":["peppolConfiguration"],"description":"Company information object."},"ProblemDetails":{"type":"object","description":"Error body returned as application/problem+json on every 4xx and 5xx response. Beyond the standard problem members it carries the traceId, errorCode and errors extensions.","properties":{"type":{"type":"string","description":"URI reference identifying the problem type. Always https://httpstatuses.com/{status}, so it restates the status and carries no Yuki-specific meaning; branch on errorCode instead.","example":"https://httpstatuses.com/400"},"title":{"type":"string","description":"Short, human-readable summary of the problem type, in English.","example":"Validation Error"},"status":{"type":"integer","description":"HTTP status code, repeated from the response status line.","example":400},"detail":{"type":"string","description":"Human-readable explanation of this specific occurrence. Free text meant for developers, not a stable contract - do not parse it.","example":"The company id is required."},"instance":{"type":"string","description":"Optional. Path of the request as the API received it. The gateway fronts the API, so it is not always populated and it may differ from the URL the client called.","example":"/api/v1/companies/3afb7b54-6144-4561-9a29-1148006f2375"},"traceId":{"type":"string","description":"Correlation id for the request - the 32-character hexadecimal W3C trace id taken from the incoming traceparent header, or a locally generated id when none was propagated. Quote it in support requests.","example":"4bf92f3577b34da6a3ce929d0e0e4736"},"errorCode":{"type":"string","description":"Stable machine-readable error identifier in {feature}:{error_type} form. This is the member to branch on, together with the status - not the feature prefix on its own. A request refused before it reaches the operation can answer 403 with validation:invalid_input, and an operation that fails on an unexpected internal state can answer 500 with that same code.","example":"companies:not_found"},"errors":{"type":"object","description":"Messages that explain the failure, grouped by key. Present on the errors raised while the request is being handled, not only on validation failures. It is absent from the errors that stop a request before it reaches the operation - the 401 for a missing or unaccepted token, the 403 for an absent scope or an unusable tenant claim, and the 500 for a session that could not be created - which carry only traceId and errorCode. Keys take one of two shapes - the name of the rejected field when the request failed model binding or field validation, otherwise the errorCode of the failure, repeating the errorCode member.","additionalProperties":{"type":"array","items":{"type":"string"}},"example":{"companies:validation_failed":["The company id is required."]}}}},"BadRequestError":{"description":"A 400 comes in two shapes that differ by title. A request that fails model binding never reaches the operation and carries the title below, with errors keyed by the rejected field. A request the operation itself rejects carries the title Validation Error, with errors keyed by the rejected field for a field check, or by the errorCode for a business rule. Both shapes carry errorCode, traceId and errors.","allOf":[{"$ref":"#/components/schemas/ProblemDetails"}],"example":{"type":"https://httpstatuses.com/400","title":"One or more validation errors occurred.","status":400,"detail":"The request contains invalid or malformed fields. See the errors property for details.","instance":"/example/bad-request","traceId":"4bf92f3577b34da6a3ce929d0e0e4736","errorCode":"validation:invalid_input","errors":{"country":["The country field is required."]}}},"UnauthorizedError":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"}],"example":{"type":"https://httpstatuses.com/401","title":"Unauthorized","status":401,"detail":"Authentication is required.","instance":"/example/unauthorized","traceId":"4bf92f3577b34da6a3ce929d0e0e4736","errorCode":"authentication:unauthorized"}},"ForbiddenError":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"}],"example":{"type":"https://httpstatuses.com/403","title":"Forbidden","status":403,"detail":"You do not have permission to access this resource.","instance":"/example/forbidden","traceId":"4bf92f3577b34da6a3ce929d0e0e4736","errorCode":"authentication:forbidden","errors":{"authentication:forbidden":["You do not have permission to access this resource."]}}},"NotFoundError":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"}],"example":{"type":"https://httpstatuses.com/404","title":"Not Found","status":404,"detail":"The requested resource could not be found.","instance":"/example/not-found","traceId":"4bf92f3577b34da6a3ce929d0e0e4736","errorCode":"companies:not_found","errors":{"companies:not_found":["The requested resource could not be found."]}}},"InternalServerError":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"}],"example":{"type":"https://httpstatuses.com/500","title":"Internal Server Error","status":500,"detail":"An unexpected error occurred.","instance":"/example/internal-server-error","traceId":"4bf92f3577b34da6a3ce929d0e0e4736","errorCode":"server:internal_error","errors":{"server:internal_error":["An unexpected error occurred."]}}},"UpdateCompany":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"The name of the company.","example":"Example Corp"},"description":{"type":"string","nullable":true,"maxLength":40,"description":"A brief description of the company, stored as its commercial name. Limited to 40 characters; longer values are truncated without an error.","example":"Cloud infrastructure and hosting"},"address":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CompanyAddress"}]},"mailingAddress":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CompanyAddress"}]},"details":{"type":"object","nullable":true,"description":"Company details information object.","properties":{"cocNumber":{"type":"string","nullable":true,"description":"Chamber of Commerce number.","example":"12345678"},"country":{"type":"string","nullable":true,"description":"Country ISO code. Must match the country of the portal the company's domain belongs to.","example":"NL"}}},"emailAddress":{"type":"string","nullable":true,"description":"Back-office mailbox of the company. Only the part before the \"@\" is kept; the domain is replaced by Yuki's own mail domain, so the value is returned as @yukiworks. and not as the address supplied here.","example":"backoffice@example.com"},"phone":{"type":"string","nullable":true,"description":"Phone number.","example":"+31 20 123 4567"},"website":{"type":"string","nullable":true,"description":"Company website (optional).","example":"https://example.com"},"legalForm":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/LegalForm"}]},"internalCustomerCode":{"type":"string","nullable":true,"description":"Internal customer code (optional).","example":"CUST001"},"accountingStartingDate":{"type":"string","format":"date","nullable":true,"description":"Accounting starting date. Alias of financials.yukiStartKeepingFinancialRecordsDate; when both are supplied, financials.yukiStartKeepingFinancialRecordsDate takes precedence.","example":"2024-01-01"},"financials":{"type":"object","nullable":true,"description":"Financial object containing financial-related settings.","properties":{"pettyCash":{"$ref":"#/components/schemas/PettyCashOption"},"financialYearFollowsCalendarMonths":{"type":"boolean","nullable":true,"description":"Whether the financial year follows calendar months.","example":true},"yukiStartKeepingFinancialRecordsYear":{"type":"string","nullable":true,"description":"The year when Yuki started keeping financial records.","example":"2023"},"yukiStartKeepingFinancialRecordsDate":{"type":"string","format":"date-time","nullable":true,"description":"The date when Yuki started keeping financial records.","example":"2023-01-01T00:00:00Z"}}},"taxInformation":{"type":"object","nullable":true,"description":"Company tax information object.","properties":{"vatNumber":{"type":"string","nullable":true,"description":"VAT number. Must be a valid VAT number for the company's country, including its country prefix; the request is rejected with 400 companies:validation_failed otherwise. The value is normalised to the national notation before it is stored, so the number returned by Get Company can differ from the one supplied here (for example BE0531247818 is returned as BE0531.247.818).","example":"NL123456782B01"},"fiscalNumber":{"type":"string","nullable":true,"description":"Fiscal number.","example":"123456789"},"payrollTaxNumber":{"type":"string","nullable":true,"description":"Payroll tax number.","example":"987654321"},"vatLiable":{"type":"boolean","nullable":true,"description":"VAT liable indicator.","example":true},"mixedOrPartialLiable":{"$ref":"#/components/schemas/MixedOrPartialLiable"},"icpFrequency":{"$ref":"#/components/schemas/ICPFrequency"},"autoICPDeclaration":{"type":"boolean","nullable":true,"description":"Whether to automatically generate ICP declaration.","example":false},"vatFrequency":{"$ref":"#/components/schemas/VATFrequency"},"showVatReturn":{"type":"boolean","nullable":true,"description":"Whether to show VAT return.","example":true}}}},"description":"Company information object."},"PatchPeppolSettingsRequest":{"type":"object","properties":{"enableSending":{"type":"boolean","nullable":true,"description":"Enables or disables Peppol sending. Omit to leave unchanged."},"enableReceiving":{"type":"boolean","nullable":true,"description":"Enables or disables Peppol receiving. Omit to leave unchanged."}},"description":"Request body for partially updating company Peppol settings."},"ConflictError":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"}],"example":{"type":"https://httpstatuses.com/409","title":"Conflict","status":409,"detail":"The request could not be completed due to a conflict with the current state of the resource.","instance":"/example/conflict","traceId":"4bf92f3577b34da6a3ce929d0e0e4736","errorCode":"domains:user_already_exists","errors":{"domains:user_already_exists":["The request could not be completed due to a conflict with the current state of the resource."]}}},"UnprocessableEntityError":{"description":"A 422 is a request the API understood and refused on eligibility or state grounds rather than on the shape of the request or the caller's permissions. It is raised while the request is being handled, so it carries errorCode, traceId and errors, with errors keyed by the errorCode. Branch on errorCode together with the status.","allOf":[{"$ref":"#/components/schemas/ProblemDetails"}],"example":{"type":"https://httpstatuses.com/422","title":"Unprocessable Entity","status":422,"detail":"Domain is not eligible for Peppol.","instance":"/example/unprocessable-entity","traceId":"4bf92f3577b34da6a3ce929d0e0e4736","errorCode":"peppol:domain_not_eligible","errors":{"peppol:domain_not_eligible":["Domain is not eligible for Peppol."]}}},"BadGatewayError":{"description":"An upstream service the request depends on did not respond or returned an error.","allOf":[{"$ref":"#/components/schemas/ProblemDetails"}],"example":{"type":"https://httpstatuses.com/502","title":"Bad Gateway","status":502,"detail":"Peppol network is currently unavailable","instance":"/example/bad-gateway","traceId":"4bf92f3577b34da6a3ce929d0e0e4736","errorCode":"peppol:network_unavailable","errors":{"peppol:network_unavailable":["Peppol network is currently unavailable"]}}},"PagedResult":{"type":"object","properties":{"totalItems":{"type":"integer","description":"Total number of items available","example":100},"offset":{"type":"integer","description":"Current offset in the list","example":10},"limit":{"type":"integer","description":"Maximum number of items returned","example":20},"items":{"type":"array","items":{"type":"object"}}}},"ContactBase":{"type":"object","description":"Base schema for a contact. Contains the properties shared by ContactPerson and ContactCompany; the type field tells which one a given contact is. Optional fields are returned as null when not set.","required":["id","name","type"],"properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier of the contact","example":"f47ac10b-58cc-4372-a567-0e02b2c3d479"},"name":{"type":"string","description":"The full name of the contact (person or company name)","example":"Acme Corporation"},"type":{"type":"string","enum":["Person","Company"],"description":"Indicates whether this contact is a natural person or a company/organization. Same values as the type field of the create and update request bodies."},"hid":{"type":"integer","nullable":true,"description":"The human-readable identifier of the contact","example":123456},"code":{"type":"string","nullable":true,"description":"The external code of the contact","example":"EXT001"},"address":{"type":"object","description":"The address of the contact. Always present; individual fields are null when not set.","properties":{"address":{"type":"string","nullable":true,"description":"Street name and number","example":"Main Street 123"},"address2":{"type":"string","nullable":true,"description":"Additional address information","example":"Suite 456"},"postalCode":{"type":"string","nullable":true,"description":"Postal code","example":"1234 AB"},"city":{"type":"string","nullable":true,"description":"City name","example":"Amsterdam"}}},"country":{"type":"string","nullable":true,"description":"The country code of the contact","example":"NL"},"phoneHome":{"type":"string","nullable":true,"description":"The phone number of the contact","example":"+31 20 123 4567"},"emailWork":{"type":"string","nullable":true,"description":"The email address of the contact","example":"work@example.com"},"website":{"type":"string","nullable":true,"description":"The website of the contact","example":"https://example.com"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels associated with this contact. Always present; empty when the contact has no labels.","example":["important","vip"]},"created":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp when the contact was created","example":"2024-01-01T12:00:00Z"},"modified":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp when the contact was last modified","example":"2024-01-15T14:30:00Z"}}},"ContactPerson":{"description":"A contact of type Person (natural person)","allOf":[{"$ref":"#/components/schemas/ContactBase"},{"type":"object","properties":{"type":{"type":"string","enum":["Person"]},"nationalRegisterNumber":{"type":"string","nullable":true,"description":"The national register / social security number of the person","example":"12345678901"}}}]},"ContactCompany":{"description":"A contact of type Company (organization)","allOf":[{"$ref":"#/components/schemas/ContactBase"},{"type":"object","properties":{"type":{"type":"string","enum":["Company"]},"vatNumber":{"type":"string","nullable":true,"description":"The VAT number of the company","example":"NL123456782B01"},"cocNumber":{"type":"string","nullable":true,"description":"The Chamber of Commerce number of the company","example":"12345678"},"mainContactPersonId":{"type":"string","format":"uuid","nullable":true,"description":"The unique identifier of the main contact person for this company","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"mainContactPerson":{"type":"string","nullable":true,"description":"The full name of the main contact person for this company","example":"Jane Smith"},"incomeTaxNumber":{"type":"string","nullable":true,"description":"The income tax number of the company","example":"123456789"}}}]},"Contact":{"description":"Represents a contact. Can be either a ContactPerson (natural person) or a ContactCompany (organization). Use the type discriminator to determine which one you received; it takes the same values as the type field of the create and update request bodies.","oneOf":[{"$ref":"#/components/schemas/ContactPerson"},{"$ref":"#/components/schemas/ContactCompany"}],"discriminator":{"propertyName":"type","mapping":{"Person":"#/components/schemas/ContactPerson","Company":"#/components/schemas/ContactCompany"}}},"ContactAddress":{"type":"object","properties":{"address":{"type":"string","description":"Street name and number.","example":"Main Street 123"},"address2":{"type":"string","description":"Additional address information.","example":"Suite 456"},"postalCode":{"type":"string","description":"Postal code.","example":"1234AB"},"city":{"type":"string","description":"City name.","example":"Amsterdam"}},"required":["address","postalCode","city"],"description":"Address information object."},"ContactRequestBase":{"type":"object","description":"Base schema for contact request bodies. Contains all common properties shared between Person and Company contact types.","properties":{"type":{"type":"string","enum":["Person","Company"],"description":"Indicates whether this contact is a natural person or a company/organization"},"name":{"type":"string","description":"Full name of the contact","example":"John Doe"},"code":{"type":"string","description":"External code of the contact","example":"EXT001"},"address":{"$ref":"#/components/schemas/ContactAddress"},"mailAddress":{"$ref":"#/components/schemas/ContactAddress"},"country":{"type":"string","description":"Country of the contact","example":"NL"},"phoneHome":{"type":"string","description":"Phone number","example":"+31 20 123 4567"},"emailWork":{"type":"string","format":"email","description":"Email address","example":"contact@example.com"},"website":{"type":"string","description":"Website","example":"https://example.com"},"tags":{"type":"array","description":"Tags associated with the contact","items":{"type":"string"},"example":["important","vip"]}}},"ContactRequestPerson":{"description":"Contact request body for a Person (natural person)","allOf":[{"$ref":"#/components/schemas/ContactRequestBase"},{"type":"object","properties":{"type":{"type":"string","enum":["Person"]},"nationalRegisterNumber":{"type":"string","description":"The national register / social security number of the person","example":"12345678901"}}}]},"ContactRequestCompany":{"description":"Contact request body for a Company (organization)","allOf":[{"$ref":"#/components/schemas/ContactRequestBase"},{"type":"object","properties":{"type":{"type":"string","enum":["Company"]},"vatNumber":{"type":"string","description":"VAT Number","example":"NL123456782B01"},"cocNumber":{"type":"string","description":"CoC number (Chamber of Commerce number)","example":"12345678"},"incomeTaxNumber":{"type":"string","description":"Income tax number","example":"123456789"},"mainContactPerson":{"type":"string","description":"Contact person of the company","example":"John Doe"}}}]},"CreateContact":{"description":"Request body for creating a new contact. Use the type discriminator to specify Person or Company. Fields name, type, and country are required.","oneOf":[{"$ref":"#/components/schemas/ContactRequestPerson"},{"$ref":"#/components/schemas/ContactRequestCompany"}],"discriminator":{"propertyName":"type","mapping":{"Person":"#/components/schemas/ContactRequestPerson","Company":"#/components/schemas/ContactRequestCompany"}},"required":["name","type","country"]},"UpdateContact":{"description":"Request body for updating an existing contact. Use the type discriminator to specify Person or Company. Only type is required; all other fields are optional for partial updates.","oneOf":[{"$ref":"#/components/schemas/ContactRequestPerson"},{"$ref":"#/components/schemas/ContactRequestCompany"}],"discriminator":{"propertyName":"type","mapping":{"Person":"#/components/schemas/ContactRequestPerson","Company":"#/components/schemas/ContactRequestCompany"}},"required":["type"]},"VatCode":{"type":"object","description":"VAT code definition available within an administration.","properties":{"id":{"type":"string","format":"uuid","nullable":true,"description":"Unique identifier of the VAT code.","example":"b1f3c1d5-3c76-4d07-9f8a-3a0ac2b502ae"},"type":{"type":"string","nullable":true,"description":"Category of the VAT code, derived from its VAT type: Sales when the type is sales-applicable, otherwise Purchase when it is purchase-applicable, otherwise Other. A type applicable to both sales and purchases is reported as Sales.","enum":["Sales","Purchase","Other"],"example":"Sales"},"vatType":{"type":"string","nullable":true,"description":"Specifies the VAT type configured for the code.","enum":["VATExempt","VATHigh","VATLow","VATOther","VATZeroPercent","VATReverseCharged","ExportOutsideTheEU","ExportInsideTheEU","InstallationOrDistanceSalesInsideTheEU","VATAgricultureRegulation","LocalVATInOtherEUCountries","AdvanceTax","ImportOutsideTheEU","AcquisitionsInsideTheEU","PrivateUse","RulesForSmallTraders","NonDeductible","VATZeroPercentReverseCharged","VatZeroPercentPurchase","ExportInsideTheEUSupplies","ExportInsideTheEUServices","VATMedium","VariousVATRegulationsInFavor","ImportInsideTheEUSupplies","ImportInsideTheEUServices","VATDigitalServicesAndOrDistanceSelling","ExportOfGoodsInsideTheEUTriangularTrade"],"example":"VATHigh"},"description":{"type":"string","nullable":true,"description":"Human readable description of the VAT code.","example":"Standard rate NL"},"vatRate":{"type":"number","format":"double","nullable":true,"description":"VAT rate configured for the code.","example":21},"active":{"type":"boolean","nullable":true,"description":"Indicates whether the VAT code is currently active.","example":true},"country":{"type":"string","nullable":true,"description":"Country where the VAT code applies (ISO 3166-1 alpha-2).","example":"NL"}}},"SalesInvoiceLine":{"type":"object","description":"Single invoice line containing product quantities, pricing and VAT details.","properties":{"description":{"type":"string","description":"Description of the invoice line.","example":"Consulting services March"},"productQuantity":{"type":"number","format":"double","description":"Quantity of units sold in this invoice line.","example":5},"productSalesPrice":{"type":"number","format":"double","description":"Sales price per unit for the line.","example":125.5},"vatCode":{"type":"string","description":"Identifier of the VAT code applied to the line.","example":"VATExempt"},"totalAmount":{"type":"number","format":"double","description":"Total amount of the invoice line including VAT when applicable.","example":756.25},"vatAmount":{"type":"number","format":"double","description":"VAT amount applied to the invoice line.","example":131.25},"amountExcludingVat":{"type":"number","format":"double","description":"Amount of the invoice line excluding VAT.","example":625},"itemDescription":{"type":"string","description":"Description of the item used in the invoice line.","example":"Consulting hourly package"},"itemReference":{"type":"string","description":"Reference of the item used in the invoice line.","example":"CONS-001"},"glAccountCode":{"type":"string","description":"GL account on which the invoice line is booked.","example":"8000"},"remarks":{"type":"string","description":"Additional remarks for the invoice line.","example":"Urgent processing required"}}},"SalesInvoice":{"type":"object","description":"Represents a sales invoice including totals, contact details and invoice lines.","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the sales invoice.","example":"8c2d1c2f-9c55-4a5e-9b71-8b2db4a23e91"},"reference":{"type":"string","description":"Reference or invoice number of the sales invoice.","example":"INV-2025-00045"},"subject":{"type":"string","description":"Subject of the sales invoice.","example":"Consulting services"},"invoiceDate":{"type":"string","format":"date","description":"Date of the invoice.","example":"2025-01-10"},"dueDate":{"type":"string","format":"date","description":"Due date of the invoice.","example":"2025-02-09"},"invoiceAmount":{"type":"number","format":"double","description":"Total invoice amount including VAT.","example":756.25},"invoiceVatAmount":{"type":"number","format":"double","description":"Total VAT amount of the invoice.","example":131.25},"invoiceAmountExcludingVat":{"type":"number","format":"double","description":"Invoice amount without VAT.","example":625},"paymentMethod":{"type":"string","description":"Payment method of the sales invoice. One of the standard Yuki payment methods (ElectronicTransfer, DirectCollection, Cash, DebitCard, CreditCard, ReceivedElectronically, ReceivedCash, ToSettle, PaidFromEquity, ReceivedInEquity, iDeal, Online) or the description of a custom payment method configured in the administration.","example":"ElectronicTransfer"},"paymentId":{"type":"string","description":"Payment identifier of the sales invoice.","example":"PAY-88391"},"paymentStatus":{"type":"string","description":"Payment status of the invoice.","enum":["NotYetPaid","PartiallyPaid","Paid"],"example":"NotYetPaid"},"openAmount":{"type":"number","format":"double","description":"Open amount remaining on the invoice.","example":756.25},"currency":{"type":"string","description":"Currency of the invoice"},"projectId":{"type":"string","format":"uuid","nullable":true,"description":"Identifier of the project the invoice is assigned to.","example":"b6a2b240-1f1b-4a44-90d9-97b9c2e6c0f7"},"projectCode":{"type":"string","nullable":true,"description":"Code of the project the invoice is assigned to."},"remarks":{"type":"string","nullable":true,"description":"Additional remarks of the invoice.","example":"Pay within 30 days"},"priceList":{"type":"string","nullable":true,"description":"Price list used for the invoice.","example":"Standard"},"created":{"type":"string","format":"date-time","description":"Timestamp when the invoice was created.","example":"2025-01-10T10:00:00Z"},"modified":{"type":"string","format":"date-time","description":"Timestamp when the invoice was last modified.","example":"2025-01-11T14:30:00Z"},"contact":{"type":"object","description":"Contact associated with the sales invoice.","properties":{"id":{"type":"string","format":"uuid","description":"GUID of the contact.","example":"f47ac10b-58cc-4372-a567-0e02b2c3d479"},"name":{"type":"string","description":"Name of the contact.","example":"John Doe"}}},"invoiceLines":{"type":"array","description":"Invoice lines that make up the sales invoice.","items":{"$ref":"#/components/schemas/SalesInvoiceLine"},"minItems":1}}},"SalesInvoicePagedResult":{"allOf":[{"$ref":"#/components/schemas/PagedResult"},{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SalesInvoice"}}}}]},"CreateSalesInvoiceRequest":{"type":"object","description":"Request payload to create a sales invoice for an administration.","properties":{"reference":{"type":"string","description":"Reference or invoice number of the sales invoice.","example":"INV-2025-00045"},"subject":{"type":"string","description":"Subject of the sales invoice.","example":"Consulting services"},"process":{"type":"boolean","description":"Should the invoice be processed out of the box."},"sendToPeppol":{"type":"boolean","description":"Indicates whether the invoice should be sent via Peppol."},"emailToCustomer":{"type":"boolean","description":"Indicates whether the invoice should be emailed to the customer."},"invoiceDate":{"type":"string","format":"date","description":"Date of the invoice.","example":"2025-01-10"},"dueDate":{"type":"string","format":"date","description":"Due date of the invoice.","example":"2025-02-09"},"paymentMethod":{"type":"string","description":"Payment method of the sales invoice. One of the standard Yuki payment methods (ElectronicTransfer, DirectCollection, Cash, DebitCard, CreditCard, ReceivedElectronically, ReceivedCash, ToSettle, PaidFromEquity, ReceivedInEquity, iDeal, Online) or the description of a custom payment method configured in the administration. Defaults to ElectronicTransfer.","example":"ElectronicTransfer"},"paymentId":{"type":"string","description":"Payment identifier of the sales invoice.","example":"PAY-88391"},"currency":{"type":"string","description":"Currency of the invoice."},"documentFileName":{"type":"string","description":"File name of the PDF visualization."},"documentBase64":{"type":"string","description":"Base64 string of the PDF visualization."},"layout":{"type":"string","description":"Yuki layout to be used for the invoice."},"projectId":{"type":"string","format":"uuid","description":"Identifier of the project the invoice is assigned to.","example":"b6a2b240-1f1b-4a44-90d9-97b9c2e6c0f7"},"projectCode":{"type":"string","description":"Code of the project the invoice is assigned to.","example":"PRJ-001"},"remarks":{"type":"string","description":"Additional remarks of the invoice."},"priceList":{"type":"string","description":"Price list used for the invoice.","example":"Standard"},"contactId":{"type":"string","format":"uuid","description":"GUID of the contact linked to the invoice.","example":"f47ac10b-58cc-4372-a567-0e02b2c3d479"},"invoiceLines":{"type":"array","description":"Lines to be included in the sales invoice.","minItems":1,"items":{"type":"object","properties":{"description":{"type":"string","description":"Description of the invoice line.","example":"Consulting services March"},"productQuantity":{"type":"number","description":"Quantity of units sold in this invoice line.","example":5},"productSalesPrice":{"type":"number","description":"Sales price per unit for the line.","example":125.5},"vatCode":{"type":"string","description":"VAT Code for the invoice line."},"vatIncluded":{"type":"boolean","description":"Whether productSalesPrice includes VAT. Input only; responses expose the computed line totals instead."},"itemDescription":{"type":"string","description":"Description of the item used in the invoice line."},"itemReference":{"type":"string","description":"Reference of the item used in the invoice line."},"glAccountCode":{"type":"string","description":"GL account on which the invoice line is booked."},"remarks":{"type":"string","description":"Additional remarks for the invoice line."}}}}},"required":["invoiceDate","contactId","invoiceLines"]},"ValidationProblemDetails":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","description":"ProblemDetails as returned when the request fails model binding or field validation. The body is a 400 with title \"One or more validation errors occurred.\" and errorCode validation:invalid_input, and every errors key is the name of a rejected field.","properties":{"errors":{"type":"object","description":"One entry per rejected field, keyed by field name, holding the validation messages reported for that field.","additionalProperties":{"type":"array","items":{"type":"string"}},"example":{"fieldName":["Error message for the field"]}}}}]},"DomainStatusRead":{"type":"string","enum":["Startup","Active","Inactive","Archived"],"description":"The status of the domain for read purposes.","example":"Active"},"Domain":{"type":"object","properties":{"id":{"type":"string","example":"e7ff8d6e-d82a-4649-be6e-523db02052d3"},"name":{"type":"string","example":"Example Domain"},"hid":{"type":"string","example":"abcd1234"},"type":{"type":"string","example":"Business"},"status":{"$ref":"#/components/schemas/DomainStatusRead"},"country":{"type":"string","example":"Netherlands"},"owner":{"type":"object","properties":{"name":{"type":"string","example":"John Doe"},"email":{"type":"string","format":"email","example":"john.doe@yuki.nl"}}},"backoffice":{"type":"object","properties":{"selfAccountingActive":{"type":"boolean","example":true},"message":{"type":"string","example":"All systems operational"},"responsible":{"type":"object","properties":{"id":{"type":"string","example":"user1"},"name":{"type":"string","example":"JaneSmith"}}},"backupResponsible":{"type":"object","properties":{"id":{"type":"string","example":"user1"},"name":{"type":"string","example":"JaneSmith"}}},"controller":{"type":"object","properties":{"id":{"type":"string","example":"user1"},"name":{"type":"string","example":"JaneSmith"}}},"accountManager":{"type":"object","properties":{"id":{"type":"string","example":"user1"},"name":{"type":"string","example":"JaneSmith"}}}}},"createdDate":{"type":"string","format":"date-time","example":"2023-01-01T10:00:00Z"},"createdBy":{"type":"string","example":"Admin User"},"modifiedDate":{"type":"string","format":"date-time","example":"2023-01-15T15:30:00Z"},"modifiedBy":{"type":"string","example":"Moderator"},"lastUserLogin":{"type":"string","format":"date-time","example":"2023-01-20T09:00:00Z"},"lastDocumentUpload":{"type":"string","format":"date-time","example":"2023-01-18T14:45:00Z"},"comments":{"type":"string","nullable":true,"description":"Free-form remarks stored on the domain.","example":"Migrated from legacy portal"},"contract":{"type":"object","properties":{"bundle":{"type":"string","example":"Medium"},"startDate":{"type":"string","format":"date","example":"2023-01-01"},"endDate":{"type":"string","format":"date","example":"2024-01-01"}}}}},"DomainStatusCreate":{"type":"string","enum":["Startup","Active"],"description":"The status of the domain for creation purposes.","example":"Active"},"DomainBundle":{"type":"string","enum":["Minimal","Small","Medium","Large","Unlimited"],"description":"The bundle type for the domain.","example":"Medium"},"Language":{"type":"string","enum":["nl-BE","en-US","fr-BE","nl-NL"],"description":"The locale for the domain. \\\nBE: nl-BE, en-US, fr-BE. \\\nNL: en-US, nl-NL\n","example":"en-US"},"CreateDomainCompanyDetails":{"type":"object","properties":{"cocNumber":{"type":"string","description":"The legal identifier of the company.","example":"BE0123456789"},"country":{"type":"string","description":"Country ISO code. Must match the country of the portal in which the domain is created.","example":"NL"}},"required":["country"],"description":"Company details information object."},"DomainCompanyFinancials":{"type":"object","properties":{"pettyCash":{"$ref":"#/components/schemas/PettyCashOption"},"financialYearFollowsCalendarMonths":{"type":"boolean","description":"Whether the financial year follows calendar months.","example":true},"yukiStartKeepingFinancialRecordsYear":{"type":"string","description":"The year when Yuki started keeping financial records.","example":"2023"},"yukiStartKeepingFinancialRecordsDate":{"type":"string","format":"date-time","description":"The date when Yuki started keeping financial records.","example":"2023-01-01T00:00:00Z"}},"description":"Financial object containing financial-related settings."},"CompanyTaxInformation":{"type":"object","properties":{"vatLiable":{"type":"boolean","description":"Whether the company is VAT liable.","example":true},"vatNumber":{"type":"string","description":"VAT number. Must be a valid VAT number for the company's country (details.country), including its country prefix; the request is rejected with 400 domains:validation_failed otherwise. The value is normalised to the national notation before it is stored, so the number returned by Get Company can differ from the one supplied here (for example BE0531247818 is returned as BE0531.247.818).","example":"NL123456782B01"},"showVatReturn":{"type":"boolean","description":"Whether to show VAT return.","example":true},"autoICPDeclaration":{"type":"boolean","description":"Whether to automatically generate ICP declaration.","example":false}},"description":"Company tax information object."},"CreateCompany":{"type":"object","properties":{"name":{"type":"string","description":"The name of the company.","example":"Example Corp"},"address":{"$ref":"#/components/schemas/ContactAddress"},"mailingAddress":{"$ref":"#/components/schemas/ContactAddress"},"details":{"$ref":"#/components/schemas/CreateDomainCompanyDetails"},"legalForm":{"$ref":"#/components/schemas/LegalForm"},"internalCustomerCode":{"type":"string","description":"The internal code that a company is defined with by the user.","example":"CUST-001"},"financials":{"$ref":"#/components/schemas/DomainCompanyFinancials"},"taxInformation":{"$ref":"#/components/schemas/CompanyTaxInformation"}},"required":["name","details"],"description":"Company information object."},"BackOffice":{"type":"object","description":"Back office configuration settings.","required":["access"],"properties":{"access":{"type":"string","enum":["AllEmployees","EmployeesBODomain","AllEmployeesSupport","EmployeesBODomainSupport"],"description":"Access level for the back office. Determines who can access the back office. Possible values: - AllEmployees: All employees have access. - EmployeesBODomain: Only employees of the BO domain have access. - AllEmployeesSupport: All employees have access, including support. - EmployeesBODomainSupport: Only employees of the BO domain and support have access.\n","example":"AllEmployees"},"responsible":{"type":"string","nullable":true,"description":"BO Responsible user ID.\nIf value is filled it will be updated, if empty string it will be disassociated, and if null no value will be created.\n","example":"user123"},"backup":{"type":"string","nullable":true,"description":"BO Backup user ID.\nIf value is filled it will be updated, if empty string it will be disassociated, and if null no value will be created.\n","example":"user456"},"controller":{"type":"string","nullable":true,"description":"BO Controller user ID.\nIf value is filled it will be updated, if empty string it will be disassociated, and if null no value will be created.\n","example":"user789"},"accountManager":{"type":"string","nullable":true,"description":"BO Account manager user ID.\nIf value is filled it will be updated, if empty string it will be disassociated, and if null no value will be created.\n","example":"user012"}}},"CreateDomain":{"type":"object","properties":{"name":{"type":"string","description":"The domain name. Only lowercase letters, numbers and dashes are allowed, and it must start with a letter or number.","example":"my-company-name"},"status":{"$ref":"#/components/schemas/DomainStatusCreate"},"bundle":{"$ref":"#/components/schemas/DomainBundle"},"language":{"$ref":"#/components/schemas/Language"},"company":{"$ref":"#/components/schemas/CreateCompany"},"createCustomerUser":{"type":"boolean","description":"Whether to also create a user account for the customer. When true, the customer (customerName/customerEmail) is invited as the first user of the domain: an invitation email is sent and, once accepted, the customer can log in with management permissions. When false, no user account is created and no email is sent. In both cases the customer is registered as the main contact person of the company created together with the domain.","example":true},"customerName":{"type":"string","description":"The full name of the customer. Always required, regardless of createCustomerUser: together with customerEmail it identifies the main contact person of the company created together with the domain.","example":"John Doe"},"customerEmail":{"type":"string","format":"email","description":"The email address of the customer. Always required, regardless of createCustomerUser: it is stored on the main contact person of the company created together with the domain and, when createCustomerUser is true, it is also used to send the invitation email.","example":"john.doe@yuki.nl"},"backoffice":{"$ref":"#/components/schemas/BackOffice"}},"required":["name","status","bundle","language","company","createCustomerUser","customerName","customerEmail"],"title":"CreateDomain","description":"Schema for creating a new domain."},"UpdateBackOffice":{"type":"object","description":"Back office configuration settings for updating a domain. All fields are optional; only the fields that are supplied are updated.\n","properties":{"access":{"type":"string","enum":["AllEmployees","EmployeesBODomain","AllEmployeesSupport","EmployeesBODomainSupport"],"description":"Access level for the back office. Determines who can access the back office. If omitted, the access level is left unchanged. Possible values: - AllEmployees: All employees have access. - EmployeesBODomain: Only employees of the BO domain have access. - AllEmployeesSupport: All employees have access, including support. - EmployeesBODomainSupport: Only employees of the BO domain and support have access.\n","example":"AllEmployees"},"responsible":{"type":"string","nullable":true,"description":"BO Responsible user ID.\nIf value is filled it will be updated, if empty string it will be disassociated, and if null no value will be created.\n","example":"user123"},"backup":{"type":"string","nullable":true,"description":"BO Backup user ID.\nIf value is filled it will be updated, if empty string it will be disassociated, and if null no value will be created.\n","example":"user456"},"controller":{"type":"string","nullable":true,"description":"BO Controller user ID.\nIf value is filled it will be updated, if empty string it will be disassociated, and if null no value will be created.\n","example":"user789"},"accountManager":{"type":"string","nullable":true,"description":"BO Account manager user ID.\nIf value is filled it will be updated, if empty string it will be disassociated, and if null no value will be created.\n","example":"user012"}}},"UpdateDomain":{"type":"object","properties":{"backoffice":{"$ref":"#/components/schemas/UpdateBackOffice"}},"required":["backoffice"],"title":"UpdateDomain","description":"Schema for updating an existing domain."},"Dummy":{"type":"object","properties":{"message":{"type":"string","example":"Hello from the Yuki domain API dummy endpoint"},"timestamp":{"type":"string","format":"date-time","example":"2026-07-07T10:00:00Z"}}},"DomainRoles":{"type":"array","description":"User roles for the domain","items":{"type":"string","enum":["Accountant","Backoffice","BackofficeController","FinAdmin","HRM","Management","Procurement","Purchase","Sales","SecurityManager","ReadOnlyUser"]}},"DomainUser":{"type":"object","properties":{"userId":{"type":"string","description":"The unique identifier of the user"},"name":{"type":"string","description":"Full name of the user","example":"John Doe"},"email":{"type":"string","format":"email","description":"User email","example":"john.doe@yuki.nl"},"roles":{"$ref":"#/components/schemas/DomainRoles"},"language":{"description":"The user's locale. Empty string when the stored value has no ISO mapping (e.g. the user never chose a language).\n","anyOf":[{"$ref":"#/components/schemas/Language"},{"type":"string","enum":[""]}]}},"required":["userId","name","email"]},"CreateDomainUser":{"type":"object","properties":{"firstName":{"type":"string","description":"First name of the user"},"lastName":{"type":"string","description":"Last name of the user"},"email":{"type":"string","format":"email","description":"User email","example":"john.doe@yuki.nl"},"language":{"$ref":"#/components/schemas/Language"},"roles":{"description":"Roles to grant the user in the domain. At least one role is required; an empty array is rejected with 400.","minItems":1,"allOf":[{"$ref":"#/components/schemas/DomainRoles"}]},"message":{"type":"string","description":"Optional message included in the invitation email sent to the new user. Applies only to domains using the legacy invitation flow;"},"companiesIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"List of company identifiers to grant access to. \nIf not provided or empty, the user will be granted access to all companies in the domain.\n","example":["123e4567-e89b-12d3-a456-426614174000","987fcdeb-51a2-3bc4-d567-890123456789"]}},"required":["firstName","lastName","email","language","roles"]},"Portal":{"type":"object","properties":{"id":{"type":"string","description":"The unique ID of the Portal","example":"3afb7b54-6144-4561-9a29-1148006f2375"},"name":{"type":"string","description":"Name of the Portal","example":"Example Portal"},"country":{"type":"string","description":"Country of the Portal in ISO-3166 (2 char) format"},"contact":{"type":"object","nullable":true,"description":"Contact person of the Portal. Null when no contact person is linked to the Portal","properties":{"id":{"type":"string","description":"ID of the contact","example":"3afb7b54-6144-4561-9a29-1148006f2375"},"name":{"type":"string","nullable":true,"description":"Name of the contact"}}},"subPortals":{"type":"array","description":"The Portal's direct (1st generation) child portals","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique ID of the child Portal","example":"3afb7b54-6144-4561-9a29-1148006f2375"},"name":{"type":"string","nullable":true,"description":"Name of the child Portal"}}}}}},"PortalUserRoles":{"type":"array","description":"User roles for portal users","items":{"type":"string","enum":["PortalAdministrator","PortalBackoffice","PortalBackofficeController","PortalDataEntry"]}},"PortalUser":{"type":"object","properties":{"id":{"type":"string","description":"The user's ID","example":"3afb7b54-6144-4561-9a29-1148006f2375"},"name":{"type":"string","description":"Full name of the user","example":"John Doe"},"email":{"type":"string","format":"email","description":"User email","example":"john.doe@yuki.nl"},"language":{"description":"The user's locale. Empty string when the stored value has no ISO mapping (e.g. the user never chose a language).\n","anyOf":[{"$ref":"#/components/schemas/Language"},{"type":"string","enum":[""]}]},"roles":{"$ref":"#/components/schemas/PortalUserRoles"}}},"CreatePortalUser":{"type":"object","properties":{"firstName":{"type":"string","description":"First name of the user"},"lastName":{"type":"string","description":"Last name of the user"},"email":{"type":"string","format":"email","description":"User email","example":"john.doe@yuki.nl"},"language":{"$ref":"#/components/schemas/Language"},"role":{"type":"string","description":"Role of the user","enum":["PortalAdministrator","PortalBackoffice","PortalDataEntry"]},"message":{"type":"string","description":"User message"}},"required":["firstName","lastName","email","language","role"]},"UpdatePortalUser":{"type":"object","properties":{"firstName":{"type":"string","description":"First name of the user"},"lastName":{"type":"string","description":"Last name of the user"},"language":{"$ref":"#/components/schemas/Language"},"roles":{"$ref":"#/components/schemas/PortalUserRoles"}},"required":["firstName","lastName","language","roles"]}},"responses":{"GetCompanyResponse":{"description":"Company object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}}}},"BadRequestResponse":{"description":"Bad Request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/BadRequestError"}}}},"UnauthorizedResponse":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}}},"ForbiddenResponse":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}}},"NotFoundResponse":{"description":"Not Found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/NotFoundError"}}}},"InternalServerErrorResponse":{"description":"Internal Server Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/InternalServerError"}}}},"ConflictResponse":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ConflictError"}}}},"UnprocessableEntityResponse":{"description":"Unprocessable Entity","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntityError"}}}},"BadGatewayResponse":{"description":"Bad Gateway","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/BadGatewayError"}}}},"GetContactsResponse":{"description":"Paged result of contacts","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PagedResult"},{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}}}}]},"examples":{"PagedContactsExample":{"summary":"A paged result containing both person and company contacts","value":{"totalItems":2,"offset":0,"limit":10,"items":[{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","name":"Acme Corporation","type":"Company","hid":654321,"code":"EXT002","address":{"address":"Main Street 123","address2":"Suite 456","postalCode":"1234 AB","city":"Amsterdam"},"country":"NL","phoneHome":"+31 20 765 4321","emailWork":"info@acme.example","website":"https://acme.example","tags":[],"created":"2024-01-01T12:00:00Z","modified":"2024-01-15T14:30:00Z","vatNumber":"NL123456782B01","cocNumber":"12345678","mainContactPersonId":"f47ac10b-58cc-4372-a567-0e02b2c3d479","mainContactPerson":"John William Doe","incomeTaxNumber":"123456789"},{"id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","name":"John William Doe","type":"Person","hid":123456,"code":"EXT001","address":{"address":"Main Street 123","address2":"Apartment 4B","postalCode":"1234 AB","city":"Amsterdam"},"country":"NL","phoneHome":"+31 20 123 4567","emailWork":"work@example.com","website":"https://johndoe.example","tags":["important"],"created":"2024-01-01T12:00:00Z","modified":"2024-01-15T14:30:00Z","nationalRegisterNumber":"12345678901"}]}}}}}},"CreateContactResponse":{"description":"Contact created successfully. Returns the ID of the newly created contact.","headers":{"Location":{"description":"The ID of the newly created contact - a bare GUID, not a URL","schema":{"type":"string","format":"uuid"},"example":"f47ac10b-58cc-4372-a567-0e02b2c3d479"}},"content":{"application/json":{"schema":{"type":"object","description":"Response containing the unique identifier of the newly created contact.","properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier of the newly created contact","example":"f47ac10b-58cc-4372-a567-0e02b2c3d479"}},"required":["id"]}}}},"GetContactResponse":{"description":"Single contact object retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"},"examples":{"ContactPersonExample":{"summary":"A contact of type Person","value":{"id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","name":"John William Doe","type":"Person","hid":123456,"code":"EXT001","address":{"address":"Main Street 123","address2":"Apartment 4B","postalCode":"1234 AB","city":"Amsterdam"},"country":"NL","phoneHome":"+31 20 123 4567","emailWork":"work@example.com","website":"https://johndoe.example","tags":["important"],"created":"2024-01-01T12:00:00Z","modified":"2024-01-15T14:30:00Z","nationalRegisterNumber":"12345678901"}},"ContactCompanyExample":{"summary":"A contact of type Company","value":{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","name":"Acme Corporation","type":"Company","hid":654321,"code":"EXT002","address":{"address":"Main Street 123","address2":"Suite 456","postalCode":"1234 AB","city":"Amsterdam"},"country":"NL","phoneHome":"+31 20 765 4321","emailWork":"info@acme.example","website":"https://acme.example","tags":[],"created":"2024-01-01T12:00:00Z","modified":"2024-01-15T14:30:00Z","vatNumber":"NL123456782B01","cocNumber":"12345678","mainContactPersonId":"f47ac10b-58cc-4372-a567-0e02b2c3d479","mainContactPerson":"John William Doe","incomeTaxNumber":"123456789"}}}}}},"DeleteContactResponse":{"description":"Contact deleted successfully"},"GetVatCodesResponse":{"description":"VAT codes retrieved successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PagedResult"},{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/VatCode"}}}}]}}}},"SalesInvoicesResponse":{"description":"Paged result of sales invoices","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesInvoicePagedResult"}}}},"CreateSalesInvoiceResponse":{"description":"Sales invoice created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesInvoice"}}}},"SalesInvoiceResponse":{"description":"Sales invoice retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesInvoice"}}}},"GetCompanyPagedResponse":{"description":"Paged result of companies","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PagedResult"},{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Company"}}}}]}}}},"GetDomainsPagedResponse":{"description":"Paged result of domains","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PagedResult"},{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Domain"}}}}]}}}},"CreateDomainResponse":{"description":"Domain successfully created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the created domain","example":"3afb7b54-6144-4561-9a29-1148006f2375"},"companyId":{"type":"string","description":"The unique identifier of the company created together with the domain","example":"8c2e0d11-4b7a-4f3e-9d02-5a6f31c9e842"}}}}}},"GetDomainResponse":{"description":"Domain object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Domain"}}}},"GetDummyResponse":{"description":"Static dummy payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dummy"}}}},"DomainUsersPagedResultResponse":{"description":"Paged result of domain users","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PagedResult"},{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/DomainUser"}}}}]}}}},"CreateDomainUserResponse":{"description":"Domain user successfully created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the created domain user","example":"3afb7b54-6144-4561-9a29-1148006f2375"}}}}}},"DomainUserResponse":{"description":"Successful domain user search response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainUser"}}}},"PortalResponse":{"description":"Portal object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Portal"}}}},"PortalUsersPagedResultResponse":{"description":"Paged result of portal users","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PagedResult"},{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PortalUser"}}}}]}}}},"PortalUserCreateResponse":{"description":"Portal user created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the created user","example":"3afb7b54-6144-4561-9a29-1148006f2375"}}}}}},"PortalUsersResponse":{"description":"Portal user object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalUser"}}}}},"parameters":{"AuthorizationHeader":{"name":"Authorization","in":"header","required":true,"description":"Bearer token for authentication","schema":{"type":"string"}},"DomainIdPath":{"name":"domain-id","in":"path","required":true,"description":"The domain name","example":"3afb7b54-6144-4561-9a29-1148006f2375","schema":{"type":"string"}},"CompanyIdPath":{"name":"company-id","in":"path","required":true,"description":"The ID of the company","example":"3afb7b54-6144-4561-9a29-1148006f2375","schema":{"type":"string","format":"uuid"}},"OffsetQuery":{"name":"offset","in":"query","required":false,"description":"Number of items to skip before collecting the result set. Defaults to 0; a negative value is rejected with 400.","schema":{"type":"integer","minimum":0,"default":0}},"LimitQuery":{"name":"limit","in":"query","required":false,"description":"Maximum number of items to return. Defaults to 20; a value outside 1-500 is rejected with 400.","schema":{"type":"integer","minimum":1,"maximum":500,"default":20}},"ContactIdPath":{"name":"contact-id","in":"path","required":true,"description":"The ID of the contact","schema":{"type":"string","format":"uuid"}},"SalesInvoiceIdPath":{"name":"sales-invoice-id","in":"path","required":true,"description":"Unique identifier of the sales invoice within the administration","schema":{"type":"string","format":"uuid"}},"SalesInvoiceReferenceQuery":{"name":"reference","in":"query","required":true,"description":"Reference or invoice number to look up a sales invoice","schema":{"type":"string"}},"PortalIdPath":{"name":"portal-id","in":"path","required":true,"description":"The portal id","example":"3afb7b54-6144-4561-9a29-1148006f2375","schema":{"type":"string"}},"EmailQuery":{"name":"email","in":"query","required":true,"description":"Email address to search for","schema":{"type":"string","format":"email"}},"GetUserIdPath":{"name":"user-id","in":"path","required":true,"description":"The user id","example":"3afb7b54-6144-4561-9a29-1148006f2375","schema":{"type":"string"}},"CustomerCodeQuery":{"name":"customerCode","in":"query","required":true,"description":"The internal customer code to search for","schema":{"type":"string"}},"CompanyIdQuery":{"name":"companyId","in":"query","required":true,"description":"The unique identifier of the company to search for","schema":{"type":"string","format":"uuid"}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"vismaConnectPortalUser":{"type":"oauth2","description":"Visma Connect token belonging to a **Portal User** - an employee of an accounting portal. The token's tenant must be a portal; the API resolves it to the caller's portal. The portal in the route must be that portal or one of the caller's master-accountant portals. Unless an endpoint says otherwise, the caller's roles are resolved against the portal.\n","flows":{"authorizationCode":{"authorizationUrl":"https://connect.identity.stagaws.visma.com/connect/authorize","tokenUrl":"https://connect.identity.stagaws.visma.com/connect/token","scopes":{"openid":"Required on every request, together with the endpoint API scope","yukiapi:domain:companies:read":"Allows reading information of a Company","yukiapi:domain:companies:update":"Allows the update of a Company","yukiapi:portal:portals:read":"Allows reading portal information","yukiapi:domain:domains:read":"Allows reading domains information","yukiapi:domain:domains:write":"Allows modifications of domain information, may include create/update","yukiapi:domain:domains:create":"Allows the creation of new domains","yukiapi:domain:domains:update":"Allows updating existing domain information","yukiapi:domain:domains:delete":"Allows the deletion of domain data","yukiapi:domain:users:read":"Allows reading of domain user data","yukiapi:domain:users:write":"Allows the creation of Domain Users","yukiapi:domain:users:delete":"Allows the deletion of Domain Users","yukiapi:portal:portals:write":"Allows updating existing portal information","yukiapi:portal:users:read":"Allows reading Portal user data","yukiapi:portal:users:write":"Allows the update of Portal user, may include create/update","yukiapi:portal:users:update":"Allows updating an existing Portal User","yukiapi:portal:users:delete":"Allows the deletion of a Portal User"}}}},"vismaConnectDomainUser":{"type":"oauth2","description":"Visma Connect token belonging to a **Domain User** - a user in a domain with access to one or more companies. The company the token was issued for must match the `company-id` in the route. The caller's roles are resolved in that company's domain.\n","flows":{"authorizationCode":{"authorizationUrl":"https://connect.identity.stagaws.visma.com/connect/authorize","tokenUrl":"https://connect.identity.stagaws.visma.com/connect/token","scopes":{"openid":"Required on every request, together with the endpoint API scope","yukiapi:company:contacts:read":"Allows reading contacts information","yukiapi:company:contacts:write":"Allows modifications of contacts information, may include create/update","yukiapi:company:contacts:create":"Allows the creation of new contacts","yukiapi:company:contacts:update":"Allows updating existing contacts information","yukiapi:company:contacts:delete":"Allows the deletion of contacts data","yukiapi:invoices:delete":"Allows the deletion of contacts and sales invoices","yukiapi:invoices:write":"Allows creating and modifying invoices and contacts","yukiapi:invoices:read":"Allows reading invoices, contacts and VAT codes"}}}}}},"tags":[{"name":"Company","description":"Operations related to companies"},{"name":"Contact","description":"Operations related to contacts"},{"name":"VAT","description":"Operations related to VAT codes of an administration"},{"name":"Sales Invoice","description":"Operations for managing sales invoices"},{"name":"Domain","description":"Operations related to domains"},{"name":"Domain User","description":"Operations related to users of domain"},{"name":"Portal","description":"Operations related to portals"},{"name":"Portal User","description":"Operations related to portal users"}],"security":[{"bearerAuth":[]}]} ```