--- title: "Create Domain User" url: "https://developer.yukisoftware.com/apis/yuki-platform-api-prod-1/versions/9cdc452d-fd77-4e06-8797-f61e76134ec9/operations/createDomainUser" --- > Full API specification: https://developer.yukisoftware.com/apis/yuki-platform-api-prod-1/versions/9cdc452d-fd77-4e06-8797-f61e76134ec9.md # Create Domain User `POST` `/domains/{domain-id}/users` Operation ID: `createDomainUser` 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. **Authorization** Called with a **Portal User** token - an employee of an accounting portal. The caller must hold at least one of these roles in the portal: `AccountantManagement`, `Accountant`. ## Path parameters - `domain-id` (string, required) - The domain name ## Header parameters - `Authorization` (string, required) - Bearer token for authentication ## Request body (required) Content types: `application/json` ## Responses - `201` - Domain user successfully created - `400` - Bad Request - `401` - Unauthorized - `403` - Forbidden - `409` - Conflict - `500` - Internal Server Error ## OpenAPI definition ```yaml openapi: 3.0.0 info: title: Yuki Platform API Prod version: 1.0.77 servers: - url: https://apirest.yukiworks.be/api/v1 paths: /domains/{domain-id}/users: 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. **Authorization** Called with a **Portal User** token - an employee of an accounting portal. The caller must hold at least one of these roles in the portal: `AccountantManagement`, `Accountant`. 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" security: - vismaConnectPortalUser: - openid - yukiapi:domain:users:write components: 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 schemas: 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. If not provided or empty, the user will be granted access to all companies in the domain. example: - 123e4567-e89b-12d3-a456-426614174000 - 987fcdeb-51a2-3bc4-d567-890123456789 required: - firstName - lastName - email - language - roles 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 DomainRoles: type: array description: User roles for the domain items: type: string enum: - Accountant - Backoffice - BackofficeController - FinAdmin - HRM - Management - Procurement - Purchase - Sales - SecurityManager - ReadOnlyUser 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. 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. 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. 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. responses: 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 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" ConflictResponse: description: Conflict content: application/problem+json: schema: $ref: "#/components/schemas/ConflictError" 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'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. 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 ```