V3-V5 API Migration FAQ for Direct Customers¶
These migration tips are intended for Gandi customers who use our API directly, to manage their own domains.
If your organization type is a Reseller, and you are managing domains on behalf of your customers, please refer to our Reseller section .
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.
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 others 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¶
How to bill your username or a company/association/public body¶
Unlike with our v3 API, in V5, you can have multiple prepaid accounts: one for your personal organization (corresponding to your username) and another one for each organization you manage (ex. if you manage domains for a company, association, or pubic body).
When operations are not free, we will bill the prepaid account of your personal organization (username) unless you specify otherwise.
To specify that you want to bill a specific organization, it is necessary to add the ID of that 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. It looks like this:
“id”: “e58f2734-5f7b-11e9-a5c3-00163ec4cb00”
Example of the default request, where your personal organization is billed for a domain name creation:
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"}}'
Example of a specific request, where you specify an organization that want to be billed for a domain name creation:
curl -X POST \
https://api.gandi.net/v5/domain/domains?sharing_id=e58f2734-5f7b-11e9-a5c3-00163ec4cb00 \
-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"}}'
Note that it is necessary that you have the necessary permissions to the organization in order to bill it. If this is not the case you will get an error message to thie effect.
Owner Change¶
Unlike in the v3 API, where you would pass on the handle 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:
curl -X POST \
https://api.gandi.net/v5/domain/changeowner/example.net \
-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-J","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.
For example:
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-J","type":"individual","email":"alice@example.org"}}'
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.
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.
For example:
curl -X POST \
https://api.gandi.net/v5/domain/transferin \
-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-J","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'
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'
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. For example:
{
"id": "e58f2734-5f7b-11e9-a5c3-00163ec4cb00",
"firstname": "Jane",
"vat_number": "FR81423093459",
"orgname": "Super Company",
"type": "company",
"email": "company@example.net",
"lastname": "Doe",
"reseller": false,
"name": "scompany",
"corporate": false
},