Manage Contacts of a Domain Name

Table of Contents

• Introduction
• Order a Domain Name
• Tasks Management
• Manage Contacts of a Domain Name
• Managing Eligibility Rules
• Configure the Display of Contact Data in the Whois
• Configure the DNS of your Domain Name
• Transfer a Domain Name

We remind you that the given API routes links lead to European API. Do not forget to replace https://eu.api.ovh.com with https://ca.api.ovh.com in API URLs to use it with your identifier.

Contact Types

Contact handling is an essential part of domain names management. It is important to note the differences between nichandles (Nic or OVHcloud accounts) and registry/Whois contacts (data stored on registry, published on Whois).

Registry/Whois Contacts

For most extensions, there are 3 different contacts which can be configured on the registry:

• Administrator: contact managing the domain name (holder and technical contacts management). They are the main contact points of the registrar.
• Technical: contact managing the technical side of the domain name (in particular, the DNS zone).
• Holder: physical or legal person holding the domain name, sometimes called the registrant. They are constrained by eligibility rules. They are legally responsible of the domain name.

For example, John contacts a web agency to create his small company's website. In this case, the web agency will organize contacts as follows:

• Administrator: the web agency
• Technical: the web agency
• Holder: John

The technical contact is often the same as the administrator. As for the holder, it has to be John. In case of dispute with the web agency, the fact that he is the holder will be legally acknowledged and will allow to recover management of his domain name.

OVHcloud Nichandle

OVHcloud nichandles represent OVHcloud accounts which can be used to connect to OVHcloud website and API. A nichandle may be associated to any OVHcloud service (domain name, DNS, server, etc.) as:

• Nic admin: service administrator, who can perform any possible action on the service;
• Nic tech: designated by the service Nic admin, they can update some technical service data;
• Nic billing: in charge of the payment of the service.

By default if not set otherwise, a Nic admin is Nic tech and Nich billing of a service as well.

Relation between OVHcloud Nichandles and Registry/Whois Contacts

Administrator and Technical Nichandles

The administrator and technical OVHcloud nichandles, and registry/Whois administrator and technical contacts are strongly related. Any update in the nichandles data triggers an automatic modification of registry/Whois contacts.

The converse is not true, however. If an administrator or technical contact is updated (using a registry UI for example), the corresponding OVHcloud nichandle will not be modified.

Billing Nichandle

The billing nichandle is not defined on the registry/Whois. This contact is used only for billing purposes, for the related OVHcloud service representing the domain name.

Holder Contact

The registry/Whois holder contact is not related to any nichandle. As a consequence, it cannot be used to connect to the OVHcloud website or API.

It is represented in the OVHcloud API by another entity, the domain.Contact object.

Administrator and Technical Nichandles Management

Creation of a New Nichandle

The following API route can be used to create an OVHcloud nichandle.

The creation rules can also be fetched with the API.

Once created, all actions associated with the new nichandle can be performed with API routes starting with /me/*.

Retrieve and Update a Nichandle

Nichandle information may be retrieved and changed with these API routes.

Nichandle Change on a Domain Service

In this section, we will see how a Nic (admin, tech or billing) can be updated on a given domain name. It works in the same way as any other OVHcloud service. More details explaining the workflow, as well as how to do this, can be found on this page.

Using the following API route, we are going to initiate a "task" which will allow the former and the new Nic to accept or refuse the change.

This endpoint returns a list of task identifiers (one per nichandle).

A nichandle change task is used to send an email to the old and to the new Nic. These emails contain a validation token used to finalize the process.

These tasks can be monitored or updated by calling the following API routes:

Holder Contact Management

The holder contact is represented and handled by routes /me/contact and /domain/contacts. In the domain names context, we stronly recommend the exclusive use of /domain/contacts routes.

When ordering a domain name, a new holder contact is created using the provided data, in order to always have a unique identifier per domain name. This makes subsequent updates easier, avoiding to change another domain name data without wanting to.

Contact Handling

The following API routes can be used to handle domain contacts.

Holder Contact Change

Deciding whether to change the holder depends on two things.

• The extension is regulated by ICANN rules (gTLDs and NewgTLDs), or by a country's administration (ccTLDs).
• The legal status of the holder (individual, company, …).

The simplest situation is the one of gTLDs, regulated by ICANN. In that case, any of the following data change is considered an holder change:

• first/last name for a physical person, or organization name for a legal person;
• email address.

As a consequence, these fields are read-only if the contact is associated to at least a domain name. Changing the holder on a gTLD is free.

For the other extensions, the eligibility rules API will return each field status. For the sake of consistency, we still consider that an email address change is an holder change.

In order to preserve a consistent usage of the OVHcloud API, we have chosen to represent holder change as a dedicated, orderable product. In most cases, this order will be free, but it allows a unique initialization process for all extensions.

This process consists in two main steps.

1. Holder change order
   1. Price selection
   2. Cart creation
   3. Addition of the holder change action to the cart
   4. Creation of the new holder contact, association with the domain name
   5. Order validation and payment
2. Holder change processing
   1. Creation of the DomainTrade task
   2. Emails are sent to the old and new holders
   3. Validation tokens are confirmed by both holders
   4. Holder data change on the registry and Whois

Holder Change Order

The following steps are described with more details in the domain name order documentation page.

Step 1: Holder change information fetch

[
    {
      "exclusive": true,
      "mandatory": false,
      "family": "trade",
      "productName": ".com",
      "productType": "delivery",
      "planCode": "com-trade",
      "prices": [
        {
          "interval": 0,
          "minimumQuantity": 1,
          "description": "Creation of a .com domain name - 1 year",
          "minimumRepeat": 1,
          "priceInUcents": 0,
          "pricingMode": "create-default",
          "capacities": [
            "installation"
          ],
          "duration": "P0D",
          "maximumRepeat": 1,
          "pricingType": "purchase",
          "price": {
            "text": "0.00 €",
            "value": 0,
            "currencyCode": "EUR"
          },
          "maximumQuantity": 1
        }
      ]
    },
    {
      // ...
    }
  ]

The main elements of this object are:

• prices : holder change price
• family : value "trade" indicates that the product represents an holder change
• planCode : commercial plan for the holder change, should equal "$extension-trade"
• pricingMode : commercial sub-plan for the holder change

Step 2: Cart creation, addition of the product to the cart

Cart creation can be performed with:

Then, the holder change product can be added to the cart:

Step 3: Add required configurations

To know which configurations are required, call the following API route:

[
  {
    "label": "OWNER_CONTACT",
    "type": "/me/contact"
  }
]

The desired contact is added to the order process using this API.

{
  "id": 123456,
  "label": "OWNER_CONTACT",
  "value": "/me/contact/123"
}

Step 4: Check cart and visualize purchase order

This step is probably the most important of the order process, and can be performed with this API call.

It allows to get the final purchase order, without generating it (it is a "dry-run").

This call also checks that eligibility rules are satisfied by the holder data.

Step 5: Order validation

Holder Change Processing

Once the purchase order has been validated and paid, the order is handled internally until an holder change task named DomainTrade is eventually created. This task can be found using the following API route:

More details about task management can be seen on this page.

The DomainTrade task is in charge of sending emails to the former and to the new holders, to confirm that the process can take place. These emails contain a validation link (secured with a private token).

Once these tokens are validated, the task will perform the holder change and update the registry and/or the Whois with the new holder data.