Transfer a domain

This guide walks you through transferring a domain to OpusDNS from another registrar, including preparation, monitoring, and handling edge cases. It also covers outbound transfers — approving or rejecting a transfer of a domain away from OpusDNS.

Flow overview

1. Prepare the domain at the current registrar (unlock, get auth code).
2. Create or select contacts.
3. Start the transfer with POST /v1/domains/transfer.
4. Monitor the transfer status.
5. Handle completion or cancel if needed.

Before you begin

Transferring a domain involves coordination between the losing registrar (where the domain currently lives) and OpusDNS (the gaining registrar). A few things must be true before you can start:

• The domain must be unlocked at the current registrar (no clientTransferProhibited status).
• You need the auth code (also called EPP code or transfer key) from the current registrar.
• The domain must have been registered for at least 60 days (ICANN policy for most gTLDs).
• The domain must not have been transferred within the last 60 days.
• The domain must not be in a redemption or pending delete state.

1. Collect the auth code

Contact your current registrar to obtain the domain's authorization code. This code proves you have the right to transfer the domain.

• Most registrars provide this through their control panel or support team.
• Auth codes typically expire after a set period (often 5–14 days).
• Some TLDs use alternative transfer mechanisms — see .uk operations for .uk releases and .eu operations / .be operations for auth code requests.

2. Prepare contacts

Most transfers require contacts alongside renewal_mode. You can reuse existing contacts or create new ones with POST /v1/contacts.

curl "$OPUSDNS_API_BASE/v1/contacts" \
  --request POST \
  --header "X-Api-Key: $OPUSDNS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com",
    "phone": "+49.1234567890",
    "street": "Musterstraße 1",
    "city": "Berlin",
    "postal_code": "10115",
    "country": "DE",
    "org": "Example GmbH"
  }'

3. Start the transfer

Use POST /v1/domains/transfer to initiate the inbound transfer:

curl "$OPUSDNS_API_BASE/v1/domains/transfer" \
  --request POST \
  --header "X-Api-Key: $OPUSDNS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "example.com",
    "auth_code": "xK9#mP2$vL5nQ8wR",
    "contacts": {
      "registrant": "contact_01h45ytscbebyvny4gc8cr8ma2",
      "admin": "contact_01h45ytscbebyvny4gc8cr8ma2",
      "tech": "contact_01h45ytscbebyvny4gc8cr8ma2",
      "billing": "contact_01h45ytscbebyvny4gc8cr8ma2"
    },
    "renewal_mode": "renew",
    "period": {
      "unit": "y",
      "value": 1
    },
    "nameservers": [
      { "hostname": "ns1.example.net" },
      { "hostname": "ns2.example.net" }
    ],
    "create_zone": true
  }'

Request fields

Registration period behavior

The period field in transfer requests works differently from registrations:

• Provided: The specified period is added to the domain's existing expiry date upon transfer completion. Most gTLDs add 1 year by default.
• Omitted: The registry's default transfer policy applies. For most gTLDs, this adds 1 year to the current expiry.

4. Monitor the transfer

The initial response is a DomainResponse with a pendingTransfer status. Transfers do not complete instantly — they require registry processing and potentially approval from the losing registrar.

Check the transfer status

Poll the domain to see the current state:

curl "$OPUSDNS_API_BASE/v1/domains/example.com" \
  --header "X-Api-Key: $OPUSDNS_API_KEY"

Transfer timeline

Monitor via events

You can also track transfer progress through the events system:

curl --get "$OPUSDNS_API_BASE/v1/events" \
  --header "X-Api-Key: $OPUSDNS_API_KEY" \
  --data-urlencode "object_type=DOMAIN" \
  --data-urlencode "type=TRANSFER"

Events will notify you when the transfer succeeds or fails. See the Events overview for details.

5. Cancel if needed

If a transfer must be stopped while it is still pending, use DELETE /v1/domains/{domain_reference}/transfer:

curl "$OPUSDNS_API_BASE/v1/domains/example.com/transfer" \
  --request DELETE \
  --header "X-Api-Key: $OPUSDNS_API_KEY"

This cancels the in-progress transfer and removes the domain object from your account. Cancellation is only possible while the transfer is in pendingTransfer status — once the registry completes the transfer, it cannot be reversed through the API.

What happens after a successful transfer

Once the transfer completes:

• The domain no longer has status pendingTransfer — it transitions to its normal state.
• The expiry date is extended by the transfer period (typically 1 year).
• Contacts are set to those provided in the transfer request.
• Nameservers are updated if provided, otherwise the existing nameservers are imported from the previous registrar.
• A DNS zone is created if create_zone was set to true.
• Registry DNSSEC data is reconciled automatically: if the domain ends up on OpusDNS nameservers, stale DS records imported from the previous provider are removed or replaced so DNS resolution is not disrupted. Domains on external nameservers are left untouched. See Automatic DNSSEC reconciliation.
• A transfer event is created (check /v1/events).

Outbound transfers

When another registrar initiates a transfer of a domain out of your account, the domain enters pendingTransfer status. As the losing side you can resolve the pending transfer explicitly with POST /v1/domains/{domain_reference}/transfer/outbound:

curl "$OPUSDNS_API_BASE/v1/domains/example.com/transfer/outbound" \
  --request POST \
  --header "X-Api-Key: $OPUSDNS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "action": "approve" }'

A few things to know:

• Approving acknowledges the transfer at the registry — it does not complete it. The domain remains in your account until the registry confirms the transfer has completed; only then is it removed and its subscription ended.
• Rejecting denies the request and the domain stays in your account unchanged.
• If you do nothing, most gTLD registries auto-approve the transfer after the pending period (typically 5 days).
• The domain must currently have a pending outbound transfer; otherwise the request fails with 400.
• Explicit resolution is only available for TLDs whose registry allows the losing registrar to act on transfers. For other TLDs the request fails with 422.

Troubleshooting

Common transfer failures

TLD-specific transfer mechanisms

Not all TLDs follow the standard auth-code-based transfer process:

• .uk domains require a registrar tag change (release). See .uk operations.
• .eu / .be domains have specific auth code request endpoints. See .eu operations and .be operations.

Next steps

• Manage a domain — update settings after transfer
• Managing DNSSEC — configure DNSSEC on your transferred domain
• Events overview — track transfer events

Related API Reference

• POST /v1/domains/transfer
• GET /v1/domains/{domain_reference}
• DELETE /v1/domains/{domain_reference}/transfer
• POST /v1/domains/{domain_reference}/transfer/outbound
• POST /v1/contacts