Domains and Contacts
The domain API allows you to get domain and contact data from the Database of Assigned Domains Names (DBNA). The domain scope in the token is required for all methods.
Domains
The following methods allow the Registrar to obtain domain data and related objects such as hosts, DS records, and contacts.
The domain views
When requesting data for one or more domains, you can include a view parameter that allows you to request additional information in the response. Supported values are:
- registrant: adds the registrant contact information
- admin: adds the admin contact information
- techs: adds the technical contact information
- hosts: adds the domain host information
- dsRecords: adds information about the DS records
- newHosts: adds information about any hosts currently being validated
- newDsRecords: adds information about any DS records currently being validated
- signed: adds information about whether the domain is DNSSec signed (added by default)
Get a domain by id
1.0 | domain | admin / domain |
GET https://api.nic.it/v1/domains/{domainId}
It allows you to get domain data by the numeric id assigned by the Registry. Example:
You can use the view parameter to integrate the response with more information. In the following example, registrant and hosts data are added to the response:
GET https://api.nic.it/v1/domains/1?view=registrant%2Chosts HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token.....
HTTP/1.1 200 OK
Content-Type: application/json
{
"id" : 1,
"domain" : "test-domain-test.it",
"status" : "ok",
"registrantId" : 1,
"adminId" : 1,
"created" : "2020-02-12T11:17:33+01:00",
"lastupdate" : "2020-02-12T11:17:33+01:00",
"expire" : "2025-02-12T23:59:59+01:00",
"registered" : true,
"registrant": {
"id": 12345,
"name": "Giulio Cesare",
"org": "Giulio Cesare Spa",
"contactId": "GC00001",
"consentForPublish": true,
"created": "2019-03-01T10:31:37+01:00",
"lastupdate": "2019-09-29T08:20:38+02:00",
"email": "hostmaster@nic.it",
"voice": "+39.0503151111",
"streets": [
"Via Moruzzi, 1"
],
"city": "Pisa",
"postalCode": "56124",
"state": "PI",
"country": "it",
"registrant": {
"regcode": "001122334455",
"nationality": "it",
"entityType": 2
}
},
"hosts": [
{
"name": "dns.nic.it"
},
{
"name": "dns2.nic.it"
}
]
}
curl "https://api.nic.it/v1/domains/1?view=registrant,hosts" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."
{
"id" : 1,
"domain" : "test-domain-test.it",
"status" : "ok",
"registrantId" : 1,
"adminId" : 1,
"created" : "2020-02-12T11:17:33+01:00",
"lastupdate" : "2020-02-12T11:17:33+01:00",
"expire" : "2025-02-12T23:59:59+01:00",
"registered" : true,
"registrant": {
"id": 12345,
"name": "Giulio Cesare",
"org": "Giulio Cesare Spa",
"contactId": "GC00001",
"consentForPublish": true,
"created": "2019-03-01T10:31:37+01:00",
"lastupdate": "2019-09-29T08:20:38+02:00",
"email": "hostmaster@nic.it",
"voice": "+39.0503151111",
"streets": [
"Via Moruzzi, 1"
],
"city": "Pisa",
"postalCode": "56124",
"state": "PI",
"country": "it",
"registrant": {
"regcode": "001122334455",
"nationality": "it",
"entityType": 2
}
},
"hosts": [
{
"name": "dns.nic.it"
},
{
"name": "dns2.nic.it"
}
]
}
{
"id" : 1,
"domain" : "test-domain-test.it",
"status" : "ok",
"registrantId" : 1,
"adminId" : 1,
"created" : "2020-02-12T11:17:33+01:00",
"lastupdate" : "2020-02-12T11:17:33+01:00",
"expire" : "2025-02-12T23:59:59+01:00",
"registered" : true,
"registrant": {
"id": 12345,
"name": "Giulio Cesare",
"org": "Giulio Cesare Spa",
"contactId": "GC00001",
"consentForPublish": true,
"created": "2019-03-01T10:31:37+01:00",
"lastupdate": "2019-09-29T08:20:38+02:00",
"email": "hostmaster@nic.it",
"voice": "+39.0503151111",
"streets": [
"Via Moruzzi, 1"
],
"city": "Pisa",
"postalCode": "56124",
"state": "PI",
"country": "it",
"registrant": {
"regcode": "001122334455",
"nationality": "it",
"entityType": 2
}
},
"hosts": [
{
"name": "dns.nic.it"
},
{
"name": "dns2.nic.it"
}
]
}
Get a domain by name
1.0 | domain | admin / domain |
GET https://api.nic.it/v1/domains/findByName/{domainName}
Allows you to get data for a domain registered by its name. Example:
You can use the view parameter to integrate the response with more information. See example on how to get a domain by id.
Info
Domain names can be searched in either ASCII/punycode or IDN UTF8 format. For example, searching for the following two names is equivalent: test-testò.it and xn--test-test-36a.it
Search for domains
1.0 | domain | admin / domain |
GET https://api.nic.it/v1/domains
You can search for domains belonging to the Registrar using multiple search parameters and operators (advanced search).
Below is the list of parameters and operators available for searching for domains:
| Parameter | Type | Cardinality | Description | Supported operators | Default Operator |
|---|---|---|---|---|---|
| domain | String | Single | Domain name in ASCII format | eq, ne | eq |
| created | DateTime | Multiple | Creation date | eq, ne, gt, lt, ge, le | eq |
| expire | DateTime | Multiple | Expire date | eq, ne, gt, lt, ge, le | eq |
| lastupdate | DateTime | Multiple | Last update | eq, ne, gt, lt, ge, le | eq |
| status | String | Multiple | Single domain status | eq, ne | eq |
| signed | Boolean | Single | True for DNSSec-signed domain, false for unsigned ones | - | - |
| hostname | String | Single | Host name associated with the domain | - | - |
| registrant.* | - | - | Domain search using registrant contact details | - | - |
| admin.* | - | - | Domain search using admin contact details | - | - |
| tech.* | - | - | Domain search using tech contacts details | - | - |
Example of searching for foreign domains (non-Italian registrant.nationality=ne:it) registered as of January 2024 (created=ge:2024-01-01&created=lt:2024-02-01):
GET /v1/domains?registrant.nationality=ne%3Ait&created=ge%3A2024-01-01&created=lt%3A2024-02-01 HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token....
HTTP/1.1 200 OK
Content-Type: application/json
{
"elements": [
{
"id": 12345,
"domain": "test-giulio-cessare.it",
"status": "ok",
"signed": false,
"registrantId": 111111,
"adminId": 22222,
"created": "2024-01-01T11:25:09+01:00",
"lastupdate": "2024-01-01T25:09+01:00",
"expire": "2025-01-01T23:59:59+01:00",
"registered": true
},
{
"id": 54321,
"domain": "test-galileo-galilei.it",
"status": "ok / dnsHold",
"signed": false,
"registrantId": 121212,
"adminId": 333333,
"created": "2024-01-03T14:13:12+01:00",
"lastupdate": "2024-01-03T15:46:05+01:00",
"expire": "2025-01-03T23:59:59+01:00",
"registered": true
}
],
"page": {
"number": 0,
"size": 20
}
}
curl "https://api.nic.it/v1/domains?registrant.nationality=ne:it&created=ge:2024-01-01&created=lt:2024-02-01" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."
{
"elements": [
{
"id": 12345,
"domain": "test-giulio-cessare.it",
"status": "ok",
"signed": false,
"registrantId": 111111,
"adminId": 22222,
"created": "2024-01-01T11:25:09+01:00",
"lastupdate": "2024-01-01T25:09+01:00",
"expire": "2025-01-01T23:59:59+01:00",
"registered": true
},
{
"id": 54321,
"domain": "test-galileo-galilei.it",
"status": "ok / dnsHold",
"signed": false,
"registrantId": 121212,
"adminId": 333333,
"created": "2024-01-03T14:13:12+01:00",
"lastupdate": "2024-01-03T15:46:05+01:00",
"expire": "2025-01-03T23:59:59+01:00",
"registered": true
}
],
"page": {
"number": 0,
"size": 20
}
}
http https://api.nic.it/v1/domains \
"Authorization: Bearer token..." \
registrant.nationality==ne:it \
created==ge:2024-01-01 created==lt:2024-02-01
{
"elements": [
{
"id": 12345,
"domain": "test-giulio-cessare.it",
"status": "ok",
"signed": false,
"registrantId": 111111,
"adminId": 22222,
"created": "2024-01-01T11:25:09+01:00",
"lastupdate": "2024-01-01T25:09+01:00",
"expire": "2025-01-01T23:59:59+01:00",
"registered": true
},
{
"id": 54321,
"domain": "test-galileo-galilei.it",
"status": "ok / dnsHold",
"signed": false,
"registrantId": 121212,
"adminId": 333333,
"created": "2024-01-03T14:13:12+01:00",
"lastupdate": "2024-01-03T15:46:05+01:00",
"expire": "2025-01-03T23:59:59+01:00",
"registered": true
}
],
"page": {
"number": 0,
"size": 20
}
}
The search results are paginated.
Note
Please note that for performance reasons, the pagination data does not include the count of items found. The count can be obtained using the count domains function with the same search parameters.
You can use use the view parameter to integrate the response with more information. See example on how to get a domain by id.
Warning
Depending on the search parameters used and the number of hits involved, it may take a long time to get results.
Count domains
1.0 | domain | admin / domain |
GET https://api.nic.it/v1/domains/count
You can count the results of a search instead of getting the data. The search parameters you can use are the same as those for domains search. Example:
Get domain events
1.0 | domain | admin / domain |
GET https://api.nic.it/v1/domains/{domainId}/events
Allows you to get the paginated list of events associated with a domain by the numeric id assigned by the Registry. Example:
GET /v1/domains/1/events HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token.....
HTTP/1.1 200 OK
Content-Type: application/json
{
"elements": [
{
"type": "epp",
"status": "succeeded",
"created": "2024-04-16T11:24:20+02:00",
"name": "test-domain-test.it",
"epp": {
"request": {
"created": "2024-04-16T11:24:18+02:00",
"command": "create",
"clientTrId": "ABC-12345"
},
"response": {
"created": "2024-04-16T11:24:20+02:00",
"code": 1000,
"codeName": "Command completed successfully",
"serverTrId": "it-123456"
}
}
}
],
"page": {
"number": 0,
"size": 20
}
}
Results are paginated.
Export domains list
1.0 | domain | admin / domain |
GET https://api.nic.it/v1/domains/export/all
This function allows you to export the entire list of domains registered by the Registrar. Two export formats are available and must be specified using the HTTP header parameter Accept:
- csv: "text/csv"
- jsonline: "application/jsonl". See jsonlines.org
You can specify some export options by adding the query parameter options, which can take one or more the following values (delimited by commas):
- domainDetail: adds the main details of the domain (such as status, creation date, expiration date, etc.)
- registrant: adds the main details of the registrant contact
- admin: adds the main details of the admin contact
- hosts: add the list of hosts associated to the domain
If no value is specified for options, only the list of domains will be exported without any additional information.
Example for exporting the list of registered domains in CSV format with domain details (domainDetail) and associated hosts (hosts):
Warning
Currently, exports are performed in real time by extracting data from the DBNA, so export times can be very long depending on the number of domains registered by the Registrar, but also depending on the details requested.
IDN conversion of domains
1.0 | domain | admin / domain |
GET https://api.nic.it/v1/domains/idnConverter
You can convert a domain name either to Unicode or Punycode format. Example:
Info
The domain parameter can be in ASCII, Punycode, or Unicode format.
Contacts
The following methods allow you to get contact data in the DBNA.
The contact views
When requesting data for one or more contacts, you can include a view parameter that allows you to request additional information in the response. Supported values are:
- status: adds information about the contact's status
- linked: adds information (boolean linked field) about whether the contact is associated to a domain
Get a contact by id
1.0 | domain | admin / domain |
GET https://api.nic.it/v1/contacts/{id}
It allows you to get the contact data by the numeric id assigned by the Registry. Example:
GET /v1/contacts/1234 HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token....
HTTP/1.1 200 OK
Content-Type: application/json
{
"id" : 1234,
"name" : "Registrante Uno",
"org" : "Registrante Uno Srl",
"contactId" : "REGISTRANT1",
"consentForPublish" : true,
"created" : "2020-02-12T11:01:49+01:00",
"lastupdate" : "2020-02-12T11:01:49+01:00",
"email" : "registrante@nic.it",
"voice" : "+39.0503151111",
"streets" : [ "Via Moruzzi, 1" ],
"city" : "Pisa",
"postalCode" : "56124",
"state" : "PI",
"country" : "it",
"registrant" : {
"regcode" : "002233445566",
"nationality" : "it",
"entityType" : 2
}
}
curl "https://api.nic.it/v1/contacts/1234" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."
{
"id" : 1234,
"name" : "Registrante Uno",
"org" : "Registrante Uno Srl",
"contactId" : "REGISTRANT1",
"consentForPublish" : true,
"created" : "2020-02-12T11:01:49+01:00",
"lastupdate" : "2020-02-12T11:01:49+01:00",
"email" : "registrante@nic.it",
"voice" : "+39.0503151111",
"streets" : [ "Via Moruzzi, 1" ],
"city" : "Pisa",
"postalCode" : "56124",
"state" : "PI",
"country" : "it",
"registrant" : {
"regcode" : "002233445566",
"nationality" : "it",
"entityType" : 2
}
}
{
"id" : 1234,
"name" : "Registrante Uno",
"org" : "Registrante Uno Srl",
"contactId" : "REGISTRANT1",
"consentForPublish" : true,
"created" : "2020-02-12T11:01:49+01:00",
"lastupdate" : "2020-02-12T11:01:49+01:00",
"email" : "registrante@nic.it",
"voice" : "+39.0503151111",
"streets" : [ "Via Moruzzi, 1" ],
"city" : "Pisa",
"postalCode" : "56124",
"state" : "PI",
"country" : "it",
"registrant" : {
"regcode" : "002233445566",
"nationality" : "it",
"entityType" : 2
}
}
You can use the view parameter to integrate the response with more information.
Get a contact by contactId
1.0 | domain | admin / domain |
GET https://api.nic.it/v1/contacts/findByContactId/{contactId}
It allows you to get the contact data by the alphanumeric id assigned by the Registrar. Example:
GET /v1/contacts/findByContactId/GC00001 HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token....
HTTP/1.1 200 OK
Content-Type: application/json
{
"id" : 1234,
"name" : "Giulio Cesare",
"org" : "Giulio Cesare Spa",
"contactId" : "GC00001",
"consentForPublish" : true,
"created" : "2020-02-12T11:01:49+01:00",
"lastupdate" : "2020-02-12T11:01:49+01:00",
"email" : "giulio.cesare@nic.it",
"voice" : "+39.0503151111",
"streets" : [ "Via Moruzzi, 1" ],
"city" : "Pisa",
"postalCode" : "56124",
"state" : "PI",
"country" : "it",
"registrant" : {
"regcode" : "002233445566",
"nationality" : "it",
"entityType" : 2
}
}
curl "https://api.nic.it/v1/contacts/findByContactId/GC00001" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."
{
"id" : 1234,
"name" : "Giulio Cesare",
"org" : "Giulio Cesare Spa",
"contactId" : "GC00001",
"consentForPublish" : true,
"created" : "2020-02-12T11:01:49+01:00",
"lastupdate" : "2020-02-12T11:01:49+01:00",
"email" : "giulio.cesare@nic.it",
"voice" : "+39.0503151111",
"streets" : [ "Via Moruzzi, 1" ],
"city" : "Pisa",
"postalCode" : "56124",
"state" : "PI",
"country" : "it",
"registrant" : {
"regcode" : "002233445566",
"nationality" : "it",
"entityType" : 2
}
}
{
"id" : 1234,
"name" : "Giulio Cesare",
"org" : "Giulio Cesare Spa",
"contactId" : "GC00001",
"consentForPublish" : true,
"created" : "2020-02-12T11:01:49+01:00",
"lastupdate" : "2020-02-12T11:01:49+01:00",
"email" : "giulio.cesare@nic.it",
"voice" : "+39.0503151111",
"streets" : [ "Via Moruzzi, 1" ],
"city" : "Pisa",
"postalCode" : "56124",
"state" : "PI",
"country" : "it",
"registrant" : {
"regcode" : "002233445566",
"nationality" : "it",
"entityType" : 2
}
}
You can use the view parameter to integrate the response with more information.
Search for contacts
1.0 | domain | admin / domain |
GET https://api.nic.it/v1/contacts
You can search for contacts belonging to the Registrar using multiple search parameters and operators (advanced search).
Below is the list of parameters and operators available for searching for contacts:
| Parameter | Type | Cardinality | Description | Supported operators | Default Operator |
|---|---|---|---|---|---|
| org | String | Single | Contact org | full-text search | - |
| name | String | Single | Contact name | full-text search | - |
| String | Single | e-mail address | - | - | |
| city | String | Single | City | - | - |
| state | String | Single | State or italian province | - | - |
| country | String | Single | Country home / HQ (ISO3166) | eq, ne | eq |
| regcode | String | Single | Fiscal code / Partita Iva / Registrant code | - | - |
| nationality | String | Single | Nationality (ISO3166) | eq, ne | eq |
| created | DateTime | Multiple | Creation date | eq, ne, gt, lt, ge, le | eq |
| ipaCode | String | Single | IPA code of gov.it domain registrants | eq, ne, isNull, isNotNull | eq |
| uoCode | String | Single | UO code of gov.it domain registrants | eq, ne, isNull, isNotNull | eq |
| schoolCode | String | Single | School code of edu.it domain registrants | eq, ne, isNull, isNotNull | eq |
| registrantType | Number | Single | Registrant type 1-7 | - | - |
Example of searching for italian registrants (nationality=it) located in the italian province of Pisa (state=PI):
GET /v1/contacts?nationality=it&state=PI HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token....
HTTP/1.1 200 OK
Content-Type: application/json
{
"elements": [
{
"id": 121212,
"name": "Giulio Cesare,
"org": "Giulio Cesare Spa",
"contactId": "GC00001",
"consentForPublish": true,
"created": "2016-10-25T00:00:00+02:00",
"lastupdate": "2017-06-16T10:16:34+02:00",
"email": "giulio.cesare@nic.it",
"voice": "+39.0503151111",
"streets": [
"Via Moruzzi, 1"
],
"city": "Pisa",
"postalCode": "56124",
"state": "PI",
"country": "it",
"registrant": {
"regcode": "002233445566",
"nationality": "it",
"entityType": 2
}
},
{
"id": 3,
"name": "Galileo Galilei",
"org": "Galileo Galilei",
"contactId": "GG00002",
"consentForPublish": false,
"created": "2022-01-30T00:00:00+01:00",
"lastupdate": "2023-06-16T10:16:34+02:00",
"email": "galileo.galilei@nic.it",
"voice": "+39.0503151111",
"streets": [
"Via G. Moruzzi, 1"
],
"city": "Pisa",
"postalCode": "56124",
"state": "PI",
"country": "it",
"registrant": {
"regcode": "GLLGLL80E01G702D",
"nationality": "it",
"entityType": 1
}
}
],
"page": {
"number": 0,
"size": 20
}
}
curl "https://api.nic.it/v1/contacts?nationality=it&state=PI" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."
{
"elements": [
{
"id": 121212,
"name": "Giulio Cesare,
"org": "Giulio Cesare Spa",
"contactId": "GC00001",
"consentForPublish": true,
"created": "2016-10-25T00:00:00+02:00",
"lastupdate": "2017-06-16T10:16:34+02:00",
"email": "giulio.cesare@nic.it",
"voice": "+39.0503151111",
"streets": [
"Via Moruzzi, 1"
],
"city": "Pisa",
"postalCode": "56124",
"state": "PI",
"country": "it",
"registrant": {
"regcode": "002233445566",
"nationality": "it",
"entityType": 2
}
},
{
"id": 3,
"name": "Galileo Galilei",
"org": "Galileo Galilei",
"contactId": "GG00002",
"consentForPublish": false,
"created": "2022-01-30T00:00:00+01:00",
"lastupdate": "2023-06-16T10:16:34+02:00",
"email": "galileo.galilei@nic.it",
"voice": "+39.0503151111",
"streets": [
"Via G. Moruzzi, 1"
],
"city": "Pisa",
"postalCode": "56124",
"state": "PI",
"country": "it",
"registrant": {
"regcode": "GLLGLL80E01G702D",
"nationality": "it",
"entityType": 1
}
}
],
"page": {
"number": 0,
"size": 20
}
}
{
"elements": [
{
"id": 121212,
"name": "Giulio Cesare,
"org": "Giulio Cesare Spa",
"contactId": "GC00001",
"consentForPublish": true,
"created": "2016-10-25T00:00:00+02:00",
"lastupdate": "2017-06-16T10:16:34+02:00",
"email": "giulio.cesare@nic.it",
"voice": "+39.0503151111",
"streets": [
"Via Moruzzi, 1"
],
"city": "Pisa",
"postalCode": "56124",
"state": "PI",
"country": "it",
"registrant": {
"regcode": "002233445566",
"nationality": "it",
"entityType": 2
}
},
{
"id": 3,
"name": "Galileo Galilei",
"org": "Galileo Galilei",
"contactId": "GG00002",
"consentForPublish": false,
"created": "2022-01-30T00:00:00+01:00",
"lastupdate": "2023-06-16T10:16:34+02:00",
"email": "galileo.galilei@nic.it",
"voice": "+39.0503151111",
"streets": [
"Via G. Moruzzi, 1"
],
"city": "Pisa",
"postalCode": "56124",
"state": "PI",
"country": "it",
"registrant": {
"regcode": "GLLGLL80E01G702D",
"nationality": "it",
"entityType": 1
}
}
],
"page": {
"number": 0,
"size": 20
}
}
The search results are paginated.
Note
Please note that for performance reasons, the pagination data does not include the count of items found. The count can be obtained using the count contacts function with the same search parameters.
You can use the view parameter to integrate the response with more information.
Warning
Depending on the search parameters used and the number of hits involved, it may take a long time to get results.
Count contacts
1.0 | domain | admin / domain |
GET https://api.nic.it/v1/contacts/count
You can count the results of a search instead of getting the data. The search parameters that can be used are the same as those for contacts search. Example:
Contare i contatti
1.0 | domain | admin / domain |
GET https://api.nic.it/v1/contacts/count
E' possibile contare i risultati di una ricerca invece di ottenerne i dati. I parametri di ricerca utilizzabili sono gli stessi indicati per la ricerca dei contatti, esempio:
Export registrants list
1.0 | domain | admin / domain |
GET https://api.nic.it/v1/contacts/export/registrants
This function allows you to export the entire list of registrants in linked status (referenced in at least one domain of the Registrar). Two export formats are available and must be specified using the HTTP header parameter Accept:
- csv: "text/csv"
- jsonline: "application/jsonl". Si veda jsonlines.org
Example for exporting the list of registrants in CSV format:
Warning
Currently, exports are performed in real time by extracting data from the DBNA, so export times can be very long depending on the number of registrants with the Registrar.