# Quickstart

import { DocsApiBaseUrl } from "../../src/components/docs/DocsApiBaseUrl";
import { DocsApiGroupList } from "../../src/components/docs/DocsApiGroupList";
import { DocsCurlExample } from "../../src/components/docs/DocsCurlExample";
import { DocsPlaygroundLink } from "../../src/components/docs/DocsPlaygroundLink";

From credentials to a registered domain in one guided path.

## 1. Obtain credentials

Contact your ResellerClub account manager or use your reseller control panel to obtain your API key credentials (user ID and API key).

## 2. Choose API environment and authorize

Click **Authorize** in the top bar.

- **Sandbox** or **Live**, choose the environment from the **API environment** dropdown. **Sandbox** is selected by default.
- Enter your user ID and API key once. All examples and playground requests use the selected base URL.

## 3. Domain registration journey

This walkthrough registers one domain end to end: check availability, create a customer and contact, register the domain, poll until the action completes, then update nameservers.

Base URL (follows your Authorize selection): <DocsApiBaseUrl />

Replace `YOUR_*` placeholders in each curl example with values from the previous step before running the next request.

| Step | Time | What you'll do | Playground |
| --- | --- | --- | --- |
| [4](#4-check-availability) | 2 min | Check if a domain name is available | <DocsPlaygroundLink href="/domains/domain-availability#check-domain-availability">Check domain availability</DocsPlaygroundLink> |
| [5](#5-create-a-customer) | 3 min | Create a customer account | <DocsPlaygroundLink href="/customers/apis#create-a-customer-account">Create a customer account</DocsPlaygroundLink> |
| [6](#6-create-a-contact) | 2 min | Create one contact (reused for all roles) | <DocsPlaygroundLink href="/contacts/apis#create-a-contact">Create a contact</DocsPlaygroundLink> |
| [7](#7-register-the-domain) | 5 min | Register the domain | <DocsPlaygroundLink href="/domains/domains#register-a-new-domain">Register a new domain</DocsPlaygroundLink> |
| [8](#8-track-completion) | 2 min | Poll action status by order ID | <DocsPlaygroundLink href="/actions/apis#search-current-actions">Search current actions</DocsPlaygroundLink> |
| [9](#9-update-nameservers) | 2 min | Point the domain at new nameservers | <DocsPlaygroundLink href="/domains/nameservers#update-domain-nameservers">Update domain nameservers</DocsPlaygroundLink> |

> **Sandbox note:** Registration is a paid write operation. Use a funded reseller test account and a cheap, available TLD. If a step returns `403 Forbidden`, check billing eligibility and API key scopes — the `code` field in the response body distinguishes scope errors from account eligibility issues.

## 4. Check availability

Confirm your chosen name is available before creating a customer.

**Try in playground:** <DocsPlaygroundLink href="/domains/domain-availability#check-domain-availability">Check domain availability</DocsPlaygroundLink>

<DocsCurlExample
  path="/domains/available"
  method="GET"
  includeAccept
  query={{ domainName: "mybrand-test-12345" }}
/>

Look for an available result for your domain name. If the name is taken, change `mybrand-test-12345` in the curl above and try again.

## 5. Create a customer

Every domain order is tied to a customer account.

**Try in playground:** <DocsPlaygroundLink href="/customers/apis#create-a-customer-account">Create a customer account</DocsPlaygroundLink>

<DocsCurlExample
  path="/customers"
  method="POST"
  includeAccept
  body={{
    username: "api-quickstart-user",
    password: "ChangeMe-Secure-1!",
    name: "API Quickstart User",
    company: "Quickstart Demo Co",
    addressLine1: "123 Example Street",
    city: "Scottsdale",
    country: "US",
    zipcode: "85251",
    phoneCountryCode: "1",
    phone: "4805550100",
  }}
/>

> **Save from response:** copy `customerId` — you will paste it into the next curl as `YOUR_CUSTOMER_ID`.

Example response:

```json
{
  "customerId": "12345678",
  "status": "Success"
}
```

## 6. Create a contact

Domain registration requires registrant, admin, technical, and billing contacts. For this quickstart, create **one** contact and reuse its ID for all four roles in the register call.

**Try in playground:** <DocsPlaygroundLink href="/contacts/apis#create-a-contact">Create a contact</DocsPlaygroundLink>

<DocsCurlExample
  path="/contacts"
  method="POST"
  includeAccept
  body={{
    customerId: "YOUR_CUSTOMER_ID",
    type: "Contact",
    name: "API Quickstart User",
    email: "quickstart@example.com",
    addressLine1: "123 Example Street",
    city: "Scottsdale",
    country: "US",
    zipcode: "85251",
    phoneCountryCode: "1",
    phone: "4805550100",
  }}
/>

Replace `YOUR_CUSTOMER_ID` with the `customerId` from step 5.

> **Save from response:** copy `contactId` (or `value`) — you will paste it into the register curl as `YOUR_CONTACT_ID`.

The Contacts API does not expose separate reg/admin/tech/billing endpoints — pass the same contact ID as `regContactId`, `adminContactId`, `techContactId`, and `billingContactId` when registering.

## 7. Register the domain

Submit the registration with customer and contact IDs, initial nameservers, and billing options.

**Try in playground:** <DocsPlaygroundLink href="/domains/domains#register-a-new-domain">Register a new domain</DocsPlaygroundLink>

<DocsCurlExample
  path="/domains"
  method="POST"
  includeAccept
  body={{
    domainName: "YOUR_DOMAIN.com",
    years: 1,
    customerId: "YOUR_CUSTOMER_ID",
    regContactId: "YOUR_CONTACT_ID",
    adminContactId: "YOUR_CONTACT_ID",
    techContactId: "YOUR_CONTACT_ID",
    billingContactId: "YOUR_CONTACT_ID",
    ns: ["ns1.example-dns.com", "ns2.example-dns.com"],
    invoiceOption: "PayInvoice",
    autoRenew: false,
  }}
/>

Replace `YOUR_DOMAIN`, `YOUR_CUSTOMER_ID`, and `YOUR_CONTACT_ID` with your values. Use nameservers valid for your account (your reseller default NS or a DNS host you control).

`invoiceOption` controls invoicing behavior. Allowed values:

| Value | Behavior |
| --- | --- |
| `NoInvoice` | No invoice; order executes |
| `PayInvoice` | Raise invoice; pay from debit if sufficient, else pending |
| `KeepInvoice` | Invoice for later; order executes |
| `OnlyAdd` | Invoice for later; registration pending |

> **Save from response:** copy `orderId` — you will paste it into the poll and nameserver curls as `YOUR_ORDER_ID`.

Example response:

```json
{
  "orderId": "987654321",
  "status": "Success",
  "message": "Domain registration initiated"
}
```

## 8. Track completion

Registration is asynchronous. Poll <DocsPlaygroundLink href="/actions/apis#search-current-actions">Search current actions</DocsPlaygroundLink> filtered by `orderId` until the action reaches a terminal status.

**Try in playground:** <DocsPlaygroundLink href="/actions/apis#search-current-actions">Search current actions</DocsPlaygroundLink>

<DocsCurlExample
  path="/actions/search-current"
  method="GET"
  includeAccept
  query={{ orderId: "YOUR_ORDER_ID", size: 10, page: 1 }}
/>

Replace `YOUR_ORDER_ID` with the `orderId` from step 7. Poll every few seconds until `actionStatus` stabilizes.

### Expected `actionStatus` values

The OpenAPI spec does not enumerate `actionStatus` values — use the `actionStatus` and `actionStatusDesc` fields in each action record. For a domain registration you will typically see:

| Phase | Typical `actionStatus` | What it means |
| --- | --- | --- |
| Queued | `Added` | Action is queued and waiting to run |
| Running | `Being Processed` | Registry or provisioning step is in progress |
| Done | `Completed` | Registration finished successfully |
| Error | `Failed` | Registration did not complete — check `actionStatusDesc` and `message` |

When `actionStatus` is `Completed` (or the action no longer appears in current actions), proceed to nameservers. For archived actions, use <DocsPlaygroundLink href="/actions/apis#search-archived-actions">Search archived actions</DocsPlaygroundLink>.

Example poll response (abbreviated):

```json
{
  "actions": [
    {
      "orderId": "987654321",
      "actionType": "AddDomain",
      "actionStatus": "Being Processed",
      "actionStatusDesc": "Action is being processed"
    }
  ]
}
```

## 9. Update nameservers

Registration requires initial nameservers in step 7. This step shows how to **change** them after the order is active — for example, pointing the domain at your DNS host.

**Try in playground:** <DocsPlaygroundLink href="/domains/nameservers#update-domain-nameservers">Update domain nameservers</DocsPlaygroundLink>

<DocsCurlExample
  path="/domains/YOUR_ORDER_ID/nameservers"
  method="PUT"
  includeAccept
  body={{
    ns: ["ns1.your-dns-host.com", "ns2.your-dns-host.com"],
  }}
/>

Replace `YOUR_ORDER_ID` in the URL with the `orderId` from step 7. If auto-open does not show the playground, click **Test** in the sidecar panel on the operation page.

A successful update returns the updated nameserver list. Propagation can take up to 48 hours depending on the TLD and registry.

## 10. What's next

You have walked through the full reseller domain flow. Explore other API groups in the sidebar or jump to a reference:

<DocsApiGroupList />

Each group expands to show OpenAPI tags and endpoints with an interactive **Test** panel.