Skip to main content
GET
/
api
/
v1
/
persons
/
{id}
cURL
curl --request GET \
  --url https://api.example.com/api/v1/persons/{id}
import requests

url = "https://api.example.com/api/v1/persons/{id}"

response = requests.get(url)

print(response.text)
const options = {method: 'GET'};

fetch('https://api.example.com/api/v1/persons/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/persons/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
package main

import (
"fmt"
"net/http"
"io"
)

func main() {

url := "https://api.example.com/api/v1/persons/{id}"

req, _ := http.NewRequest("GET", url, nil)

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/persons/{id}")
.asString();
require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/persons/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "academicTitle": "<string>",
  "firstName": "<string>",
  "middleName": "<string>",
  "lastName": "<string>",
  "birthName": "<string>",
  "prefixToLastName": "<string>",
  "titleOfNobility": "<string>",
  "suffixToLastName": "<string>",
  "dateOfBirth": "2023-12-25",
  "citizenship": "<string>",
  "address": {
    "street": "<string>",
    "houseNumber": "<string>",
    "additionalAddressInfo": "<string>",
    "zipCode": "<string>",
    "city": "<string>",
    "stateCode": "<string>",
    "country": "<string>"
  },
  "bankDetails": {
    "iban": "<string>",
    "bic": "<string>",
    "payee": "<string>"
  },
  "businessEmail": "jsmith@example.com",
  "usualPlaceOfWork": "<string>",
  "groupEntryDate": "2023-12-25",
  "groupExitDate": "2023-12-25",
  "exitReasonId": "<string>",
  "exitNoticeDate": "2023-12-25",
  "expectedStartOfPension": "2023-12-25",
  "employeeNumber": "<string>",
  "jobTitle": "<string>",
  "legalEntity": {
    "id": "<string>"
  },
  "groups": [
    {
      "id": "<string>"
    }
  ],
  "managerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "keyNumber": "<string>",
  "employments": [
    {
      "payrollContractId": "<string>",
      "fullTime": true,
      "permanent": true,
      "start": "2023-12-25",
      "end": "2023-12-25",
      "fixedTermEndDate": "2023-12-25",
      "workingHours": {
        "daily": 98.99,
        "weekly": 98.99,
        "monthly": 123
      }
    }
  ],
  "customFields": [
    {
      "name": "<string>",
      "textValue": "<string>",
      "numberValue": 123,
      "booleanValue": true,
      "dateValue": "2023-12-25",
      "selection": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ]
    }
  ],
  "payrollContractIds": [
    "<string>"
  ]
}
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.

Path Parameters

id
string
required

Response

200 - application/json

OK

A person is a human being

id
string<uuid>

Unique identifier. Matches the ID of the person in the VEDA Horizon (Base) API

academicTitle
string
  1. Payroll Expert - LPTITL
  2. Platform - Personal information > General (Formerly title)
Maximum string length: 80
Example:

"Dr."

firstName
string
  1. Payroll Expert - LPVNAM
  2. Platform - Personal information > General
Maximum string length: 80
Example:

"Max"

middleName
string
  1. Payroll Expert includes the middle name in the firstName field. If present, this field is always empty.
  2. Platform - Personal information > General
Maximum string length: 80
Example:

"Moritz"

lastName
string
  1. Payroll Expert - LPNAME (Formerly name)
  2. Platform - Personal information > General
Maximum string length: 80
Example:

"Mustermann"

birthName
string
  1. Payroll Expert - LPGNAM
  2. Platform - Personal information > General
Maximum string length: 80
Example:

"Musterfamilie"

prefixToLastName
string
  1. Payroll Expert - LPVSWO (Formerly namePrefix)
  2. Platform - Personal information > General (Formerly namePrefix)
Maximum string length: 80
Example:

"zum"

titleOfNobility
string
  1. Payroll Expert - LPNMZU (Formerly nameAffix)
  2. Platform - Personal information > General (Formerly nameAffix)
Maximum string length: 80
Example:

"Baron"

suffixToLastName
string

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)
Maximum string length: 80
Example:

"junior"

gender
enum<string>

Gender according to birth certificate or passport

  1. Payroll Expert - LPGENU
  2. Platform - Personal information > General
Available options:
MALE,
FEMALE,
INTERSEX,
UNSPECIFIED
Example:

"FEMALE"

dateOfBirth
string<date>
  1. Payroll Expert - LPGBDT
  2. Platform - Personal information > General
Example:

"2023-06-14"

citizenship
string<ISO 3166-1 alpha-2>
  1. Payroll Expert - LPSTAA
  2. Platform - Personal information > General
Required string length: 2
Example:

"DE"

address
StreetAddress · object
  1. Payroll Expert
  2. Platform - Personal information > Personal contact information
bankDetails
object
  1. Platform - Personal information > Compensation-relevant information
businessEmail
string<email>

The standard business email address

  1. Platform - Business information > Business contact details
Maximum string length: 254
Pattern: |^.+@.+$
Example:

"Max.Mustermann@example.com"

usualPlaceOfWork
string

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)
Maximum string length: 33
status
enum<string>

Account status of the person.

  1. Platform - Administration > Basics > Users
Available options:
ACTIVE,
INACTIVE
groupEntryDate
string<date>

Start of first employment with the organisation

  1. Platform - Business information > General (Formerly enterpriseEntryDate)
Example:

"1999-02-31"

groupExitDate
string<date>

End or planned end of last employment with the organization

  1. Payroll Expert - LPADDT (Formerly terminationDate)
  2. Platform - Business information > General (Formerly leavingDate)
Example:

"2050-12-24"

exitReasonId
string

Identifier of the reason for exit

  1. Payroll Expert - LPATGR (Formerly terminationReasonId)
Maximum string length: 2
exitNoticeDate
string<date>

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
string<date>
  1. Platform - Business information > General
Example:

"2099-12-31"

employeeNumber
string
  1. Platform - Business information > General
Maximum string length: 20
Example:

"56"

jobTitle
string
  1. Platform - Business information > General (Formerly employmentTitleDisplayName)
Maximum string length: 400
Example:

"Integrations Team Lead"

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
object[]

Grouping (ha!) of a person. A person can be member of multiple groups of the same and different types.

managerId
string<uuid>

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
string

The person's ID number. Used for identification at time-recording or similar terminals.

  1. Time Expert
employments
object[]

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.
customFields
object[]

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.

payrollContractIds
string[]
deprecated

(⚠️ 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.