How to create a Microsoft Tenant via the API

Introduction

This article explains how to create a new Microsoft Tenant (an onmicrosoft.com Domain) for a Customer Organization by using the Platform API instead of the Platform user interface. It covers how to check that the Domain name is free, how to send the Create a Tenant request, and how to confirm that the Tenant was created.

A Customer needs a valid Microsoft Tenant before it can buy Microsoft Offers. Creating the Tenant through the API lets you include this step in your own purchase flow. 

In this article:

• Prerequisites
• Request headers
• Step 1: Find the Customer ID
• Step 2: Validate the Domain name
• Step 3: Create the Tenant
• Step 4: Confirm the Tenant was created
• What happens after the Tenant is created
• Troubleshooting
• Important information
• Summary
• Related content

Prerequisites

Make sure the following is in place before you call the API:

• You have an active subscription on the AppXite developer portal for the product that includes the Customers API, and you have its subscription key.
• You can get a Bearer token for the Platform API. See Platform API Access for details.
• The Customer Organization already exists on the Platform.
• The Customer profile is complete and correct, including the address and Tax ID. These details are sent to Microsoft for validation when the Tenant is created.

Request headers

The Validate Domain Name and Create a Tenant operations use the following headers:

Step 1: Find the Customer ID

The Tenant is created for the Customer whose internal Organization ID you send in the X-On-Behalf-Of header.

1. Call the List all customers operation in the Customers API.
2. Find the Customer in the response and copy its internal ID.
3. Keep this ID. You use it in the X-On-Behalf-Of header in Step 3 and in the URL in Step 4.

Step 2: Validate the Domain name

Microsoft requires every Tenant Domain name to be unique. Create a Tenant accepts a request even when the name is already taken, so always check the name first.

POST https://api.appxite.com/customers/tenants/validateDomain

Request body. Send the Domain name without the .onmicrosoft.com part:

{
  "DomainName": "contosodemo",
  "VendorId": "af817907-beb0-4ce2-be96-b674de7a876b"
}

The operation returns 200 OK in both cases. Read the IsValid field:

Option A: The Domain name is available

{
  "ErrorMessage": "",
  "IsValid": true
}

Continue to Step 3.

Option B: The Domain name is taken

{
  "ErrorMessage": "Domain name: \"contosodemo.onmicrosoft.com\" is not available",
  "IsValid": false
}

Choose a different name and validate it again.

Step 3: Create the Tenant

Send the Create a Tenant request with the validated Domain name.

POST https://api.appxite.com/customers/tenants

Headers: include all required headers from Request headers, with the Customer ID from Step 1 in X-On-Behalf-Of.

Request body:

{
  "domain": "contosodemo",
  "vendorId": "af817907-beb0-4ce2-be96-b674de7a876b"
}

Fields:

• domain – the requested Domain name without the .onmicrosoft.com part. The Platform adds the suffix.
• vendorId – the static identifier of Microsoft on the Platform.

The operation returns 202 Accepted with the full Domain name:

{
  "Domain": "contosodemo.onmicrosoft.com",
  "VendorId": "af817907-beb0-4ce2-be96-b674de7a876b"
}

Step 4: Confirm the Tenant was created

Call List Microsoft tenants for the customer to see all Tenants for the Customer. This operation is available to Seller Admins, Distributor Admins, and any user with access to the Customer Organization.

GET https://api.appxite.com/customers/{customerId}/mstenants

Replace {customerId} with the Customer ID from Step 1. The response lists every Tenant request for the Customer, including requests that did not succeed. The same Domain name can appear more than once, each time with its own InternalId:

[
  {
    "DomainName": "contosodemo.onmicrosoft.com",
    "InternalId": "<Platform tenant ID>",
    "ExternalId": "<Microsoft Tenant ID>"
  },
  {
    "DomainName": "contosodemo.onmicrosoft.com",
    "InternalId": "<Platform tenant ID>",
    "ExternalId": null
  }
]

Check the ExternalId field of the entry for your request:

• Populated – the Tenant was created. ExternalId is the Microsoft Tenant ID.
• null – no Tenant was created for this entry. The request is still processing, the Domain name was already taken, or Microsoft rejected the Customer details. If it stays empty, see Troubleshooting.

In the example, the first entry is a working Tenant. The second entry is a repeated request for the same Domain name, so no new Tenant was created.

What happens after the Tenant is created

• The primary contact in the Customer Organization profile receives an email with the new account details, including the full admin username (for example, admin@contosodemo.onmicrosoft.com).
• The Customer can sign in at admin.microsoft.com with this admin account.
• The Tenant appears in the Tenant Domain dropdown in the Platform whenever a Microsoft Offer is purchased for this Customer. If the Customer has several Tenants, choose the correct one for each purchase.
• You can now place Microsoft Orders for the Customer, through the API or the Platform.

Troubleshooting

If you cannot resolve the issue, submit a support ticket to the Platform Support Team. Include the Customer ID, the requested Domain name, the InternalId of the failed entry, the Environment value, and the time of the request.

Important information

• Create a Tenant does not check whether the Domain name is available. It returns 202 Accepted even when the same name is submitted again. Always validate the name first.
• Tenant creation is asynchronous. The 202 Accepted response does not include the Microsoft Tenant ID or failure reasons; you must check List Microsoft tenants for the customer.
• Domain names must follow Microsoft naming rules. See Restrictions in Microsoft domain creation.
• The latest Customer profile data on the Platform is sent to Microsoft at creation time. If Tax ID is empty, Microsoft marks the Customer as tax-exempt.

Summary

To create a Microsoft Tenant via the API, get the Customer ID, validate the Domain name with Validate Domain Name, send Create a Tenant with the Customer ID in X-On-Behalf-Of, and confirm the result with List Microsoft tenants for the customer. The 202 Accepted response is not a confirmation: the Tenant is ready only when its entry has a populated ExternalId. A Customer can have several Tenants.

Related content

• Create a Tenant – AppXite developer portal
• Platform API Access
• Manage Microsoft Customer Tenants
• How to create Microsoft Tenant Domain for a Customer Organization?
• What Is Microsoft Tenant Domain?
• Resolve "hostname is not valid" error for Microsoft tenant domain
• Validate company names, customer names, and email addresses (Microsoft)