---
title: "Create Domain"
url: "https://developer.yukisoftware.com/apis/yuki-platform-api-prod-1/versions/1237fe18-1f8f-477a-8f52-b3546dd409bf/operations/createDomain"
---

> Full API specification: https://developer.yukisoftware.com/apis/yuki-platform-api-prod-1/versions/1237fe18-1f8f-477a-8f52-b3546dd409bf.md

# Create Domain

`POST` `/portals/{portal-id}/domains`

Operation ID: `createDomain`

This endpoint allows the creation of a new domain. Ensure you have the necessary permissions before attempting to create a domain. You should have yukiapi:domain:domains:create and yukiapi:domain:domains:write scopes to access this endpoint. <!-- authorization:start --> **Authorization** Called with a **Portal User** token - an employee of an accounting portal. The caller must hold at least one of these roles: `AccountantManagement`, `Accountant`. <!-- authorization:end -->

## Path parameters

- `portal-id` (string, required) - The portal id

## Header parameters

- `Authorization` (string, required) - Bearer token for authentication
- `Content-Type` (string, required) - Content type of the request body

## Request body (required)

Content types: `application/json`

## Responses

- `201` - Domain successfully created
- `400` - Bad Request
- `401` - Unauthorized
- `403` - Forbidden
- `500` - Internal Server Error

## OpenAPI definition

```yaml
openapi: 3.0.0
info:
  title: Yuki Platform API Prod
  version: 1.0.52
servers:
  - url: https://apirest.yukiworks.com/api/v1
paths:
  /portals/{portal-id}/domains:
    post:
      x-environments:
        - development
        - pilot
        - production
      x-portal-visibility:
        - internal
        - trusted
        - prod
      x-required-roles:
        - any-of:
            - AccountantManagement
            - Accountant
      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 yukiapi:domain:domains:create and yukiapi:domain:domains:write
        scopes to access this endpoint.


        <!-- authorization:start -->


        **Authorization**


        Called with a **Portal User** token - an employee of an accounting
        portal.


        The caller must hold at least one of these roles:
        `AccountantManagement`, `Accountant`.


        <!-- authorization:end -->
      operationId: createDomain
      tags:
        - Domain
      parameters:
        - $ref: "#/components/parameters/AuthorizationHeader"
        - $ref: "#/components/parameters/ContentTypeHeader"
        - $ref: "#/components/parameters/PortalIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateDomain"
      security:
        - vismaConnectPortalUser:
            - yukiapi:domain:domains:create
            - 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"
        "500":
          $ref: "#/components/responses/InternalServerErrorResponse"
security:
  - vismaConnectPortalUser:
      - yukiapi:domain:domains:create
      - yukiapi:domain:domains:write
components:
  parameters:
    AuthorizationHeader:
      name: Authorization
      in: header
      required: true
      description: Bearer token for authentication
      schema:
        type: string
    ContentTypeHeader:
      name: Content-Type
      in: header
      required: true
      description: Content type of the request body
      schema:
        type: string
        default: application/json
    PortalIdPath:
      name: portal-id
      in: path
      required: true
      description: The portal id
      example: 3afb7b54-6144-4561-9a29-1148006f2375
      schema:
        type: string
  schemas:
    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
      additionalProperties: false
      title: CreateDomain
      description: Schema for creating a new domain.
    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. \
        BE: nl-BE, en-US, fr-BE. \
        NL: en-US, nl-NL
      example: en-US
    CreateCompany:
      type: object
      properties:
        name:
          type: string
          description: The name of the company.
          example: Example Corp
        internalCustomerCode:
          type: string
          description: The internal code that a company is defined with by the user.
          example: CUST-001
        details:
          $ref: "#/components/schemas/CreateDomainCompanyDetails"
        legalInformation:
          $ref: "#/components/schemas/CompanyLegalInformation"
        address:
          $ref: "#/components/schemas/ContactAddress"
        mailingAddress:
          $ref: "#/components/schemas/ContactAddress"
        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.
          example: AllEmployees
        responsible:
          type: string
          nullable: true
          description: >
            BO Responsible user ID.

            If value is filled it will be updated, if empty string it will be
            disassociated, and if null no value will be created.
          example: user123
        backup:
          type: string
          nullable: true
          description: >
            BO Backup user ID.

            If value is filled it will be updated, if empty string it will be
            disassociated, and if null no value will be created.
          example: user456
        controller:
          type: string
          nullable: true
          description: >
            BO Controller user ID.

            If value is filled it will be updated, if empty string it will be
            disassociated, and if null no value will be created.
          example: user789
        accountManager:
          type: string
          nullable: true
          description: >
            BO Account manager user ID.

            If value is filled it will be updated, if empty string it will be
            disassociated, and if null no value will be created.
          example: user012
    BadRequestError:
      allOf:
        - $ref: "#/components/schemas/ProblemDetails"
      example:
        type: https://example.com/errors/bad-request
        title: Bad Request
        status: 400
        detail: The request is invalid or malformed.
        instance: /example/bad-request
    UnauthorizedError:
      allOf:
        - $ref: "#/components/schemas/ProblemDetails"
      example:
        type: https://example.com/errors/unauthorized
        title: Unauthorized
        status: 401
        detail: Authentication is required.
        instance: /example/unauthorized
    ForbiddenError:
      allOf:
        - $ref: "#/components/schemas/ProblemDetails"
      example:
        type: https://example.com/errors/forbidden
        title: Forbidden
        status: 403
        detail: You do not have permission to access this resource.
        instance: /example/forbidden
    InternalServerError:
      allOf:
        - $ref: "#/components/schemas/ProblemDetails"
      example:
        type: https://example.com/errors/internal-server-error
        title: Internal Server Error
        status: 500
        detail: An unexpected error occurred.
        instance: /example/internal-server-error
    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.
    CompanyLegalInformation:
      type: object
      properties:
        type:
          type: integer
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
            - 7
            - 8
            - 9
          description: |
            Legal form of the company:
            0 - Unknown
            1 - SolePartnership
            2 - PrivateLimited
            3 - PublicLimited
            4 - GeneralPartnership
            5 - LimitedPartnership
            6 - Partnership
            7 - Association
            8 - Foundation
            9 - Cooperative
          example: 2
      description: Company legal information object.
    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.
    DomainCompanyFinancials:
      type: object
      properties:
        pettyCashOption:
          $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.
          example: NL123456789B01
        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.
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          example: https://dev.yuki.nl/errors/problem
        title:
          type: string
          example: Problem
        status:
          type: integer
          example: 500
        detail:
          type: string
          example: An unexpected error occurred.
        instance:
          type: string
          example: /example/endpoint
    PettyCashOption:
      type: string
      nullable: true
      enum:
        - Unknown
        - Regularly
        - Petty
        - None
      description: |
        Cash usage option: Unknown, Regularly, Petty, None
      example: Regularly
  responses:
    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
    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"
    InternalServerErrorResponse:
      description: Internal Server Error
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/InternalServerError"
  securitySchemes:
    vismaConnectPortalUser:
      type: oauth2
      description: >
        Visma Connect token belonging to a **Portal User** - an employee of an
        accounting portal. The token carries a `portal-id` claim, and the portal
        it identifies must match the portal in the route. Unless an endpoint
        says otherwise, the caller's roles are resolved against the portal.
      flows:
        authorizationCode:
          authorizationUrl: https://connect.identity.stagaws.visma.com/connect/authorize
          tokenUrl: https://connect.identity.stagaws.visma.com/connect/token
          scopes:
            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 update of domain user data, may include create/update
            yukiapi:domain:users:update: Allows updating a Domain User
            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
```