Erstellen eines Personendatensatzes.

POST /personen

Mittels dieser Schnittstelle wird ein neuer Datensatz „Person“ erstellt.

Ein CREATE zum Erstellen von Personendatensätzen muss mit HTTP-POST auf die API /personen erfolgen. Die Anfrage-Nutzdaten (Request Payload) beinhalten ein JSON-Objekt des Datentyps Personendatensatz. Siehe auch die einzelnen Datenmodelle zu Personendatensatz und Person.

Die folgende Tabelle listet die Attribute einer Person (personendatensatz.person), welche von einem Quellsystem oder Dienst nicht gesetzt werden können.

Attribut	In den Anfrage-Nutzdaten erforderlich?	Bemerkung
`id`	nein	ID der Person. Wird vom Schulconnex-Server vergeben und ist eindeutig. Dieses Attribut ist unveränderbar (immutable).
`mandant`	nein	ID des Mandanten, dem die Person zugeordnet ist. Wird vom Schulconnex-Server vergeben und ist eindeutig. Dieser Wert ist eine Referenz auf einen Mandanten.
`revision`	nein	Revision der Person. Wird vom Schulconnex-Server mit der Erstellung des Datensatzes sowie Aktualisierung generiert. Dieser Wert kann nicht von Quellsystemen oder Diensten gesetzt werden.

In Anbetracht der Attribute, die von einem Quellsystem oder Dienst bei der Erstellung einer Person nicht gesetzt oder verändert werden können, ergibt sich folgende JSON-Struktur der Anfrage-Nutzdaten (Request Payload):

{
  "referrer": <String>, // ID der Person im Quellsystem.
  "name": {
    "familienname": <String>,
    //Familienname der Person. Dieses Feld ist ein Pflichtfeld.
    "vorname": <String>,
    // Vorname der Person. Dieses Feld ist ein Pflichtfeld.
    "initialenfamilienname": <String>,
    //Initial oder Initialen des Familiennames der Person. D
    "initialenvorname ": <String>,
    // Initial oder Initialen des Vornamens der Person.
    "rufname": <String>, // Rufname der Person.
    "titel": <String>, // Titel der Person.
    "anrede": [
      <String> // Liste von Anreden der Person.
    ],
    "namenssuffix": [
      <String> // Liste von Namenssuffixe der Person.
    ],
    "sortierindex": <String> // sortierindex des Nachnamens
  },
  "geburt": {
    "datum": <Datum>, // Geburtsdatum der Person.
    "geburtsort": <String> // Geburtsort der Person.
  },
  "geschlecht": <Code>,
  // Geschlecht der Person. Siehe Code-Liste „Geschlecht“.
  "lokalisierung": <String>, // Zm Beispiel "de", String basierend auf RFC 5646.
  "vertrauensstufe": <Code>,
  // Vertrauensstufe. Siehe Code-Liste „Vertrauensstufe“.
  "auskunftssperre": <Code>
  // Auskunftssperre. Siehe Code-Liste „Boolean“.
  // Dieses Feld ist ein Pflichtfeld.
 }

Bei einer erfolgreichen Anforderung zum Erstellen eines Personendatensatzes wird diese Anforderung mit einer Repräsentation des Personendatensatzes in den Antwort-Nutzdaten und dem HTTP Status Code 201 quittiert.

Request

application/json

Body

required

referrer string

Identifikations-ID einer Person. Wird vom Quellsystem vergeben und muss im Quellsystem eindeutig sein (z. B. eine einheitliche Personalnummer).

stammorganisation string

ID der Stammorganisation. Personen können einer Organisation angehören, jedoch zeitweise an einer anderen Organisation tätig sein. Der häufigste Anwendungsfall ist die Abordnung eines Lehrenden an eine andere Dienststelle. Die Stammorganisation ist unabhängig vom Personenkontext.

name

object

required

familienname stringrequired

Familienname(n) der Person. Mehrere Familiennamen werden durch Leerzeichen separiert.

vorname stringrequired

Mehrere Vornamen werden durch Leerzeichen separiert.

initialenfamilienname string

Possible values: <= 8 characters

Initial oder Initialen des Familiennamens, maximal acht Zeichen.

initialenvorname string

Possible values: <= 8 characters

Initial oder Initialen des Vornamens, maximal acht Zeichen.

rufname string

Possible values: <= 32 characters

Bei mehreren Vornamen wird der täglich im Gebrauch genutzte Vorname geführt, maximal 32 Zeichen.

titel string

Possible values: <= 128 characters

Titel der Person (bspw. ein akademischer Grad, Dienst- und Amtsbezeichnungen oder militärische Ränge), maximal 128 Zeichen.

anrede string[]

Possible values: <= 64 characters

Liste (Array) von Namenszusätzen bei der Anrede. Jeder einzelne Namenszusatz hat eine Maximallänge von 64 Zeichen, die Maximallänge für alle Namenszusätze liegt bei 512 Zeichen.

namenssuffix string[]

Possible values: <= 64 characters

Liste (Array) von Namenssuffixen. Jeder einzelne Namenssuffix hat eine Maximallänge von 64 Zeichen, die Maximallänge für alle Namenssuffixe liegt bei 1024 Zeichen.

sortierindex string

Possible values: Value must match regular expression ^[0-9]+$

Index des Buchstabens des Nachnamens, nach dem sortiert werden soll. Der Index ist Null-basiert, d. h. ein Wert von „4“ zeigt an, dass die ersten vier Buchstaben ignoriert und ab dem fünften Buchstaben des Nachnamens sortiert werden soll. Ist kein Sortierindex angegeben, so ist der Nachname entsprechend dem ersten Buchstaben in Listen einzusortieren, äquivalent zum Sortierindex „0“.

geburt

object

datum date

Geburtsdatum einer Person.

geburtsort string

Geburtsort einer Person, bestehend aus Ortsname und Land, beispielsweise „Eindhoven, Niederlande“. Wird kein Land angegeben, so wird als Land „Deutschland“ angenommen, d.h. der Geburtsort „Erfurt“ ist wie „Erfurt, Deutschland“ zu behandeln.

geschlecht components-code-Geschlecht (string)

Possible values: [m, w, d, x]

Geschlecht:

m männlich
w weiblich
d divers
x keine Angabe

lokalisierung string

Basierend auf RFC 5646. Mögliche Beispiele:

de deutsch
de-XX deutsch, Anrede du, einfache Sprache
en-GB englisch (Vereinigtes Königreich)

vertrauensstufe components-code-Vertrauensstufe (string)

Possible values: [Kein, Unbe, Teil, Voll]

Wie folgt:

Kein - kein - Der Schlüsselbesitzer ist nicht vertrauenswürdig.
Unbe - unbekannt - Der Schlüsselbesitzer ist unbekannt.
Teil - vertraut - Dem Schlüsselbesitzer wird vertraut.
Voll - verifiziert - Der Schlüsselbesitzer ist eindeutig und formal identifiziert.

auskunftssperre components-code-Boolean (string)required

Possible values: [Ja, Nein]

Die Codeliste „Boolean“ regelt das Mapping der deutschen Wörter „ja“ und „nein“ auf die englischen Begriffe „true“ und „false“:

Ja true
Nein false

Responses

application/json

Schema
Example (from schema)

Schema

id stringrequired

ID der Person. Wird vom Schulconnex-Server vergeben und ist eindeutig. Dieses Attribut ist unveränderbar (immutable).

mandant stringrequired

ID des Mandanten, dem die Personen zugeordnet ist. Wird vom Schulconnex-Server vergeben und ist eindeutig.

revision stringrequired

Revision der Person. Wird vom Schulconnex-Server mit der Erstellung des Datensatzes sowie Aktualisierung generiert. Dieser Wert kann nicht von Quellsystemen oder Diensten gesetzt werden.

referrer string

Identifikations-ID einer Person. Wird vom Quellsystem vergeben und muss im Quellsystem eindeutig sein (z. B. eine einheitliche Personalnummer).

stammorganisation string

name

object

required

familienname stringrequired

Familienname(n) der Person. Mehrere Familiennamen werden durch Leerzeichen separiert.

vorname stringrequired

Mehrere Vornamen werden durch Leerzeichen separiert.

initialenfamilienname string

Possible values: <= 8 characters

Initial oder Initialen des Familiennamens, maximal acht Zeichen.

initialenvorname string

Possible values: <= 8 characters

Initial oder Initialen des Vornamens, maximal acht Zeichen.

rufname string

Possible values: <= 32 characters

Bei mehreren Vornamen wird der täglich im Gebrauch genutzte Vorname geführt, maximal 32 Zeichen.

titel string

Possible values: <= 128 characters

Titel der Person (bspw. ein akademischer Grad, Dienst- und Amtsbezeichnungen oder militärische Ränge), maximal 128 Zeichen.

anrede string[]

Possible values: <= 64 characters

Liste (Array) von Namenszusätzen bei der Anrede. Jeder einzelne Namenszusatz hat eine Maximallänge von 64 Zeichen, die Maximallänge für alle Namenszusätze liegt bei 512 Zeichen.

namenssuffix string[]

Possible values: <= 64 characters

Liste (Array) von Namenssuffixen. Jeder einzelne Namenssuffix hat eine Maximallänge von 64 Zeichen, die Maximallänge für alle Namenssuffixe liegt bei 1024 Zeichen.

sortierindex string

Possible values: Value must match regular expression ^[0-9]+$

geburt

object

datum date

Geburtsdatum einer Person.

geburtsort string

geschlecht components-code-Geschlecht (string)

Possible values: [m, w, d, x]

Geschlecht:

m männlich
w weiblich
d divers
x keine Angabe

lokalisierung string

Basierend auf RFC 5646. Mögliche Beispiele:

de deutsch
de-XX deutsch, Anrede du, einfache Sprache
en-GB englisch (Vereinigtes Königreich)

vertrauensstufe components-code-Vertrauensstufe (string)

Possible values: [Kein, Unbe, Teil, Voll]

Wie folgt:

Kein - kein - Der Schlüsselbesitzer ist nicht vertrauenswürdig.
Unbe - unbekannt - Der Schlüsselbesitzer ist unbekannt.
Teil - vertraut - Dem Schlüsselbesitzer wird vertraut.
Voll - verifiziert - Der Schlüsselbesitzer ist eindeutig und formal identifiziert.

auskunftssperre components-code-Boolean (string)required

Possible values: [Ja, Nein]

Die Codeliste „Boolean“ regelt das Mapping der deutschen Wörter „ja“ und „nein“ auf die englischen Begriffe „true“ und „false“:

Ja true
Nein false

{
  "id": "a6e1a860-8d44-4b2b-aef7-aa2c8bf5beb5",
  "mandant": "58f45270-8e54-40c6-a212-980307fc19be",
  "revision": "1",
  "referrer": "125",
  "stammorganisation": "ad4a5d27-631d-49a3-bc0a-cc28614f8443",
  "name": {
    "familienname": "von Musterfrau",
    "vorname": "Natalie",
    "initialenfamilienname": "M",
    "initialenvorname": "N",
    "rufname": "string",
    "titel": "string",
    "anrede": [
      "string"
    ],
    "namenssuffix": [
      "string"
    ],
    "sortierindex": "4"
  },
  "geburt": {
    "datum": "2005-05-01",
    "geburtsort": "Berlin, Deutschland"
  },
  "geschlecht": "m",
  "lokalisierung": "de",
  "vertrauensstufe": "Kein",
  "auskunftssperre": "Ja"
}

Erstellen eines Personendatensatzes.

/personen

Request​

Body

Responses​

Request

Responses