Persons API

Persons API

A Person is the core record for students, teachers, staff, contacts and external persons. All of them share the same base entity; the object type (e.g. PERSON, STUDENT, TEACHER) determines the behaviour, classification and default folder placement.

Create a Person

Mutation

mutation CreatePerson(
  $person: PersonCreateInput!
  $parentID: ID
  $objectType: String!
) {
  createPerson(
    person: $person
    parentID: $parentID
    objectType: $objectType
  ) {
    status
    message
    id
    person {
      id
      lastName
      preName
      birthday
    }
  }
}

Minimal variables

Only lastName is strictly required by validation (2 – 59 characters). parentID falls back to the default person folder when set to the special identifier special://PERSONFLDROOT.

{
  "objectType": "PERSON",
  "parentID": "special://PERSONFLDROOT",
  "person": {
    "lastName": "Müller",
    "preName": "Anna",
    "birthday": "1998-03-21",
    "sex": "F",
    "languageCode": "de"
  }
}

Response

{
  "data": {
    "createPerson": {
      "status": "SUCCESS",
      "message": null,
      "id": "8f3a1a8e-...-1c",
      "person": {
        "id": "8f3a1a8e-...-1c",
        "lastName": "Müller",
        "preName": "Anna",
        "birthday": "1998-03-21"
      }
    }
  }
}

The returned id is a UID and is used everywhere else in the API. The internal numeric personID is never exposed.

Create a Person Together with an Address

The newAddresses field on PersonCreateInput accepts one or more addresses that are inserted in the same transaction:

{
  "objectType": "PERSON",
  "parentID": "special://PERSONFLDROOT",
  "person": {
    "lastName": "Müller",
    "preName": "Anna",
    "languageCode": "de",
    "newAddresses": [
      {
        "isMain": true,
        "street": "Marktgasse",
        "streetNr": "12",
        "areaCode": "3011",
        "city": "Bern",
        "countryCode": "CH",
        "email": "anna.mueller@example.ch",
        "phone": "+41 31 123 45 67"
      }
    ]
  }
}

Common PersonCreateInput Fields

All fields are optional unless marked. The input extends PersonUpdateInput which extends BaseObjectInput, so every base-object field (remarks, validFrom, validTo, ownerID, customFields, …) is also accepted.

Field	Type	Notes
lastName	String	Required. 2 – 59 characters.
preName	String	0 – 59 characters.
middleName	String	0 – 25 characters.
personNumber	String	Customer-facing number; must be unique if set.
birthday	Date	YYYY-MM-DD. Must be between 1850-01-01 and today.
sex	Sex	M, F, X.
languageCode	String	ISO 2-letter code — must match a configured language.
salutation	String	0 – 25 characters.
salutationWithName	String	0 – 100 characters.
citizenshipCountryCode	String	ISO 2-letter country code.
ahvnr	String	Swiss social security number.
bankIbanNumber	String	Validated with IsIBAN.
code	String	PersonCode — free text, 0 – 255 characters.
deliverMessageType	enum	Default channel for system messages.
customFields	list	Customer-specific custom field values. See Schema.
newAddresses	list	Create one or more addresses in the same call.

Any field that fails validation (for instance lastName shorter than 2 characters, or an unknown languageCode) causes the mutation to return status: "ERROR" with an explanatory message.

Update a Person

mutation UpdatePerson($id: ID!, $person: PersonUpdateInput!) {
  updatePerson(id: $id, person: $person) {
    status
    message
    person {
      id
      lastName
      preName
    }
  }
}

PersonUpdateInput takes the same fields as PersonCreateInput minus newAddresses. Only the fields you send are changed; omitted fields keep their current value.

Query a Person

Single item:

query {
  person(id: "8f3a1a8e-...-1c") {
    id
    personNumber
    lastName
    preName
    birthday
    mainAddress {
      email
      phone
    }
  }
}

List with filter and paging:

query {
  persons(
    options: {
      searchTerm: "Müller"
      onlyActive: true
      orderBy: "lastName"
      orderDirection: ASC
      limit: 25
      offset: 0
    }
  ) {
    totalCount
    nodes {
      id
      lastName
      preName
    }
  }
}

Delete a Person

mutation {
  deletePerson(id: "8f3a1a8e-...-1c") {
    status
    message
  }
}

A delete is soft unless the caller has the administrative purge right. Linked data (addresses, memberships, course participants …) is kept for audit purposes.

Authorization

All person mutations and queries require a JWT (see Authentication). The server additionally performs an ACL check against parentID for createPerson and against the object itself for update and delete. A caller without the required access right receives status: "DENIED".

Related

• Course Participants — book a person into a course
• Course Registrations — register one or more persons for one or more courses
• Public Enrollment — sign up a new or existing person from an anonymous website form