Create domain

Namespace: microsoft.graph

Adds a domain to the tenant.

Important: You cannot use an associated domain with your Microsoft Entra tenant until ownership is verified. See List verificationDnsRecords for details. Root domains require verification. For example, contoso.com requires verification. If a root domain is verified, subdomains of the root domain are automatically verified. For example, subdomain.contoso.com is automatically be verified if contoso.com has been verified.

This API is available in the following national cloud deployments.

Global service US Government L4 US Government L5 (DOD) China operated by 21Vianet

Permissions

Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

Permission type Least privileged permissions Higher privileged permissions
Delegated (work or school account) Domain.ReadWrite.All Not available.
Delegated (personal Microsoft account) Not supported. Not supported.
Application Domain.ReadWrite.All Not available.

Important

In delegated scenarios with work or school accounts, the signed-in user must be assigned a supported Microsoft Entra role or a custom role with a supported role permission. Domain Name Administrator is the least privileged role supported for this operation.

HTTP request

POST /domains

Request headers

Name Description
Authorization Bearer {token}. Required. Learn more about authentication and authorization.
Content-Type application/json

Request body

In the request body, supply a JSON representation of domain object.

The request body contains the id property for the new domain. Id is the only property that can be specified and it is required. The id property value is the fully qualified domain name to create.

Response

If successful, this method returns 201 Created response code and domain object in the response body.

Example

Request

In the request body, supply a JSON representation of domain object.

POST https://graph.microsoft.com/v1.0/domains
Content-type: application/json

{
  "id": "contoso.com"
}
Response

Note: The response object shown here might be shortened for readability.

HTTP/1.1 201 Created
Content-type: application/json

{
  "authenticationType": "authenticationType-value",
  "availabilityStatus": "availabilityStatus-value",
  "id": "contoso.com",
  "isAdminManaged": true,
  "isDefault": true,
  "isInitial": true,
  "isRoot": true
}