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

# Persons

<Info>
  In many fields, you will see two systems listed in a specific order. These lists indicate the order of precedence of
  the systems. The returned value is taken from the first system in the list that is deployed in your environment,
  regardless of where information has been stored.

  Payroll and Time & Security data can only be retrieved if the person mappings have been configured in the VEDA
  Horizon Platform. If multiple contracts are active, the primary employment is used.
</Info>


## OpenAPI

````yaml GET /api/v1/persons
openapi: 3.1.0
info:
  title: VEDA API
  description: >-
    The VEDA API is a unified API that provides access to various components of
    the VEDA HR Cloud. It simplifies the integration process by offering a
    single entry point for all API requests.
  contact:
    name: Tim Augustin
    email: tim.augustin@veda.net
  version: v1
servers: []
security: []
paths:
  /api/v1/persons:
    get:
      tags:
        - employees-controller
      operationId: getPersons
      parameters:
        - name: modifiedSince
          in: query
          description: >-
            Only persons whose data has changed since this date are included in
            the results.

            The returned elements only contain information from systems in which
            changes have occurred; they do not contain complete person data.
            This enables us to produce faster results. If you feel that this
            should change, please provide us with feedback.
          required: false
          schema:
            type: string
            format: date-time
            description: >-
              Only persons whose data has changed since this date are included
              in the results.

              The returned elements only contain information from systems in
              which changes have occurred; they do not contain complete person
              data. This enables us to produce faster results. If you feel that
              this should change, please provide us with feedback.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Person'
components:
  schemas:
    Person:
      type: object
      description: A person is a human being
      properties:
        id:
          type: string
          format: uuid
          description: >-
            Unique identifier. Matches the ID of the person in the VEDA Horizon
            (Base) API
        academicTitle:
          type: string
          description: |-
            1. Payroll Expert - LPTITL
            1. Platform - Personal information > General (Formerly title)
          examples:
            - Dr.
          maxLength: 80
        firstName:
          type: string
          description: |-
            1. Payroll Expert - LPVNAM
            1. Platform - Personal information > General
          examples:
            - Max
          maxLength: 80
        middleName:
          type: string
          description: >-
            1. Payroll Expert includes the middle name in the firstName field.
            If present, this field is always empty.

            1. Platform - Personal information > General
          examples:
            - Moritz
          maxLength: 80
        lastName:
          type: string
          description: |-
            1. Payroll Expert - LPNAME (Formerly name)
            1. Platform - Personal information > General
          examples:
            - Mustermann
          maxLength: 80
        birthName:
          type: string
          description: |-
            1. Payroll Expert - LPGNAM
            1. Platform - Personal information > General
          examples:
            - Musterfamilie
          maxLength: 80
        prefixToLastName:
          type: string
          description: |-
            1. Payroll Expert - LPVSWO (Formerly namePrefix)
            1. Platform - Personal information > General (Formerly namePrefix)
          examples:
            - zum
          maxLength: 80
        titleOfNobility:
          type: string
          description: |
            1. Payroll Expert - LPNMZU (Formerly nameAffix)
            1. Platform - Personal information > General (Formerly nameAffix)
          examples:
            - Baron
          maxLength: 80
        suffixToLastName:
          type: string
          description: >-
            E.g. additions like senior, junior, or suffixed academic titles like
            M.Sc., M.A., abbreviations of religious orders like SJ, or
            abbreviations of public offices like MP


            1. Platform - Personal information > General (Formerly
            titlePostPositioned)
          examples:
            - junior
          maxLength: 80
        gender:
          type: string
          description: |-
            Gender according to birth certificate or passport

            1. Payroll Expert - LPGENU
            1. Platform - Personal information > General
          enum:
            - MALE
            - FEMALE
            - INTERSEX
            - UNSPECIFIED
          examples:
            - FEMALE
        dateOfBirth:
          type: string
          format: date
          description: |-
            1. Payroll Expert - LPGBDT
            1. Platform - Personal information > General
          examples:
            - '2023-06-14'
        citizenship:
          type: string
          format: ISO 3166-1 alpha-2
          description: |-
            1. Payroll Expert - LPSTAA
            1. Platform - Personal information > General
          examples:
            - DE
          maxLength: 2
          minLength: 2
        address:
          description: |-
            1. Payroll Expert
            1. Platform - Personal information > Personal contact information
          oneOf:
            - $ref: '#/components/schemas/Address'
            - $ref: '#/components/schemas/AddressPostOfficeBox'
        bankDetails:
          $ref: '#/components/schemas/BankDetails'
          description: >-
            1. Platform - Personal information > Compensation-relevant
            information
        businessEmail:
          type: string
          format: email
          description: |-
            The standard business email address

            1. Platform - Business information > Business contact details
          examples:
            - Max.Mustermann@example.com
          maxLength: 254
          pattern: '|^.+@.+$'
        usualPlaceOfWork:
          type: string
          description: >-
            Name of the place where the person can usually be reached and can
            receive visitors or mail, for example.


            1. Payroll Expert - LPBEOR (Formerly placeOfEmployment)
          maxLength: 33
        status:
          type: string
          description: |
            Account status of the person.

            1. Platform - Administration > Basics > Users
          enum:
            - ACTIVE
            - INACTIVE
        groupEntryDate:
          type: string
          format: date
          description: >-
            Start of first employment with the organisation


            1. Platform - Business information > General (Formerly
            enterpriseEntryDate)
          examples:
            - '1999-02-31'
        groupExitDate:
          type: string
          format: date
          description: |-
            End or planned end of last employment with the organization

            1. Payroll Expert - LPADDT (Formerly terminationDate)
            1. Platform - Business information > General (Formerly leavingDate)
          examples:
            - '2050-12-24'
        exitReasonId:
          type: string
          description: |-
            Identifier of the reason for exit

            1. Payroll Expert - LPATGR (Formerly terminationReasonId)
          maxLength: 2
        exitNoticeDate:
          type: string
          format: date
          description: >-
            Effective date of termination.

            Depending on the reason for termination, either the date of receipt
            of the termination or the date on which the termination was
            declared.


            1. Payroll Expert - LPKUDT (Formerly terminationCommunicatedDate)
        expectedStartOfPension:
          type: string
          format: date
          description: 1. Platform - Business information > General
          examples:
            - '2099-12-31'
        employeeNumber:
          type: string
          description: 1. Platform - Business information > General
          examples:
            - '56'
          maxLength: 20
        jobTitle:
          type: string
          description: >-
            1. Platform - Business information > General (Formerly
            employmentTitleDisplayName)
          examples:
            - Integrations Team Lead
          maxLength: 400
        legalEntity:
          $ref: '#/components/schemas/LegalEntity'
          description: >
            The legal entity the person is primarily associated with. They are
            similar to groups, but you can only have one.


            1. Payroll Expert - LPWERK (Formerly branchId)
        groups:
          type: array
          description: >
            Grouping (ha!) of a person. A person can be member of multiple
            groups of the same and different types.
          items:
            $ref: '#/components/schemas/Group'
        managerId:
          type: string
          format: uuid
          description: >-
            Person id of the disciplinary manager. Further information about the
            manager (as person) can be retrieved using this id


            1. Platform - Business information > General
        keyNumber:
          type: string
          description: >-
            The person's ID number. Used for identification at time-recording or
            similar terminals.


            1. Time Expert
        employments:
          type: array
          description: >
            Information about the person's employment(s). While most employees
            have a single employment, multiple concurrent employments are
            possible.

            Common scenarios include:

            - Employees in multiple roles across different subsidiaries

            - Employees on parental leave who maintain a part-time position
            during this period

            Only employment records that exist in Payroll Expert, and for which
            matching person mappings are configured in VEDA Horizon, will be
            returned. Any additional employments or mappings will be ignored.
          items:
            $ref: '#/components/schemas/Employment'
        customFields:
          type: array
          description: >
            Custom fields of the person.

            Before any custom fields can be returned, you need to configure the
            API to include the fields you need. This can be done in the Platform
            under Administration > Basics > External applications > Second icon
            in the action column.
          items:
            $ref: '#/components/schemas/PersonCustomField'
        payrollContractIds:
          type: array
          deprecated: true
          description: >-
            **(⚠️ Deprecated - Please use `employments.id` instead. It includes
            more information in addition to the ids)** Maintained field for
            backwards compatibility.


            Contract ids are used to identify individuals in the payroll system.
            One person can have multiple payroll contracts, e.g. if they have
            multiple jobs or roles in the organization.

            This list may contain values that are not available in Payroll. If
            this is the case, please correct the person mappings in VEDA
            Horizon.

            In the past, payroll contracts were identified using a combination
            of the company and employee number. Currently, the ids are in the
            form 'companyId-employeeNumber'. You can use this information if you
            already have it, but it may not be stable in the future.
          items:
            type: string
          uniqueItems: true
    Address:
      type: object
      properties:
        street:
          type: string
          description: |-
            1. Payroll Expert
            1. Platform - Excluding houseNumber
          examples:
            - Carl-Zeiss-Straße
          maxLength: 255
        houseNumber:
          type: string
          description: >-
            1. Payroll Expert (Formerly streetNumber)

            1. Platform - The house number is not a separate field here. The
            house number is automatically extracted from the address field
          examples:
            - '14'
          maxLength: 20
        additionalAddressInfo:
          type: string
          description: |-
            Apartment or suite information
            1. Payroll Expert (Formerly addressLine2)
            1. Platform
          maxLength: 255
        zipCode:
          type: string
          description: |-
            1. Payroll Expert (Formerly postalCode)
            1. Platform (Formerly postalCode)
          examples:
            - '52477'
          maxLength: 10
        city:
          type: string
          examples:
            - Alsdorf
          maxLength: 255
        stateCode:
          type: string
          format: ISO 3166-2
          description: |-
            1. Not available in Payroll Expert
            1. Platform (Formerly regionCode)
          examples:
            - DE-NW
          maxLength: 6
          minLength: 4
        country:
          type: string
          format: ISO 3166-1 alpha-2
          description: |-
            1. Payroll Expert
            1. Platform (Formerly countryCode)
          examples:
            - DE
          maxLength: 2
          minLength: 2
      title: StreetAddress
    AddressPostOfficeBox:
      type: object
      properties:
        additionalAddressInfo:
          type: string
          description: |-
            Apartment or suite information
            1. Payroll Expert (Formerly addressLine2)
            1. Platform
          maxLength: 255
        postOfficeBox:
          type: string
          description: >-
            If the post office box is filled, the street and house number fields
            must be empty

            1. Platform - Personal information > Personal contact information
          maxLength: 20
        zipCode:
          type: string
          description: >-
            1. Payroll Expert (Formerly postalCode)

            1. Platform - Personal information > Personal contact information
            (Formerly postalCode)
          examples:
            - '52477'
          maxLength: 10
        city:
          type: string
          examples:
            - Alsdorf
          maxLength: 255
        stateCode:
          type: string
          format: ISO 3166-2
          description: >-
            1. Platform - Personal information > Personal contact information
            (Formerly regionCode)
          examples:
            - DE-NW
          maxLength: 6
          minLength: 4
        country:
          type: string
          format: ISO 3166-1 alpha-2
          description: >-
            1. Payroll Expert

            1. Platform - Personal information > Personal contact information
            (Formerly countryCode)
          examples:
            - DE
          maxLength: 2
          minLength: 2
      title: PostOfficeBox
    BankDetails:
      type: object
      properties:
        iban:
          type: string
          description: >-
            International Bank Account Number

            For more information, see:
            https://wikipedia.org/wiki/International_Bank_Account_Number
          examples:
            - DE07123412341234123412
          maxLength: 34
          minLength: 5
          pattern: ^[A-Z]{2}\d{2}[A-Z\d]{1,30}$
        bic:
          type: string
          description: |-
            Business Identifier Code / SWIFT Code
            For more information, see: https://de.wikipedia.org/wiki/ISO_9362
          examples:
            - DEUTDEFF
          maxLength: 11
          minLength: 8
          pattern: ^[A-Z\d]{4}[A-Z]{2}[A-Z\d]{2}(?:[A-Z\d]{3})?$
        payee:
          type: string
          description: The name of the payee, if different from the person
          examples:
            - Hein Janmaat
          maxLength: 70
    LegalEntity:
      type: object
      properties:
        id:
          type: string
          maxLength: 5
          minLength: 0
    Group:
      type: object
      properties:
        id:
          type: string
          description: |
            The group's identifier. Format depends on `type`:
            - `COMPANY`: UUID
            - `PAYROLL_COMPANY`: string
            - `TIME_COMPANY`: string
            - `ORGANISATIONAL_UNIT`: UUID
            - `COST_CENTER`: string ≤ 10 chars
            - `PAYROLL_GROUP`: int 1–6
            - `BUSINESS_AREA`: string ≤ 3 chars
        type:
          type: string
          description: >
            Type of the group.


            - `COMPANY`
               1. Platform - Business information > General (Formerly companyId)
            - `PAYROLL_COMPANY`
               1. Payroll Expert - LPFIRM (Formerly companyId)
            - `TIME_COMPANY`
                1. Time Expert (Formerly company)
            - `ORGANISATIONAL_UNIT` One of possible multiple organisational
            units the person belongs to.
                1. Platform - Business information > General (Formerly divisionIds)
            - `COST_CENTER` The master cost center assigned to the person.
                1. Payroll Expert - LPKOST (Formerly costCenter)
                1. Time Expert (Formerly costCenter)
            - `PAYROLL_GROUP` Payroll for employees in the same group is
            processed at the same time.
                1. Payroll Expert - LPABGR (Formerly abrechnungsgruppe)
            - `BUSINESS_AREA`
                1. Payroll Expert - LPSABE (Formerly sachbereich)
          enum:
            - COMPANY
            - PAYROLL_COMPANY
            - TIME_COMPANY
            - ORGANISATIONAL_UNIT
            - COST_CENTER
            - PAYROLL_GROUP
            - BUSINESS_AREA
    Employment:
      type: object
      properties:
        payrollContractId:
          type: string
          description: Identifier of the payroll contract that represents this employment
        personGroupCode:
          type: integer
          format: int32
          description: >
            Person group codes according to the German Data Collection and
            Transmission Ordinance (DEÜV), used in notifications to German
            social security entities.

            For allowed values, see:
            https://www.gkv-datenaustausch.de/arbeitgeber/deuev/deuev.jsp#:~:text=Schl%C3%BCsselzahlen%20f%C3%BCr%20Personengruppen
          enum:
            - '101'
            - '102'
            - '103'
            - '104'
            - '105'
            - '106'
            - '107'
            - '108'
            - '109'
            - '110'
            - '111'
            - '112'
            - '113'
            - '114'
            - '116'
            - '117'
            - '118'
            - '119'
            - '120'
            - '121'
            - '122'
            - '123'
            - '124'
            - '127'
            - '140'
            - '141'
            - '142'
            - '143'
            - '144'
            - '149'
            - '150'
            - '190'
          externalDocs:
            description: Schlüsselzahlen für Personengruppen in DEÜV-Meldungen
            url: >-
              https://www.gkv-datenaustausch.de/arbeitgeber/deuev/deuev.jsp#:~:text=Schl%C3%BCsselzahlen%20f%C3%BCr%20Personengruppen
        fullTime:
          type: boolean
          description: |
            Whether the employment is full-time or part-time.

            1. Payroll Expert - LPVTFO (formerly sv.vertragsform)
        permanent:
          type: boolean
          description: |
            Whether the employment is a permanent or fixed-term position.

            1. Payroll Expert - LPVTFO (formerly sv.vertragsform)
        start:
          type: string
          format: date
          description: |
            Start of the employment.

            1. Payroll Expert - LPETDT (Formerly entryDate)
          examples:
            - '1999-02-31'
        end:
          type: string
          format: date
          description: |
            End of the employment.

            1. Payroll Expert - LPADDT (Formerly terminationDate)
          examples:
            - '2020-02-31'
        fixedTermEndDate:
          type: string
          format: date
          description: >-
            Planned end of this fixed-term employment (permanent = `false`). May
            differ from the actual end of employment, e.g. in case of early
            termination.


            1. Payroll Expert - LPAVBD (Formerly fixedTermDate)
        workingHours:
          $ref: '#/components/schemas/WorkingHours'
        paymentTime:
          anyOf:
            - type: string
              enum:
                - FIFTEENTH
                - TWENTY_FIFTH
                - LAST_DAY_OF_MONTH
                - FIFTEENTH_OF_FOLLOWING_MONTH
            - type: string
    PersonCustomField:
      type: object
      properties:
        name:
          type: string
          description: Name of the custom field
        type:
          type: string
          description: Type of the custom field
          enum:
            - STRING
            - NUMBER
            - BOOLEAN
            - DATE
            - SELECT
            - MULTI_SELECT
        textValue:
          type: string
          description: >-
            Text value (for customFieldType=STRING). If customFieldType=SELECT
            or customFieldType=MULTI_SELECT it contains a textual representation
            of the selected item(s) additionally to their id(s) in 'selection'
        numberValue:
          type: number
          format: double
          description: Number value (for customFieldType=NUMBER)
        booleanValue:
          type: boolean
          description: Boolean value (for customFieldType=BOOLEAN)
        dateValue:
          type: string
          format: date
          description: Date value (for customFieldType=DATE)
        selection:
          type: array
          description: >-
            Ids of selected value(s) (for customFieldType=SELECT or
            customFieldType=MULTI_SELECT). Additionally 'textValue' contains a
            textual representation of the selected item(s)
          items:
            type: string
            format: uuid
    WorkingHours:
      type: object
      properties:
        daily:
          type: number
          format: double
          description: |
            1. Payroll Expert - LPTSTD
          examples:
            - 8
          maximum: 99.99
        weekly:
          type: number
          format: double
          description: |
            1. Payroll Expert - LPWSTD
          examples:
            - 40
          maximum: 99.99
        monthly:
          type: number
          format: double
          description: |
            1. Payroll Expert - LPMSTD
          maximum: 999.99

````