NicNames API v2 (2.0)

Download OpenAPI specification:

E-mail: support@nicnames.com Terms of Service

Glossary

OID - Order ID
CTS - Creation date and time
UTS - Modification date and time
ETS - Expiration date and time

Time

Any field of time type represents the number of seconds elapsed since the Unix epoch, which is 1970-01-01T00:00:00Z.

Webhook URL for Asynchronous Results and Events

For operations returning a 202 (Accepted) status code, the final result will be delivered asynchronously via a webhook. Your system will receive a POST request at the specified URL with the following parameters sent as application/x-www-form-urlencoded data:

object: Event data in JSON format.
timestamp: The Unix timestamp (in milliseconds) representing the time when the webhook notification was sent.
signature: A signature generated using the HMAC-SHA256 algorithm. This signature is created by concatenating the object (event data in JSON format) and timestamp as a string. The resulting string is then signed with your webhook_secret key using the HMAC-SHA256 algorithm. The final signature will be returned in hexadecimal format (lowercase letters).

Codes

List of possible result and error codes returned by this API

440000 - UNKNOWN
441000 - SUCCESS
441001 - PENDING
442001 - ERROR_REMOTE
442002 - ERROR_EXCEPTION
442003 - ERROR_FORBIDDEN
442006 - ERROR_UNKNOWN_STATUS
442007 - ERROR_NOT_FOUND
442008 - ERROR_STATUS_PROHIBITED
442009 - ERROR_PARAM_VALUE_POLICY
442010 - ERROR_INVALID_PARAM_VALUE
442011 - ERROR_PARAM_VALUE_REQUIRED
442012 - ERROR_UNAUTHORIZED

Statuses

List of possible status codes returned by this API

new – The order has been created but not yet paid.
active – The order is active and operational.
expired – The order has expired and is no longer active. Renewal is required to restore it.
pendingUpdate – A order update request is in progress.
arrested – The order has been restricted or suspended due to policy violation, legal action, or administrative hold.
redemptionPeriod – The order has expired and is in the redemption grace period. It can still be restored for an additional fee.
closed – The order has been deleted and cannot be restored.
pendingRegistrantEmailVerification – The domain is awaiting email verification by the registrant. A confirmation request has been sent but not yet completed.
lockRegistrantEmailVerification – The domain is locked because the registrant's email address has not been verified.
lockExpiration – The domain is locked due to expiration and requires renewal.
lockTransfer – The domain is locked to prevent transfer to another registrar.
lockRegistrant60 – The domain is locked and prevents changes to the registrant’s information for 60 days.
lockTransfer60 – The domain is locked and prevents transfer to another registrar for 60 days.
tokenized - The domain is represented as a digital token.
unknown – The order is in an undefined or undocumented state. This may indicate an internal error or an unexpected status value.

List domains

Authorizations:

API-Key

Request Body schema: application/json

pgn	integer <int32> Default: 1 Page number 1..N
pgl	integer <int32> [ 1 .. 100 ] Default: 25 Page length 1..K
filter	string

Responses

Request samples

Payload

Content type

application/json

{"pgn": 5,
"pgl": 50,
"filter": "email = 'email@example.com'"
}

Response samples

200
4XX
5XX

Content type

application/json

{"total": 12345,
"list": [{"oid": "o54321",
"type": "common",
"status": ["orderActive"
],
"cts": 1577836800,
"uts": 1577836800,
"ets": 1577836800,
"domain": {"name": "example.com",
"registrant": "c987654321",
"admin": "c987654321",
"tech": "c987654321",
"billing": "c987654321",
"ns": ["ns1.example.com"
],
"w3a": "eip155:1:0xcf9d756965e97dc144E90e447C5184B26861a8C0"
}
}
]
}

Info domain

Authorizations:

API-Key

path Parameters

domainName

required

string [ 1 .. 253 ] characters

Example: example.com

Responses

Response samples

200
4XX
5XX

Content type

application/json

Example

common

{"oid": "o54321",
"type": "common",
"status": ["orderActive"
],
"cts": 1577836800,
"uts": 1577836800,
"ets": 1577836800
}

Create a domain

Authorizations:

API-Key

path Parameters

domainName

required

string [ 1 .. 253 ] characters

Example: example.com

Request Body schema: application/json

required	object (PriceModel)
registrant required	string
admin	string
tech	string
billing	string
ns	Array of strings

Responses

Request samples

Payload

Content type

application/json

{"registrant": "c987654321",
"price": {"amt": 12.34,
"ccy": 840,
"op": "CREATE",
"period": {"unit": "YEARS",
"value": 1
}
}
}

Response samples

201
202
4XX
5XX

Content type

application/json

Example

common

{"oid": "o54321",
"type": "common",
"status": ["orderActive"
],
"cts": 1577836800,
"uts": 1577836800,
"ets": 1577836800
}

Transfer a domain

Authorizations:

API-Key

path Parameters

domainName

required

string [ 1 .. 253 ] characters

Example: example.com

Request Body schema: application/json

required	object (PriceModel)
registrant required	string
authCode required	string

Responses

Request samples

Payload

Content type

application/json

{"authCode": "xGi%8KFk3wQV",
"registrant": "c987654321",
"price": {"amt": 12.34,
"ccy": 840,
"op": "TRANSFER",
"period": {"unit": "YEARS",
"value": 1
}
}
}

Response samples

200
202
4XX
5XX

Content type

application/json

Example

common

{"oid": "o54321",
"type": "common",
"status": ["orderActive"
],
"cts": 1577836800,
"uts": 1577836800,
"ets": 1577836800
}

Renew a domain

Authorizations:

API-Key

path Parameters

domainName

required

string [ 1 .. 253 ] characters

Example: example.com

Request Body schema: application/json

required	object (PriceModel)
currentETS required	integer <int64>

Responses

Request samples

Payload

Content type

application/json

{"currentETS": 1577836800,
"price": {"amt": 12.34,
"ccy": 840,
"op": "RENEW",
"period": {"unit": "YEARS",
"value": 1
}
}
}

Response samples

200
202
4XX
5XX

Content type

application/json

Example

common

{"oid": "o54321",
"type": "common",
"status": ["orderActive"
],
"cts": 1577836800,
"uts": 1577836800,
"ets": 1577836800
}

Update a domain name servers

Authorizations:

API-Key

path Parameters

domainName

required

string [ 1 .. 253 ] characters

Example: example.com

Request Body schema: application/json

ns

required

Array of strings [ 0 .. 13 ] items

Responses

Request samples

Payload

Content type

application/json

{"ns": ["ns1.example.com"
]
}

Response samples

200
202
4XX
5XX

Content type

application/json

Example

common

{"oid": "o54321",
"type": "common",
"status": ["orderActive"
],
"cts": 1577836800,
"uts": 1577836800,
"ets": 1577836800
}

Update a domain whois privacy

Authorizations:

API-Key

path Parameters

domainName

required

string [ 1 .. 253 ] characters

Example: example.com

Request Body schema: application/json

registrant	any Enum: "enable" "disable"
admin	any Enum: "enable" "disable"
tech	any Enum: "enable" "disable"
billing	any Enum: "enable" "disable"

Responses

Request samples

Payload

Content type

application/json

{"registrant": "enable",
"admin": "enable",
"tech": "enable",
"billing": "enable"
}

Response samples

200
202
4XX
5XX

Content type

application/json

Example

common

{"oid": "o54321",
"type": "common",
"status": ["orderActive"
],
"cts": 1577836800,
"uts": 1577836800,
"ets": 1577836800
}

Restore a domain

Authorizations:

API-Key

path Parameters

domainName

required

string [ 1 .. 253 ] characters

Example: example.com

Request Body schema: application/json

required

object (PriceModel)

Responses

Request samples

Payload

Content type

application/json

{"currentETS": 1577836800,
"price": {"amt": 12.34,
"ccy": 840,
"op": "RENEW",
"period": {"unit": "YEARS",
"value": 1
}
}
}

Response samples

200
202
4XX
5XX

Content type

application/json

Example

common

{"oid": "o54321",
"type": "common",
"status": ["orderActive"
],
"cts": 1577836800,
"uts": 1577836800,
"ets": 1577836800
}

List contacts

Authorizations:

API-Key

Request Body schema: application/json

pgn	integer <int32> Default: 1 Page number 1..N
pgl	integer <int32> [ 1 .. 100 ] Default: 25 Page length 1..K
filter	string

Responses

Request samples

Payload

Content type

application/json

{"pgn": 5,
"pgl": 50,
"filter": "email = 'email@example.com'"
}

Response samples

200
4XX
5XX

Content type

application/json

{"total": 12345,
"list": [{"contactId": "c987654321",
"firstName": "John",
"middleName": "string",
"lastName": "Doe",
"org": "Acme Corporation",
"orgPhone": "+15551234567",
"cc": "us",
"pc": "62704",
"sp": "IL",
"city": "Springfield",
"addr": "123 Main Street",
"email": "john.doe@example.com",
"phone": "+15551234567",
"phonePolicy": true,
"fax": "string"
}
]
}

Create a contact

Authorizations:

API-Key

Request Body schema: application/json

firstName required	string
middleName	string
lastName required	string
org	string
orgPhone	string
cc required	string
pc required	string
sp required	string
city required	string
addr required	string
email required	string
phone required	string
phonePolicy required	boolean
fax	string

Responses

Request samples

Payload

Content type

application/json

{"firstName": "John",
"lastName": "Doe",
"org": "Acme Corporation",
"orgPhone": "+15551234567",
"cc": "us",
"pc": "19713",
"sp": "DE",
"city": "Newark",
"addr": "123 Main Street",
"email": "john.doe@example.com",
"phone": "+15551234567",
"phonePolicy": true
}

Response samples

201
4XX
5XX

Content type

application/json

{"contactId": "c987654321",
"firstName": "John",
"lastName": "Doe",
"org": "Acme Corporation",
"orgPhone": "+15551234567",
"cc": "us",
"pc": "62704",
"sp": "IL",
"city": "Springfield",
"addr": "123 Main Street",
"email": "john.doe@example.com",
"phone": "+15551234567",
"phonePolicy": true
}

Info contact

Authorizations:

API-Key

path Parameters

contactId

required

string

Responses

Response samples

200
4XX
5XX

Content type

application/json

{"contactId": "c987654321",
"firstName": "John",
"middleName": "string",
"lastName": "Doe",
"org": "Acme Corporation",
"orgPhone": "+15551234567",
"cc": "us",
"pc": "62704",
"sp": "IL",
"city": "Springfield",
"addr": "123 Main Street",
"email": "john.doe@example.com",
"phone": "+15551234567",
"phonePolicy": true,
"fax": "string"
}

Check domain availability

Authorizations:

API-Key

path Parameters

domainName

required

string [ 1 .. 253 ] characters

Example: example.com

Responses

Response samples

200
4XX
5XX

Content type

application/json

{"domainName": "string",
"availableFor": "CREATE",
"tier": "REGULAR",
"price": [{"amt": 12.34,
"ccy": 840,
"op": "CREATE",
"period": {"unit": "YEARS",
"value": 1
}
},
{"amt": 23.45,
"ccy": 840,
"op": "CREATE",
"period": {"unit": "YEARS",
"value": 2
}
}
]
}

Resend registrant email verification email

Authorizations:

API-Key

path Parameters

domainName

required

string [ 1 .. 253 ] characters

Example: example.com

Responses

Response samples

202
4XX
5XX

Content type

application/json

{"code": 123456,
"email": "email@example.com"
}

Get registrant email verification status

Authorizations:

API-Key

path Parameters

domainName

required

string [ 1 .. 253 ] characters

Example: example.com

Responses

Response samples

200
4XX
5XX

Content type

application/json

{"code": 123456,
"email": "email@example.com"
}