REST Resource: projects.locations.registrations

Resource: Registration

The Registration resource facilitates managing and configuring domain name registrations.

There are several ways to create a new Registration resource:

To create a new Registration resource, find a suitable domain name by calling the registrations.searchDomains method with a query to see available domain name options. After choosing a name, call registrations.retrieveRegisterParameters to ensure availability and obtain information like pricing, which is needed to build a call to registrations.register.

Another way to create a new Registration is to transfer an existing domain from another registrar. First, go to the current registrar to unlock the domain for transfer and retrieve the domain's transfer authorization code. Then call registrations.retrieveTransferParameters to confirm that the domain is unlocked and to get values needed to build a call to registrations.transfer.

Finally, you can create a new Registration by importing an existing domain managed with Google Domains. First, call registrations.retrieveImportableDomains to list domains to which the calling user has sufficient access. Then call registrations.import on any domain names you want to use with Cloud Domains.

JSON representation 
{
  "name": string,
  "domainName": string,
  "createTime": string,
  "expireTime": string,
  "state": enum (State),
  "issues": [
    enum (Issue)
  ],
  "labels": {
    string: string,
    ...
  },
  "managementSettings": {
    object (ManagementSettings)
  },
  "dnsSettings": {
    object (DnsSettings)
  },
  "contactSettings": {
    object (ContactSettings)
  },
  "pendingContactSettings": {
    object (ContactSettings)
  },
  "supportedPrivacy": [
    enum (ContactPrivacy)
  ],
  "registerFailureReason": enum (RegisterFailureReason),
  "transferFailureReason": enum (TransferFailureReason)
}
Fields
name

string

Output only. Name of the Registration resource, in the format projects/*/locations/*/registrations/<domainName>.
domainName

string

Required. Immutable. The domain name. Unicode domain names must be expressed in Punycode format.
createTime

string (Timestamp format)

Output only. The creation timestamp of the Registration resource.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
expireTime

string (Timestamp format)

Output only. The expiration timestamp of the Registration.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
state

enum (State)

Output only. The state of the Registration
issues[]

enum (Issue)

Output only. The set of issues with the Registration that require attention.
labels

map (key: string, value: string)

Set of labels associated with the Registration.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
managementSettings

object (ManagementSettings)

Settings for management of the Registration, including renewal, billing, and transfer. You cannot update these with the registrations.patch method. To update these settings, use the registrations.configureManagementSettings method.
dnsSettings

object (DnsSettings)

Settings controlling the DNS configuration of the Registration. You cannot update these with the registrations.patch method. To update these settings, use the registrations.configureDnsSettings method.
contactSettings

object (ContactSettings)

Required. Settings for contact information linked to the Registration. You cannot update these with the registrations.patch method. To update these settings, use the registrations.configureContactSettings method.
pendingContactSettings

object (ContactSettings)

Output only. Pending contact settings for the Registration. Updates to the contactSettings field that change its registrantContact or privacy fields require email confirmation by the registrantContact before taking effect. This field is set only if there are pending updates to the contactSettings that have not been confirmed. To confirm the changes, the registrantContact must follow the instructions in the email they receive.
supportedPrivacy[]

enum (ContactPrivacy)

Output only. Set of options for the contactSettings.privacy field that this Registration supports.
registerFailureReason

enum (RegisterFailureReason)

Output only. The reason the domain registration failed. Only set for domains in REGISTRATION_FAILED state.
transferFailureReason

enum (TransferFailureReason)

Output only. The reason the domain transfer failed. Only set for domains in TRANSFER_FAILED state.

State

Possible states of a Registration.

Enums
STATE_UNSPECIFIED The state is undefined.
REGISTRATION_PENDING The domain is being registered.
REGISTRATION_FAILED The domain registration failed. You can delete resources in this state to allow registration to be retried.
TRANSFER_PENDING The domain is being transferred from another registrar to Cloud Domains.
TRANSFER_FAILED The attempt to transfer the domain from another registrar to Cloud Domains failed. You can delete resources in this state and retry the transfer.
IMPORT_PENDING The domain is being imported from Google Domains to Cloud Domains.
ACTIVE The domain is registered and operational. The domain renews automatically as long as it remains in this state.
SUSPENDED The domain is suspended and inoperative. For more details, see the issues field.
EXPORTED The domain is no longer managed with Cloud Domains. It may have been transferred to another registrar or exported for management in Google Domains. You can no longer update it with this API, and information shown about it may be stale. Domains in this state are not automatically renewed by Cloud Domains.

Issue

Possible issues with a Registration that require attention.

Enums
ISSUE_UNSPECIFIED The issue is undefined.
CONTACT_SUPPORT Contact the Cloud Support team to resolve a problem with this domain.
UNVERIFIED_EMAIL ICANN requires verification of the email address in the Registration's contactSettings.registrant_contact field. To verify the email address, follow the instructions in the email the registrantContact receives following registration. If you do not complete email verification within 15 days of registration, the domain is suspended. To resend the verification email, call registrations.configureContactSettings and provide the current registrantContact.email.

ManagementSettings

Defines renewal, billing, and transfer settings for a Registration.

JSON representation 
{
  "renewalMethod": enum (RenewalMethod),
  "transferLockState": enum (TransferLockState)
}
Fields
renewalMethod

enum (RenewalMethod)

Output only. The renewal method for this Registration.
transferLockState

enum (TransferLockState)

Controls whether the domain can be transferred to another registrar.

RenewalMethod

Defines how the Registration is renewed.

Enums
RENEWAL_METHOD_UNSPECIFIED The renewal method is undefined.
AUTOMATIC_RENEWAL

The domain is automatically renewed each year .

To disable automatic renewals, delete the resource by calling registrations.delete or export it by calling registrations.export.
MANUAL_RENEWAL

The domain must be explicitly renewed each year before its expireTime. This option is only available when the Registration is in state EXPORTED.

To manage the domain's current billing and renewal settings, go to Google Domains.

TransferLockState

Possible states of a Registration's transfer lock.

Enums
TRANSFER_LOCK_STATE_UNSPECIFIED The state is unspecified.
UNLOCKED The domain is unlocked and can be transferred to another registrar.
LOCKED The domain is locked and cannot be transferred to another registrar.

DnsSettings

Defines the DNS configuration of a Registration, including name servers, DNSSEC, and glue records.

JSON representation 
{
  "glueRecords": [
    {
      object (GlueRecord)
    }
  ],

  // Union field dns_provider can be only one of the following:
  "customDns": {
    object (CustomDns)
  },
  "googleDomainsDns": {
    object (GoogleDomainsDns)
  }
  // End of list of possible types for union field dns_provider.
}
Fields
glueRecords[]

object (GlueRecord)

The list of glue records for this Registration. Commonly empty.
Union field dns_provider. The DNS provider of the registration. dns_provider can be only one of the following:
customDns

object (CustomDns)

An arbitrary DNS provider identified by its name servers.
googleDomainsDns

object (GoogleDomainsDns)

The free DNS zone provided by Google Domains.

CustomDns

Configuration for an arbitrary DNS provider.

JSON representation 
{
  "nameServers": [
    string
  ],
  "dsRecords": [
    {
      object (DsRecord)
    }
  ]
}
Fields
nameServers[]

string

Required. A list of name servers that store the DNS zone for this domain. Each name server is a domain name, with Unicode domain names expressed in Punycode format.
dsRecords[]

object (DsRecord)

The list of DS records for this domain, which are used to enable DNSSEC. The domain's DNS provider can provide the values to set here. If this field is empty, DNSSEC is disabled.

DsRecord

Defines a Delegation Signer (DS) record, which is needed to enable DNSSEC for a domain. It contains a digest (hash) of a DNSKEY record that must be present in the domain's DNS zone.

JSON representation 
{
  "keyTag": integer,
  "algorithm": enum (Algorithm),
  "digestType": enum (DigestType),
  "digest": string
}
Fields
keyTag

integer

The key tag of the record. Must be set in range 0 -- 65535.
algorithm

enum (Algorithm)

The algorithm used to generate the referenced DNSKEY.
digestType

enum (DigestType)

The hash function used to generate the digest of the referenced DNSKEY.
digest

string

The digest generated from the referenced DNSKEY.

Algorithm

List of algorithms used to create a DNSKEY. Certain algorithms are not supported for particular domains.

Enums
ALGORITHM_UNSPECIFIED The algorithm is unspecified.
RSAMD5 RSA/MD5. Cannot be used for new deployments.
DH Diffie-Hellman. Cannot be used for new deployments.
DSA DSA/SHA1. Not recommended for new deployments.
ECC ECC. Not recommended for new deployments.
RSASHA1 RSA/SHA-1. Not recommended for new deployments.
DSANSEC3SHA1 DSA-NSEC3-SHA1. Not recommended for new deployments.
RSASHA1NSEC3SHA1 RSA/SHA1-NSEC3-SHA1. Not recommended for new deployments.
RSASHA256 RSA/SHA-256.
RSASHA512 RSA/SHA-512.
ECCGOST GOST R 34.10-2001.
ECDSAP256SHA256 ECDSA Curve P-256 with SHA-256.
ECDSAP384SHA384 ECDSA Curve P-384 with SHA-384.
ED25519 Ed25519.
ED448 Ed448.
INDIRECT Reserved for Indirect Keys. Cannot be used for new deployments.
PRIVATEDNS Private algorithm. Cannot be used for new deployments.
PRIVATEOID Private algorithm OID. Cannot be used for new deployments.

DigestType

List of hash functions that may have been used to generate a digest of a DNSKEY.

Enums
DIGEST_TYPE_UNSPECIFIED The DigestType is unspecified.
SHA1 SHA-1. Not recommended for new deployments.
SHA256 SHA-256.
GOST3411 GOST R 34.11-94.
SHA384 SHA-384.

GoogleDomainsDns

Configuration for using the free DNS zone provided by Google Domains as a Registration's dns_provider. You cannot configure the DNS zone itself using the API. To configure the DNS zone, go to Google Domains.

JSON representation 
{
  "nameServers": [
    string
  ],
  "dsState": enum (DsState),
  "dsRecords": [
    {
      object (DsRecord)
    }
  ]
}
Fields
nameServers[]

string

Output only. A list of name servers that store the DNS zone for this domain. Each name server is a domain name, with Unicode domain names expressed in Punycode format. This field is automatically populated with the name servers assigned to the Google Domains DNS zone.
dsState

enum (DsState)

Required. The state of DS records for this domain. Used to enable or disable automatic DNSSEC.
dsRecords[]

object (DsRecord)

Output only. The list of DS records published for this domain. The list is automatically populated when dsState is DS_RECORDS_PUBLISHED, otherwise it remains empty.

DsState

The publication state of DS records for a Registration.

Enums
DS_STATE_UNSPECIFIED DS state is unspecified.
DS_RECORDS_UNPUBLISHED DNSSEC is disabled for this domain. No DS records for this domain are published in the parent DNS zone.
DS_RECORDS_PUBLISHED DNSSEC is enabled for this domain. Appropriate DS records for this domain are published in the parent DNS zone. This option is valid only if the DNS zone referenced in the Registration's dns_provider field is already DNSSEC-signed.

GlueRecord

Defines a host on your domain that is a DNS name server for your domain and/or other domains. Glue records are a way of making the IP address of a name server known, even when it serves DNS queries for its parent domain. For example, when ns.example.com is a name server for example.com, the host ns.example.com must have a glue record to break the circular DNS reference.

JSON representation 
{
  "hostName": string,
  "ipv4Addresses": [
    string
  ],
  "ipv6Addresses": [
    string
  ]
}
Fields
hostName

string

Required. Domain name of the host in Punycode format.
ipv4Addresses[]

string

List of IPv4 addresses corresponding to this host in the standard decimal format (e.g. 198.51.100.1). At least one of ipv4_address and ipv6_address must be set.
ipv6Addresses[]

string

List of IPv6 addresses corresponding to this host in the standard hexadecimal format (e.g. 2001:db8::). At least one of ipv4_address and ipv6_address must be set.

ContactSettings

Defines the contact information associated with a Registration.

ICANN requires all domain names to have associated contact information. The registrantContact is considered the domain's legal owner, and often the other contacts are identical.

JSON representation 
{
  "privacy": enum (ContactPrivacy),
  "registrantContact": {
    object (Contact)
  },
  "adminContact": {
    object (Contact)
  },
  "technicalContact": {
    object (Contact)
  }
}
Fields
privacy

enum (ContactPrivacy)

Required. Privacy setting for the contacts associated with the Registration.
registrantContact

object (Contact)

Required. The registrant contact for the Registration.

Caution: Anyone with access to this email address, phone number, and/or postal address can take control of the domain.

Warning: For new Registrations, the registrant receives an email confirmation that they must complete within 15 days to avoid domain suspension.
adminContact

object (Contact)

Required. The administrative contact for the Registration.
technicalContact

object (Contact)

Required. The technical contact for the Registration.

ContactPrivacy

Defines a set of possible contact privacy settings for a Registration.

ICANN maintains the WHOIS database, a publicly accessible mapping from domain name to contact information, and requires that each domain name have an entry. Choose from these options to control how much information in your ContactSettings is published.

Enums
CONTACT_PRIVACY_UNSPECIFIED The contact privacy settings are undefined.
PUBLIC_CONTACT_DATA All the data from ContactSettings is publicly available. When setting this option, you must also provide a PUBLIC_CONTACT_DATA_ACKNOWLEDGEMENT in the contactNotices field of the request.
PRIVATE_CONTACT_DATA None of the data from ContactSettings is publicly available. Instead, proxy contact data is published for your domain. Email sent to the proxy email address is forwarded to the registrant's email address. Cloud Domains provides this privacy proxy service at no additional cost.
REDACTED_CONTACT_DATA Some data from ContactSettings is publicly available. The actual information redacted depends on the domain. For details, see the registration privacy article.

Contact

Details required for a contact associated with a Registration.

JSON representation 
{
  "postalAddress": {
    object (PostalAddress)
  },
  "email": string,
  "phoneNumber": string,
  "faxNumber": string
}
Fields
postalAddress

object (PostalAddress)

Required. Postal address of the contact.
email

string

Required. Email address of the contact.
phoneNumber

string

Required. Phone number of the contact in international format. For example, "+1-800-555-0123".
faxNumber

string

Fax number of the contact in international format. For example, "+1-800-555-0123".

RegisterFailureReason

Reasons why a domain registration may have failed.

Enums
REGISTER_FAILURE_REASON_UNSPECIFIED Register failure unspecified.
REGISTER_FAILURE_REASON_UNKNOWN Registration failed for an unknown reason.
DOMAIN_NOT_AVAILABLE The domain is not available for registration.
INVALID_CONTACTS The provided contact information was rejected.

TransferFailureReason

Reasons why a domain transfer may have failed.

Enums
TRANSFER_FAILURE_REASON_UNSPECIFIED Transfer failure unspecified.
TRANSFER_FAILURE_REASON_UNKNOWN Transfer failed for an unknown reason.
EMAIL_CONFIRMATION_FAILURE An email confirmation sent to the user was rejected or expired.
DOMAIN_NOT_REGISTERED The domain is available for registration.
DOMAIN_HAS_TRANSFER_LOCK The domain has a transfer lock with its current registrar which must be removed prior to transfer.
INVALID_AUTHORIZATION_CODE The authorization code entered is not valid.
TRANSFER_CANCELLED The transfer was cancelled by the domain owner, current registrar, or TLD registry.
TRANSFER_REJECTED The transfer was rejected by the current registrar. Contact the current registrar for more information.
INVALID_REGISTRANT_EMAIL_ADDRESS The registrant email address cannot be parsed from the domain's current public contact data.
DOMAIN_NOT_ELIGIBLE_FOR_TRANSFER The domain is not eligible for transfer due requirements imposed by the current registrar or TLD registry.
TRANSFER_ALREADY_PENDING Another transfer is already pending for this domain. The existing transfer attempt must expire or be cancelled in order to proceed.

Methods

configureContactSettings

 Updates a Registration's contact settings.

configureDnsSettings

 Updates a Registration's DNS settings.

configureManagementSettings

 Updates a Registration's management settings.

delete

 Deletes a Registration resource.

export

 Exports a Registration resource, such that it is no longer managed by Cloud Domains.

get

 Gets the details of a Registration resource.

getIamPolicy

 Gets the access control policy for a resource.

import

 Imports a domain name from Google Domains for use in Cloud Domains.

list

 Lists the Registration resources in a project.

patch

 Updates select fields of a Registration resource, notably labels.

register

 Registers a new domain name and creates a corresponding Registration resource.

resetAuthorizationCode

 Resets the authorization code of the Registration to a new random string.

retrieveAuthorizationCode

 Gets the authorization code of the Registration for the purpose of transferring the domain to another registrar.

retrieveImportableDomains

 Lists domain names from Google Domains that can be imported to Cloud Domains using the ImportDomain method.

retrieveRegisterParameters

 Gets parameters needed to register a new domain name, including price and up-to-date availability.

retrieveTransferParameters

 Gets parameters needed to transfer a domain name from another registrar to Cloud Domains.

searchDomains

 Searches for available domain names similar to the provided query.

setIamPolicy

 Sets the access control policy on the specified resource.

testIamPermissions

 Returns permissions that a caller has on the specified resource.

transfer

 Transfers a domain name from another registrar to Cloud Domains.