Skip to content

Commit aeffac8

Browse files
juankuquintanajuankuquintana
authored
Document registrant-changes endpoints (#895)
1 parent 04d4648 commit aeffac8

File tree

2 files changed

+224
-0
lines changed

2 files changed

+224
-0
lines changed

‎content/v2/registrar/registrant-changes.markdown‎

Lines changed: 223 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,223 @@
1+
---
2+
title: Registrant changes API | DNSimple API v2
3+
excerpt: This page documents the DNSimple registrant changes API v2.
4+
---
5+
6+
# Registrant changes API
7+
8+
* TOC
9+
{:toc}
10+
11+
Change the registrant contact for a registered domain.
12+
13+
<info>
14+
The process may require additional steps depending on the TLD and registry requirements, such as extended attributes.
15+
</info>
16+
17+
18+
## List registrant changes {#listRegistrantChanges}
19+
20+
GET /:account/registrar/registrant_changes
21+
22+
List all registrant changes in the account.
23+
24+
### Parameters
25+
26+
Name | Type | Description
27+
-----|------|------------
28+
`:account` | `integer` | The account id
29+
30+
### Filters
31+
32+
Name | Description
33+
-----|------------
34+
`state` | Filter by state. Valid values: `new`, `pending`, `completed`, `cancelling`, `cancelled`. Defaults to open states (`new`, `pending`) if not specified.
35+
`domain_id` | Only include domains containing given domain ID
36+
`contact_id` | Only include domains containing given contact ID
37+
38+
### Sorting
39+
40+
For general information about sorting, please refer to the [main guide](/v2/#sorting).
41+
42+
Name | Description
43+
-----|------------
44+
`id` | Sort registrant changes by ID
45+
46+
The default sorting policy is by ascending `id`.
47+
48+
### Example
49+
50+
List registrant changes for the account `1010`:
51+
52+
curl -H 'Authorization: Bearer <token>' \
53+
-H 'Accept: application/json' \
54+
https://api.dnsimple.com/v2/1010/registrar/registrant_changes
55+
56+
### Response
57+
58+
Responds with HTTP 200 on success
59+
60+
~~~json
61+
<%= pretty_print_fixture("/api/listRegistrantChanges/success.http") %>
62+
~~~
63+
64+
## Start registrant change {#createRegistrantChange}
65+
66+
POST /:account/registrar/registrant_changes
67+
68+
Start a registrant change for a domain.
69+
70+
### Parameters
71+
72+
Name | Type | Description
73+
-----|------|------------
74+
`:account` | `integer` | The account id
75+
`domain_id` | `string`, `integer` | The domain name or id
76+
`contact_id` | `string`, `integer` | The contact id
77+
`extended_attributes` | `object` | Extended attributes required for certain TLDs. See [TLD extended attributes](/v2/tlds/#getTldExtendedAttributes) for details.
78+
79+
### Example
80+
81+
Start a registrant change for the domain `example.com` in the account `1010`:
82+
83+
curl -H 'Authorization: Bearer <token>' \
84+
-H 'Accept: application/json' \
85+
-H 'Content-Type: application/json' \
86+
-X POST \
87+
-d '{"domain_id":"example.com","contact_id":"2"}' \
88+
https://api.dnsimple.com/v2/1010/registrar/registrant_changes
89+
90+
### Response
91+
92+
Responds with HTTP 201 if the registrant change is completed immediately.
93+
94+
Responds with HTTP 202 if the registrant change has started and is pending completion.
95+
96+
~~~json
97+
<%= pretty_print_fixture("/api/createRegistrantChange/success.http") %>
98+
~~~
99+
100+
### Errors
101+
102+
Responds with [HTTP 400](/v2#bad-request/) if the registrant change cannot be started.
103+
104+
Responds with [HTTP 401](/v2#unauthorized/) in case of authentication issues.
105+
106+
## Check registrant change requirements {#checkRegistrantChange}
107+
108+
POST /:account/registrar/registrant_changes/check
109+
110+
Check the requirements for a registrant change before starting it.
111+
112+
### Parameters
113+
114+
Name | Type | Description
115+
-----|------|------------
116+
`:account` | `integer` | The account id
117+
`domain_id` | `string`, `integer` | The domain name or id
118+
`contact_id` | `string`, `integer` | The contact id
119+
120+
### Example
121+
122+
Check registrant change requirements for the domain `example.com` in the account `1010`:
123+
124+
curl -H 'Authorization: Bearer <token>' \
125+
-H 'Accept: application/json' \
126+
-H 'Content-Type: application/json' \
127+
-X POST \
128+
-d '{"domain_id":"example.com","contact_id":"2"}' \
129+
https://api.dnsimple.com/v2/1010/registrar/registrant_changes/check
130+
131+
### Response
132+
133+
Responds with HTTP 200 on success
134+
135+
~~~json
136+
<%= pretty_print_fixture("/api/checkRegistrantChange/success.http") %>
137+
~~~
138+
139+
### Errors
140+
141+
Responds with [HTTP 400](/v2#bad-request/) if the check cannot be performed.
142+
143+
Responds with [HTTP 401](/v2#unauthorized/) in case of authentication issues.
144+
145+
## Retrieve a registrant change {#getRegistrantChange}
146+
147+
GET /:account/registrar/registrant_changes/:registrant_change
148+
149+
Retrieve the details of an existing registrant change.
150+
151+
### Parameters
152+
153+
Name | Type | Description
154+
-----|------|------------
155+
`:account` | `integer` | The account id
156+
`:registrant_change` | `integer` | The registrant change id
157+
158+
### Example
159+
160+
Get registrant change `101` in the account `1010`:
161+
162+
curl -H 'Authorization: Bearer <token>' \
163+
-H 'Accept: application/json' \
164+
https://api.dnsimple.com/v2/1010/registrar/registrant_changes/101
165+
166+
### Response
167+
168+
Responds with HTTP 200 on success
169+
170+
~~~json
171+
<%= pretty_print_fixture("/api/getRegistrantChange/success.http") %>
172+
~~~
173+
174+
### Errors
175+
176+
Responds with [HTTP 404](/v2#not-found/) if the registrant change doesn't exist.
177+
178+
Responds with [HTTP 401](/v2#unauthorized/) in case of authentication issues.
179+
180+
## Cancel a registrant change {#deleteRegistrantChange}
181+
182+
DELETE /:account/registrar/registrant_changes/:registrant_change
183+
184+
Cancel an ongoing registrant change.
185+
186+
### Parameters
187+
188+
Name | Type | Description
189+
-----|------|------------
190+
`:account` | `integer` | The account id
191+
`:registrant_change` | `integer` | The registrant change id
192+
193+
### Example
194+
195+
Cancel registrant change `101` in the account `1010`:
196+
197+
curl -H 'Authorization: Bearer <token>' \
198+
-H 'Accept: application/json' \
199+
-X DELETE \
200+
https://api.dnsimple.com/v2/1010/registrar/registrant_changes/101
201+
202+
### Response
203+
204+
Responds with HTTP 204 if the registrant change is cancelled immediately.
205+
206+
Responds with HTTP 202 if the registrant change is being cancelled (state is `cancelling`).
207+
208+
~~~json
209+
<%= pretty_print_fixture("/api/deleteRegistrantChange/success_async.http") %>
210+
~~~
211+
212+
<note>
213+
The code block above shows the response for HTTP 202. HTTP 204 responses have no body.
214+
</note>
215+
216+
### Errors
217+
218+
Responds with [HTTP 400](/v2#bad-request/) if the registrant change cannot be cancelled.
219+
220+
Responds with [HTTP 401](/v2#unauthorized/) in case of authentication issues.
221+
222+
Responds with [HTTP 404](/v2#not-found/) if the registrant change doesn't exist.
223+

‎layouts/sidebar.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ <h4 class="sidebar-title">API v2</h4>
2626
<li><ul class="nav-list">
2727
<li><a href="/v2/registrar/auto-renewal/">Auto Renewal</a></li>
2828
<li><a href="/v2/registrar/delegation/">Delegation</a></li>
29+
<li><a href="/v2/registrar/registrant-changes/">Registrant Changes</a></li>
2930
<li><a href="/v2/registrar/transfer-lock/">Transfer Lock</a></li>
3031
<li><a href="/v2/registrar/whois-privacy/">Whois Privacy</a></li>
3132
</ul></li>

0 commit comments

Comments
 (0)