# Create a sub-account Creates a sub-account directly beneath the one you are signed in to. The parent is always taken from the caller and cannot be set from the request. The response is the same shape as reading the account, so a follow-up read is not needed. Only `name` is required. Send `_options.create_admin` together with the four `contact_*` fields to create the account's first administrator at the same time, and add `_options.send_welcome` to email them an invitation - without an administrator, nobody can sign in to the new account yet. Leave `create_defaults` on unless you intend to configure the account from scratch; a sub-account without the default statuses, forms and templates is not usable on its own. **`meta` is stored whole.** The object you send replaces the stored one rather than merging into it, so send every key you want to keep. **Creating a sub-account is refused once the account has reached its configured limit on sub-accounts**, and the limit of any account above it applies too, so a parent at its own limit blocks the whole branch. Fields beyond the ones below are accepted from callers with elevated access. The account's own configured attributes are accepted as `custom_*` fields. The endpoint also accepts a `recipe` file - a blueprint to build the new account from, sent as `multipart/form-data` instead of JSON. It is left out of the parameters below because a blueprint comes from exporting an existing account, which is not part of the published API. Endpoint: POST /api/v2/account Version: 2.0.0 Security: default ## Header parameters: - `Rosterfy-Platform` (string) ## Request fields (application/json): - `name` (string, required) Display name of the sub-account, up to 255 characters. This is what people see in the account switcher and in anything branded with the account name. - `contact_firstname` (string) First name of the person to set up as the sub-account's first administrator. Required when _options.create_admin is set, and otherwise recorded as the account contact. - `contact_lastname` (string) Last name of that person. Required when _options.create_admin is set. - `contact_email` (string) Email address of that person, which becomes the administrator's sign-in address. Required when _options.create_admin is set. - `contact_phone` (string) Phone number of that person, in international format such as au-297809703. Required when _options.create_admin is set. - `_options` (object) - `_options.create_admin` (boolean) Whether to create an administrator in the new sub-account from the contact_* fields. Without it the contact details are stored but no one can sign in to the account yet. Create only. - `_options.send_welcome` (boolean) Whether to email that new administrator an invitation with a link to set their password. Only has an effect alongside _options.create_admin, and only when the account has a welcome email template configured. Create only. - `meta` (object) - `meta.publish` (boolean) Whether the sub-account is listed to people browsing the sub-accounts they could join. Unpublished accounts stay reachable by direct link. - `meta.hide_from_new_applicants` (boolean) Whether to keep the sub-account out of the list someone sees while registering. It stays visible to people who already have an account. - `meta.promote` (boolean) Whether to feature the sub-account ahead of the others. The number of promoted accounts an account may have at once is capped, and exceeding it is rejected. - `meta.join` (boolean) Whether people may join this sub-account themselves rather than being added to it. - `visibility_rules` (array) Optional conditions narrowing which people may see or join this sub-account. Structure is not part of the contract and is not validated - build the rules in the admin console and send back what a read returns. Send an empty array to clear them. - `sort_order` (integer) Position of the sub-account in lists that show a group of them together. Lower sorts first; accounts sharing a value fall back to name order. - `start_timestamp` (string) When the sub-account becomes active, as YYYY-MM-DD HH:MM:SS. Must be within 25 years either side of now. Leave null for an account that is active immediately. - `end_timestamp` (string) When the sub-account stops being active, as YYYY-MM-DD HH:MM:SS. Must be later than start_timestamp and within 25 years of now. Leave null for no end. - `create_defaults` (boolean) Whether to populate the new sub-account with the default statuses, forms and templates a usable account needs. Leave it off only when the account is going to be filled from elsewhere. Create only. - `locale` (string) Language the new sub-account starts in, as a locale code such as en or fr. Also becomes the only language available in it until more are added. Create only. - `custom_*` (string) A custom attribute, named by its code - custom_shirt_size, for example. The value follows the attribute's own type, so it may be a string, a number, a boolean or a list. See the custom attributes documentation. ## Response 201 fields (application/json): - `object` (object) - `object.id` (integer) - `object.parent_id` (integer) - `object.account_type_id` (integer) - `object.path` (string) - `object.name` (string) - `object.config` (object) - `object.config.active_settings` (array) - `object.meta` (array) - `object.visibility_rules` (array) - `object.status` (string) - `object.status_reason` (string | null) - `object.sort_order` (integer) - `object.start_timestamp` (string | null) - `object.end_timestamp` (string | null) - `object.notes` (string | null) - `object.contact_firstname` (string | null) - `object.contact_lastname` (string | null) - `object.contact_email` (string | null) - `object.contact_phone` (string | null) - `object.support_manager_email` (string) - `object.allow_deletion_request` (integer) - `object.organization_type` (string | null) - `object.contract_start_date` (string) - `object.contract_end_date` (string) - `object.billing_contact_email` (string) - `object.billing_support_email` (string) - `object.is_enabled` (integer) - `object.additional_billing_support_email` (string) - `object.delete_requested_at` (string | null) - `object.is_archived` (integer) - `object.trial_ends_at` (string | null) - `object.can_erase` (integer) - `object.deleted_at` (string | null) - `object.is_erased` (integer) - `object.created_at` (string) - `object.updated_at` (string) - `object.domain` (array) - `nice` (object) - `nice.rrn` (string) - `nice.address` (string) - `nice.address_oneline` (string) - `nice.account_type_id` (integer) - `nice.account_type_id:value` (integer) - `nice.account_type_id:array` (integer) - `nice.allow_deletion_request` (string) - `nice.contact_firstname` (string) - `nice.contact_lastname` (string) - `nice.contact_phone:qr_code_value` (string) - `nice.contact_phone` (string) - `nice.contact_phone:raw` (string) - `nice.contract_end_date` (string) - `nice.contract_end_date__dayofweek` (string) - `nice.contract_start_date` (string) - `nice.contract_start_date__dayofweek` (string) - `nice.name` (string) - `nice.notes` (string) - `nice.organization_type` (string | null) - `nice.organization_type:value` (string | null) - `nice.organization_type:array` (string | null) - `nice.status` (string) - `nice.status:value` (string) - `nice.status:array` (string) - `nice.status_reason` (string) - `nice.created_at` (string) - `nice.url` (string) - `nice.branding_name` (string) - `nice.branding_subtitle` (string | null) - `nice.branding_logo` (string | null) - `nice.branding_logo_mono` (string | null) - `nice.branding_logo_stacked` (string | null) - `nice.branding_banner` (string | null) - `nice.branding_favicon` (string | null) - `nice.branding_description` (string | null) - `nice.branding_primary_color` (string) - `nice.branding_complimentary_color` (string | null) - `nice.branding_secondary_color` (string) - `nice.register` (boolean) - `nice.organisation_contact` (string) - `nice.has_subaccount_approved_email_template` (boolean) - `nice.has_subaccount_rejected_email_template` (boolean) - `nice.parent_account_name` (string) - `relations` (object) - `relations.current_user_checkpoint` (object) - `relations.current_user_checkpoint.object` (object) - `relations.current_user_checkpoint.object.id` (integer) - `relations.current_user_checkpoint.object.user_checkpoint_type_id` (string | null) - `relations.current_user_checkpoint.object.name` (string) - `relations.current_user_checkpoint.object.label` (string) - `relations.current_user_checkpoint.object.permissions` (object) - `relations.current_user_checkpoint.object.permissions.all` (string) - `relations.current_user_checkpoint.object.actions` (array) - `relations.current_user_checkpoint.object.is_inheritable` (integer) - `relations.current_user_checkpoint.object.sort_order` (integer) - `relations.current_user_checkpoint.object.deleted_at` (string | null) - `relations.current_user_checkpoint.object.created_at` (string) - `relations.current_user_checkpoint.object.updated_at` (string) - `relations.current_user_checkpoint.nice` (object) - `relations.current_user_checkpoint.nice.rrn` (string) - `relations.current_user_checkpoint.nice.content_id` (integer) - `relations.current_user_checkpoint.nice.account_name_path` (string) - `relations.current_user_checkpoint.nice.is_foreign_account` (boolean) - `relations.current_user_checkpoint.permissions` (object) - `relations.current_user_checkpoint.permissions.read` (boolean) - `relations.current_user_checkpoint.permissions.update` (boolean) - `relations.current_user_checkpoint.permissions.delete` (boolean) - `relations.parent` (array) - `relations.account` (array) - `permissions` (object) - `permissions.read` (boolean) - `permissions.update` (boolean) - `permissions.delete` (boolean) - `permissions.apply` (boolean) - `permissions.apply_error` (string) - `permissions.view_subaccount_selection_menu` (boolean) - `attributes` (object)