Domains - Create Or Update

  • Reference
Service:
App Service
API Version:
2023-01-01

Description for Creates or updates a domain.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DomainRegistration/domains/{domainName}?api-version=2023-01-01

URI Parameters

Name In Required Type Description
domainName
 path True

string

Name of the domain.

Regex pattern: [a-zA-Z0-9][a-zA-Z0-9\.-]+
resourceGroupName
 path True

string

Name of the resource group to which the resource belongs.

Regex pattern: ^[-\w\._\(\)]+[^\.]$
subscriptionId
 path True

string

Your Azure subscription ID. This is a GUID-formatted string (e.g. 00000000-0000-0000-0000-000000000000).
api-version
 query True

string

API Version

Request Body

Name Required Type Description
location True

string

Resource Location.
properties.consent True

DomainPurchaseConsent

Legal agreement consent.
properties.contactAdmin True

Contact

Administrative contact.
properties.contactBilling True

Contact

Billing contact.
properties.contactRegistrant True

Contact

Registrant contact.
properties.contactTech True

Contact

Technical contact.
kind

string

Kind of resource.
properties.authCode

string

properties.autoRenew

boolean

true if the domain should be automatically renewed; otherwise, false.
properties.dnsType

DnsType

Current DNS type
properties.dnsZoneId

string

Azure DNS Zone to use
properties.privacy

boolean

true if domain privacy is enabled for this domain; otherwise, false.
properties.targetDnsType

DnsType

Target DNS type (would be used for migration)
tags

object

Resource tags.

Responses

Name Type Description
200 OK

Domain

Domain purchase was successful.
202 Accepted

Domain

Domain purchase is in progress.
Other Status Codes

DefaultErrorResponse

App Service error response.

Security

azure_auth

Azure Active Directory OAuth2 Flow

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name Description
user_impersonation impersonate your user account

Examples

Create App Service Domain

Sample Request

PUT https://management.azure.com/subscriptions/34adfa4f-cedf-4dc0-ba29-b6d1a69ab345/resourceGroups/testrg123/providers/Microsoft.DomainRegistration/domains/example.com?api-version=2023-01-01

{
  "location": "global",
  "tags": {},
  "properties": {
    "authCode": "exampleAuthCode",
    "privacy": false,
    "autoRenew": true,
    "dnsType": "DefaultDomainRegistrarDns",
    "consent": {
      "agreementKeys": [
        "agreementKey1"
      ],
      "agreedBy": "192.0.2.1",
      "agreedAt": "2021-09-10T19:30:53Z"
    },
    "contactTech": {
      "email": "tech@email.com",
      "fax": "1-245-534-2242",
      "nameFirst": "John",
      "nameLast": "Doe",
      "nameMiddle": "",
      "jobTitle": "Tech",
      "organization": "Microsoft Inc.",
      "phone": "1-245-534-2242",
      "addressMailing": {
        "address1": "3400 State St",
        "city": "Chicago",
        "state": "IL",
        "country": "United States",
        "postalCode": "67098"
      }
    },
    "contactBilling": {
      "email": "billing@email.com",
      "fax": "1-245-534-2242",
      "nameFirst": "John",
      "nameLast": "Doe",
      "nameMiddle": "",
      "jobTitle": "Billing",
      "organization": "Microsoft Inc.",
      "phone": "1-245-534-2242",
      "addressMailing": {
        "address1": "3400 State St",
        "city": "Chicago",
        "state": "IL",
        "country": "United States",
        "postalCode": "67098"
      }
    },
    "contactAdmin": {
      "email": "admin@email.com",
      "fax": "1-245-534-2242",
      "nameFirst": "John",
      "nameLast": "Doe",
      "nameMiddle": "",
      "jobTitle": "Admin",
      "organization": "Microsoft Inc.",
      "phone": "1-245-534-2242",
      "addressMailing": {
        "address1": "3400 State St",
        "city": "Chicago",
        "state": "IL",
        "country": "United States",
        "postalCode": "67098"
      }
    },
    "contactRegistrant": {
      "email": "registrant@email.com",
      "fax": "1-245-534-2242",
      "nameFirst": "John",
      "nameLast": "Doe",
      "nameMiddle": "",
      "jobTitle": "Registrant",
      "organization": "Microsoft Inc.",
      "phone": "1-245-534-2242",
      "addressMailing": {
        "address1": "3400 State St",
        "city": "Chicago",
        "state": "IL",
        "country": "United States",
        "postalCode": "67098"
      }
    }
  }
}

Sample Response

Status code:
200 
{
  "id": "/subscriptions/34adfa4f-cedf-4dc0-ba29-b6d1a69ab345/resourceGroups/testrg123/providers/Microsoft.DomainRegistration/domains/example.com",
  "name": "example.com",
  "type": "Microsoft.DomainRegistration/domains",
  "location": "global",
  "tags": {},
  "properties": {
    "authCode": "exampleAuthCode",
    "registrationStatus": "Active",
    "provisioningState": "Succeeded",
    "nameServers": [
      "ns01.ote.domaincontrol.com",
      "ns02.ote.domaincontrol.com"
    ],
    "privacy": false,
    "createdTime": "2021-09-10T19:30:53Z",
    "expirationTime": "2022-09-10T19:30:53Z",
    "autoRenew": true,
    "readyForDnsRecordManagement": true,
    "managedHostNames": [],
    "domainNotRenewableReasons": [
      "ExpirationNotInRenewalTimeRange"
    ],
    "dnsType": "DefaultDomainRegistrarDns",
    "consent": {
      "agreementKeys": [
        "agreementKey1"
      ],
      "agreedBy": "192.0.2.1",
      "agreedAt": "2021-09-10T19:30:53Z"
    },
    "contactTech": {
      "email": "tech@email.com",
      "fax": "1-245-534-2242",
      "nameFirst": "John",
      "nameLast": "Doe",
      "nameMiddle": "",
      "jobTitle": "Tech",
      "organization": "Microsoft Inc.",
      "phone": "1-245-534-2242",
      "addressMailing": {
        "address1": "3400 State St",
        "city": "Chicago",
        "state": "IL",
        "country": "United States",
        "postalCode": "67098"
      }
    },
    "contactBilling": {
      "email": "billing@email.com",
      "fax": "1-245-534-2242",
      "nameFirst": "John",
      "nameLast": "Doe",
      "nameMiddle": "",
      "jobTitle": "Billing",
      "organization": "Microsoft Inc.",
      "phone": "1-245-534-2242",
      "addressMailing": {
        "address1": "3400 State St",
        "city": "Chicago",
        "state": "IL",
        "country": "United States",
        "postalCode": "67098"
      }
    },
    "contactAdmin": {
      "email": "admin@email.com",
      "fax": "1-245-534-2242",
      "nameFirst": "John",
      "nameLast": "Doe",
      "nameMiddle": "",
      "jobTitle": "Admin",
      "organization": "Microsoft Inc.",
      "phone": "1-245-534-2242",
      "addressMailing": {
        "address1": "3400 State St",
        "city": "Chicago",
        "state": "IL",
        "country": "United States",
        "postalCode": "67098"
      }
    },
    "contactRegistrant": {
      "email": "registrant@email.com",
      "fax": "1-245-534-2242",
      "nameFirst": "John",
      "nameLast": "Doe",
      "nameMiddle": "",
      "jobTitle": "Registrant",
      "organization": "Microsoft Inc.",
      "phone": "1-245-534-2242",
      "addressMailing": {
        "address1": "3400 State St",
        "city": "Chicago",
        "state": "IL",
        "country": "United States",
        "postalCode": "67098"
      }
    }
  }
}
Status code:
202 
{
  "id": "/subscriptions/34adfa4f-cedf-4dc0-ba29-b6d1a69ab345/resourceGroups/testrg123/providers/Microsoft.DomainRegistration/domains/example.com",
  "name": "example.com",
  "type": "Microsoft.DomainRegistration/domains",
  "location": "global",
  "tags": {},
  "properties": {
    "authCode": "exampleAuthCode",
    "registrationStatus": "Active",
    "provisioningState": "Succeeded",
    "nameServers": [
      "ns01.ote.domaincontrol.com",
      "ns02.ote.domaincontrol.com"
    ],
    "privacy": false,
    "createdTime": "2021-09-10T19:30:53Z",
    "expirationTime": "2022-09-10T19:30:53Z",
    "autoRenew": true,
    "readyForDnsRecordManagement": true,
    "managedHostNames": [],
    "domainNotRenewableReasons": [
      "ExpirationNotInRenewalTimeRange"
    ],
    "dnsType": "DefaultDomainRegistrarDns",
    "consent": {
      "agreementKeys": [
        "agreementKey1"
      ],
      "agreedBy": "192.0.2.1",
      "agreedAt": "2021-09-10T19:30:53Z"
    },
    "contactTech": {
      "email": "tech@email.com",
      "fax": "1-245-534-2242",
      "nameFirst": "John",
      "nameLast": "Doe",
      "nameMiddle": "",
      "jobTitle": "Tech",
      "organization": "Microsoft Inc.",
      "phone": "1-245-534-2242",
      "addressMailing": {
        "address1": "3400 State St",
        "city": "Chicago",
        "state": "IL",
        "country": "United States",
        "postalCode": "67098"
      }
    },
    "contactBilling": {
      "email": "billing@email.com",
      "fax": "1-245-534-2242",
      "nameFirst": "John",
      "nameLast": "Doe",
      "nameMiddle": "",
      "jobTitle": "Billing",
      "organization": "Microsoft Inc.",
      "phone": "1-245-534-2242",
      "addressMailing": {
        "address1": "3400 State St",
        "city": "Chicago",
        "state": "IL",
        "country": "United States",
        "postalCode": "67098"
      }
    },
    "contactAdmin": {
      "email": "admin@email.com",
      "fax": "1-245-534-2242",
      "nameFirst": "John",
      "nameLast": "Doe",
      "nameMiddle": "",
      "jobTitle": "Admin",
      "organization": "Microsoft Inc.",
      "phone": "1-245-534-2242",
      "addressMailing": {
        "address1": "3400 State St",
        "city": "Chicago",
        "state": "IL",
        "country": "United States",
        "postalCode": "67098"
      }
    },
    "contactRegistrant": {
      "email": "registrant@email.com",
      "fax": "1-245-534-2242",
      "nameFirst": "John",
      "nameLast": "Doe",
      "nameMiddle": "",
      "jobTitle": "Registrant",
      "organization": "Microsoft Inc.",
      "phone": "1-245-534-2242",
      "addressMailing": {
        "address1": "3400 State St",
        "city": "Chicago",
        "state": "IL",
        "country": "United States",
        "postalCode": "67098"
      }
    }
  }
}

Definitions

Name Description
Address

Address information for domain registration.
AzureResourceType

Type of the Azure resource the hostname is assigned to.
Contact

Contact information for domain registration. If 'Domain Privacy' option is not selected then the contact information is made publicly available through the Whois directories as per ICANN requirements.
CustomHostNameDnsRecordType

Type of the DNS record.
DefaultErrorResponse

App Service error response.
Details
DnsType

Current DNS type
Domain

Information about a domain.
DomainPurchaseConsent

Domain purchase consent object, representing acceptance of applicable legal agreements.
DomainStatus

Domain registration status.
Error

Error model.
HostName

Details of a hostname derived from a domain.
HostNameType

Type of the hostname.
ProvisioningState

Domain provisioning state.
ResourceNotRenewableReason

Reasons why domain is not renewable.

Address

Address information for domain registration.

Name Type Description
address1

string

First line of an Address.
address2

string

The second line of the Address. Optional.
city

string

The city for the address.
country

string

The country for the address.
postalCode

string

The postal code for the address.
state

string

The state or province for the address.

AzureResourceType

Type of the Azure resource the hostname is assigned to.

Name Type Description
TrafficManager

string

Website

string

Contact

Contact information for domain registration. If 'Domain Privacy' option is not selected then the contact information is made publicly available through the Whois directories as per ICANN requirements.

Name Type Description
addressMailing

Address

Mailing address.
email

string

Email address.
fax

string

Fax number.
jobTitle

string

Job title.
nameFirst

string

First name.
nameLast

string

Last name.
nameMiddle

string

Middle name.
organization

string

Organization contact belongs to.
phone

string

Phone number.

CustomHostNameDnsRecordType

Type of the DNS record.

Name Type Description
A

string

CName

string

DefaultErrorResponse

App Service error response.

Name Type Description
error

Error

Error model.

Details

Name Type Description
code

string

Standardized string to programmatically identify the error.
message

string

Detailed error description and debugging information.
target

string

Detailed error description and debugging information.

DnsType

Current DNS type

Name Type Description
AzureDns

string

DefaultDomainRegistrarDns

string

Domain

Information about a domain.

Name Type Default Value Description
id

string

Resource Id.
kind

string

Kind of resource.
location

string

Resource Location.
name

string

Resource Name.
properties.authCode

string

properties.autoRenew

boolean

True

true if the domain should be automatically renewed; otherwise, false.
properties.consent

DomainPurchaseConsent

Legal agreement consent.
properties.contactAdmin

Contact

Administrative contact.
properties.contactBilling

Contact

Billing contact.
properties.contactRegistrant

Contact

Registrant contact.
properties.contactTech

Contact

Technical contact.
properties.createdTime

string

Domain creation timestamp.
properties.dnsType

DnsType

Current DNS type
properties.dnsZoneId

string

Azure DNS Zone to use
properties.domainNotRenewableReasons

ResourceNotRenewableReason[]

Reasons why domain is not renewable.
properties.expirationTime

string

Domain expiration timestamp.
properties.lastRenewedTime

string

Timestamp when the domain was renewed last time.
properties.managedHostNames

HostName[]

All hostnames derived from the domain and assigned to Azure resources.
properties.nameServers

string[]

Name servers.
properties.privacy

boolean

true if domain privacy is enabled for this domain; otherwise, false.
properties.provisioningState

ProvisioningState

Domain provisioning state.
properties.readyForDnsRecordManagement

boolean

true if Azure can assign this domain to App Service apps; otherwise, false. This value will be true if domain registration status is active and it is hosted on name servers Azure has programmatic access to.
properties.registrationStatus

DomainStatus

Domain registration status.
properties.targetDnsType

DnsType

Target DNS type (would be used for migration)
tags

object

Resource tags.
type

string

Resource type.

DomainPurchaseConsent

Domain purchase consent object, representing acceptance of applicable legal agreements.

Name Type Description
agreedAt

string

Timestamp when the agreements were accepted.
agreedBy

string

Client IP address.
agreementKeys

string[]

List of applicable legal agreement keys. This list can be retrieved using ListLegalAgreements API under TopLevelDomain resource.

DomainStatus

Domain registration status.

Name Type Description
Active

string

Awaiting

string

Cancelled

string

Confiscated

string

Disabled

string

Excluded

string

Expired

string

Failed

string

Held

string

JsonConverterFailed

string

Locked

string

Parked

string

Pending

string

Reserved

string

Reverted

string

Suspended

string

Transferred

string

Unknown

string

Unlocked

string

Unparked

string

Updated

string

Error

Error model.

Name Type Description
code

string

Standardized string to programmatically identify the error.
details

Details[]

Detailed errors.
innererror

string

More information to debug error.
message

string

Detailed error description and debugging information.
target

string

Detailed error description and debugging information.

HostName

Details of a hostname derived from a domain.

Name Type Description
azureResourceName

string

Name of the Azure resource the hostname is assigned to. If it is assigned to a Traffic Manager then it will be the Traffic Manager name otherwise it will be the app name.
azureResourceType

AzureResourceType

Type of the Azure resource the hostname is assigned to.
customHostNameDnsRecordType

CustomHostNameDnsRecordType

Type of the DNS record.
hostNameType

HostNameType

Type of the hostname.
name

string

Name of the hostname.
siteNames

string[]

List of apps the hostname is assigned to. This list will have more than one app only if the hostname is pointing to a Traffic Manager.

HostNameType

Type of the hostname.

Name Type Description
Managed

string

Verified

string

ProvisioningState

Domain provisioning state.

Name Type Description
Canceled

string

Deleting

string

Failed

string

InProgress

string

Succeeded

string

ResourceNotRenewableReason

Reasons why domain is not renewable.

Name Type Description
ExpirationNotInRenewalTimeRange

string

RegistrationStatusNotSupportedForRenewal

string

SubscriptionNotActive

string