Jobs

Domain commands

This page covers the domain-related commands available in the Jobs API: registering, updating, and transferring domains — both individually and in bulk.

domain_create

Register a single domain:

{
  "type": "domain_create",
  "idempotency_key": "reg-example-com-2026",
  "payload": {
    "name": "example.com",
    "contacts": {
      "registrant": "contact_01h45ytscbebyvny4gc8cr8ma2",
      "admin": "contact_01h45ytscbebyvny4gc8cr8ma2",
      "tech": "contact_01h45ytscbebyvny4gc8cr8ma2"
    },
    "nameservers": ["ns1.opusdns.com", "ns2.opusdns.net"],
    "renewal_mode": "renew",
    "period": { "unit": "y", "value": 1 },
    "create_zone": true
  }
}

Payload fields

Field Required Default Description
name Yes — Domain name to register.
contacts Yes — Contact handles or contact IDs for registrant, admin, tech, and billing.
period Yes — Registration period. unit is "y" (years), value is the number of years.
renewal_mode Yes — How the domain renews: renew, autoexpire, autodelete, or renewonce.
nameservers No null Array of nameserver hostnames.
create_zone No false If true, automatically create an OpusDNS DNS zone for this domain.
auth_code No null Authorization code (6–32 characters). Used for specific TLDs that require it at registration.
expected_price No null Expected price. If set and the actual price differs, the registration is rejected.
attributes No null TLD-specific registry attributes (keyed by attribute name).
claims_notice_acceptance_hash No null TMCH claims notice hash (for domains under trademark protection).

Contacts

The contacts field accepts either contact IDs or inline contact handles:

Using contact IDs (recommended for bulk operations):

"contacts": {
  "registrant": "contact_01h45ytscbebyvny4gc8cr8ma2",
  "admin": "contact_01h45ytscbebyvny4gc8cr8ma2",
  "tech": "contact_01h45ytscbebyvny4gc8cr8ma2"
}

Using inline contact handles (for one-off registrations):

"contacts": {
  "registrant": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "phone": "+49.30123456",
    "street": "Friedrichstraße 123",
    "city": "Berlin",
    "postal_code": "10117",
    "country": "DE"
  }
}

domain_create_bulk

Register multiple domains efficiently using the template + instances pattern:

{
  "type": "domain_create_bulk",
  "payload": {
    "template": {
      "contacts": {
        "registrant": "contact_01h45ytscbebyvny4gc8cr8ma2",
        "admin": "contact_01h45ytscbebyvny4gc8cr8ma2",
        "tech": "contact_01h45ytscbebyvny4gc8cr8ma2"
      },
      "nameservers": ["ns1.opusdns.com", "ns2.opusdns.net"],
      "renewal_mode": "renew",
      "period": { "unit": "y", "value": 1 },
      "create_zone": true
    },
    "instances": [
      { "name": "example.com" },
      { "name": "example.net" },
      { "name": "example.org" },
      { "name": "my-brand.de", "period": { "unit": "y", "value": 2 } }
    ]
  }
}

The template defines shared defaults — contacts, nameservers, renewal mode, and period apply to every instance. Each instance specifies the domain name and can optionally override any template field.

Up to 1,000 instances per bulk command. Instance-level overrides completely replace the template's setting for that field.

domain_update

Update settings on a single domain:

{
  "type": "domain_update",
  "payload": {
    "domain_id": "domain_01h45ytscbebyvny4gc8cr8ma2",
    "renewal_mode": "autoexpire",
    "nameservers": ["ns1.newprovider.com", "ns2.newprovider.com"]
  }
}

Payload fields

Field Required Description
domain_id Yes The domain to update (TypeID).
contacts No Updated contact handles or IDs.
nameservers No New nameserver list.
renewal_mode No New renewal mode.
statuses No Set the full list of client statuses (replaces existing).
status_changes No Add or remove specific statuses (relative change).
auth_code No Set a new authorization code.

Statuses vs. status_changes

statuses and status_changes are mutually exclusive — use one or the other, never both in the same command.

statuses — replaces the entire status set:

{
  "type": "domain_update",
  "payload": {
    "domain_id": "domain_01h45ytscbebyvny4gc8cr8ma2",
    "statuses": ["clientTransferProhibited", "clientDeleteProhibited"]
  }
}

status_changes — adds or removes specific statuses without affecting others: 

{
  "type": "domain_update",
  "payload": {
    "domain_id": "domain_01h45ytscbebyvny4gc8cr8ma2",
    "status_changes": {
      "add": ["clientTransferProhibited"],
      "remove": ["clientHold"]
    }
  }
}

domain_update_bulk

Update settings across many domains at once. This is particularly powerful with status_changes in the template:

Example: Lock transfers across your portfolio 

{
  "type": "domain_update_bulk",
  "payload": {
    "template": {
      "status_changes": {
        "add": ["clientTransferProhibited"]
      }
    },
    "instances": [
      { "name": "example.com" },
      { "name": "example.net" },
      { "name": "example.org" }
    ]
  }
}

Example: Bulk update with per-domain overrides

If one domain needs different treatment, its instance can override the template: 

{
  "type": "domain_update_bulk",
  "payload": {
    "template": {
      "status_changes": {
        "add": ["clientTransferProhibited"]
      }
    },
    "instances": [
      { "name": "example.com" },
      { "name": "example.net" },
      {
        "name": "special-case.com",
        "status_changes": {
          "remove": ["clientHold"]
        }
      }
    ]
  }
}

In this example, special-case.com uses its own status_changes (removing clientHold) instead of the template's (adding clientTransferProhibited). An instance-level override completely replaces the template's setting for that field.

Example: Change nameservers in bulk 

{
  "type": "domain_update_bulk",
  "payload": {
    "template": {
      "nameservers": ["ns1.opusdns.com", "ns2.opusdns.net"]
    },
    "instances": [
      { "name": "example.com" },
      { "name": "example.net" },
      { "name": "example.org" }
    ]
  }
}

Instance identification

Each instance can identify the target domain by either name or domain_id, but not both: 

{ "name": "example.com" }
// or
{ "domain_id": "domain_01h45ytscbebyvny4gc8cr8ma2" }

domain_transfer

Initiate an inbound transfer for a single domain:

{
  "type": "domain_transfer",
  "idempotency_key": "transfer-example-com-2026",
  "payload": {
    "name": "example.com",
    "auth_code": "Xy9!kL2m",
    "contacts": {
      "registrant": "contact_01h45ytscbebyvny4gc8cr8ma2",
      "admin": "contact_01h45ytscbebyvny4gc8cr8ma2",
      "tech": "contact_01h45ytscbebyvny4gc8cr8ma2"
    },
    "renewal_mode": "renew",
    "period": { "unit": "y", "value": 1 },
    "create_zone": true
  }
}

Payload fields

Field Required Description
name Yes Domain name to transfer.
auth_code Yes Authorization code from the current registrar (6–32 characters).
contacts Conditional Contact handles or IDs. Required for most TLDs, but optional for TLDs where every supported contact role has a minimum of 0 (e.g. .ca, .ch).
renewal_mode Yes Renewal mode after transfer.
period No Transfer period.
nameservers No Nameservers to set after transfer completes.
create_zone No If true, create a DNS zone automatically. Defaults to false.
expected_price No Expected transfer price. Rejects if actual price differs.
attributes No TLD-specific registry attributes.

domain_transfer_bulk

Transfer multiple domains using the template + instances pattern:

{
  "type": "domain_transfer_bulk",
  "payload": {
    "template": {
      "contacts": {
        "registrant": "contact_01h45ytscbebyvny4gc8cr8ma2",
        "admin": "contact_01h45ytscbebyvny4gc8cr8ma2",
        "tech": "contact_01h45ytscbebyvny4gc8cr8ma2"
      },
      "renewal_mode": "renew",
      "create_zone": true
    },
    "instances": [
      { "name": "example.com", "auth_code": "Xy9!kL2m" },
      { "name": "example.net", "auth_code": "Ab3$nR7p" },
      { "name": "example.org", "auth_code": "Cd5&hT1q" }
    ]
  }
}

Each instance must include its own auth_code since authorization codes are unique per domain. Shared settings like contacts, renewal mode, and zone creation go in the template. The contacts block can be omitted entirely for TLDs that do not require any contacts on transfer (every supported contact role has a minimum of 0, e.g. .ca, .ch).

Full batch example

Here's a real-world example combining multiple command types in a single batch: 

curl "$OPUSDNS_API_BASE/v1/jobs" \
  --request POST \
  --header "X-Api-Key: $OPUSDNS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "label": "Portfolio setup - May 2026",
    "commands": [
      {
        "type": "domain_create_bulk",
        "idempotency_key": "may-2026-registrations",
        "payload": {
          "template": {
            "contacts": {
              "registrant": "contact_01h45ytscbebyvny4gc8cr8ma2"
            },
            "renewal_mode": "renew",
            "period": { "unit": "y", "value": 1 },
            "create_zone": true
          },
          "instances": [
            { "name": "newbrand.com" },
            { "name": "newbrand.net" },
            { "name": "newbrand.de", "period": { "unit": "y", "value": 2 } }
          ]
        }
      },
      {
        "type": "domain_transfer_bulk",
        "payload": {
          "template": {
            "contacts": {
              "registrant": "contact_01h45ytscbebyvny4gc8cr8ma2"
            },
            "renewal_mode": "renew"
          },
          "instances": [
            { "name": "existing-domain.com", "auth_code": "Xy9!kL2m" },
            { "name": "existing-domain.eu", "auth_code": "Mn4@pQ8w" }
          ]
        }
      },
      {
        "type": "domain_update_bulk",
        "payload": {
          "template": {
            "status_changes": {
              "add": ["clientTransferProhibited"]
            }
          },
          "instances": [
            { "name": "protect-this.com" },
            { "name": "protect-that.net" }
          ]
        }
      }
    ]
  }'

This single batch registers 3 domains, transfers 2 domains, and locks 2 domains — creating 7 jobs total.

Related pages

Previous
Jobs overview
Next
DNS & infrastructure commands