> ## Documentation Index
> Fetch the complete documentation index at: https://docs.netzfabrik.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Handle anlegen

> Legt einen Kontakt an. `type` ist `PERS` (Person), `ORG` (Organisation, `company` ist dann Pflicht) oder `ROLE` (Funktionskontakt). Telefon- und Faxnummer im internationalen Format in `phone` bzw. `fax`; die Felder `phone1`-`phone3` und `fax1`-`fax3` sind veraltet.

Die Antwort enthält in `warnings` Hinweise auf Felder, die einzelne TLDs zusätzlich verlangen. Sie blockieren das Anlegen nicht.



## OpenAPI

````yaml /api-reference/openapi.json post /handles
openapi: 3.1.0
info:
  title: NETZFABRIK API
  description: >-
    REST-API der NETZFABRIK-Plattform für Domains, DNS, Cloud-Server, Webspaces,
    E-Mail-Dienste und Konto. Authentifizierung per JWT (Authorization: Bearer)
    oder API-Token (X-API-TOKEN).
  termsOfService: https://www.netzfabrik.com/tos
  contact:
    name: NETZFABRIK GmbH
    url: https://www.netzfabrik.com
    email: info@netzfabrik.com
  license:
    name: Proprietary
    url: https://www.netzfabrik.com/license
  version: 2026-11-19-9237c1a3
servers:
  - url: https://api.netzfabrik.com
security:
  - JWT: []
  - ApiToken: []
tags:
  - name: Login
  - name: Zwei-Faktor-Authentifizierung
  - name: Passkeys
  - name: Benutzer
  - name: Konten
  - name: Kunden
  - name: Verträge
  - name: Rechnungen
  - name: Support-Tickets
  - name: Domains
  - name: Domain-Bestellungen
  - name: Premium-Domains
  - name: Inhaberwechsel
  - name: Handles (Kontakte)
  - name: Handle-Verifizierung
  - name: TLD-Daten
  - name: Domain-Preise
  - name: Preislisten-Vorlagen
  - name: Preislisten-Versionen
  - name: Preis-Überschreibungen
  - name: Preisänderungen
  - name: Domain-Aktionen
  - name: Öffentliche Preislisten
  - name: Domain-Reseller
  - name: DNS-Zonen
  - name: DNS-Records
  - name: Weiterleitungen
  - name: Cloud-Server
  - name: Cloud-Server-Vorlagen
  - name: Regionen
  - name: SSH-Keys
  - name: ISO-Images
  - name: Anwendungen
  - name: Webspaces
  - name: Webspace-Tarife
  - name: Object Storage
  - name: E-Mail-Protection
  - name: E-Mail-Security
  - name: E-Mail-Archiv
  - name: Colocation
  - name: Racks
  - name: Stromzuführungen
  - name: Interconnections
  - name: VLANs
  - name: Traffic
paths:
  /handles:
    post:
      tags:
        - Handles (Kontakte)
      summary: Handle anlegen
      description: >-
        Legt einen Kontakt an. `type` ist `PERS` (Person), `ORG` (Organisation,
        `company` ist dann Pflicht) oder `ROLE` (Funktionskontakt). Telefon- und
        Faxnummer im internationalen Format in `phone` bzw. `fax`; die Felder
        `phone1`-`phone3` und `fax1`-`fax3` sind veraltet.


        Die Antwort enthält in `warnings` Hinweise auf Felder, die einzelne TLDs
        zusätzlich verlangen. Sie blockieren das Anlegen nicht.
      operationId: createHandle
      parameters:
        - $ref: '#/components/parameters/CustomerId'
      requestBody:
        description: The new Handle resource
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Handle.CreateHandleRequest-handle.write'
            example:
              type: ORG
              company: Musterfirma GmbH
              firstname: Max
              lastname: Mustermann
              address: Musterstraße 1
              city: Köln
              zipcode: '50667'
              countryCode: DE
              email: domains@musterfirma.de
              phone: +49 221 1234567
              language: de
        required: true
      responses:
        '201':
          description: Handle resource created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Handle-handle.read'
          links: {}
        '400':
          description: Invalid input
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          links: {}
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          links: {}
        '422':
          description: An error occurred
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ConstraintViolation'
            application/json:
              schema:
                $ref: '#/components/schemas/ConstraintViolation'
          links: {}
components:
  parameters:
    CustomerId:
      name: X-Customer-Id
      in: header
      required: false
      description: >-
        Optionaler Kundenkontext. Ohne Header arbeitet die Anfrage im
        Standard-Kunden des angemeldeten Benutzers. Mit der ID eines anderen
        Kunden handelt die Anfrage in dessen Kontext: Listen, Lese- und
        Schreibzugriffe beziehen sich dann auf diesen Kunden.


        Erlaubt sind der eigene Kunde, jeder Unterkunde im eigenen Teilbaum
        (Reseller handelt für seinen Endkunden) sowie Kunden, in denen der
        Benutzer selbst Mitglied ist. Übergeordnete oder fremde Kunden werden
        mit `403 Forbidden` abgewiesen, eine unbekannte ID ebenfalls.


        Die IDs der erreichbaren Kunden liefern `GET /user/customers` und `GET
        /customers/{id}/children`.
      schema:
        type: string
        example: 01JD4Q8W3N6Y2K5T7R9V0B1C2D
  schemas:
    Handle.CreateHandleRequest-handle.write:
      type: object
      properties:
        firstname:
          minLength: 2
          maxLength: 255
          description: Pflicht bei type=PERS.
          default: ''
          example: John
          type: string
        lastname:
          minLength: 2
          maxLength: 255
          description: Pflicht bei type=PERS.
          default: ''
          example: Doe
          type: string
        company:
          minLength: 2
          maxLength: 255
          description: Pflicht bei type=ORG.
          example: ACME Inc.
          type:
            - string
            - 'null'
        address:
          minLength: 2
          maxLength: 255
          default: ''
          example: Mainstreet 1
          type: string
        addressLine2:
          maxLength: 255
          description: Adresszeile 2 (Zusatz).
          example: c/o Musterfirma
          type:
            - string
            - 'null'
        city:
          minLength: 2
          maxLength: 255
          default: ''
          example: Cologne
          type: string
        state:
          maxLength: 255
          description: Bundesstaat/Region. Pflicht für Adressen in US/CA/AU.
          example: NY
          type:
            - string
            - 'null'
        zipcode:
          minLength: 2
          maxLength: 255
          default: ''
          example: '12345'
          type: string
        countryCode:
          minLength: 2
          maxLength: 255
          description: ISO 3166-1 alpha-2 country code
          default: ''
          example: DE
          type: string
        email:
          format: email
          minLength: 2
          maxLength: 255
          externalDocs:
            url: https://schema.org/email
          default: ''
          example: acme@example.com
          type: string
        language:
          pattern: ^([a-z]{2})$
          description: Sprache des Kontakts, ISO 639-1.
          example: de
          type:
            - string
            - 'null'
        phone:
          description: >-
            Telefonnummer, freies Format (+49 89 123456, +49-89-123456,
            +49.89123456, 0049..., national "089/123456" zusammen mit
            countryCode). Wird beim Speichern in E.164 normalisiert. Bevorzugt
            gegenüber phone1/2/3.
          example: +49 89 123456
          type:
            - string
            - 'null'
        fax:
          description: Faxnummer, freies Format. Wird in E.164 normalisiert.
          example: +49 89 123457
          type:
            - string
            - 'null'
        phone1:
          pattern: ^(\+\d{1,3})$
          description: 'DEPRECATED: Ländervorwahl. Stattdessen "phone" nutzen.'
          deprecated: true
          default: ''
          example: '+49'
          type: string
        phone2:
          pattern: ^(\d{0,5})$
          description: 'DEPRECATED: Ortsvorwahl. Stattdessen "phone" nutzen.'
          deprecated: true
          default: ''
          example: '221'
          type: string
        phone3:
          pattern: ^(\d{0,15})$
          description: 'DEPRECATED: Rufnummer. Stattdessen "phone" nutzen.'
          deprecated: true
          default: ''
          example: '1234567'
          type: string
        fax1:
          pattern: ^(\+\d{1,3})$
          description: 'DEPRECATED: Fax-Ländervorwahl. Stattdessen "fax" nutzen.'
          deprecated: true
          example: '+49'
          type:
            - string
            - 'null'
        fax2:
          pattern: ^(\d{0,5})$
          description: 'DEPRECATED: Fax-Ortsvorwahl. Stattdessen "fax" nutzen.'
          deprecated: true
          example: '221'
          type:
            - string
            - 'null'
        fax3:
          pattern: ^(\d{0,15})$
          description: 'DEPRECATED: Fax-Rufnummer. Stattdessen "fax" nutzen.'
          deprecated: true
          example: '1234567'
          type:
            - string
            - 'null'
        type:
          enum:
            - ORG
            - PERS
            - ROLE
          description: >-
            Handle-Typ, explizit: PERS (Person), ORG (Organisation) oder ROLE.
            ORG erfordert company, PERS erfordert firstname+lastname.
          default: PERS
          example: PERS
          type: string
      required:
        - address
        - city
        - zipcode
        - countryCode
        - email
        - type
    Handle-handle.read:
      type: object
      properties:
        id:
          readOnly: true
          example: 01F9Z3ZJXZQZJZJZJZJZJZJZJZ
          type: string
        firstname:
          example: John
          type: string
        lastname:
          example: Doe
          type: string
        company:
          example: ACME Inc.
          type:
            - string
            - 'null'
        address:
          description: Adresszeile 1 (Straße + Hausnummer)
          example: Mainstreet 1
          type: string
        addressLine2:
          maxLength: 255
          description: >-
            Adresszeile 2 (Zusatz). Registrare ohne zweite Zeile bekommen sie
            angehängt.
          example: c/o Musterfirma
          type:
            - string
            - 'null'
        city:
          example: Cologne
          type: string
        state:
          maxLength: 255
          description: >-
            Bundesstaat/Region (ISO-3166-2-Subcode wo vorhanden). Pflicht für
            US/CA/AU.
          example: NY
          type:
            - string
            - 'null'
        zipcode:
          example: '12345'
          type: string
        countryCode:
          description: ISO 3166-1 alpha-2 country code
          example: DE
          type: string
        email:
          example: acme@example.com
          type: string
        language:
          pattern: ^([a-z]{2})$
          description: Sprache des Kontakts, ISO 639-1 (klein).
          example: de
          type:
            - string
            - 'null'
        note:
          example: Some internal note
          type:
            - string
            - 'null'
        verified:
          type: boolean
        phone:
          readOnly: true
          description: Telefonnummer in E.164-Kanonform (maßgeblich).
          example: '+4989123456'
          type:
            - string
            - 'null'
        fax:
          readOnly: true
          description: Faxnummer in E.164-Kanonform (maßgeblich).
          example: '+4989123457'
          type:
            - string
            - 'null'
        phone1:
          pattern: ^(\+\d{1,3})$
          description: 'DEPRECATED: Ländervorwahl. Abgeleitet aus phone (E.164).'
          example: '+49'
          type: string
        phone2:
          pattern: ^(\d{0,5})$
          description: 'DEPRECATED: Ortsvorwahl. Leer, wenn unbekannt.'
          example: '221'
          type: string
        phone3:
          pattern: ^(\d{1,15})$
          description: 'DEPRECATED: Rufnummer. Abgeleitet aus phone (E.164).'
          example: '1234567'
          type: string
        fax1:
          pattern: ^(\+\d{1,3})$
          description: 'DEPRECATED: Fax-Ländervorwahl. Abgeleitet aus fax (E.164).'
          example: '+49'
          type:
            - string
            - 'null'
        fax2:
          pattern: ^(\d{0,5})$
          description: 'DEPRECATED: Fax-Ortsvorwahl. Leer, wenn unbekannt.'
          example: '221'
          type:
            - string
            - 'null'
        fax3:
          pattern: ^(\d{1,15})$
          description: 'DEPRECATED: Fax-Rufnummer. Abgeleitet aus fax (E.164).'
          example: '1234567'
          type:
            - string
            - 'null'
        type:
          example: PERS
          type: string
          enum:
            - ORG
            - PERS
            - ROLE
        registrarRelations:
          readOnly: true
          description: >-
            Zuordnung: bei welchem Registrar der Handle angelegt ist und welche
            ID er dort hat (z. B. InternetX Contact-ID, nic.ch Handle).
          type: array
          items:
            $ref: '#/components/schemas/DomainRegistrarHandle-handle.read'
        warnings:
          description: Hinweise auf fehlende Pflichtfelder (nur bei POST/PUT gefüllt).
          type: array
          items:
            type: string
    Error:
      type: object
      description: A representation of common errors.
      properties:
        title:
          readOnly: true
          description: A short, human-readable summary of the problem.
          type:
            - string
            - 'null'
        detail:
          readOnly: true
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem.
          type:
            - string
            - 'null'
        status:
          type:
            - integer
            - 'null'
          examples:
            - 404
          default: 400
        instance:
          readOnly: true
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem. It may or may not yield further information if
            dereferenced.
          type:
            - string
            - 'null'
        type:
          readOnly: true
          description: A URI reference that identifies the problem type
          type: string
    ConstraintViolation:
      type: object
      description: Unprocessable entity
      properties:
        status:
          default: 422
          type: integer
        violations:
          type: array
          items:
            type: object
            properties:
              propertyPath:
                type: string
                description: The property path of the violation
              message:
                type: string
                description: The message associated with the violation
              code:
                type: string
                description: The code of the violation
              hint:
                type: string
                description: An extra hint to understand the violation
              payload:
                type: object
                additionalProperties: true
                description: The serialized payload of the violation
            required:
              - propertyPath
              - message
        detail:
          readOnly: true
          type: string
        type:
          readOnly: true
          type: string
        title:
          readOnly: true
          type:
            - string
            - 'null'
        instance:
          readOnly: true
          type:
            - string
            - 'null'
    DomainRegistrarHandle-handle.read:
      type: object
      properties:
        id:
          readOnly: true
          description: >-
            Externe Handle-ID beim Registrar (z. B. InternetX Contact-ID
            "24161044", nic.ch EPP-Handle).
          type: string
        registrar:
          $ref: '#/components/schemas/DomainRegistrar-handle.read'
    DomainRegistrar-handle.read:
      type: object
      properties:
        id:
          readOnly: true
          type: string
        type:
          type: string
          enum:
            - INTERNET_X
            - DOMAIN_BESTELLSYSTEM
            - SwitchCh
            - CPS_DATENSYSTEME
            - OPUSDNS
  securitySchemes:
    JWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Access-Token aus `POST /auth/login` (E-Mail und Passwort), gesendet als
        `Authorization: Bearer <token>`.


        Das Token ist zeitlich begrenzt gültig. Mit dem `refresh_token` aus
        derselben Antwort holt `POST /auth/token/refresh` ein neues Token-Paar,
        ohne das Passwort erneut zu senden; `POST /auth/token/invalidate` macht
        den Refresh-Token beim Abmelden ungültig.


        Ist für das Konto ein zweiter Faktor aktiv oder vorgeschrieben, liefert
        der Login statt des Token-Paars `mfaRequired: true` bzw.
        `mfaEnrollmentRequired: true` und ein kurzlebiges `preAuthToken`. Mit
        diesem Token (ebenfalls als Bearer) wird der zweite Faktor über `POST
        /auth/2fa/verify` bestätigt; erst danach gibt es das volle Token-Paar.
    ApiToken:
      type: apiKey
      in: header
      name: X-API-TOKEN
      description: >-
        Persönlicher API-Token für Skripte, CI/CD und
        Server-zu-Server-Integrationen, gesendet im Header `X-API-TOKEN:
        <token>`.


        Tokens werden im Kundenpanel unter **Einstellungen → Sicherheit**
        angelegt oder per `POST /user/api-tokens` mit einem gültigen JWT. Der
        Klartext erscheint nur einmal in der Antwort beim Anlegen. Ein Token
        handelt mit den Rechten des Benutzers, der ihn erstellt hat, kann ein
        Ablaufdatum haben und wird mit `DELETE /user/api-tokens/{id}` sofort
        widerrufen.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.