Create Admin

Full JSON Schema for Creating & Updating Admins

📘

Note that this JSON schema differs subtly from the Admin object that is returned by the API. Use the format specified below, not the one returned.

Additionally, Admins created via the API will not automatically receive the "Welcome Email" sent when admins are created via the UI.

Required Fields

The minimum required fields are email, first_name and last_name. Using only the minimum required fields will create an admin in a Pending state. In order to complete provisioning of the Admin, a Full Access Admin will be required to select the role (Full Access or Restricted Access) in the UI. If the admin is assigned Restricted Access in the UI, an access policy will need to be applied and the specific Staff Groups to which the admin has access will need to be chosen.

/* NOTE that all of the admin data must be wrapped in an "admin" key: */
{  
  "admin": {
    "email": "[email protected]",  /* required! */
    "first_name": "Emerald",                /* required! */
    "middle_name": "J",
    "last_name": "Keebler"                  /* required! */
  }
}

Creating Fully Provisioned Admins

The JSON Schema below will allow API users to fully provision an Admin (Full Access or Restricted Access) without requiring interface within the UI.

{
  "admin": {
    "email": "[email protected]",
    "first_name": "Timothy", 
    "middle_name": "Albert",
    "last_name": "Jones", 
    "role": "restricted_admin",
    "policy": 2,         // Only available for restricted admin
    "groups": [          // Only available for restricted admin
      1
    ] 
  }
}

📘

A note on Policies

The "policy" value is retrieved from the List Managed Access Policies endpoint and is only available if that feature is enabled in the UI. All policies must be configured in the UI.

422 Errors

Occur in the following scenarios:

• Not all required fields are included. The error message will describe the missing field. This includes policy and groups if the role of restricted_admin is assigned.
• policy or groups are assigned to a pending_admin or an admin.
• An invalid group ID, policy ID, or role (not one of the three Admin Roles) is assigned.
• An email that already exists in the organization (admin or employee) is used to attempt to create a new admin. The error message will read: "This admin has already been created on this account with the CURRENT_ROLE role".

In each of these scenarios, the returned body will be a Hash called errors. The key is the field with the error, and the value is an array of strings containing the error message(s). See the given example for more.