# Domains
Covered in this doc:
* [Search available domains](#search-available-domains)
* [List domains](#list-domains)
* [Register a domain](#register-a-domain)
* [Renew a domain](#renew-a-domain)
## Search available domains
This method allows you search against registered domains using a keyword and see if they are available or already registered.
```
GET /api/v2/domains/search/?keyword=somebusinessname
```
Passing a list of TLDs to the search
```
GET /api/v2/domains/search/?keyword=somebusinessname&tlds=net,com,co.uk,ch
```
### Parameters
| Name | Type | Description |
|---|
| Name | Type | Description |
keyword | string | required This is the search query. It can accept a set of keywords (i.e. "some business name") or the actual domain desired (i.e. "somebusinessname.com") |
tlds | string | optional Customize the Domain TLDs that will be searched. Passed as a comma separated list of tlds.
Example: com,net,org,co.uk |
### Response
```javascript
[
{
"available": false,
"domain": "somebusinessname.com"
},
{
"available": false,
"domain": "somebusinessname.net"
},
{
"available": true,
"domain": "somebusinessname.org"
}
]
```
## List domains
List all domains currently registered
```
GET /api/v2/domains/
```
### Response
```javascript
{
"meta": {
"limit": 20,
"next": "/api/v2/businesses/?limit=20&offset=20",
"offset": 0,
"previous": null,
"total_count": 1039
},
"objects": [
{
"auto_renew": false,
"expires": "2016-06-26",
"id": 1401,
"registered": "2013-06-26",
"registrar": "namecom",
"resource_uri": "/api/v2/domains/1401/",
"sld": "somebusinessname",
"tld": "com",
"user_id": 248114,
"whois_privacy": false,
"whois_privacy_expires": null
},
...
]
}
```
## Register a domain
Register a domain by providing the domain name as well as the registrant contact details (name, address, etc)
```
POST /api/v2/domains/
```
### Parameters
| Name | Type | Description |
| ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `first_name` | `string` | **required** First name of domain owner |
| `last_name` | `string` | **required** Last name of domain owner |
| `address_1` | `string` | **required** Street address of domain owner |
| `city` | `string` | **required** |
| `state` | `string` | **required** Two character state/provence code |
| `zip` | `string` | **required** |
| `country` | `string` | **required** Two character country code (i.e. US, CA) |
| `phone` | `string` | **required** Contact phone number |
| `email` | `string` | **required** Contact email address |
| `period` | `integer` | **required** Number of years to register the domain |
| | | |
| **Optional** | | |
| `address_2` | `string` | Apt/unit number |
| `organization` | `string` | Name of the business/organization. Optional but required for `.org` domains |
| `partner_domain_id` | `string` | Unique partner ID for this domain for tracking purposes (billing, account ID). Only one domain can exist for each for these IDs. |
| `partner_domain_sub_id` | `string` | Partner ID that is not unique for tracking purposes. |
| `language_code` | `string` | Only required for certain TLDs and for IDNA (Punycode) language domains, but safe to send for all registrations.
Pass just the 2 character language code (i.e. es) for the domain.
|
### Response
A status code of `201 created` is returned on a successful creation and contains the created domain object as JSON
## Registrant details
For an individual domain, you can retrieve the registrant details like name, address and contact information on the domain.
```
GET /api/v2/domains/:id/detail/
```
### Response
```javascript
{
"auto_renew":false,
"contacts":[
{
"address_1":"555 Main St",
"address_2":"",
"city":"Seattle",
"country":"US",
"email":"contact@example.com",
"fax":"",
"first_name":"John",
"last_name":"Doe",
"organization":"",
"phone":"+12065555555",
"state":"WA",
"tax_id":"",
"type":[
"registrant",
"administrative",
"billing",
"technical"
],
"zip":"98121"
}
],
"create_date":"2019-01-29T23:27:58",
"domain_name":"domainname.com",
"expire_date":"2020-01-29T23:27:58",
"locked":true,
"nameservers":[
"ns1mtw.name.com",
"ns2bkr.name.com",
"ns3cqz.name.com",
"ns4fmw.name.com"
]
}
```
## Renew a Domain
Renew a domain for a period of years.
```
POST /api/v2/domains/:id/renew/
```
### Parameters
| Name | Type | Description |
| -------- | --------- | ----------------------------------------------------------- |
| `period` | `integer` | **required** Number of additional years to renew the domain |
### Response
A status code of `202 accepted` is returned on a successful renewal of the domain and contains the domain object as JSON
## Reset DNS zone for domain
This method will reset the DNS entries assigned to a domain to defaults for the instance. This is helpful if you have changed values and would like to update an older domain's DNS records.
```
PUT /api/v2/domains/:id/reset_zone/
```