Halter anlegen

Halter werden unabhängig von Anträgen gespeichert und über holder_id referenziert. Neue Halter erhalten verification_status = unverified. Die Umgebung folgt dem API-Schlüssel.

Beschreibung

Legt einen Halter in Ihrem Konto an.

Parameter

Idempotency-KeyheaderPflicht

Eindeutiger Schlüssel für diese Anlage. Bei Retries unverändert wiederverwenden.

Beispiel: holder-customer-1842-v1

Request-Body

Der Body wird als application/json übertragen. Verwenden Sie ausschließlich die dokumentierten Feldnamen.

Request-Felder

Feld	Typ	Angabe	Beschreibung
`type`	enum	Pflicht	`person`, `company` oder `sole_proprietor`.
`first_name`	string	Bedingt	Pflicht für Personen und Einzelunternehmen.
`last_name`	string	Bedingt	Pflicht für Personen und Einzelunternehmen.
`birth_date`	date	Optional	Geburtsdatum im Format YYYY-MM-DD.
`birth_place`	string	Optional	Geburtsort der Person.
`birth_name`	string	Optional	Geburtsname, falls abweichend.
`title`	string	Optional	Akademischer oder amtlicher Titel.
`gender`	enum	Optional	`male`, `female`, `diverse` oder `unspecified`.
`company_name`	string	Bedingt	Pflicht für Unternehmen und Einzelunternehmen.
`register.type`	enum	Bedingt	Für Unternehmen: `HRA`, `HRB`, `VR`, `GNR` oder `PR`.
`register.number`	string	Bedingt	Registernummer des Unternehmens.
`business_sector`	string	Bedingt	Dreistelliger Wirtschaftszweig für Unternehmen und Einzelunternehmen.
`email`	email	Optional	Kontaktadresse des Halters.
`phone`	string	Optional	Telefonnummer des Halters.
`address`	object	Pflicht	Anschrift des Halters.
`address.street`	string	Pflicht	Straße.
`address.house_number`	string	Pflicht	Hausnummer.
`address.house_number_suffix`	string	Optional	Zusatz zur Hausnummer.
`address.address_extra`	string	Optional	Zusätzliche Anschriftzeile.
`address.postal_code`	string	Pflicht	Fünfstellige deutsche Postleitzahl.
`address.city`	string	Pflicht	Ort.
`address.country_code`	string	Optional	ISO-3166-1-Alpha-2-Ländercode; Standard `DE`.
`external_reference`	string	Optional	Referenz aus dem eigenen System; maximal 100 Zeichen.

{
  "type": "person",
  "first_name": "Mara",
  "last_name": "Beispiel",
  "birth_date": "1988-04-12",
  "birth_place": "Bremen",
  "email": "mara.beispiel@example.com",
  "phone": "+491701234567",
  "address": {
    "street": "Am Markt",
    "house_number": "12",
    "postal_code": "28195",
    "city": "Bremen",
    "country_code": "DE"
  },
  "external_reference": "customer-1842"
}

SchemaquelleOpenAPI 3.1 herunterladen

Responses

201

Halter angelegt. Die Ressource ist direkt verwendbar, auch wenn sie noch unverifiziert ist.

409

Idempotenzkonflikt: derselbe Schlüssel wurde mit einem anderen Body verwendet.

422

Personen-, Firmen- oder Adressdaten sind unvollständig.

Response-Body

Content-Type: application/json. Die erfolgreiche Antwort enthält die nachfolgend beschriebenen Felder.

Response-Felder

Feld	Typ	Angabe	Beschreibung
`id`	string	Immer	Öffentliche Halter-ID.
`object`	string	Immer	Konstanter Wert `holder`.
`environment`	enum	Immer	`test` oder `live`.
`livemode`	boolean	Immer	`true` für Live-Ressourcen.
`revision`	integer	Immer	Fortlaufende Versionsnummer der Halterdaten; erhöht sich bei Änderungen.
`external_reference`	string\|null	Optional	Referenz aus dem eigenen System.
`verification_status`	enum	Immer	`unverified`, `pending`, `verified` oder `failed`.
`data`	object	Immer	Personen-, Unternehmens-, Kontakt- und Anschriftdaten der aktuellen Revision.
`created_at`	date-time	Immer	Erstellungszeitpunkt im ISO-8601-Format.
`updated_at`	date-time	Immer	Letzte Änderung im ISO-8601-Format.

{
  "id": "hld_test_1a2b3c4d5e6f708192a3b4c5",
  "object": "holder",
  "environment": "test",
  "livemode": false,
  "external_reference": "customer-1842",
  "revision": 1,
  "verification_status": "unverified",
  "data": {
    "type": "person",
    "first_name": "Mara",
    "last_name": "Beispiel",
    "birth_date": "1988-04-12",
    "birth_place": "Bremen",
    "email": "mara.beispiel@example.com",
    "phone": "+491701234567",
    "address": {
      "street": "Am Markt",
      "house_number": "12",
      "postal_code": "28195",
      "city": "Bremen",
      "country_code": "DE"
    }
  },
  "created_at": "2026-08-26T10:15:00+02:00",
  "updated_at": "2026-08-26T10:15:00+02:00"
}

Person, Unternehmen oder Einzelunternehmen

type unterscheidet person, company und sole_proprietor. Unternehmen benötigen Firmenname, Registerdaten und dreistelligen Wirtschaftszweig. Einzelunternehmen benötigen Personen- und Unternehmensnamen sowie den Wirtschaftszweig.

Umgebung aus dem Schlüssel

{ "id": "hld_test_1a2b3c4d5e6f708192a3b4c5", "object": "holder", "environment": "test", "livemode": false, "external_reference": "customer-1842", "revision": 1, "verification_status": "unverified", "data": { "type": "person", "first_name": "Mara", "last_name": "Beispiel", "birth_date": "1988-04-12", "birth_place": "Bremen", "email": "mara.beispiel@example.com", "phone": "+491701234567", "address": { "street": "Am Markt", "house_number": "12", "postal_code": "28195", "city": "Bremen", "country_code": "DE" } }, "created_at": "2026-08-26T10:15:00+02:00", "updated_at": "2026-08-26T10:15:00+02:00" }