V3-V5 API Migration FAQ for Resellers¶

These migration tips are intended for Gandi resellers who use our API to manage domains on behalf of their customers.

If you use our API as a direct customer and you are managing your own domains, please refer to our Direct Customers section.

CUSTOMER MANAGEMENT¶

Gandi v5 introduces the notion of “customers” to our resellers.

A “Customer” refers to one of your customers, who is the owner of a product that is managed by your reseller oranization.

When you purchase or transfer a domain name to Gandi from your reseller account, we automatically use the owner information that you provided in the payload to create a “customer” entity under your reseller organization’s management.

Customer entities do not behave like usernames (or like ‘handles’ in our v3 API), in that it is not possible to use them as actual accounts that can be logged into.

Additional examples is on the organization API documentation at https://api.gandi.net/docs/organization/

Get all Customers Information¶

If you need to see a list of all of your customers and their basic information, you can use the following request, where ‘xx’ is replaced with the id of your reseller organization:

curl -X GET \
  https://api.gandi.net/v5/organization/organizations/xx/customers \
  -H 'authorization: Apikey your-api-key'

Get a Specific Customer’s Information¶

To see the complete contact information of one of your customers, add their id (‘yy’) to the path as follows:

curl -X GET \
  https://api.gandi.net/v5/organization/organizations/xx/customers/yy \
  -H 'authorization: Apikey your-api-key'

Updating, Deleting, and Creating Customers¶

Unlike with the v3 API, with v5 there is not the notion of updating a single ‘handle’ and then that information is propagated to all the domains using it. In v5, if you need to update the information of your customer that is already being used on a domain, you must update the domain’s contact information directly, on a domain-by-domain basis.

Also unlike in v3, in v5 there is no need to create a customer prior to a domain operation (creation, transfer, change owner), because this is done automatically from the information you provide in your request.

Therefore, while these three methods are documented, we do not recommend that you use them, as they are not part of the normal v5 API workflow at this time, and will result in duplicate customer entries that are not syncronized.

CONTACT MANAGEMENT¶

In Gandi’s v5 API, contacts are directly associated with the domain name, and so are not manipulated as independant objects as was done in v3.

It is important to consider that any time you need to update the information associated with a contact (or change the contact itself), that you need to update the domain name’s information, on a domain-by-domain basis.

Get all Contact Information¶

Unlike in our v3 API, you do not directly manage or need to manage domain contacts with our v5 API.

We provide you with a way to view the contact contact information that is associated with a domain that you manage for informational purposes, however

This is done by querying the domain name and adding /contacts to the path, as follows:

curl -X GET \
  https://api.gandi.net/v5/domain/domains/example.net/contacts \
  -H 'authorization: Apikey your-api-key'

The response will then provide you with all the information that the domain name has for all of its contacts, including the owner, for example:

{
  "admin": {
    "city": "Paris",
    "given": "Alice",
    "family": "Doe",
    "zip": "75001",
    "extra_parameters": {},
    "country": "FR",
    "streetaddr": "5 rue neuve",
    "data_obfuscated": true,
    "mail_obfuscated": true,
    "phone": "+33.123456789",
    "same_as_owner": true,
    "state": "FR-IDF",
    "type": "individual",
    "email": "alice@example.org"
  },

For more details on this, see: https://api.gandi.net/docs/domains/#v5-domain-domains-domain-contacts

Contact Creation¶

With Gandi v5, Contacts are automatically created as part of domain name operations, because you post their contact information in the body of your request.

You therefore do not need to specifically create a domain contact, or even the owner contact, prior to a domain name creation/transfer/owner change operation, or, as was the case in v3, use an existing contact “handle”. This is because the contact information is required payload in the body of the request itself.

For example, in v3, you would have used the contact.create() method prior to creating a domain if you didn’t already have a handle corresponding to the contact. For example, like this:

>>> contact_spec = {
...   'given': 'First Name',
...   'family': 'Last Name',
...   'email': 'example@example.com',
...   'streetaddr': 'My Street Address',
...   'zip': '75011',
...   'city': 'Paris',
...   'country': 'FR',
...   'phone':'+33.123456789',
...   'type': 0,
...   'password': 'xxxxxxxx'}
>>> contact = api.contact.create(apikey, contact_spec)
>>> contact['handle']

This would in turn provide you with a handle, such as ‘FLN123-GANDI’, which you would then associate with a domain name creation using the domain.create() method:

>>> domain_spec = {
...     'owner': 'FLN123-GANDI',
...     'admin': 'FLN123-GANDI',
...     'bill': 'FLN123-GANDI',
...     'tech': 'FLN123-GANDI',
...     'nameservers': ['a.dns.gandi-ote.net', 'b.dns.gandi-ote.net',
...                     'c.dns.gandi-ote.net'],
...     'duration': 1}
>>> op = api.domain.create(apikey, 'mydomain.net', domain_spec)

However, in v5, you simpy pass on the contact information directly in the body of the domain create request, regardless of whether or not you already have the same contact information associated with another domain. :

curl -X POST \
  https://api.gandi.net/v5/domain/domains \
  -H 'authorization: Apikey your-api-key' \
  -H 'content-type: application/json' \
  -d '{"fqdn":"example.com","duration":5,"owner":{"city":"Paris","given":"Alice","family":"Doe","zip":"75001","country":"FR","streetaddr":"5 rue neuve","phone":"+33.123456789","state":"FR-IDF","type":"individual","email":"alice@example.org"}}'

Consequently, unlike with our v3 API, you do not create anything like a handle that corresponds to a contact, or re-use an existing one. In v5, you provide all the contact information each time you make your request.

Contact Information Update (other than the owner)¶

Contrary to our v3 API, there are no contact handles in v5 to update.

Updating the contact information of a domain name is done by updating the domain name’s information. Consequently, you will PATCH the contact information of the domain name to which you want to edit by providing the new information in the payload, like this:

curl -X PATCH \
  https://api.gandi.net/v5/domain/domains/example.net/contacts \
  -H 'authorization: Apikey your-api-key' \
  -H 'content-type: application/json' \
  -d '{"admin":{"lang":"en","city":"Paris","given":"Bob","family":"Doe","zip":"75001","extra_parameters":{},"country":"FR","streetaddr":"8 rue neuve","data_obfuscated":true,"mail_obfuscated":true,"phone":"+33.123456788","state":"FR-IDF","type":"individual","email":"bob@example.org"}}'

Contact updates are done on a domain-by-domain basis. Therefore, updating the contact information of one domain will not affect any other domains that may have the previous contact information. You will need to repeat the update on each domain that may be concerned by the update.

See: https://api.gandi.net/docs/domains/#patch-v5-domain-domains-domain-contacts

Owner Information Update¶

If you need to update some of the information of a domain’s owner such as the contact information or extra paramaters needed for some extensions, this is done by a PUT request on a domain-by-domain basis, where you pass on the updated information in the body, like this:

curl -X PUT \
https://api.gandi.net/v5/domain/domains/example.net/contacts/owner \
-H 'authorization: Apikey your-api-key' \
-H 'content-type: application/json' \
-d '{"country":"FR","streetaddr":"8 rue neuve","email":"bob@example.org"}}'

Owner information updates are done on a domain-by-domain basis. Therefore, updating the owner contact information of one domain will not affect any others that may have the previous information or the owner. You will need to repeat the update on each domain that may be concerned by the update.

See: https://api.gandi.net/docs/domains/#put-v5-domain-domains-domain-contacts-owner

DOMAIN OPERATIONS¶

Billing your reseller organization¶

Unlike with our v3 API, in V5, you have at least two prepaid accounts. One for your personal organization (corresponding to your username) and another one for each organization you manage (ex. your reseller organization).

When operations are not free, in order to assure that your reseller oranization is billed an not your personal organization, it is necessary to add the ID of your reseller organization (sharing_id) to the end of the path.

To get the sharing_id of an organization you manage, use the following request:

curl -X GET \
  https://api.gandi.net/v5/organization/organizations \
  -H 'authorization: Apikey your-api-key'

In the response, the ‘id’ that you see associated with an organization is the sharing_id that you will use in the above request:

“id”: “e58f2734-5f7b-11e9-a5c3-00163ec4cb00”

In the below tips, we will refer to this as the ‘reseller_id’. Just paste the id corresponding to your reseller orgznization in stead of reseller_id in the example paths to be sure that your reseller organization is billed for the operation.

Owner Change¶

Unlike in the v3 API, where you would pass on the h4.comandle of the new owner, when you perform an owner change using our v5 API, you need to provide all of the new owner’s information in the body of your request.

The below example demonstrates an owner change for the domain example.net to Alice Doe.

Because the reseller_id is added to the path, your reseller organization will be billed for the operation, the domain will be managed under your reseller account, and the new owner will be automatically added as a customer of your reseller organization:

curl -X POST \
  https://api.gandi.net/v5/domain/changeowner/example.net?sharing_id=reseller_id \
  -H 'authorization: Apikey your-api-key' \
  -H 'content-type: application/json' \
  -d '{"owner":{"city":"Paris","given":"Alice","family":"Doe","zip":"75001","country":"FR","streetaddr":"5 rue neuve","data_obfuscated":true,"mail_obfuscated":true,"phone":"+33.123456789","state":"FR-IDF","type":"individual","email":"alice@example.org"}}'

See: https://api.gandi.net/docs/domains/#post-v5-domain-changeowner-domain

Contact Change¶

In Gandi’s v3 API, if you needed to change the contact of a domain (from one person, or company, to another), you would set the handle that corresponds to the new contact on the domain, like this:

>>> contacts_spec = {
...     'admin': 'FLN123-GANDI',
...     'tech': 'FLN123-GANDI',
...     'bill': 'FLN123-GANDI'}
>>> api.domain.contacts.set(apikey, 'mydomain.net', contacts_spec)

As our v5 API does not use handles, changing a contact in v5 corresponds to updating all of a contact’s information for a domain name.

It is therefore done by a PATCH on a specific domain name (see Contact Information Update (other than the owner).

Domain Name Creation¶

The creation of a domain name in v5 is done by a POST of the desired domain name and the information you want to apply to it.

A key difference from how this was done in v3 is that you need to provide all of the domain owner and contact information details directly in the payload, rather than specifying a ‘handle’ that corresponds to contact information.

If you only specify the ‘owner’ contact information, that information will be used for all the domain contacts.

Because the reseller_id is added to the path, your reseller organization will be billed for the operation, the domain will be managed under your reseller account, and the owner will be automatically added as a customer of your reseller organization:

For example:

curl -X POST \
  https://api.gandi.net/v5/domain/domains?sharing_id=reseller_id \
  -H 'authorization: Apikey your-api-key' \
  -H 'content-type: application/json' \
  -d '{"fqdn":"example.com","duration":5,"owner":{"city":"Paris","given":"Alice","family":"Doe","zip":"75001","country":"FR","streetaddr":"5 rue neuve","phone":"+33.123456789","state":"FR-IDF","type":"individual","email":"alice@example.org"}}'

see: https://api.gandi.net/docs/domains/#v5-domain-domains

Domain Name Transfer¶

The transfer of a domain name to Gandi in v5 is done by a POST of the desired domain name and the information you want to apply to it, similar to a domain name creation request.

If you only specify the ‘owner’ contact information, that information will be used for all the domain contacts.

For example:

curl -X POST \
  https://api.gandi.net/v5/domain/transferin?sharing_id=reseller_id \
  -H 'authorization: Apikey your-api-key' \
  -H 'content-type: application/json' \
  -d '{"fqdn":"example.com","authinfo":"xyz5500","duration":2,"owner":{"city":"Paris","given":"Alice","family":"Doe","zip":"75001","country":"FR","streetaddr":"5 rue neuve","phone":"+33.123456789","state":"FR-IDF","type":"individual","email":"alice@example.org"}}'

see: https://api.gandi.net/docs/domains/#post-v5-domain-transferin

BILLING¶

Unlike in v3, where you had a single prepaid account, because Gandi v5 uses the notion of ‘Organizations’, you may have several different prepaid accounts, depending on whether or not you have created an organization for your company, association, or public body for which you manage domain names.

By default, you will have a prepaid account on your personal organization (your username).

If you have created another organization, for example, that corresponds to your company, then that organization will have its own prepaid account.

How to see the balance of your personal organization’s prepaid account¶

To see your personal balance, you just need to use the following route and your API key:

curl -X GET \
  https://api.gandi.net/v5/billing/info \
  -H 'authorization: Apikey your-api-key'

see: https://api.gandi.net/docs/billing/#v5-billing-info

How to see the balance of another organization’s prepaid account that you manage¶

To see the prepaid account balance of an organization corresponding to your company, association, or public body that you manage via your account, you must add the sharing_id corresponding to the desired organization in the path, like this:

curl -X GET \
  https://api.gandi.net/v5/billing/info/e58f2734-5f7b-11e9-a5c3-00163ec4cb00 \
  -H 'authorization: Apikey your-api-key'

see: https://api.gandi.net/docs/billing/#v5-billing-info