User Management API overview

What is User Management API?

The User Management API provides your organization the ability to programmatically create user accounts within an existing Amazon Business account. Each user is created with the name, email, and role specified in the request, allowing your admins to easily manage account users. By using this API, your organization can provision users according to Amazon Business standards.

Benefits of User Management API

The User Management API provides the following benefits:

Programmatic user creation

User Management API can streamline your onboarding processes by automating the process of user account creation.

Time and cost savings

User Management API reduces manual administrative tasks for opening accounts, saving time and resources for your IT teams.

Consistent user experience

When implemented along with other products, such as Product Search API and Ordering API, User Management API can enable a uniform experience across the search and ordering processes by returning accurate results for the user’s specific permissions and policies, displaying relevant guided buying policies, and accommodating multiple legal entities.

How User Management API works

You can provision new user accounts by passing a request to User Management API.

Operation

User Management supports the following operation:

Operation	Method	Path	Description
`createBusinessUserAccount`	POST	/businessAccounts/2021-08-30/businessUserAccount	Creates a new Amazon Business user account with a specified name and email, and an autogenerated password. Adds the account holder to the specified group with an specified role. The account holder will receive an email message to update the account password.

Registering a new user account

Prerequisites

Before you begin integrating with the User Management API, ensure you have completed the following steps:

Complete the API onboarding process to register as a developer, create an app client, and retrieve API access and refresh tokens. For more information, see Onboarding overview.
Reach out to your Amazon Business technical contact to gain access to the User Management role. For more information, see Amazon Business API roles.
Enable Account Authority to ensure that your email domain is allow-listed for registering users. For more information, reach out to your Amazon Business technical contact.

Register a new account

Call the createBusinessUserAccount operation to register a new account. In the request, include the following attributes:

Name	Description	Schema	Required
`accountHolder`	The name of the account holder to whom the Amazon Business user account will be created for. The account holder's email shouldn't be associated to an existing Amazon Business user account.	AccountHolder	Yes
`groupId`	A group identifier that indicates which business group the account holder will be added to. The ID should already exist before adding a user. The `idType` can be `GroupId` or `GroupTag`. For confirmation on the correct ID to pass in the `id` field, reach out to your Amazon Business technical contact.	BusinessGroupIdentifier	Yes
`role`	The business role that will be assigned to the account holder.	BusinessRole	Yes
`region`	The country or region where the user account will be created.	Region	Yes
`notificationTypesToSuppress`	A list of enums that specifies the types of notification to suppress.	< NotificationType > array	No

POST https://na.business-api.amazon.com/businessAccounts/2021-08-30/businessUserAccount

{
  "accountHolder": {
    "email": "[email protected]",
    "givenName": "Jane",
    "familyName": "Doe"
  },
  "groupId": {
    "idType": "GroupId",
    "id": "A2Z379D4K6H123"
  },
  "role": "Requisitioner",
  "region": "US",
  "notificationTypesToSuppress": [
    "EMAIL"
  ]
}

import requests

url = "https://na.business-api.amazon.com/businessAccounts/2021-08-30/businessUserAccount "

payload = {
  "accountHolder": {
    "email": "[email protected]",
    "givenName": "Jane",
    "familyName": "Doe"
  },
  "groupId": {
    "idType": "GroupId",
    "id": "A2Z379D4K6H123"
  },
  "role": "Requisitioner",
  "region": "US",
  "notificationTypesToSuppress": [
    "EMAIL"
  ]
}
headers = {
    "accept": "application/json",
    "x-amz-access-token": "<Access token retrieved in Prerequisites Step 1>",
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

A successful request returns an empty response with a 201 HTTP response code. After a successful request, the new user account is provisioned as part of the Amazon Business group. An email is sent to the new user’s email, prompting them to provide a new password.

201 OK

Error handling

If your request is not successful, the API returns an errors object that provides information about what went wrong. For more information, see Error responses and schemas.