Darwin

To access the Darwin API, the scope darwin must be present in the token, and users belonging to the following groups can access the API:

• admin
• domain
• darwin

A user belonging to the darwin group will have limited access to requests assigned by the administrator user (admin group).

For details on available methods and resources, see the OpenAPI documentation.

Warning

The Darwin API is not currently available on the test platform (pubtest).

Overview

The Darwin API allows the Registrar to work on procedures reported by the Registry concerning anomalies on registrant contacts. It makes it possible to manage open requests, the involved contacts and domains, detected anomalies, processing events, required documents, and any proposed updates for the reference contact.

The typical workflow is as follows:

1. search for available Darwin requests;
2. take ownership of or assign a request;
3. inspect the reference contact, linked contacts, domains, anomalies, and events;
4. upload required documents and, if needed, submit an update to the contact data;
5. validate the submitted data and process the request.

Statuses and useful values

Request statuses

Possible values for the status field of a Darwin request are:

• submitted
• pending
• rejected
• registrarUpdated
• processing
• processingExpired
• expired
• completed
• processingCancelled
• cancelled

Darwin contact statuses

Possible values for the status field of a Darwin contact are:

• submitted
• rejected
• locked
• processed

Contact actions

Possible values for the action field are:

Code	Description
todo	Contact selected to be updated
hold	Contact that will not be updated and whose linked domains will be set to serverHold
delete	Contact that will be deleted together with the linked domains

Assignment statuses

The following values are available to filter requests through the registrarAssignation parameter:

• all
• assigned
• unassigned
• assignedToMe

Document types

Possible values for the documentType field are:

Code	Description
IC	Identity card
PASS	Passport
FC	Tax code
CHAMBER	Chamber of Commerce extract
DEED	Articles of incorporation
CERT	VAT registration certificate
OTHER	Other

Anomaly types

Possible codes returned in the codes field of Darwin anomalies are:

Code	Description
1010	Classifier predicted bad registrant organization name
1020	Language impossible to detect for registrant organization
1030	Language inconsistent with the nationality field
1040	Language inconsistent with the country field
1050	Person name similar to a company name
1060	Person name inconsistent with Fiscal Code
1070	Name inconsistent with VAT validation
1080	Org value set NOT OK by an operator
2010	Nationality must be equal to country
2020	Nationality set NOT OK by an operator
3010	Classifier predicted bad registrant address
3020	Language impossible to detect for registrant address
3030	Registrant address not found
3040	Address inconsistent with the country code
3050	Address inconsistent with VAT validation
3060	Address set NOT OK by an operator
4010	Irregular Fiscal Code or VAT number
4020	VIES check failed
4021	VAT number not found
4022	VAT name anomaly
4023	VAT address anomaly
4030	Many different registrants with this regcode
4040	F.C. or VAT number set NOT OK by an operator

Darwin requests

Search requests

1.0 | darwin | admin / domain / darwin |

GET https://api.nic.it/v1/darwin/requests

Returns the paged list of Darwin requests. The following filters are available:

Parameter	Description
referenceContactOrg	search by reference contact organization (startsWith)
referenceContactRegcode	search by reference contact identifier code
registrarAssignation	filter by assignment state
status	filter by request status
page	result page, default 0
size	number of elements per page, default 20
view	adds extra information; allowed values are referenceContact and expirationDays, comma-separated

HTTPcURL

GET /v1/darwin/requests?status=pending&registrarAssignation=assignedToMe&view=referenceContact,expirationDays HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "elements" : [ {
    "id" : 125,
    "registrarId" : 10,
    "status" : "pending",
    "statusDate" : "2024-04-10T09:14:21+02:00",
    "created" : "2024-04-08T11:30:00+02:00",
    "expirationDays" : 5,
    "referenceContact" : {
      "contactId" : 101,
      "requestId" : 125,
      "registrarContactId" : "C-1001",
      "dbnaId" : 998877,
      "org" : "Example S.r.l.",
      "regcode" : "RSSMRA80A01H501Z"
    }
  } ],
  "page" : {
    "page" : 0,
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1
  }
}

curl "https://api.nic.it/v1/darwin/requests?status=pending&registrarAssignation=assignedToMe&view=referenceContact,expirationDays" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "elements" : [ {
    "id" : 125,
    "registrarId" : 10,
    "status" : "pending",
    "statusDate" : "2024-04-10T09:14:21+02:00",
    "created" : "2024-04-08T11:30:00+02:00",
    "expirationDays" : 5,
    "referenceContact" : {
      "contactId" : 101,
      "requestId" : 125,
      "registrarContactId" : "C-1001",
      "dbnaId" : 998877,
      "org" : "Example S.r.l.",
      "regcode" : "RSSMRA80A01H501Z"
    }
  } ],
  "page" : {
    "page" : 0,
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1
  }
}

Search results are paged.

Count requests

1.0 | darwin | admin / domain / darwin |

GET https://api.nic.it/v1/darwin/requests/count

Returns the number of requests that match the same filters available for the search.

HTTPcURL

GET /v1/darwin/requests/count?status=pending&registrarAssignation=assigned HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "count" : 12
}

curl "https://api.nic.it/v1/darwin/requests/count?status=pending&registrarAssignation=assigned" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "count" : 12
}

Get expiring requests

1.0 | darwin | admin / domain / darwin |

GET https://api.nic.it/v1/darwin/requests/expiring?days={days}

Returns the paged list of requests expiring within the number of days specified by days. The same search filters related to the reference contact and assignment state are available.

HTTPcURL

GET /v1/darwin/requests/expiring?days=7&registrarAssignation=assignedToMe&view=referenceContact,expirationDays HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "elements" : [ {
    "id" : 125,
    "registrarId" : 10,
    "status" : "pending",
    "statusDate" : "2024-04-10T09:14:21+02:00",
    "created" : "2024-04-08T11:30:00+02:00",
    "expirationDays" : 5,
    "referenceContact" : {
      "contactId" : 101,
      "requestId" : 125,
      "registrarContactId" : "C-1001",
      "dbnaId" : 998877,
      "org" : "Example S.r.l.",
      "regcode" : "RSSMRA80A01H501Z"
    }
  } ],
  "page" : {
    "page" : 0,
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1
  }
}

curl "https://api.nic.it/v1/darwin/requests/expiring?days=7&registrarAssignation=assignedToMe&view=referenceContact,expirationDays" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "elements" : [ {
    "id" : 125,
    "registrarId" : 10,
    "status" : "pending",
    "statusDate" : "2024-04-10T09:14:21+02:00",
    "created" : "2024-04-08T11:30:00+02:00",
    "expirationDays" : 5,
    "referenceContact" : {
      "contactId" : 101,
      "requestId" : 125,
      "registrarContactId" : "C-1001",
      "dbnaId" : 998877,
      "org" : "Example S.r.l.",
      "regcode" : "RSSMRA80A01H501Z"
    }
  } ],
  "page" : {
    "page" : 0,
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1
  }
}

Search results are paged.

Count expiring requests

1.0 | darwin | admin / domain / darwin |

GET https://api.nic.it/v1/darwin/requests/expiring/count?days={days}

Returns the number of requests expiring within the specified number of days.

HTTPcURL

GET /v1/darwin/requests/expiring/count?days=7&registrarAssignation=assignedToMe HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "count" : 3
}

curl "https://api.nic.it/v1/darwin/requests/expiring/count?days=7&registrarAssignation=assignedToMe" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "count" : 3
}

Get a request by id

1.0 | darwin | admin / domain / darwin |

GET https://api.nic.it/v1/darwin/requests/{requestId}

Returns the request details. Here too, the optional view parameter can be used to include referenceContact and expirationDays.

HTTPcURL

GET /v1/darwin/requests/125?view=referenceContact,expirationDays HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id" : 125,
  "registrarId" : 10,
  "status" : "pending",
  "statusDate" : "2024-04-10T09:14:21+02:00",
  "note" : "Verify registrant data",
  "created" : "2024-04-08T11:30:00+02:00",
  "expirationDays" : 5,
  "referenceContact" : {
    "contactId" : 101,
    "requestId" : 125,
    "registrarContactId" : "C-1001",
    "dbnaId" : 998877,
    "org" : "Example S.r.l.",
    "regcode" : "RSSMRA80A01H501Z"
  },
  "requiredDocuments" : {
    "documents" : [ "IC", "FC" ]
  },
  "registrarUser" : {
    "id" : 123,
    "username" : "darwin.user",
    "name" : "Mario Rossi"
  }
}

curl "https://api.nic.it/v1/darwin/requests/125?view=referenceContact,expirationDays" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "id" : 125,
  "registrarId" : 10,
  "status" : "pending",
  "statusDate" : "2024-04-10T09:14:21+02:00",
  "note" : "Verify registrant data",
  "created" : "2024-04-08T11:30:00+02:00",
  "expirationDays" : 5,
  "referenceContact" : {
    "contactId" : 101,
    "requestId" : 125,
    "registrarContactId" : "C-1001",
    "dbnaId" : 998877,
    "org" : "Example S.r.l.",
    "regcode" : "RSSMRA80A01H501Z"
  },
  "requiredDocuments" : {
    "documents" : [ "IC", "FC" ]
  },
  "registrarUser" : {
    "id" : 123,
    "username" : "darwin.user",
    "name" : "Mario Rossi"
  }
}

Get request anomalies

1.0 | darwin | admin / domain / darwin |

GET https://api.nic.it/v1/darwin/requests/{requestId}/anomalies

Returns the list of anomalies associated with the request. Each anomaly contains:

• field: anomalous field;
• codes: list of anomaly codes;
• contacts: optional list of involved contacts.

HTTPcURL

GET /v1/darwin/requests/125/anomalies HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token...

HTTP/1.1 200 OK
Content-Type: application/json

[ {
  "field" : "registrant.regcode",
  "codes" : [ 4010, 4030 ],
  "contacts" : [ "C-1001", "C-1002" ]
} ]

curl "https://api.nic.it/v1/darwin/requests/125/anomalies" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

[ {
  "field" : "registrant.regcode",
  "codes" : [ 4010, 4030 ],
  "contacts" : [ "C-1001", "C-1002" ]
} ]

Get the chosen reference contact

1.0 | darwin | admin / domain / darwin |

GET https://api.nic.it/v1/darwin/requests/{requestId}/referenceContact

Returns the data of the contact chosen as reference for the request: Darwin and DBNA identifiers, registrarContactId, organization, and identifier code.

HTTPcURL

GET /v1/darwin/requests/125/referenceContact HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "contactId" : 101,
  "requestId" : 125,
  "registrarContactId" : "C-1001",
  "dbnaId" : 998877,
  "org" : "Example S.r.l.",
  "regcode" : "RSSMRA80A01H501Z"
}

curl "https://api.nic.it/v1/darwin/requests/125/referenceContact" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "contactId" : 101,
  "requestId" : 125,
  "registrarContactId" : "C-1001",
  "dbnaId" : 998877,
  "org" : "Example S.r.l.",
  "regcode" : "RSSMRA80A01H501Z"
}

Get days until expiration

1.0 | darwin | admin / domain / darwin |

GET https://api.nic.it/v1/darwin/requests/{requestId}/expirationDays

Returns the number of days remaining before the request expires.

HTTPcURL

GET /v1/darwin/requests/125/expirationDays HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "count" : 5
}

curl "https://api.nic.it/v1/darwin/requests/125/expirationDays" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "count" : 5
}

Assign a request to the authenticated user

1.0 | darwin | admin / domain |

POST https://api.nic.it/v1/darwin/requests/{requestId}/assignToMe

Assigns the request to the authenticated user. The method can return 409 Conflict if the request is already assigned or if its status is not compatible with the operation.

HTTPcURL

POST /v1/darwin/requests/125/assignToMe HTTP/1.1
Host: api.nic.it
Authorization: Bearer token...

HTTP/1.1 204 No Content

curl -X POST "https://api.nic.it/v1/darwin/requests/125/assignToMe" \
-H "Authorization: Bearer token..."

Assign a request to a user

1.0 | darwin | admin |

POST https://api.nic.it/v1/darwin/requests/{requestId}/assignToUser

Allows an admin user to assign the request to a specific Darwin user using the following payload:

{
  "userId" : 123
}

HTTPcURL

POST /v1/darwin/requests/125/assignToUser HTTP/1.1
Content-Type: application/json
Host: api.nic.it
Authorization: Bearer token...

{
  "userId" : 123
}

HTTP/1.1 204 No Content

curl -X POST "https://api.nic.it/v1/darwin/requests/125/assignToUser" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer token..." \
-d '{
  "userId" : 123
}'

Release assignment

1.0 | darwin | admin / domain |

POST https://api.nic.it/v1/darwin/requests/{requestId}/assignationRelease

Releases the assignment of the request. The method can return 409 Conflict if the request is not assigned or if its status is not compatible with the operation.

HTTPcURL

POST /v1/darwin/requests/125/assignationRelease HTTP/1.1
Host: api.nic.it
Authorization: Bearer token...

HTTP/1.1 204 No Content

curl -X POST "https://api.nic.it/v1/darwin/requests/125/assignationRelease" \
-H "Authorization: Bearer token..."

Process a request

1.0 | darwin | admin / domain / darwin |

POST https://api.nic.it/v1/darwin/requests/{requestId}/process

Starts processing the request and returns the updated state of the resource. If data is missing or inconsistent, the service returns 400 Bad Request.

HTTPcURL

POST /v1/darwin/requests/125/process HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id" : 125,
  "registrarId" : 10,
  "status" : "processing",
  "statusDate" : "2024-04-10T10:02:11+02:00",
  "created" : "2024-04-08T11:30:00+02:00"
}

curl -X POST "https://api.nic.it/v1/darwin/requests/125/process" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "id" : 125,
  "registrarId" : 10,
  "status" : "processing",
  "statusDate" : "2024-04-10T10:02:11+02:00",
  "created" : "2024-04-08T11:30:00+02:00"
}

Darwin contacts

Search contacts

1.0 | darwin | admin / domain / darwin |

GET https://api.nic.it/v1/darwin/contacts

Allows searching for Darwin contacts linked to requests using the following filters:

Parameter	Description
action	filtra per azione (todo, hold, delete)
dbnaId	numeric identifier of the contact in DBNA
registrarContactId	contact identifier assigned by the Registrar
requestId	Darwin request identifier
page	result page, default 0
size	number of elements per page, default 20

Each element contains, among other fields, id, dbnaId, requestId, registrarContactId, action, status, and the reference flag.

HTTPcURL

GET /v1/darwin/contacts?requestId=125&action=todo&page=0&size=20 HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "elements" : [ {
    "id" : 101,
    "dbnaId" : 998877,
    "requestId" : 125,
    "registrarContactId" : "C-1001",
    "action" : "todo",
    "status" : "submitted",
    "reference" : true
  } ],
  "page" : {
    "page" : 0,
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1
  }
}

curl "https://api.nic.it/v1/darwin/contacts?requestId=125&action=todo&page=0&size=20" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "elements" : [ {
    "id" : 101,
    "dbnaId" : 998877,
    "requestId" : 125,
    "registrarContactId" : "C-1001",
    "action" : "todo",
    "status" : "submitted",
    "reference" : true
  } ],
  "page" : {
    "page" : 0,
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1
  }
}

Search results are paged.

Count contacts

1.0 | darwin | admin / domain / darwin |

GET https://api.nic.it/v1/darwin/contacts/count

Returns the total number of contacts matching the search filters.

HTTPcURL

GET /v1/darwin/contacts/count?requestId=125&action=todo HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "count" : 4
}

curl "https://api.nic.it/v1/darwin/contacts/count?requestId=125&action=todo" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "count" : 4
}

Get a contact

1.0 | darwin | admin / domain / darwin |

GET https://api.nic.it/v1/darwin/contacts/{contactId}

Returns the details of the Darwin contact.

HTTPcURL

GET /v1/darwin/contacts/101 HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id" : 101,
  "dbnaId" : 998877,
  "requestId" : 125,
  "registrarContactId" : "C-1001",
  "action" : "todo",
  "status" : "submitted",
  "reference" : true
}

curl "https://api.nic.it/v1/darwin/contacts/101" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "id" : 101,
  "dbnaId" : 998877,
  "requestId" : 125,
  "registrarContactId" : "C-1001",
  "action" : "todo",
  "status" : "submitted",
  "reference" : true
}

Update contact action

1.0 | darwin | admin / domain / darwin |

PATCH https://api.nic.it/v1/darwin/contacts/{contactId}

Allows updating the action associated with a single contact:

{
  "action" : "hold"
}

HTTPcURL

PATCH /v1/darwin/contacts/101 HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: api.nic.it
Authorization: Bearer token...

{
  "action" : "hold"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id" : 101,
  "dbnaId" : 998877,
  "requestId" : 125,
  "registrarContactId" : "C-1001",
  "action" : "hold",
  "status" : "submitted",
  "reference" : true
}

curl -X PATCH "https://api.nic.it/v1/darwin/contacts/101" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer token..." \
-d '{
  "action" : "hold"
}'

{
  "id" : 101,
  "dbnaId" : 998877,
  "requestId" : 125,
  "registrarContactId" : "C-1001",
  "action" : "hold",
  "status" : "submitted",
  "reference" : true
}

Bulk update contact actions for a request

1.0 | darwin | admin / domain / darwin |

PUT https://api.nic.it/v1/darwin/contacts/changeAction/request/{requestId}

Applies the same action to all contacts linked to the specified request.

HTTPcURL

PUT /v1/darwin/contacts/changeAction/request/125 HTTP/1.1
Content-Type: application/json
Host: api.nic.it
Authorization: Bearer token...

{
  "action" : "hold"
}

HTTP/1.1 200 OK

curl -X PUT "https://api.nic.it/v1/darwin/contacts/changeAction/request/125" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer token..." \
-d '{
  "action" : "hold"
}'

Get contact anomalies

1.0 | darwin | admin / domain / darwin |

GET https://api.nic.it/v1/darwin/contacts/{contactId}/anomalies

If the optional all=true parameter is present, the service returns both general anomalies and those specific to the contact.

HTTPcURL

GET /v1/darwin/contacts/101/anomalies?all=true HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token...

HTTP/1.1 200 OK
Content-Type: application/json

[ {
  "field" : "email",
  "codes" : [ 3010 ]
}, {
  "field" : "registrant.regcode",
  "codes" : [ 4010 ],
  "contacts" : [ "C-1001" ]
} ]

curl "https://api.nic.it/v1/darwin/contacts/101/anomalies?all=true" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

[ {
  "field" : "email",
  "codes" : [ 3010 ]
}, {
  "field" : "registrant.regcode",
  "codes" : [ 4010 ],
  "contacts" : [ "C-1001" ]
} ]

Get DBNA contact data

1.0 | darwin | admin / domain / darwin |

GET https://api.nic.it/v1/darwin/contacts/{contactId}/dbna

Returns the contact data as stored in DBNA.

HTTPcURL

GET /v1/darwin/contacts/101/dbna HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id" : 998877,
  "name" : "Mario Rossi",
  "org" : "Example S.r.l.",
  "contactId" : "C-1001",
  "consentForPublish" : true,
  "email" : "info@example.it",
  "voice" : "+39.0612345678",
  "streets" : [ "Via Roma 1" ],
  "city" : "Roma",
  "postalCode" : "00100",
  "state" : "RM",
  "country" : "it",
  "registrant" : {
    "regcode" : "RSSMRA80A01H501Z",
    "nationality" : "it",
    "entityType" : 1
  },
  "status" : "ok / linked",
  "linked" : true
}

curl "https://api.nic.it/v1/darwin/contacts/101/dbna" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "id" : 998877,
  "name" : "Mario Rossi",
  "org" : "Example S.r.l.",
  "contactId" : "C-1001",
  "consentForPublish" : true,
  "email" : "info@example.it",
  "voice" : "+39.0612345678",
  "streets" : [ "Via Roma 1" ],
  "city" : "Roma",
  "postalCode" : "00100",
  "state" : "RM",
  "country" : "it",
  "registrant" : {
    "regcode" : "RSSMRA80A01H501Z",
    "nationality" : "it",
    "entityType" : 1
  },
  "status" : "ok / linked",
  "linked" : true
}

Contact data updates

Contact data updates allow proposing a new version of the registrant data to associate with the Darwin request.

The contactData payload contains the following main fields:

• name
• org
• streets 1 to 3 values
• city
• state
• postalCode
• country (cannot be changed by the Registrar)
• voice
• fax
• email
• consentForPublish
• registrant.regcode

The registrant.nationality and registrant.entityType fields are read-only.

List updates for a request

1.0 | darwin | admin / domain / darwin |

GET https://api.nic.it/v1/darwin/contactUpdates?requestId={requestId}

Returns all updates entered for the request.

HTTPcURL

GET /v1/darwin/contactUpdates?requestId=125 HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token...

HTTP/1.1 200 OK
Content-Type: application/json

[ {
  "id" : 501,
  "requestId" : 125,
  "message" : "Registrant requested a contact data update",
  "contactData" : {
    "name" : "Mario Rossi",
    "org" : "Example S.r.l.",
    "streets" : [ "Via Roma 1" ],
    "city" : "Roma",
    "state" : "RM",
    "postalCode" : "00100",
    "country" : "IT",
    "voice" : "+39.0612345678",
    "email" : "info@example.it",
    "consentForPublish" : true,
    "registrant" : {
      "regcode" : "RSSMRA80A01H501Z"
    }
  },
  "created" : "2024-04-10T09:30:00+02:00"
} ]

curl "https://api.nic.it/v1/darwin/contactUpdates?requestId=125" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

[ {
  "id" : 501,
  "requestId" : 125,
  "message" : "Registrant requested a contact data update",
  "contactData" : {
    "name" : "Mario Rossi",
    "org" : "Example S.r.l.",
    "streets" : [ "Via Roma 1" ],
    "city" : "Roma",
    "state" : "RM",
    "postalCode" : "00100",
    "country" : "IT",
    "voice" : "+39.0612345678",
    "email" : "info@example.it",
    "consentForPublish" : true,
    "registrant" : {
      "regcode" : "RSSMRA80A01H501Z"
    }
  },
  "created" : "2024-04-10T09:30:00+02:00"
} ]

Get the current update

1.0 | darwin | admin / domain / darwin |

GET https://api.nic.it/v1/darwin/contactUpdates/current?requestId={requestId}

Returns the latest update entered for the request.

HTTPcURL

GET /v1/darwin/contactUpdates/current?requestId=125 HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id" : 501,
  "requestId" : 125,
  "message" : "Registrant requested a contact data update",
  "contactData" : {
    "name" : "Mario Rossi",
    "org" : "Example S.r.l.",
    "streets" : [ "Via Roma 1" ],
    "city" : "Roma",
    "state" : "RM",
    "postalCode" : "00100",
    "country" : "IT",
    "voice" : "+39.0612345678",
    "email" : "info@example.it",
    "consentForPublish" : true,
    "registrant" : {
      "regcode" : "RSSMRA80A01H501Z"
    }
  },
  "created" : "2024-04-10T09:30:00+02:00"
}

curl "https://api.nic.it/v1/darwin/contactUpdates/current?requestId=125" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "id" : 501,
  "requestId" : 125,
  "message" : "Registrant requested a contact data update",
  "contactData" : {
    "name" : "Mario Rossi",
    "org" : "Example S.r.l.",
    "streets" : [ "Via Roma 1" ],
    "city" : "Roma",
    "state" : "RM",
    "postalCode" : "00100",
    "country" : "IT",
    "voice" : "+39.0612345678",
    "email" : "info@example.it",
    "consentForPublish" : true,
    "registrant" : {
      "regcode" : "RSSMRA80A01H501Z"
    }
  },
  "created" : "2024-04-10T09:30:00+02:00"
}

Get an update by id

1.0 | darwin | admin / domain / darwin |

GET https://api.nic.it/v1/darwin/contactUpdates/{contactUpdateId}

Returns the details of a specific update.

HTTPcURL

GET /v1/darwin/contactUpdates/501 HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id" : 501,
  "requestId" : 125,
  "message" : "Registrant requested a contact data update",
  "contactData" : {
    "name" : "Mario Rossi",
    "org" : "Example S.r.l.",
    "streets" : [ "Via Roma 1" ],
    "city" : "Roma",
    "state" : "RM",
    "postalCode" : "00100",
    "country" : "IT",
    "voice" : "+39.0612345678",
    "email" : "info@example.it",
    "consentForPublish" : true,
    "registrant" : {
      "regcode" : "RSSMRA80A01H501Z"
    }
  },
  "created" : "2024-04-10T09:30:00+02:00"
}

curl "https://api.nic.it/v1/darwin/contactUpdates/501" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "id" : 501,
  "requestId" : 125,
  "message" : "Registrant requested a contact data update",
  "contactData" : {
    "name" : "Mario Rossi",
    "org" : "Example S.r.l.",
    "streets" : [ "Via Roma 1" ],
    "city" : "Roma",
    "state" : "RM",
    "postalCode" : "00100",
    "country" : "IT",
    "voice" : "+39.0612345678",
    "email" : "info@example.it",
    "consentForPublish" : true,
    "registrant" : {
      "regcode" : "RSSMRA80A01H501Z"
    }
  },
  "created" : "2024-04-10T09:30:00+02:00"
}

Create an update

1.0 | darwin | admin / domain / darwin |

POST https://api.nic.it/v1/darwin/contactUpdates

Example payload:

{
  "requestId" : 125,
  "message" : "Registrant requested a contact data update",
  "contactData" : {
    "name" : "Mario Rossi",
    "org" : "Example S.r.l.",
    "streets" : [ "Via Roma 1" ],
    "city" : "Roma",
    "state" : "RM",
    "postalCode" : "00100",
    "country" : "IT",
    "voice" : "+39.0612345678",
    "email" : "info@example.it",
    "consentForPublish" : true,
    "registrant" : {
      "regcode" : "RSSMRA80A01H501Z"
    }
  }
}

The service returns 201 Created with the created update. If the request status is not compatible, 409 Conflict is returned.

HTTPcURL

POST /v1/darwin/contactUpdates HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: api.nic.it
Authorization: Bearer token...

{
  "requestId" : 125,
  "message" : "Registrant requested a contact data update",
  "contactData" : {
    "name" : "Mario Rossi",
    "org" : "Example S.r.l.",
    "streets" : [ "Via Roma 1" ],
    "city" : "Roma",
    "state" : "RM",
    "postalCode" : "00100",
    "country" : "IT",
    "voice" : "+39.0612345678",
    "email" : "info@example.it",
    "consentForPublish" : true,
    "registrant" : {
      "regcode" : "RSSMRA80A01H501Z"
    }
  }
}

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id" : 501,
  "requestId" : 125,
  "message" : "Registrant requested a contact data update",
  "contactData" : {
    "name" : "Mario Rossi",
    "org" : "Example S.r.l.",
    "streets" : [ "Via Roma 1" ],
    "city" : "Roma",
    "state" : "RM",
    "postalCode" : "00100",
    "country" : "IT",
    "voice" : "+39.0612345678",
    "email" : "info@example.it",
    "consentForPublish" : true,
    "registrant" : {
      "regcode" : "RSSMRA80A01H501Z"
    }
  },
  "created" : "2024-04-10T09:30:00+02:00"
}

curl -X POST "https://api.nic.it/v1/darwin/contactUpdates" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer token..." \
-d '{
  "requestId" : 125,
  "message" : "Registrant requested a contact data update",
  "contactData" : {
    "name" : "Mario Rossi",
    "org" : "Example S.r.l.",
    "streets" : [ "Via Roma 1" ],
    "city" : "Roma",
    "state" : "RM",
    "postalCode" : "00100",
    "country" : "IT",
    "voice" : "+39.0612345678",
    "email" : "info@example.it",
    "consentForPublish" : true,
    "registrant" : {
      "regcode" : "RSSMRA80A01H501Z"
    }
  }
}'

{
  "id" : 501,
  "requestId" : 125,
  "message" : "Registrant requested a contact data update",
  "contactData" : {
    "name" : "Mario Rossi",
    "org" : "Example S.r.l.",
    "streets" : [ "Via Roma 1" ],
    "city" : "Roma",
    "state" : "RM",
    "postalCode" : "00100",
    "country" : "IT",
    "voice" : "+39.0612345678",
    "email" : "info@example.it",
    "consentForPublish" : true,
    "registrant" : {
      "regcode" : "RSSMRA80A01H501Z"
    }
  },
  "created" : "2024-04-10T09:30:00+02:00"
}

Validate update data

1.0 | darwin | admin / domain / darwin |

POST https://api.nic.it/v1/darwin/contactUpdates/validate

Validates an update payload without creating new resources. On success, it returns 204 No Content.

HTTPcURL

POST /v1/darwin/contactUpdates/validate HTTP/1.1
Content-Type: application/json
Host: api.nic.it
Authorization: Bearer token...

{
  "requestId" : 125,
  "contactData" : {
    "name" : "Mario Rossi",
    "org" : "Example S.r.l.",
    "streets" : [ "Via Roma 1" ],
    "city" : "Roma",
    "state" : "RM",
    "postalCode" : "00100",
    "country" : "IT",
    "voice" : "+39.0612345678",
    "email" : "info@example.it",
    "consentForPublish" : true,
    "registrant" : {
      "regcode" : "RSSMRA80A01H501Z"
    }
  }
}

HTTP/1.1 204 No Content

curl -X POST "https://api.nic.it/v1/darwin/contactUpdates/validate" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer token..." \
-d '{
  "requestId" : 125,
  "contactData" : {
    "name" : "Mario Rossi",
    "org" : "Example S.r.l.",
    "streets" : [ "Via Roma 1" ],
    "city" : "Roma",
    "state" : "RM",
    "postalCode" : "00100",
    "country" : "IT",
    "voice" : "+39.0612345678",
    "email" : "info@example.it",
    "consentForPublish" : true,
    "registrant" : {
      "regcode" : "RSSMRA80A01H501Z"
    }
  }
}'

Darwin domains

Search domains

1.0 | darwin | admin / domain / darwin |

GET https://api.nic.it/v1/darwin/domains

Allows searching for domains involved in one or more Darwin requests. Available filters are:

• contactId
• dbnaId
• domain
• registrarContactId
• requestId
• page
• size

HTTPcURL

GET /v1/darwin/domains?requestId=125&registrarContactId=C-1001 HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "elements" : [ {
    "id" : 301,
    "dbnaId" : 778899,
    "domain" : "example.it",
    "registrarContactId" : "C-1001",
    "requestId" : 125,
    "contactId" : 101,
    "status" : "locked"
  } ],
  "page" : {
    "page" : 0,
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1
  }
}

curl "https://api.nic.it/v1/darwin/domains?requestId=125&registrarContactId=C-1001" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "elements" : [ {
    "id" : 301,
    "dbnaId" : 778899,
    "domain" : "example.it",
    "registrarContactId" : "C-1001",
    "requestId" : 125,
    "contactId" : 101,
    "status" : "locked"
  } ],
  "page" : {
    "page" : 0,
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1
  }
}

Search results are paged.

Count domains

1.0 | darwin | admin / domain / darwin |

GET https://api.nic.it/v1/darwin/domains/count

Returns the total number of domains matching the specified filters.

HTTPcURL

GET /v1/darwin/domains/count?requestId=125 HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "count" : 2
}

curl "https://api.nic.it/v1/darwin/domains/count?requestId=125" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "count" : 2
}

Get a domain

1.0 | darwin | admin / domain / darwin |

GET https://api.nic.it/v1/darwin/domains/{id}

Returns the details of a Darwin domain, including its status (locked, incompatible, rejected, processed).

HTTPcURL

GET /v1/darwin/domains/301 HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id" : 301,
  "dbnaId" : 778899,
  "domain" : "example.it",
  "registrarContactId" : "C-1001",
  "requestId" : 125,
  "contactId" : 101,
  "status" : "locked"
}

curl "https://api.nic.it/v1/darwin/domains/301" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "id" : 301,
  "dbnaId" : 778899,
  "domain" : "example.it",
  "registrarContactId" : "C-1001",
  "requestId" : 125,
  "contactId" : 101,
  "status" : "locked"
}

Get DBNA domain data

1.0 | darwin | admin / domain / darwin |

GET https://api.nic.it/v1/darwin/domains/{id}/dbna

Returns the domain data as stored in DBNA.

HTTPcURL

GET /v1/darwin/domains/301/dbna HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id" : 778899,
  "domain" : "example.it",
  "status" : "ok / clientUpdateProhibited",
  "signed" : false,
  "registrantId" : 998877,
  "created" : "2023-04-16T11:24:20+02:00",
  "lastupdate" : "2024-04-16T11:24:20+02:00",
  "expire" : "2025-04-16T23:59:59+02:00",
  "registered" : true
}

curl "https://api.nic.it/v1/darwin/domains/301/dbna" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "id" : 778899,
  "domain" : "example.it",
  "status" : "ok / clientUpdateProhibited",
  "signed" : false,
  "registrantId" : 998877,
  "created" : "2023-04-16T11:24:20+02:00",
  "lastupdate" : "2024-04-16T11:24:20+02:00",
  "expire" : "2025-04-16T23:59:59+02:00",
  "registered" : true
}

Darwin documents

Search documents

1.0 | darwin | admin / domain / darwin |

GET https://api.nic.it/v1/darwin/documents

Allows searching for documents uploaded for Darwin requests using the following filters:

• documentType
• requestId
• page
• size

HTTPcURL

GET /v1/darwin/documents?requestId=125&documentType=IC HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "elements" : [ {
    "id" : "a1b2c3",
    "requestId" : 125,
    "fileName" : "identity-card.pdf",
    "fileSize" : 248392,
    "documentType" : "IC",
    "fileType" : "pdf",
    "note" : "Registrant document",
    "created" : "2024-04-10T09:45:00+02:00"
  } ],
  "page" : {
    "page" : 0,
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1
  }
}

curl "https://api.nic.it/v1/darwin/documents?requestId=125&documentType=IC" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "elements" : [ {
    "id" : "a1b2c3",
    "requestId" : 125,
    "fileName" : "identity-card.pdf",
    "fileSize" : 248392,
    "documentType" : "IC",
    "fileType" : "pdf",
    "note" : "Registrant document",
    "created" : "2024-04-10T09:45:00+02:00"
  } ],
  "page" : {
    "page" : 0,
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1
  }
}

Search results are paged.

Count documents

1.0 | darwin | admin / domain / darwin |

GET https://api.nic.it/v1/darwin/documents/count

Returns the total number of found documents.

HTTPcURL

GET /v1/darwin/documents/count?requestId=125 HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "count" : 1
}

curl "https://api.nic.it/v1/darwin/documents/count?requestId=125" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "count" : 1
}

Get a document

1.0 | darwin | admin / domain / darwin |

GET https://api.nic.it/v1/darwin/documents/{documentId}

Returns the document metadata, including fileName, fileSize, documentType, fileType, note, and created.

HTTPcURL

GET /v1/darwin/documents/a1b2c3 HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id" : "a1b2c3",
  "requestId" : 125,
  "fileName" : "identity-card.pdf",
  "fileSize" : 248392,
  "documentType" : "IC",
  "fileType" : "pdf",
  "note" : "Registrant document",
  "created" : "2024-04-10T09:45:00+02:00"
}

curl "https://api.nic.it/v1/darwin/documents/a1b2c3" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "id" : "a1b2c3",
  "requestId" : 125,
  "fileName" : "identity-card.pdf",
  "fileSize" : 248392,
  "documentType" : "IC",
  "fileType" : "pdf",
  "note" : "Registrant document",
  "created" : "2024-04-10T09:45:00+02:00"
}

Create a document

1.0 | darwin | admin / domain / darwin |

PUT https://api.nic.it/v1/darwin/documents

Creates a new document for a Darwin request. The uploaded file must have application/pdf or image/jpeg as content type. If the file is too large, the service returns 413 Request Entity Too Large. For details about the upload payload and required fields, refer to the OpenAPI documentation for the specific operation.

HTTPcURL

PUT /v1/darwin/documents HTTP/1.1
Content-Type: multipart/form-data; boundary=------------------------abcdef1234567890
Host: api.nic.it
Authorization: Bearer token...

--------------------------abcdef1234567890
Content-Disposition: form-data; name="document"
Content-Type: application/json

{
  "requestId" : 125,
  "documentType" : "IC",
  "note" : "Registrant document"
}
--------------------------abcdef1234567890
Content-Disposition: form-data; name="file"; filename="identity-card.pdf"
Content-Type: application/pdf

...binary content...
--------------------------abcdef1234567890--

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id" : "a1b2c3",
  "requestId" : 125,
  "fileName" : "identity-card.pdf",
  "fileSize" : 248392,
  "documentType" : "IC",
  "fileType" : "pdf",
  "note" : "Registrant document",
  "created" : "2024-04-10T09:45:00+02:00"
}

curl -X PUT "https://api.nic.it/v1/darwin/documents" \
-H "Authorization: Bearer token..." \
-F 'document={"requestId":125,"documentType":"IC","note":"Registrant document"};type=application/json' \
-F "file=@identity-card.pdf;type=application/pdf"

{
  "id" : "a1b2c3",
  "requestId" : 125,
  "fileName" : "identity-card.pdf",
  "fileSize" : 248392,
  "documentType" : "IC",
  "fileType" : "pdf",
  "note" : "Registrant document",
  "created" : "2024-04-10T09:45:00+02:00"
}

Delete a document

1.0 | darwin | admin / domain / darwin |

DELETE https://api.nic.it/v1/darwin/documents/{documentId}

Deletes a previously uploaded document.

HTTPcURL

DELETE /v1/darwin/documents/a1b2c3 HTTP/1.1
Host: api.nic.it
Authorization: Bearer token...

HTTP/1.1 204 No Content

curl -X DELETE "https://api.nic.it/v1/darwin/documents/a1b2c3" \
-H "Authorization: Bearer token..."

Download a document

1.0 | darwin | admin / domain / darwin |

GET https://api.nic.it/v1/darwin/documents/{documentId}/download

Returns the binary content of the document.

HTTPcURL

GET /v1/darwin/documents/a1b2c3/download HTTP/1.1
Host: api.nic.it
Authorization: Bearer token...

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="identity-card.pdf"

...binary content...

curl "https://api.nic.it/v1/darwin/documents/a1b2c3/download" \
-H "Authorization: Bearer token..." \
-o identity-card.pdf

Darwin events

Search request events

1.0 | darwin | admin / domain / darwin |

GET https://api.nic.it/v1/darwin/events?requestId={requestId}

Returns the paged list of events associated with a request. The type parameter allows filtering by event type.

The main event types defined by the API are:

• submitted
• rejected
• toPending
• registrarUpdated
• registrarUpdateRejected
• registrarUpdateApproved
• toProcessing
• expired
• completed
• expiredCompleted
• updatedRequiredDocuments
• cancelled
• cancelledCompleted
• registryUpdated
• registrarUserAssignation
• registrarUserRelease
• registryUserAssignation
• registryUserRelease

HTTPcURL

GET /v1/darwin/events?requestId=125&type=registrarUpdated HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "elements" : [ {
    "requestId" : 125,
    "type" : "registrarUpdated",
    "user" : "darwin.user",
    "message" : "Data update entered by the Registrar",
    "created" : "2024-04-10T09:30:00+02:00"
  } ],
  "page" : {
    "page" : 0,
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1
  }
}

curl "https://api.nic.it/v1/darwin/events?requestId=125&type=registrarUpdated" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "elements" : [ {
    "requestId" : 125,
    "type" : "registrarUpdated",
    "user" : "darwin.user",
    "message" : "Data update entered by the Registrar",
    "created" : "2024-04-10T09:30:00+02:00"
  } ],
  "page" : {
    "page" : 0,
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1
  }
}

Search results are paged.

Count events

1.0 | darwin | admin / domain / darwin |

GET https://api.nic.it/v1/darwin/events/count?requestId={requestId}

Returns the total number of request events, optionally filtered by type.

HTTPcURL

GET /v1/darwin/events/count?requestId=125&type=registrarUpdated HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "count" : 1
}

curl "https://api.nic.it/v1/darwin/events/count?requestId=125&type=registrarUpdated" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "count" : 1
}

Most common application errors

In addition to standard HTTP status codes (401 Unauthorized, 403 Forbidden, 404 Not Found), Darwin endpoints may also return:

• 400 Bad Request for missing parameters, invalid payloads, or inconsistent data;
• 409 Conflict for operations not compatible with the current request or assignment state;
• 413 Request Entity Too Large when uploading files that are too large.