Ga naar inhoud

Domeinregistratie

Registrar-operaties — TLD-registraties registreren, verhuizen en beheren, samen met hun contacten. Dit is iets anders dan Domeinen, dat de hostnames beheert die aan WordPress-sites zijn gekoppeld.

Feature-flagged

Deze endpoints worden afgeschermd door de domain-registration feature flag. Wanneer die uitstaat, retourneert elk endpoint hier 503 {"errors":[...],"code":"feature_disabled"}.

Account-scope vereist (X-Auth-Account) — een ontbrekende header retourneert 400. OAuth-scopes: lezen domains:read, schrijven domains:write. Mutaties vereisen de can_edit-rol. Mutaties kunnen synchroon worden afgerond (200) of een asynchroon registrar-proces openen (202 met pending_process). TLD's zonder geconfigureerde registrar retourneren 503 registrar_unavailable; upstream registrar-fouten retourneren 502.

409 registration_busy beschermt niet elke mutatie

Zolang een registratie een lopend RTR-proces heeft, wordt een mutatie afgewezen met 409 registration_busy — maar die bescherming geldt alleen voor een vaste lijst acties: update, nameservers, lock, privacy, dnssec, holder, contacts, push_transfer en registrant_change. force_sync, transfer_out, resend_contact_verification en de endpoints resend / cancel voor processen zijn niet beschermd en lopen ook door op een registratie waar al een proces loopt.

Een domein registreren/verhuizen is een bestelling

De endpoints hier controleren beschikbaarheid (check / suggesties) en beheren bestaande registraties. Om daadwerkelijk een domein te registreren of te verhuizen, plaats je een betaalde bestelling via POST /api/orders/domain (zie het volledige paramoverzicht in Bestellingen). Om de houder van een registratie te wijzigen als betaalde bestelling, gebruik je POST /api/domain_registrations/:id/registrant_change (de factureerbare tegenhanger van PATCH .../holder).

Domeincontacten

Herbruikbare contacten voor houder/admin/tech/facturatie die domeinregistraties ondersteunen. Een contact wordt bij het aanmaken aan één TLD vastgepind omdat elke registry een andere set velden valideert. :id is het numerieke contact-ID.

Vorm van een domeincontact
  • id: Integer
  • handle: String
  • first_name: String
  • last_name: String
  • organization: String
  • street_address: String
  • post_code: String
  • city: String
  • state: String
  • country: String | ISO-2
  • email: String
  • phone: String | E.164, +CC.NUMBER
  • extra_properties: Object | TLD-specifieke registry-velden
  • validations: Array
  • split_from_id: Integer | null
  • created_at: DateTime
  • updated_at: DateTime

Domeincontacten weergeven

GET /api/domain_contacts

Params (optioneel)
  • q: String | substring-match tegen handle, organisatie, volledige naam of registratienaam

Retourneert { "domain_contacts": [ ... ] }.

Een domeincontact bekijken

GET /api/domain_contacts/:id

Een domeincontact aanmaken

POST /api/domain_contacts

Maakt het contact aan bij de registrar ÉN lokaal. Retourneert 201. Je moet tld_id of tld_name meegeven zodat de juiste registry-regels van toepassing zijn. Een onbekende TLD retourneert 404 tld_not_found.

Params
  • tld_id: Integer | één van tld_id / tld_name vereist
  • tld_name: String | bijv. ".uk", ".com"
  • domain_contact: Object (vereist)
    • first_name, last_name, organization, street_address, post_code, city, state: String
    • country: String | ISO-2
    • email: String
    • phone: String | E.164 (+CC.NUMBER)
    • extra_properties: Object | TLD-specifieke registry-velden

Een domeincontact bijwerken

PATCH /api/domain_contacts/:id

Retourneert 200, of 202 met pending_process wanneer de registry de update asynchroon verwerkt. Als een momenteel gekoppeld domein de wijziging afwijst, wordt het contact transparant gesplitst (het origineel houdt de mislukkende domeinen, voor de rest wordt een nieuw contact aangemaakt). Geef tld_id/tld_name mee om te bepalen welke TLD-validatieregels van toepassing zijn (standaard de TLD van de eerste gekoppelde registratie).

Params
  • tld_id | tld_name: zie aanmaken
  • domain_contact: Object | dezelfde velden als bij aanmaken (allemaal optioneel)

Een domeincontact verwijderen

DELETE /api/domain_contacts/:id

Alleen toegestaan wanneer geen enkele registratie dit contact gebruikt. Retourneert 204.

Fouten
  • 422 contact_in_use | nog gekoppeld aan een registratie
  • 422 tld_required_for_orphan | verweesd contact + geen tld_id/tld_name opgegeven

Verificatie-e-mail opnieuw verzenden

POST /api/domain_contacts/:id/resend_verification

Voor contacten op TLD's die houdervalidatie vereisen (.au, .it, …). Retourneert { "status": "queued" }.

Domeinregistraties

:id is de registratie-guid.

Vorm van een domeinregistratie
  • id: String | guid
  • name: String
  • status: String
  • expires_at: DateTime
  • auto_renew: Boolean
  • locked: Boolean
  • privacy_protect: Boolean
  • dnssec_enabled: Boolean
  • server_transfer_prohibited: Boolean
  • local_contact_active: Boolean
  • cancellation_deadline_at: DateTime | indien van toepassing
  • within_cancellation_window: Boolean | indien van toepassing
  • nameservers: Array<String>
  • tld: Object | { id, name, registrar }
  • owner_contact / admin_contact / tech_contact / billing_contact: Object | zie vorm van een domeincontact, of null
  • pending_async: Boolean
  • rtr_process_id: String
  • rtr_process_status: String
  • transfer_out_pending: Boolean
  • push_transfer_pending: Boolean
  • subscription_id: String
  • feature_flags: Object | { supports_privacy, supports_transfer_lock, supports_push_transfer, supports_dnssec, requires_contact_validation, authcode_behavior }
  • fees: Object | { privacy_enable, registrant_change } — elk { amount_cents, currency } of null. Alleen geprijsd op weergeven en bekijken; elk ander antwoord dat een registratie teruggeeft, rapporteert beide als null, ongeacht de werkelijke kosten van de TLD
  • created_at: DateTime
  • updated_at: DateTime

Elk endpoint dat een registratie teruggeeft, rendert dezelfde envelope. Zolang een RTR-proces loopt (pending_async is true) draagt die envelope ook een pending_process-object — bij de 202 die het proces opent, en bij elk later antwoord totdat het proces klaar is. De rest van de tijd wordt het volledig weggelaten.

Vorm van pending_process
  • id: String | de identifier van het RTR-proces — dezelfde waarde als rtr_process_id
  • action: String | null | het registrar-commando dat het proces heeft geopend, bijv. PushTransfer, UpdateContactCommand; null wanneer het endpoint geen label heeft meegegeven
  • status: String | de processtatus van de registrar, of pending zolang er nog geen is gerapporteerd — dezelfde waarde als rtr_process_status
  • poll_url: String | relatief pad (geen absolute URL) naar het proces van deze registratie, bijv. /api/domain_registrations/{id}/processes/{process-id} — dit is wat een 202-aanroeper pollt; zie Een proces ophalen

Domeinregistraties weergeven

GET /api/domain_registrations

Params (optioneel)
  • q: String | hoofdletterongevoelige substring-match tegen name

Retourneert { "domain_registrations": [ ... ] }.

Een domeinregistratie bekijken

GET /api/domain_registrations/:id

Voegt, indien van toepassing, toe. dns_zone, linked_site en transfer_out worden volledig uit de JSON weggelaten wanneer ze niet van toepassing zijn — ze komen nooit terug als null, dus controleer op de aanwezigheid van de sleutel in plaats van op een null-waarde:

Geretourneerde params
  • domain_registration: Object | zie vorm hierboven
  • dns_zone: Object | { id, name } — alleen wanneer het account een DnsZone heeft voor deze naam
  • linked_site: Object | { id, name } — alleen wanneer een Site deze naam als hostname gebruikt
  • transfer_out: Object | live registry-weergave, alleen terwijl transfer_out_pending true is

Beschikbaarheid controleren

POST /api/domain_registrations/check

Params
  • domain: String (vereist) | volledig gekwalificeerd, bijv. "example.com"
Geretourneerde params
  • domain: String | genormaliseerde lookup
  • available: Boolean | alleen true wanneer de registry zegt dat het beschikbaar is ÉN er een registratieprijs bestaat voor dit account — een naam die de registry wel zou verkopen komt dus alsnog terug als false wanneer wij er geen prijs voor hebben
  • premium: Boolean
  • owned_by_account: Boolean
  • reason: String | null | door de registrar opgegeven reden wanneer niet beschikbaar
  • price: Object | null | { amount_cents, currency } — huidige bestelbare registratieprijs
  • transfer_price: Object | null | { amount_cents, currency } — huidige bestelbare inkomende verhuisprijs

Het veld voor de registratieprijs heet price, niet create_price

De registratieprijs komt terug als price; alleen de verhuisprijs houdt het achtervoegsel _price. Beide sleutels zijn altijd aanwezig, en beide kunnen null zijn wanneer we voor die rol geen bestelbare prijs hebben op het plan van dit account.

Fouten
  • 422 missing_domain / invalid_domain / unknown_tld
  • 502 request_failed | de lookup bij de registrar is mislukt of gaf een fout. Dit endpoint gebruikt geen registrar_unavailable: elk foutpad hier draagt zijn eigen code, dus request_failed is de enige 502-code die het uitstuurt

Domeinsuggesties

POST /api/domain_registrations/suggestions

Params
  • domain: String (vereist) | basisnaam of volledig gekwalificeerd
Geretourneerde params
  • domain: String | genormaliseerde lookup
  • suggestions: Array<Object>
    • domain: String
    • tld: String
    • source: String | ADAC-categorisatie (bijv. "spinner", "premium")
    • available: Boolean
    • price: Object | { amount_cents, currency }
Fouten
  • 422 missing_domain
  • 503 missing_api_key
  • 502 registrar_unavailable

Een registratie bijwerken

PATCH /api/domain_registrations/:id

Op dit moment is auto_renew het enige ondersteunde veld. Het omschakelen houdt de Stripe-facturatie gesynchroniseerd en restitueert binnen het annuleringsvenster van de TLD waar van toepassing.

Params
  • domain_registration: Object
    • auto_renew: Boolean
Geretourneerde params
  • domain_registration: Object | ververst
  • scenario: String | enabled, clean_cancel, refund_cancel, of late_cancel
Fouten
  • 422 invalid_param | auto_renew is meegestuurd maar is geen boolean
  • 422 cancellation_window_passed | kan auto-renew niet uitschakelen na het venster
  • 400 no_op | geen ondersteunde velden in de update

Nameservers bijwerken

PATCH /api/domain_registrations/:id/nameservers

Params
  • nameservers: Array<String> (vereist)

Retourneert 200 of 202 (met pending_process).

Fouten
  • 422 nameservers_required | de lijst is leeg / allemaal blanco

Verhuisslot in-/uitschakelen

PATCH /api/domain_registrations/:id/lock

Schakelt CLIENT_TRANSFER_PROHIBITED bij de registry in of uit.

Params
  • locked: Boolean (vereist)
Fouten
  • 422 invalid_param | locked ontbreekt of is geen boolean
  • 422 lock_unsupported | TLD ondersteunt geen verhuisslot
  • 422 server_transfer_prohibited | registry heeft verhuizingen verboden

WHOIS-privacy in-/uitschakelen

PATCH /api/domain_registrations/:id/privacy

Params
  • privacy_protect: Boolean (vereist)

Privacy uitschakelen is altijd gratis. Inschakelen op een betaalde TLD retourneert 402:

Reactie met kosten (402 Payment Required)
  • errors: Array
  • code: String | payment_required
  • price: Object | { amount_cents, currency, role: "privacy" }
  • portal_url: String
  • remediation: String
Fouten
  • 422 invalid_param | privacy_protect ontbreekt of is geen boolean
  • 422 privacy_unsupported | TLD ondersteunt geen WHOIS-privacy

DNSSEC beheren

PATCH /api/domain_registrations/:id/dnssec

Params
  • mode: String (vereist) | enable, disable, of add_keys
  • key_data: Array<Object> | vereist voor enable / add_keys
    • flags: Integer
    • algorithm: Integer
    • publicKey: String | base64
Fouten
  • 422 invalid_mode | mode ontbreekt of onbekend
  • 422 dnssec_no_keys | enable/add_keys aangeroepen zonder key_data

Houder (registrant) wijzigen

PATCH /api/domain_registrations/:id/holder

Bewerk het bestaande houdercontact ter plekke, of vervang het.

Params
  • holder_contact: Object (vereist)
    • action_mode: String | edit_current of change
    • first_name, last_name, organization, street_address, post_code, city, state: String
    • country: String | ISO-2
    • email: String
    • phone: String | E.164
    • extra_properties: Object
    • confirm_reverification: "1" | vereist wanneer bewerkingen een gevalideerd veld raken
  • source_domain_contact_id: Integer | met change, hergebruik dit bestaande contact
  • new_contact: Object | met change, maak een nieuw contact aan

De kostenpoort gaat alleen af bij action_mode: change op een betaalde TLD (retourneert 402 payment_required met een price-blok waarvan de role gelijk is aan registrant_change + portal_url); edit_current-bewerkingen zijn altijd gratis. Om de factureerbare wijziging direct uit te voeren (in plaats van naar het portaal te worden gestuurd), gebruik je POST .../registrant_change.

Fouten
  • 402 payment_required | action_mode: change op een TLD die houderwijzigingen factureert (prijs role: "registrant_change", kostenblok + portal_url)
  • 409 reverification_required | gevalideerde velden gewijzigd zonder confirm_reverification: "1"
  • 404 source_contact_not_found | source_domain_contact_id niet gevonden of niet gebruikt in dit account

Een houderwijziging (registrant) bestellen

POST /api/domain_registrations/:id/registrant_change

Plaatst een betaalde bestelling om de houder (eigenaar) van de registratie te wijzigen — voor TLD's die houderwijzigingen factureren (bijv. .com / .net via Verisign IRTP). Dit is de factureerbare tegenhanger van PATCH .../holder: dat endpoint maakt gratis bewerkingen en stuurt kostendragende wijzigingen naar het portaal met 402; dit endpoint belast de standaard betaalmethode van het account off-session en past de wijziging asynchroon toe. Retourneert dezelfde 202 Accepted bestel-/winkelwagen-envelope als POST /api/orders — poll de geretourneerde bestelling via /api/orders/:id.

OAuth-geblokkeerd; vereist een gebruiker met bestelrechten

Niet op de domains:write-allowlist — OAuth-toegangstokens kunnen dit niet bereiken. Vereist een gebruiker-scoped credential (bestellingen zijn eigendom van een User): een system Account-bearer key retourneert 401 user_required, en een gebruiker zonder rechten om een bestelling aan te maken retourneert 403 forbidden. Net als bij andere mutaties wijst een lopend RTR-proces af met 409 registration_busy.

Params (geef exact ÉÉN bron voor de nieuwe eigenaar op)
  • source_domain_contact_id: Integer | hergebruik een bestaand contact dat eigendom is van het account
  • new_contact: Object | maak een nieuw eigenaarscontact aan
    • first_name, last_name, country (ISO-2), email, phone (E.164 +CC.NUMBER): vereist
    • organization, street_address, post_code, city, state: String | optioneel
    • extra_properties: Object | optioneel, TLD-specifieke registry-velden

Retourneert 202 met de bestel-/winkelwagen-envelope.

Fouten
  • 401 user_required | system Account-bearer key (geen gebruiker)
  • 403 forbidden | gebruiker mist rechten om een bestelling aan te maken
  • 403 trial_account | proefaccounts kunnen niet bestellen
  • 409 registration_busy | er loopt al een RTR-proces
  • 400 no_default_payment_method | geen opgeslagen standaardbetaalmethode om off-session mee te belasten. Dit wordt gecontroleerd voordat er iets wordt opgebouwd, dus er wordt niets aangemaakt en niets in rekening gebracht
  • 422 source_contact_not_found | source_domain_contact_id niet gevonden (let op: 422 hier vs 404 op /holder)
  • 422 contact_invalid | new_contact mist vereiste velden of is door de registry afgewezen (bevat violations)
  • 422 no_registrant_change_price | geen houderwijzigingsprijs geconfigureerd voor dit account/deze TLD
  • 422 cart_pay_failed | betaling kon niet worden gestart (een voor de bestelling aangemaakt contact wordt afgebroken)

Rolcontacten bijwerken

PATCH /api/domain_registrations/:id/contacts

Stel rolcontacten voor admin / tech / facturatie in (de houder wordt gewijzigd via /holder). Elke rol is onafhankelijk optioneel. Kies voor elke aanwezige rol één bron:

  • {role}_contact: { source: "same_as_owner" }
  • {role}_contact: { source: "existing" } + {role}_source_domain_contact_id: <id>
  • {role}_contact: { source: "new" } + {role}_new_contact: { ...velden... }
Fouten
  • 422 owner_contact_missing | same_as_owner gebruikt zonder ingesteld houdercontact

De EPP-/authcode ophalen

GET /api/domain_registrations/:id/epp_code

Vereist de domains:write-scope, ook al is het een GET. Retourneert { "authcode": "..." }.

Fouten
  • 422 server_transfer_prohibited | registry heeft verhuizingen verboden
  • 422 authcode_unavailable | TLD verbergt de authcode (authcode_behavior: hidden)
  • 502 authcode_unavailable | registrar gaf de authcode niet terug

Geforceerd opnieuw synchroniseren

POST /api/domain_registrations/:id/force_sync

Leest het domein opnieuw uit bij de registrar en synchroniseert de lokale staat.

Geretourneerde params
  • domain_registration: Object | ververst
  • changed: Array<String> | namen van velden die zijn gewijzigd

Een lopende uitgaande verhuizing afhandelen

POST /api/domain_registrations/:id/transfer_out

Params
  • decision: String (vereist) | approve of reject
Fouten
  • 422 no_pending_transfer_out
  • 422 invalid_decision

Push-verhuizing naar een andere provider

POST /api/domain_registrations/:id/push_transfer

Registrar-naar-registrar push-verhuizing (geen authcode). Retourneert 200 of 202.

Params
  • recipient: String (vereist) | doel-registrar-handle (bijv. "REG-IDS")
Fouten
  • 422 | de registrar heeft de push-verhuizing afgewezen — de TLD ondersteunt er geen, er loopt er al een, of het domein is niet verhuisbaar

Dit endpoint retourneert geen foutcode

Een afgewezen push-verhuizing antwoordt met 422 en een errors-array, zonder enige code-sleutel, dus er is geen machineleesbare identifier om op te vertakken. Behandel elke 422 hier als één uitkomst ("push-verhuizing afgewezen") en toon de tekst uit errors; vertak niet op push_transfer_unsupported, push_transfer_in_progress of domain_not_transferable — die strings worden nooit verstuurd.

Verificatie van houdercontact opnieuw verzenden

POST /api/domain_registrations/:id/resend_contact_verification

Voor TLD's die verificatie van het houdercontact vereisen. Retourneert { "status": "queued" }.

Fouten
  • 422 verification_not_applicable | TLD vereist geen validatie, of geen houdercontact

Hosts (glue records)

Glue records voor een registratie. Genest onder /api/domain_registrations/:domain_registration_id/hosts. De route-param is :host_name.

Hosts weergeven

GET .../hosts

Geretourneerde params
  • hosts: Array<Object>
    • host_name: String | bijv. "ns1.example.com"
    • addresses: Array<Object>
      • address: String | IP-literal
      • version: Integer | 4 of 6

Een host aanmaken

POST .../hosts

De hostname moet een subdomein van de registratie zijn. Elk adres wordt automatisch geclassificeerd als IPv4/IPv6. Retourneert 201 { "host": { ... } }.

Params
  • host_name: String (vereist) | volledig gekwalificeerd subdomein
  • addresses: Array<Object> (vereist, ten minste één)
    • address: String | IP-literal (geen CIDR)

De adressen van een host bijwerken

PATCH .../hosts/:host_name

Vervangt de adressenset. Retourneert 200.

Params
  • addresses: Array<Object> (vereist) | zelfde vorm als bij aanmaken

Een host verwijderen

DELETE .../hosts/:host_name

Retourneert 204.

Processen

RTR-processen die aan een registratie zijn gekoppeld — elke asynchrone registrar-operatie opent er een. Poll deze na een 202. Genest onder /api/domain_registrations/:domain_registration_id/processes.

Processen weergeven

GET .../processes

Retourneert { "processes": [ ... ] }, nieuwste eerst (ruwe RTR-procesrecords).

Een proces ophalen

GET .../processes/:id

Geretourneerde params
  • process: Object | ruwe RTR-procesbody
  • log: Array<Object>

Een proces waarvan de identifier niet bij de registratie hoort, retourneert 404.

Fouten
  • 503 registrar_unavailable | er is geen registrar geconfigureerd voor deze TLD
  • 502 process_unavailable | de registrar kon het proces niet teruggeven

Een onderbroken proces hervatten

POST .../processes/:id/resend

Retourneert { "status": "queued" }.

Een proces annuleren

DELETE .../processes/:id/cancel

Retourneert { "status": "cancelled" }.