NAV
Curl Python

Simployer API documentation

Welcome to our API documentation!

Simployer API Doc

This page contains information about our REST endpoints and details regarding webhook endpoints. We are currently in a phase where we will replace our existing WCF’s with REST and will continuously publish new endpoints on this page.

Not a developer?

Please visit our webpage to learn more about our products.

Simployer Access and SSO

Looking for our SSO options? Please look here for product description.

Person API v1.0

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Base URLs:

Authentication

Person

getPersons

Code samples

## You can also use wget
curl -X GET https:///v1/person \
  -H 'Accept: application/json' \
  -H 'X-ApiKey: API_KEY'


import requests
headers = {
  'Accept': 'application/json',
  'X-ApiKey': 'API_KEY'
}

r = requests.get('https://apis.dev.simployer.com/v1/person', headers = headers)

print(r.json())

GET /v1/person

Example responses

200 Response

[
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "firstname": "string",
    "lastname": "string",
    "shortname": "string",
    "birthdate": "2019-08-24T14:15:22Z",
    "gender": {
      "label": "string",
      "id": "00000000-0000-0000-0000-000000000000"
    },
    "nationality": "string"
  }
]

<?xml version="1.0" encoding="UTF-8" ?>
<id>00000000-0000-0000-0000-000000000000</id>
<firstname>string</firstname>
<lastname>string</lastname>
<shortname>string</shortname>
<birthdate>2019-08-24T14:15:22Z</birthdate>
<gender>
  <label>string</label>
  <id>00000000-0000-0000-0000-000000000000</id>
</gender>
<nationality>string</nationality>

Responses

Status Meaning Description Schema
200 OK OK Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
anonymous [Person] false none none
» id string(uuid) false none none
» firstname string false none none
» lastname string false none none
» shortname string false none none
» birthdate string(date-time) false none none
» gender Gender false none none
»» label string false none none
»» id string(uuid) false none none
» nationality string false none none

getPersonById

Code samples

## You can also use wget
curl -X GET https:///v1/person/{id} \
  -H 'Accept: application/json' \
  -H 'X-ApiKey: API_KEY'


import requests
headers = {
  'Accept': 'application/json',
  'X-ApiKey': 'API_KEY'
}

r = requests.get('https://apis.dev.simployer.com/v1/person/{id}', headers = headers)

print(r.json())

GET /v1/person/{id}

Parameters

Name In Type Required Description
id path string(uuid) true none

Example responses

200 Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "firstname": "string",
  "lastname": "string",
  "shortname": "string",
  "birthdate": "2019-08-24T14:15:22Z",
  "gender": {
    "label": "string",
    "id": "00000000-0000-0000-0000-000000000000"
  },
  "nationality": "string"
}

<?xml version="1.0" encoding="UTF-8" ?>
<Person>
  <id>00000000-0000-0000-0000-000000000000</id>
  <firstname>string</firstname>
  <lastname>string</lastname>
  <shortname>string</shortname>
  <birthdate>2019-08-24T14:15:22Z</birthdate>
  <gender>
    <label>string</label>
    <id>00000000-0000-0000-0000-000000000000</id>
  </gender>
  <nationality>string</nationality>
</Person>

Responses

Status Meaning Description Schema
200 OK OK Person

PersonAddress

getPersonAddresses

Code samples

## You can also use wget
curl -X GET https:///v1/person/{personId}/address \
  -H 'Accept: application/json' \
  -H 'X-ApiKey: API_KEY'


import requests
headers = {
  'Accept': 'application/json',
  'X-ApiKey': 'API_KEY'
}

r = requests.get('https://apis.dev.simployer.com/v1/person/{personId}/address', headers = headers)

print(r.json())

GET /v1/person/{personId}/address

Parameters

Name In Type Required Description
personId path string(uuid) true none

Example responses

200 Response

[
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "label": "string",
    "isPrimary": true,
    "countryCode": "string",
    "streetName1": "string",
    "streetName2": "string",
    "streetName3": "string",
    "postalCode": "string",
    "postalPlace": "string"
  }
]

<?xml version="1.0" encoding="UTF-8" ?>
<id>00000000-0000-0000-0000-000000000000</id>
<label>string</label>
<isPrimary>true</isPrimary>
<countryCode>string</countryCode>
<streetName1>string</streetName1>
<streetName2>string</streetName2>
<streetName3>string</streetName3>
<postalCode>string</postalCode>
<postalPlace>string</postalPlace>

Responses

Status Meaning Description Schema
200 OK OK Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
anonymous [PersonAddress] false none none
» id string(uuid) false none none
» label string false none none
» isPrimary boolean false none none
» countryCode string false none none
» streetName1 string false none none
» streetName2 string false none none
» streetName3 string false none none
» postalCode string false none none
» postalPlace string false none none

getPersonAddressById

Code samples

## You can also use wget
curl -X GET https:///v1/person/{personId}/address/{addressId} \
  -H 'Accept: application/json' \
  -H 'X-ApiKey: API_KEY'


import requests
headers = {
  'Accept': 'application/json',
  'X-ApiKey': 'API_KEY'
}

r = requests.get('https://apis.dev.simployer.com/v1/person/{personId}/address/{addressId}', headers = headers)

print(r.json())

GET /v1/person/{personId}/address/{addressId}

Parameters

Name In Type Required Description
personId path string(uuid) true none
addressId path string(uuid) true none

Example responses

200 Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "label": "string",
  "isPrimary": true,
  "countryCode": "string",
  "streetName1": "string",
  "streetName2": "string",
  "streetName3": "string",
  "postalCode": "string",
  "postalPlace": "string"
}

<?xml version="1.0" encoding="UTF-8" ?>
<PersonAddress>
  <id>00000000-0000-0000-0000-000000000000</id>
  <label>string</label>
  <isPrimary>true</isPrimary>
  <countryCode>string</countryCode>
  <streetName1>string</streetName1>
  <streetName2>string</streetName2>
  <streetName3>string</streetName3>
  <postalCode>string</postalCode>
  <postalPlace>string</postalPlace>
</PersonAddress>

Responses

Status Meaning Description Schema
200 OK OK PersonAddress

PersonElectronicAddress

getPersonEmailAddresses

Code samples

## You can also use wget
curl -X GET https:///v1/person/{personId}/email \
  -H 'Accept: application/json' \
  -H 'X-ApiKey: API_KEY'


import requests
headers = {
  'Accept': 'application/json',
  'X-ApiKey': 'API_KEY'
}

r = requests.get('https://apis.dev.simployer.com/v1/person/{personId}/email', headers = headers)

print(r.json())

GET /v1/person/{personId}/email

Parameters

Name In Type Required Description
personId path string(uuid) true none

Example responses

200 Response

[
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "label": "string",
    "isPrimary": true,
    "address": "string"
  }
]

<?xml version="1.0" encoding="UTF-8" ?>
<id>00000000-0000-0000-0000-000000000000</id>
<label>string</label>
<isPrimary>true</isPrimary>
<address>string</address>

Responses

Status Meaning Description Schema
200 OK OK Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
anonymous [PersonElectronicAddress] false none none
» id string(uuid) false none none
» label string false none none
» isPrimary boolean false none none
» address string false none none

getPersonEmailAddressById

Code samples

## You can also use wget
curl -X GET https:///v1/person/{personId}/email/{emailId} \
  -H 'Accept: application/json' \
  -H 'X-ApiKey: API_KEY'


import requests
headers = {
  'Accept': 'application/json',
  'X-ApiKey': 'API_KEY'
}

r = requests.get('https://apis.dev.simployer.com/v1/person/{personId}/email/{emailId}', headers = headers)

print(r.json())

GET /v1/person/{personId}/email/{emailId}

Parameters

Name In Type Required Description
personId path string(uuid) true none
emailId path string(uuid) true none

Example responses

200 Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "label": "string",
  "isPrimary": true,
  "address": "string"
}

<?xml version="1.0" encoding="UTF-8" ?>
<PersonElectronicAddress>
  <id>00000000-0000-0000-0000-000000000000</id>
  <label>string</label>
  <isPrimary>true</isPrimary>
  <address>string</address>
</PersonElectronicAddress>

Responses

Status Meaning Description Schema
200 OK OK PersonElectronicAddress

PersonPhone

getPersonPhones

Code samples

## You can also use wget
curl -X GET https:///v1/person/{personId}/phone \
  -H 'Accept: application/json' \
  -H 'X-ApiKey: API_KEY'


import requests
headers = {
  'Accept': 'application/json',
  'X-ApiKey': 'API_KEY'
}

r = requests.get('https://apis.dev.simployer.com/v1/person/{personId}/phone', headers = headers)

print(r.json())

GET /v1/person/{personId}/phone

Parameters

Name In Type Required Description
personId path string(uuid) true none

Example responses

200 Response

[
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "label": "string",
    "isPrimary": true,
    "number": "string"
  }
]

<?xml version="1.0" encoding="UTF-8" ?>
<id>00000000-0000-0000-0000-000000000000</id>
<label>string</label>
<isPrimary>true</isPrimary>
<number>string</number>

Responses

Status Meaning Description Schema
200 OK OK Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
anonymous [PersonPhone] false none none
» id string(uuid) false none none
» label string false none none
» isPrimary boolean false none none
» number string false none none

getPersonPhoneById

Code samples

## You can also use wget
curl -X GET https:///v1/person/{personId}/phone/{phoneId} \
  -H 'Accept: application/json' \
  -H 'X-ApiKey: API_KEY'


import requests
headers = {
  'Accept': 'application/json',
  'X-ApiKey': 'API_KEY'
}

r = requests.get('https://apis.dev.simployer.com/v1/person/{personId}/phone/{phoneId}', headers = headers)

print(r.json())

GET /v1/person/{personId}/phone/{phoneId}

Parameters

Name In Type Required Description
personId path string(uuid) true none
phoneId path string(uuid) true none

Example responses

200 Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "label": "string",
  "isPrimary": true,
  "number": "string"
}

<?xml version="1.0" encoding="UTF-8" ?>
<PersonPhone>
  <id>00000000-0000-0000-0000-000000000000</id>
  <label>string</label>
  <isPrimary>true</isPrimary>
  <number>string</number>
</PersonPhone>

Responses

Status Meaning Description Schema
200 OK OK PersonPhone

Schemas

Person

{
  "id": "00000000-0000-0000-0000-000000000000",
  "firstname": "string",
  "lastname": "string",
  "shortname": "string",
  "birthdate": "2019-08-24T14:15:22Z",
  "gender": {
    "label": "string",
    "id": "00000000-0000-0000-0000-000000000000"
  },
  "nationality": "string"
}

Properties

Name Type Required Restrictions Description
id string(uuid) false none none
firstname string false none none
lastname string false none none
shortname string false none none
birthdate string(date-time) false none none
gender Gender false none none
nationality string false none none

Gender

{
  "label": "string",
  "id": "00000000-0000-0000-0000-000000000000"
}

Properties

Name Type Required Restrictions Description
label string false none none
id string(uuid) false none none

PersonAddress

{
  "id": "00000000-0000-0000-0000-000000000000",
  "label": "string",
  "isPrimary": true,
  "countryCode": "string",
  "streetName1": "string",
  "streetName2": "string",
  "streetName3": "string",
  "postalCode": "string",
  "postalPlace": "string"
}

Properties

Name Type Required Restrictions Description
id string(uuid) false none none
label string false none none
isPrimary boolean false none none
countryCode string false none none
streetName1 string false none none
streetName2 string false none none
streetName3 string false none none
postalCode string false none none
postalPlace string false none none

PersonElectronicAddress

{
  "id": "00000000-0000-0000-0000-000000000000",
  "label": "string",
  "isPrimary": true,
  "address": "string"
}

Properties

Name Type Required Restrictions Description
id string(uuid) false none none
label string false none none
isPrimary boolean false none none
address string false none none

PersonPhone

{
  "id": "00000000-0000-0000-0000-000000000000",
  "label": "string",
  "isPrimary": true,
  "number": "string"
}

Properties

Name Type Required Restrictions Description
id string(uuid) false none none
label string false none none
isPrimary boolean false none none
number string false none none

Unit API v1.0

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Base URLs:

Authentication

LegalUnit

getLegalUnits

Code samples

## You can also use wget
curl -X GET https:///v1/legalunit \
  -H 'Accept: application/json' \
  -H 'X-ApiKey: API_KEY'


import requests
headers = {
  'Accept': 'application/json',
  'X-ApiKey': 'API_KEY'
}

r = requests.get('https://apis.dev.simployer.com/v1/legalunit', headers = headers)

print(r.json())

GET /v1/legalunit

Example responses

200 Response

[
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "organizationNumber": "string",
    "name": "string"
  }
]

<?xml version="1.0" encoding="UTF-8" ?>
<id>00000000-0000-0000-0000-000000000000</id>
<organizationNumber>string</organizationNumber>
<name>string</name>

Responses

Status Meaning Description Schema
200 OK OK Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
anonymous [LegalUnit] false none none
» id string(uuid) false none none
» organizationNumber string false none none
» name string false none none

getLegalUnitById

Code samples

## You can also use wget
curl -X GET https:///v1/legalunit/{id} \
  -H 'Accept: application/json' \
  -H 'X-ApiKey: API_KEY'


import requests
headers = {
  'Accept': 'application/json',
  'X-ApiKey': 'API_KEY'
}

r = requests.get('https://apis.dev.simployer.com/v1/legalunit/{id}', headers = headers)

print(r.json())

GET /v1/legalunit/{id}

Parameters

Name In Type Required Description
id path string(uuid) true none

Example responses

200 Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "organizationNumber": "string",
  "name": "string"
}

<?xml version="1.0" encoding="UTF-8" ?>
<LegalUnit>
  <id>00000000-0000-0000-0000-000000000000</id>
  <organizationNumber>string</organizationNumber>
  <name>string</name>
</LegalUnit>

Responses

Status Meaning Description Schema
200 OK OK LegalUnit

Unit

getUnits

Code samples

## You can also use wget
curl -X GET https:///v1/unit \
  -H 'Accept: application/json' \
  -H 'X-ApiKey: API_KEY'


import requests
headers = {
  'Accept': 'application/json',
  'X-ApiKey': 'API_KEY'
}

r = requests.get('https://apis.dev.simployer.com/v1/unit', headers = headers)

print(r.json())

GET /v1/unit

Example responses

200 Response

[
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "label": "string",
    "name": "string"
  }
]

<?xml version="1.0" encoding="UTF-8" ?>
<id>00000000-0000-0000-0000-000000000000</id>
<label>string</label>
<name>string</name>

Responses

Status Meaning Description Schema
200 OK OK Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
anonymous [Unit] false none none
» id string(uuid) false none none
» label string false none none
» name string false none none

getUnitById

Code samples

## You can also use wget
curl -X GET https:///v1/unit/{id} \
  -H 'Accept: application/json' \
  -H 'X-ApiKey: API_KEY'


import requests
headers = {
  'Accept': 'application/json',
  'X-ApiKey': 'API_KEY'
}

r = requests.get('https://apis.dev.simployer.com/v1/unit/{id}', headers = headers)

print(r.json())

GET /v1/unit/{id}

Parameters

Name In Type Required Description
id path string(uuid) true none

Example responses

200 Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "label": "string",
  "name": "string"
}

<?xml version="1.0" encoding="UTF-8" ?>
<Unit>
  <id>00000000-0000-0000-0000-000000000000</id>
  <label>string</label>
  <name>string</name>
</Unit>

Responses

Status Meaning Description Schema
200 OK OK Unit

UnitAddress

getUnitAddresses

Code samples

## You can also use wget
curl -X GET https:///v1/unit/{unitId}/address \
  -H 'Accept: application/json' \
  -H 'X-ApiKey: API_KEY'


import requests
headers = {
  'Accept': 'application/json',
  'X-ApiKey': 'API_KEY'
}

r = requests.get('https://apis.dev.simployer.com/v1/unit/{unitId}/address', headers = headers)

print(r.json())

GET /v1/unit/{unitId}/address

Parameters

Name In Type Required Description
unitId path string(uuid) true none

Example responses

200 Response

[
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "isPrimary": true,
    "label": "string",
    "countryCode": "string",
    "streetName1": "string",
    "streetName2": "string",
    "streetName3": "string",
    "postalCode": "string",
    "postalPlace": "string"
  }
]

<?xml version="1.0" encoding="UTF-8" ?>
<id>00000000-0000-0000-0000-000000000000</id>
<isPrimary>true</isPrimary>
<label>string</label>
<countryCode>string</countryCode>
<streetName1>string</streetName1>
<streetName2>string</streetName2>
<streetName3>string</streetName3>
<postalCode>string</postalCode>
<postalPlace>string</postalPlace>

Responses

Status Meaning Description Schema
200 OK OK Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
anonymous [UnitAddress] false none none
» id string(uuid) false none none
» isPrimary boolean false none none
» label string false none none
» countryCode string false none none
» streetName1 string false none none
» streetName2 string false none none
» streetName3 string false none none
» postalCode string false none none
» postalPlace string false none none

getUnitAddressById

Code samples

## You can also use wget
curl -X GET https:///v1/unit/{unitId}/address/{addressId} \
  -H 'Accept: application/json' \
  -H 'X-ApiKey: API_KEY'


import requests
headers = {
  'Accept': 'application/json',
  'X-ApiKey': 'API_KEY'
}

r = requests.get('https://apis.dev.simployer.com/v1/unit/{unitId}/address/{addressId}', headers = headers)

print(r.json())

GET /v1/unit/{unitId}/address/{addressId}

Parameters

Name In Type Required Description
unitId path string(uuid) true none
addressId path string(uuid) true none

Example responses

200 Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "isPrimary": true,
  "label": "string",
  "countryCode": "string",
  "streetName1": "string",
  "streetName2": "string",
  "streetName3": "string",
  "postalCode": "string",
  "postalPlace": "string"
}

<?xml version="1.0" encoding="UTF-8" ?>
<UnitAddress>
  <id>00000000-0000-0000-0000-000000000000</id>
  <isPrimary>true</isPrimary>
  <label>string</label>
  <countryCode>string</countryCode>
  <streetName1>string</streetName1>
  <streetName2>string</streetName2>
  <streetName3>string</streetName3>
  <postalCode>string</postalCode>
  <postalPlace>string</postalPlace>
</UnitAddress>

Responses

Status Meaning Description Schema
200 OK OK UnitAddress

UnitElectronicAddress

getUnitEmailAddresses

Code samples

## You can also use wget
curl -X GET https:///v1/unit/{unitId}/email \
  -H 'Accept: application/json' \
  -H 'X-ApiKey: API_KEY'


import requests
headers = {
  'Accept': 'application/json',
  'X-ApiKey': 'API_KEY'
}

r = requests.get('https://apis.dev.simployer.com/v1/unit/{unitId}/email', headers = headers)

print(r.json())

GET /v1/unit/{unitId}/email

Parameters

Name In Type Required Description
unitId path string(uuid) true none

Example responses

200 Response

[
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "label": "string",
    "isPrimary": true,
    "address": "string"
  }
]

<?xml version="1.0" encoding="UTF-8" ?>
<id>00000000-0000-0000-0000-000000000000</id>
<label>string</label>
<isPrimary>true</isPrimary>
<address>string</address>

Responses

Status Meaning Description Schema
200 OK OK Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
anonymous [UnitElectronicAddress] false none none
» id string(uuid) false none none
» label string false none none
» isPrimary boolean false none none
» address string false none none

getUnitEmailAddressById

Code samples

## You can also use wget
curl -X GET https:///v1/unit/{unitId}/email/{emailId} \
  -H 'Accept: application/json' \
  -H 'X-ApiKey: API_KEY'


import requests
headers = {
  'Accept': 'application/json',
  'X-ApiKey': 'API_KEY'
}

r = requests.get('https://apis.dev.simployer.com/v1/unit/{unitId}/email/{emailId}', headers = headers)

print(r.json())

GET /v1/unit/{unitId}/email/{emailId}

Parameters

Name In Type Required Description
unitId path string(uuid) true none
emailId path string(uuid) true none

Example responses

200 Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "label": "string",
  "isPrimary": true,
  "address": "string"
}

<?xml version="1.0" encoding="UTF-8" ?>
<UnitElectronicAddress>
  <id>00000000-0000-0000-0000-000000000000</id>
  <label>string</label>
  <isPrimary>true</isPrimary>
  <address>string</address>
</UnitElectronicAddress>

Responses

Status Meaning Description Schema
200 OK OK UnitElectronicAddress

UnitPhone

getUnitPhones

Code samples

## You can also use wget
curl -X GET https:///v1/unit/{unitId}/phone \
  -H 'Accept: application/json' \
  -H 'X-ApiKey: API_KEY'


import requests
headers = {
  'Accept': 'application/json',
  'X-ApiKey': 'API_KEY'
}

r = requests.get('https://apis.dev.simployer.com/v1/unit/{unitId}/phone', headers = headers)

print(r.json())

GET /v1/unit/{unitId}/phone

Parameters

Name In Type Required Description
unitId path string(uuid) true none

Example responses

200 Response

[
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "isPrimary": true,
    "label": "string",
    "number": "string"
  }
]

<?xml version="1.0" encoding="UTF-8" ?>
<id>00000000-0000-0000-0000-000000000000</id>
<isPrimary>true</isPrimary>
<label>string</label>
<number>string</number>

Responses

Status Meaning Description Schema
200 OK OK Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
anonymous [UnitPhone] false none none
» id string(uuid) false none none
» isPrimary boolean false none none
» label string false none none
» number string false none none

getUnitPhoneById

Code samples

## You can also use wget
curl -X GET https:///v1/unit/{unitId}/phone/{phoneId} \
  -H 'Accept: application/json' \
  -H 'X-ApiKey: API_KEY'


import requests
headers = {
  'Accept': 'application/json',
  'X-ApiKey': 'API_KEY'
}

r = requests.get('https://apis.dev.simployer.com/v1/unit/{unitId}/phone/{phoneId}', headers = headers)

print(r.json())

GET /v1/unit/{unitId}/phone/{phoneId}

Parameters

Name In Type Required Description
unitId path string(uuid) true none
phoneId path string(uuid) true none

Example responses

200 Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "isPrimary": true,
  "label": "string",
  "number": "string"
}

<?xml version="1.0" encoding="UTF-8" ?>
<UnitPhone>
  <id>00000000-0000-0000-0000-000000000000</id>
  <isPrimary>true</isPrimary>
  <label>string</label>
  <number>string</number>
</UnitPhone>

Responses

Status Meaning Description Schema
200 OK OK UnitPhone

Schemas

LegalUnit

{
  "id": "00000000-0000-0000-0000-000000000000",
  "organizationNumber": "string",
  "name": "string"
}

Properties

Name Type Required Restrictions Description
id string(uuid) false none none
organizationNumber string false none none
name string false none none

Unit

{
  "id": "00000000-0000-0000-0000-000000000000",
  "label": "string",
  "name": "string"
}

Properties

Name Type Required Restrictions Description
id string(uuid) false none none
label string false none none
name string false none none

UnitAddress

{
  "id": "00000000-0000-0000-0000-000000000000",
  "isPrimary": true,
  "label": "string",
  "countryCode": "string",
  "streetName1": "string",
  "streetName2": "string",
  "streetName3": "string",
  "postalCode": "string",
  "postalPlace": "string"
}

Properties

Name Type Required Restrictions Description
id string(uuid) false none none
isPrimary boolean false none none
label string false none none
countryCode string false none none
streetName1 string false none none
streetName2 string false none none
streetName3 string false none none
postalCode string false none none
postalPlace string false none none

UnitElectronicAddress

{
  "id": "00000000-0000-0000-0000-000000000000",
  "label": "string",
  "isPrimary": true,
  "address": "string"
}

Properties

Name Type Required Restrictions Description
id string(uuid) false none none
label string false none none
isPrimary boolean false none none
address string false none none

UnitPhone

{
  "id": "00000000-0000-0000-0000-000000000000",
  "isPrimary": true,
  "label": "string",
  "number": "string"
}

Properties

Name Type Required Restrictions Description
id string(uuid) false none none
isPrimary boolean false none none
label string false none none
number string false none none

Getting started with Analytics API

What is Analytics API

Analytics API is a REST API that enable our customers to read and then analyze their Simployer HRM data. Analytics API implements OData open standard. It can be accessed using various third party tools e.g. Excel, Power BI, as well as consumed by customer’s internal systems.

How to use Analytics API

URL

OData endpoint:

Documentation/test site (for more information see Swagger UI section later in this document):

Usage in Self-Service BI Tools

For specific SSBI tool, user should check if it supports OData Feed. Alternatively you can try to treat API as typical REST endpoints, but note, that API has a paging mechanism and a limit of results per query (see FAQ section for more details).

Authentication methods

Analytics API supports multiple authentication methods to support various integration tools. Users can choose to use:

Excel, Power BI

Below you can find examples of two approaches to authenticate and connect to Analytics API using Excel. For Power BI it is similar as both of these solutions use Power Query.

Basic authentication

Go to Data > Get Data > From Other Sources > From OData Feed (Power BI: Home > Get Data > OData feed)

Analytics API docs

In the pop up, provide Analytics API endpoint URL and press OK: https://analytics-api.simployer.com/v1/person

User will be prompted for credentials. Switch to "Basic" tab and provide API key in the "Password" box, leaving "User name" empty:

Analytics API docs

Click "Connect" and the data should be fetched from the Analytics API.

Web API

Go to Data > Get Data > From Other Sources > Blank Query (Power BI: Home > Get Data > Blank Query)

Analytics API docs

In the formula bar, provide OData Feed function with proper Analytics API URL and press Enter:

= OData.Feed("https://analytics-api.simployer.com/v1/person", null, [ApiKeyName="api-key"])

User will be prompted for credentials.

Analytics API docs

Click "Edit Credentials", switch to "Web API" tab and provide API key in the "Key" box.

Analytics API docs

Click "Connect" and the data should be fetched from the Analytics API.

OData Standard

Analytics API is a REST API based on open data protocol OData V4. This protocol allows users to use number of features:

All of these features are described in OData documentation available here: https://www.odata.org/getting-started/basic-tutorial/. Below we will describe most common use cases for the solution.

Swagger UI

There is Swagger UI integrated in the solution which allows user to test the endpoints before connecting using any Self-Service BI solution.

Overall look at Swagger UI

All available endpoints are listed in Swagger UI, including corresponding schemas. Below there is an example with limited number of entities:

Analytics API docs

When expanding any of schemas, user will see detailed description of each property inside. If there are any references to other entities, user will also see them as expandable properties - see absences, immediateSupervisor, affiliationUnit, employees and directReports below. User can make use of these properties using $expand OData feature to include referenced entities to the result set.

Analytics API docs

Using Swagger UI

To use Swagger UI to make calls to the endpoints, user has to be authorized. To do so, he should use Authorize button just above endpoints declaration. User will be prompted to provide API key which is unique for each of our customer.

Once authorized, user can test Analytics API endpoints using Try it out button (available when expanding each endpoint). Sample usage below:

Analytics API docs

According to the setup above, we want to fetch one Person (sk = 1) including his Affiliation Unit details. For both these entities we want to limit the properties returned to only few columns listed (this can be nested for $expand feature as shown above). Sample response from Analytics API below:

Analytics API docs

FAQ

I get {"error":"Missing API key"} error when trying to connect to OData endpoint.

Please follow instructions specific to tool you’re using:

Where can I find data model’s documentation?

Data model’s documentation is available in Swagger UI ("Schemas" paragraph, just below endpoints list).

How to use filter in the query?

To use filter feature, you have to use "$filter" keyword in your query. You can refer to the OData basic tutorial here, e.g. if you want to select only Person with first name "Anna", you can use this filter: v1/Person?$filter=firstName eq 'Anna'.

There are also other filter logical operators available, you can refer to OData URL Conventions document here to get a list of them.

To use this feature, you have to use "$expand" keyword in your query. You can refer to the OData basic tutorial here. See Using Swagger UI section above, this approach can be used in any other tool capable to utilize OData endpoints. When you fetch data for entity that has some relationship set (e.g. Person as shown in one of previous paragraphs), you may also get extra columns in Excel (affiliationUnit in this example):

= OData.Feed("https://analytics-api.simployer.com/v1/person?$filter=sk eq 1", null, [ApiKeyName="api-key"])

Analytics API docs

but if you try to expand them by clicking, you will see that they’re not populated:

Analytics API docs

To fix it, you can include $expand keyword and state which entity you want to be expanded:

= OData.Feed("https://analytics-api.simployer.com/v1/person?$filter=sk eq 1&$expand=affiliationUnit", null, [ApiKeyName="api-key"])

Analytics API docs

My dataset is large, and it seems that I don’t get all the data from the endpoint. Why?

Our API use OData paging mechanism. It means that you can get limited number of records per one query. This limit is currently set to 100 000 rows. In general OData connectors (e.g. connector in Power BI) should handle it by their own. If you are utilizing API manually you have two options to handle it:

Solution for my issues is not listed here. How can I get an additional help?

You can reach out to the support team at analytics-support@simployer.com.

Analytics API v1.0

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Analytics API is a REST API that enable our customers to read and then analyze their Simployer HRM data. Analytics API implements OData open standard. It can be accessed using various third party tools e.g. Excel, Power BI, as well as consumed by customer’s internal systems.

Authentication

Absence

getAbsence

Code samples

## You can also use wget
curl -X GET /v1/absence \
  -H 'Accept: application/json' \
  -H 'X-ApiKey: API_KEY'


import requests
headers = {
  'Accept': 'application/json',
  'X-ApiKey': 'API_KEY'
}

r = requests.get('/v1/absence', headers = headers)

print(r.json())

GET /v1/absence

Returns Absence entities

Parameters

Name In Type Required Description
$select query string false Limits the properties returned in the result.
$expand query string false Indicates the related entities to be represented inline. The maximum depth is 2.
$filter query string false Restricts the set of items returned. The maximum number of expressions is 100. The allowed functions are: allfunctions.
$orderby query string false Specifies the order in which items are returned. The maximum number of expressions is 5.
$top query integer(int32) false Limits the number of items returned from a collection.
$skip query integer(int32) false Excludes the specified number of items of the queried collection from the result.
$count query boolean false Indicates whether the total count of items within a collection are returned in the result.

Example responses

200 Response

{
  "value": [
    {
      "sk": 0,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "personSk": 0,
      "startDate": "2019-08-24T14:15:22Z",
      "endDate": "2019-08-24T14:15:22Z",
      "percentageAssignment": 0,
      "status": "string",
      "absenceCategory": "string",
      "absenceType": "string",
      "isFteReduction": "string",
      "isAbsent": "string",
      "employmentAbsences": [],
      "person": {}
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK Success AbsenceIEnumerableODataValue

Employee

getEmployee

Code samples

## You can also use wget
curl -X GET /v1/employee \
  -H 'Accept: application/json' \
  -H 'X-ApiKey: API_KEY'


import requests
headers = {
  'Accept': 'application/json',
  'X-ApiKey': 'API_KEY'
}

r = requests.get('/v1/employee', headers = headers)

print(r.json())

GET /v1/employee

Returns Employee entities

Parameters

Name In Type Required Description
$select query string false Limits the properties returned in the result.
$expand query string false Indicates the related entities to be represented inline. The maximum depth is 2.
$filter query string false Restricts the set of items returned. The maximum number of expressions is 100. The allowed functions are: allfunctions.
$orderby query string false Specifies the order in which items are returned. The maximum number of expressions is 5.
$top query integer(int32) false Limits the number of items returned from a collection.
$skip query integer(int32) false Excludes the specified number of items of the queried collection from the result.
$count query boolean false Indicates whether the total count of items within a collection are returned in the result.

Example responses

200 Response

{
  "value": [
    {
      "sk": 0,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "unitSk": 0,
      "personSk": 0,
      "person": {},
      "number": "string",
      "unit": {},
      "employments": []
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK Success EmployeeIEnumerableODataValue

Employment

getEmployment

Code samples

## You can also use wget
curl -X GET /v1/employment \
  -H 'Accept: application/json' \
  -H 'X-ApiKey: API_KEY'


import requests
headers = {
  'Accept': 'application/json',
  'X-ApiKey': 'API_KEY'
}

r = requests.get('/v1/employment', headers = headers)

print(r.json())

GET /v1/employment

Returns Employment entities

Parameters

Name In Type Required Description
$select query string false Limits the properties returned in the result.
$expand query string false Indicates the related entities to be represented inline. The maximum depth is 2.
$filter query string false Restricts the set of items returned. The maximum number of expressions is 100. The allowed functions are: allfunctions.
$orderby query string false Specifies the order in which items are returned. The maximum number of expressions is 5.
$top query integer(int32) false Limits the number of items returned from a collection.
$skip query integer(int32) false Excludes the specified number of items of the queried collection from the result.
$count query boolean false Indicates whether the total count of items within a collection are returned in the result.

Example responses

200 Response

{
  "value": [
    {
      "sk": 0,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "unitSk": 0,
      "unit": {},
      "employeeSk": 0,
      "categoryName": "string",
      "includeInFte": "string",
      "positionName": "string",
      "startDate": "2019-08-24T14:15:22Z",
      "endDate": "2019-08-24T14:15:22Z",
      "percentageAssignment": 0,
      "hoursPerWeekAssignment": 0,
      "continuity": "string",
      "isActive": "string",
      "employee": {},
      "employmentAbsences": []
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK Success EmploymentIEnumerableODataValue

EmploymentAbsence

getEmploymentAbsence

Code samples

## You can also use wget
curl -X GET /v1/employmentAbsence \
  -H 'Accept: application/json' \
  -H 'X-ApiKey: API_KEY'


import requests
headers = {
  'Accept': 'application/json',
  'X-ApiKey': 'API_KEY'
}

r = requests.get('/v1/employmentAbsence', headers = headers)

print(r.json())

GET /v1/employmentAbsence

Returns EmploymentAbsence entities

Parameters

Name In Type Required Description
$select query string false Limits the properties returned in the result.
$expand query string false Indicates the related entities to be represented inline. The maximum depth is 2.
$filter query string false Restricts the set of items returned. The maximum number of expressions is 100. The allowed functions are: allfunctions.
$orderby query string false Specifies the order in which items are returned. The maximum number of expressions is 5.
$top query integer(int32) false Limits the number of items returned from a collection.
$skip query integer(int32) false Excludes the specified number of items of the queried collection from the result.
$count query boolean false Indicates whether the total count of items within a collection are returned in the result.

Example responses

200 Response

{
  "value": [
    {
      "sk": 0,
      "absenceSk": 0,
      "employmentSk": 0,
      "startDate": "2019-08-24T14:15:22Z",
      "endDate": "2019-08-24T14:15:22Z",
      "percentageAssignment": 0,
      "absence": {},
      "employment": {}
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK Success EmploymentAbsenceIEnumerableODataValue

FteByMonth

getFteByMonth

Code samples

## You can also use wget
curl -X GET /v1/fteByMonth \
  -H 'Accept: application/json' \
  -H 'X-ApiKey: API_KEY'


import requests
headers = {
  'Accept': 'application/json',
  'X-ApiKey': 'API_KEY'
}

r = requests.get('/v1/fteByMonth', headers = headers)

print(r.json())

GET /v1/fteByMonth

Returns monthly FTE and Actual FTE statistics

Parameters

Name In Type Required Description
$select query string false Limits the properties returned in the result.
$expand query string false Indicates the related entities to be represented inline. The maximum depth is 2.
$filter query string false Restricts the set of items returned. The maximum number of expressions is 100. The allowed functions are: allfunctions.
$orderby query string false Specifies the order in which items are returned. The maximum number of expressions is 5.
$top query integer(int32) false Limits the number of items returned from a collection.
$skip query integer(int32) false Excludes the specified number of items of the queried collection from the result.
$count query boolean false Indicates whether the total count of items within a collection are returned in the result.

Example responses

200 Response

{
  "value": [
    {
      "employmentSk": 0,
      "employment": {},
      "unitSk": 0,
      "employeeSk": 0,
      "startOfMonth": "2019-08-24T14:15:22Z",
      "fte": 0,
      "actualFte": 0,
      "unit": {},
      "employee": {}
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK Success FteByMonthIEnumerableODataValue

LoadStatus

getLoadStatus

Code samples

## You can also use wget
curl -X GET /v1/loadStatus \
  -H 'Accept: application/json' \
  -H 'X-ApiKey: API_KEY'


import requests
headers = {
  'Accept': 'application/json',
  'X-ApiKey': 'API_KEY'
}

r = requests.get('/v1/loadStatus', headers = headers)

print(r.json())

GET /v1/loadStatus

Returns status of latest data load. It returns only one entry with Id = 1.

Parameters

Name In Type Required Description
$select query string false Limits the properties returned in the result.
$expand query string false Indicates the related entities to be represented inline. The maximum depth is 2.
$filter query string false Restricts the set of items returned. The maximum number of expressions is 100. The allowed functions are: allfunctions.
$orderby query string false Specifies the order in which items are returned. The maximum number of expressions is 5.
$top query integer(int32) false Limits the number of items returned from a collection.
$skip query integer(int32) false Excludes the specified number of items of the queried collection from the result.
$count query boolean false Indicates whether the total count of items within a collection are returned in the result.

Example responses

200 Response

{
  "value": [
    {
      "id": 0,
      "status": "string",
      "updateTimeUtc": "2019-08-24T14:15:22Z"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK Success LoadStatusIEnumerableODataValue

Person

getPerson

Code samples

## You can also use wget
curl -X GET /v1/person \
  -H 'Accept: application/json' \
  -H 'X-ApiKey: API_KEY'


import requests
headers = {
  'Accept': 'application/json',
  'X-ApiKey': 'API_KEY'
}

r = requests.get('/v1/person', headers = headers)

print(r.json())

GET /v1/person

Returns Person entities

Parameters

Name In Type Required Description
$select query string false Limits the properties returned in the result.
$expand query string false Indicates the related entities to be represented inline. The maximum depth is 2.
$filter query string false Restricts the set of items returned. The maximum number of expressions is 100. The allowed functions are: allfunctions.
$orderby query string false Specifies the order in which items are returned. The maximum number of expressions is 5.
$top query integer(int32) false Limits the number of items returned from a collection.
$skip query integer(int32) false Excludes the specified number of items of the queried collection from the result.
$count query boolean false Indicates whether the total count of items within a collection are returned in the result.

Example responses

200 Response

{
  "value": [
    {
      "sk": 0,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "firstName": "string",
      "lastName": "string",
      "fullName": "string",
      "shortName": "string",
      "birthDate": "2019-08-24T14:15:22Z",
      "age": "string",
      "gender": "string",
      "nationality": "string",
      "civilStatus": "string",
      "isActive": "string",
      "seniorityMonths": 0,
      "immediateSupervisorSk": 0,
      "affiliationUnitSk": 0,
      "additionalInfo": "string",
      "primaryBankAccountCountry": "string",
      "primaryBankAccount": "string",
      "secondaryBankAccountCountry": "string",
      "secondaryBankAccount": "string",
      "absences": [],
      "addresses": [],
      "electronicAddresses": [],
      "phoneNumbers": [],
      "nextOfKin": [],
      "children": [],
      "immediateSupervisor": {},
      "affiliationUnit": {},
      "employees": [],
      "directReports": []
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK Success PersonIEnumerableODataValue

PersonAddress

getPersonAddress

Code samples

## You can also use wget
curl -X GET /v1/personAddress \
  -H 'Accept: application/json' \
  -H 'X-ApiKey: API_KEY'


import requests
headers = {
  'Accept': 'application/json',
  'X-ApiKey': 'API_KEY'
}

r = requests.get('/v1/personAddress', headers = headers)

print(r.json())

GET /v1/personAddress

Returns PersonAddress entities

Parameters

Name In Type Required Description
$select query string false Limits the properties returned in the result.
$expand query string false Indicates the related entities to be represented inline. The maximum depth is 2.
$filter query string false Restricts the set of items returned. The maximum number of expressions is 100. The allowed functions are: allfunctions.
$orderby query string false Specifies the order in which items are returned. The maximum number of expressions is 5.
$top query integer(int32) false Limits the number of items returned from a collection.
$skip query integer(int32) false Excludes the specified number of items of the queried collection from the result.
$count query boolean false Indicates whether the total count of items within a collection are returned in the result.

Example responses

200 Response

{
  "value": [
    {
      "sk": 0,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "personSk": 0,
      "addressKind": "string",
      "address": "string",
      "postalCode": "string",
      "postalPlace": "string",
      "country": "string",
      "person": {}
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK Success PersonAddressIEnumerableODataValue

PersonChild

getPersonChild

Code samples

## You can also use wget
curl -X GET /v1/personChild \
  -H 'Accept: application/json' \
  -H 'X-ApiKey: API_KEY'


import requests
headers = {
  'Accept': 'application/json',
  'X-ApiKey': 'API_KEY'
}

r = requests.get('/v1/personChild', headers = headers)

print(r.json())

GET /v1/personChild

Returns PersonChild entities

Parameters

Name In Type Required Description
$select query string false Limits the properties returned in the result.
$expand query string false Indicates the related entities to be represented inline. The maximum depth is 2.
$filter query string false Restricts the set of items returned. The maximum number of expressions is 100. The allowed functions are: allfunctions.
$orderby query string false Specifies the order in which items are returned. The maximum number of expressions is 5.
$top query integer(int32) false Limits the number of items returned from a collection.
$skip query integer(int32) false Excludes the specified number of items of the queried collection from the result.
$count query boolean false Indicates whether the total count of items within a collection are returned in the result.

Example responses

200 Response

{
  "value": [
    {
      "sk": 0,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "personSk": 0,
      "firstName": "string",
      "lastName": "string",
      "fullName": "string",
      "birthDate": "2019-08-24T14:15:22Z",
      "age": "string",
      "gender": "string",
      "livesWithPerson": "string",
      "isSharedCustody": "string",
      "sharedCustodyPercentageAssignment": 0,
      "isChronicallyIll": "string",
      "isStepchild": "string",
      "comment": "string",
      "person": {}
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK Success PersonChildIEnumerableODataValue

PersonElectronicAddress

getPersonElectronicAddress

Code samples

## You can also use wget
curl -X GET /v1/personElectronicAddress \
  -H 'Accept: application/json' \
  -H 'X-ApiKey: API_KEY'


import requests
headers = {
  'Accept': 'application/json',
  'X-ApiKey': 'API_KEY'
}

r = requests.get('/v1/personElectronicAddress', headers = headers)

print(r.json())

GET /v1/personElectronicAddress

Returns PersonElectronicAddress entities

Parameters

Name In Type Required Description
$select query string false Limits the properties returned in the result.
$expand query string false Indicates the related entities to be represented inline. The maximum depth is 2.
$filter query string false Restricts the set of items returned. The maximum number of expressions is 100. The allowed functions are: allfunctions.
$orderby query string false Specifies the order in which items are returned. The maximum number of expressions is 5.
$top query integer(int32) false Limits the number of items returned from a collection.
$skip query integer(int32) false Excludes the specified number of items of the queried collection from the result.
$count query boolean false Indicates whether the total count of items within a collection are returned in the result.

Example responses

200 Response

{
  "value": [
    {
      "sk": 0,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "personSk": 0,
      "type": "string",
      "address": "string",
      "person": {}
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK Success PersonElectronicAddressIEnumerableODataValue

PersonNextOfKin

getPersonNextOfKin

Code samples

## You can also use wget
curl -X GET /v1/personNextOfKin \
  -H 'Accept: application/json' \
  -H 'X-ApiKey: API_KEY'


import requests
headers = {
  'Accept': 'application/json',
  'X-ApiKey': 'API_KEY'
}

r = requests.get('/v1/personNextOfKin', headers = headers)

print(r.json())

GET /v1/personNextOfKin

Returns PersonNextOfKin entities

Parameters

Name In Type Required Description
$select query string false Limits the properties returned in the result.
$expand query string false Indicates the related entities to be represented inline. The maximum depth is 2.
$filter query string false Restricts the set of items returned. The maximum number of expressions is 100. The allowed functions are: allfunctions.
$orderby query string false Specifies the order in which items are returned. The maximum number of expressions is 5.
$top query integer(int32) false Limits the number of items returned from a collection.
$skip query integer(int32) false Excludes the specified number of items of the queried collection from the result.
$count query boolean false Indicates whether the total count of items within a collection are returned in the result.

Example responses

200 Response

{
  "value": [
    {
      "sk": 0,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "personSk": 0,
      "relationType": "string",
      "firstName": "string",
      "lastName": "string",
      "fullName": "string",
      "email": "string",
      "phoneNumber": "string",
      "address": "string",
      "postalCode": "string",
      "postalPlace": "string",
      "country": "string",
      "person": {}
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK Success PersonNextOfKinIEnumerableODataValue

PersonPhoneNumber

getPersonPhoneNumber

Code samples

## You can also use wget
curl -X GET /v1/personPhoneNumber \
  -H 'Accept: application/json' \
  -H 'X-ApiKey: API_KEY'


import requests
headers = {
  'Accept': 'application/json',
  'X-ApiKey': 'API_KEY'
}

r = requests.get('/v1/personPhoneNumber', headers = headers)

print(r.json())

GET /v1/personPhoneNumber

Returns PersonPhoneNumber entities

Parameters

Name In Type Required Description
$select query string false Limits the properties returned in the result.
$expand query string false Indicates the related entities to be represented inline. The maximum depth is 2.
$filter query string false Restricts the set of items returned. The maximum number of expressions is 100. The allowed functions are: allfunctions.
$orderby query string false Specifies the order in which items are returned. The maximum number of expressions is 5.
$top query integer(int32) false Limits the number of items returned from a collection.
$skip query integer(int32) false Excludes the specified number of items of the queried collection from the result.
$count query boolean false Indicates whether the total count of items within a collection are returned in the result.

Example responses

200 Response

{
  "value": [
    {
      "sk": 0,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "personSk": 0,
      "type": "string",
      "number": "string",
      "person": {}
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK Success PersonPhoneNumberIEnumerableODataValue

Unit

getUnit

Code samples

## You can also use wget
curl -X GET /v1/unit \
  -H 'Accept: application/json' \
  -H 'X-ApiKey: API_KEY'


import requests
headers = {
  'Accept': 'application/json',
  'X-ApiKey': 'API_KEY'
}

r = requests.get('/v1/unit', headers = headers)

print(r.json())

GET /v1/unit

Returns Unit entities

Parameters

Name In Type Required Description
$select query string false Limits the properties returned in the result.
$expand query string false Indicates the related entities to be represented inline. The maximum depth is 2.
$filter query string false Restricts the set of items returned. The maximum number of expressions is 100. The allowed functions are: allfunctions.
$orderby query string false Specifies the order in which items are returned. The maximum number of expressions is 5.
$top query integer(int32) false Limits the number of items returned from a collection.
$skip query integer(int32) false Excludes the specified number of items of the queried collection from the result.
$count query boolean false Indicates whether the total count of items within a collection are returned in the result.

Example responses

200 Response

{
  "value": [
    {
      "sk": 0,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "parentUnitSk": 0,
      "unitName": "string",
      "alias": "string",
      "organizationNumber": "string",
      "unitType": "string",
      "employees": [],
      "managerSk": 0,
      "parentUnit": {},
      "subunits": [],
      "employments": [],
      "managers": []
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK Success UnitIEnumerableODataValue

Schemas

Absence

{
  "sk": 0,
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "personSk": 0,
  "startDate": "2019-08-24T14:15:22Z",
  "endDate": "2019-08-24T14:15:22Z",
  "percentageAssignment": 0,
  "status": "string",
  "absenceCategory": "string",
  "absenceType": "string",
  "isFteReduction": "string",
  "isAbsent": "string",
  "employmentAbsences": [],
  "person": {}
}

A registered period of person's absence or their limited availability at work

Properties

Name Type Required Restrictions Description
sk integer(int32) true none Unique identifier of the entity (a Surrogate Key used in analytics API)
id string(uuid) true none Simployer HRM system identifier of the entity
personSk integer(int32) true none Identifier of the person for whom this absence is registered
startDate string(date-time) true none First day of absence
endDate string(date-time)¦null true none Last day of absence, null if absence is still in progress
percentageAssignment number(double) true none Percentage of person absence (i.e. fully absent or half day, etc.)

Values:
* between 0 and 1; 1 meaning person is absent the whole period
status string true none Absence status

Values:
* Unhandled
* Approved
* Declined
* Proposed
* Deleted (obsolete)
* In progress
* Conflicted
* Child unit statistics
absenceCategory string true none Categorization of absence. It's an indicator of Simployer's module where absence was registered

Values:
* Vacation
* Leave & absence
* Sick leave
absenceType string true none Absence type
isFteReduction string true none If the absence should be treated as FTE reduction period (based on absence type)

Values:
* Yes
* No
isAbsent string true none If the person was absent at the period. This is based on few factors (e.g. absence type, status). If yes, absence is used in e.g. lost FTE calculations

Values:
* Yes
* No
employmentAbsences [EmploymentAbsence]¦null false none Employment-absences that occured for this absence - can be used with $expand OData query option
person Person false none A physical person

AbsenceIEnumerableODataValue

{
  "value": []
}

Properties

Name Type Required Restrictions Description
value [Absence] false none [A registered period of person's absence or their limited availability at work]

Employee

{
  "sk": 0,
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "unitSk": 0,
  "personSk": 0,
  "person": {},
  "number": "string",
  "unit": {},
  "employments": []
}

Represents a relation between a person and their employer (a legal unit)

Properties

Name Type Required Restrictions Description
sk integer(int32) true none Unique identifier of the entity (a Surrogate Key used in analytics API)
id string(uuid) true none Simployer HRM id of employee as used in Simployer systems
unitSk integer(int32) true none Affiliation unit's identifier
personSk integer(int32) true none Identifier of the person whose relation with employer is represented by this employee
person Person false none A physical person
number string true none Employee number
unit Unit false none A logical grouping within the company. Unit can, but doesn't have to, have a legal identity
employments [Employment]¦null false none Employments assigned to this employee - can be used with $expand OData query option

EmployeeIEnumerableODataValue

{
  "value": []
}

Properties

Name Type Required Restrictions Description
value [Employee] false none [Represents a relation between a person and their employer (a legal unit)]

Employment

{
  "sk": 0,
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "unitSk": 0,
  "unit": {},
  "employeeSk": 0,
  "categoryName": "string",
  "includeInFte": "string",
  "positionName": "string",
  "startDate": "2019-08-24T14:15:22Z",
  "endDate": "2019-08-24T14:15:22Z",
  "percentageAssignment": 0,
  "hoursPerWeekAssignment": 0,
  "continuity": "string",
  "isActive": "string",
  "employee": {},
  "employmentAbsences": []
}

Employment information for employee in unit and period of time

Properties

Name Type Required Restrictions Description
sk integer(int32) true none Unique identifier of the entity (a Surrogate Key used in analytics API)
id string(uuid) true none Simployer HRM id for the entity
unitSk integer(int32) true none Unit's, where this employment is registered, identifier
unit Unit false none A logical grouping within the company. Unit can, but doesn't have to, have a legal identity
employeeSk integer(int32) true none Identifier of the employee that's one of the parties in the employment
categoryName string true none Employment category
includeInFte string true none If the employment should be included in FTE calculations

Values:
* Yes
* No
positionName string true none Position on the employment contract
startDate string(date-time) true none Employment contract start date
endDate string(date-time)¦null true none Employment end date, null if not specified
percentageAssignment number(double) true none Percentage assigment of full-time position

Values:
* between 0 and 1; 1 meaning employee is employed full-time
hoursPerWeekAssignment number(double) true none Assignment in hours per week
continuity string true none Status of employment's continuity. It gives an insight of employee's situation in the organization at the end of this employment.

Values:
* No - there's no other ongoing employment at the end of this employment. This means that employee is no longer employed in organization
* Same legal unit - there's another ongoing employment within the same legal unit at the end of this employment
* Different legal unit - there's another ongoing employment within different legal unit at the end of this employment
* Ongoing - this employment is still ongoing, there's no end date set, therefore no way to determine further employments
isActive string true none If the employment is active in the system

Values:
* Yes
* No
employee Employee false none Represents a relation between a person and their employer (a legal unit)
employmentAbsences [EmploymentAbsence]¦null false none Employment-absences that occured for this employment - can be used with $expand OData query option

EmploymentAbsence

{
  "sk": 0,
  "absenceSk": 0,
  "employmentSk": 0,
  "startDate": "2019-08-24T14:15:22Z",
  "endDate": "2019-08-24T14:15:22Z",
  "percentageAssignment": 0,
  "absence": {},
  "employment": {}
}

Employment-absence information, based on absence and employment data.
Entries available here are intersection of absence and employment periods.
If no employment is present during absence, there will be no employment-absence entry for it

Properties

Name Type Required Restrictions Description
sk integer(int32) true none Unique identifier of the entity (a Surrogate Key used in analytics API)
absenceSk integer(int32) true none Related absence's identifier
employmentSk integer(int32) true none Related employment's identifier
startDate string(date-time) true none First day of employment-absence
endDate string(date-time)¦null true none Last day of employment-absence, null if employment-absence is still in progress
percentageAssignment number(double) true none Percentage assigment

Values:
* between 0 and 1; 1 meaning employee is fully absent. This is a result of multiplying absence's and employment's PercentageAssignment properties
absence Absence false none A registered period of person's absence or their limited availability at work
employment Employment false none Employment information for employee in unit and period of time

EmploymentAbsenceIEnumerableODataValue

{
  "value": []
}

Properties

Name Type Required Restrictions Description
value [EmploymentAbsence] false none [Employment-absence information, based on absence and employment data.

Entries available here are intersection of absence and employment periods.

If no employment is present during absence, there will be no employment-absence entry for it]

EmploymentIEnumerableODataValue

{
  "value": []
}

Properties

Name Type Required Restrictions Description
value [Employment] false none [Employment information for employee in unit and period of time]

FteByMonth

{
  "employmentSk": 0,
  "employment": {},
  "unitSk": 0,
  "employeeSk": 0,
  "startOfMonth": "2019-08-24T14:15:22Z",
  "fte": 0,
  "actualFte": 0,
  "unit": {},
  "employee": {}
}

Monthly FTE and actual FTE per employment, based on employment and absence information

Properties

Name Type Required Restrictions Description
employmentSk integer(int32) true none Employment's identifier
employment Employment false none Employment information for employee in unit and period of time
unitSk integer(int32) true none Unit's identifier
employeeSk integer(int32) true none Employee's identifier
startOfMonth string(date-time) true none First day of month
fte number(double) true none FTE value for specified month

Values:
* between 0 and 1; 1 meaning one man-month
actualFte number(double) true none Actual FTE value for specified month

Values:
* between 0 and 1; 1 meaning one man-month
unit Unit false none A logical grouping within the company. Unit can, but doesn't have to, have a legal identity
employee Employee false none Represents a relation between a person and their employer (a legal unit)

FteByMonthIEnumerableODataValue

{
  "value": []
}

Properties

Name Type Required Restrictions Description
value [FteByMonth] false none [Monthly FTE and actual FTE per employment, based on employment and absence information]

LoadStatus

{
  "id": 0,
  "status": "string",
  "updateTimeUtc": "2019-08-24T14:15:22Z"
}

Data load status (last load status and update time)

Properties

Name Type Required Restrictions Description
id integer(int32) true none Id of entry (internal)
status string true none Status of last load.

Values:
* Succeeded - data is loaded correctly;
* Failed - data is currently in inconsistent state, try again later.
updateTimeUtc string(date-time)¦null true none Date of last status update (UTC)

LoadStatusIEnumerableODataValue

{
  "value": []
}

Properties

Name Type Required Restrictions Description
value [LoadStatus] false none [Data load status (last load status and update time)]

Person

{
  "sk": 0,
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "firstName": "string",
  "lastName": "string",
  "fullName": "string",
  "shortName": "string",
  "birthDate": "2019-08-24T14:15:22Z",
  "age": "string",
  "gender": "string",
  "nationality": "string",
  "civilStatus": "string",
  "isActive": "string",
  "seniorityMonths": 0,
  "immediateSupervisorSk": 0,
  "affiliationUnitSk": 0,
  "additionalInfo": "string",
  "primaryBankAccountCountry": "string",
  "primaryBankAccount": "string",
  "secondaryBankAccountCountry": "string",
  "secondaryBankAccount": "string",
  "absences": [],
  "addresses": [],
  "electronicAddresses": [],
  "phoneNumbers": [],
  "nextOfKin": [],
  "children": [],
  "immediateSupervisor": {},
  "affiliationUnit": {},
  "employees": [],
  "directReports": []
}

A physical person

Properties

Name Type Required Restrictions Description
sk integer(int32) true none Unique identifier of the entity (a Surrogate Key used in analytics API)
id string(uuid) true none System GUID of person entity as used in Simployer HRM
firstName string¦null true none First name
lastName string¦null true none Last name
fullName string true none Full name
shortName string true none Short name
birthDate string(date-time)¦null true none Date of birth (or null if not set)
age string true none Age in full years
gender string true none Gender

Values:
* Female
* Male
nationality string true none Nationality
civilStatus string true none Civil status

Values:
* Unmarried
* Married
* Live-in
* Live-in with common children
* Separated
* Divorced
* Widow
* Widower
* Partnership
* Not set
isActive string true none If the person's account is active in the system

Values:
* Yes
* No
seniorityMonths integer(int32) true none Seniority in full months. It's based on person's employments, and seniority date - if provided
immediateSupervisorSk integer(int32) true none Immediate supervisor's person entry identifier
affiliationUnitSk integer(int32) true none Affiliation unit's identifier
additionalInfo string true none Additional information
primaryBankAccountCountry string true none Primary bank account's country of origin
primaryBankAccount string true none Primary bank account number
secondaryBankAccountCountry string true none Secondary bank account's country of origin
secondaryBankAccount string true none Secondary bank account number
absences [Absence]¦null false none Absences registered for that person - can be used with $expand OData query option
addresses [PersonAddress]¦null false none Persons's addresses - can be used with $expand OData query option
electronicAddresses [PersonElectronicAddress]¦null false none Person's electronic addresses - can be used with $expand OData query option
phoneNumbers [PersonPhoneNumber]¦null false none Person's phone numbers - can be used with $expand OData query option
nextOfKin [PersonNextOfKin]¦null false none Person's next of kin - can be used with $expand OData query option
children [PersonChild]¦null false none Person's children - can be used with $expand OData query option
immediateSupervisor Person false none A physical person
affiliationUnit Unit false none A logical grouping within the company. Unit can, but doesn't have to, have a legal identity
employees [Employee]¦null false none Employees that represent this person - can be used with $expand OData query option
directReports [Person]¦null false none Persons for whom this person is immediate supervisor - can be used with $expand OData query option

PersonAddress

{
  "sk": 0,
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "personSk": 0,
  "addressKind": "string",
  "address": "string",
  "postalCode": "string",
  "postalPlace": "string",
  "country": "string",
  "person": {}
}

Person's address details

Properties

Name Type Required Restrictions Description
sk integer(int32) true none Unique identifier of the entity (a Surrogate Key used in analytics API)
id string(uuid) true none System GUID of person address entity as used in Simployer HRM
personSk integer(int32) true none Identifier of the person whose address is represented by this entity
addressKind string true none Address kind

Values:
* Primary
* Commuter home
* Delivery
* Department
* Home
* Post
* Vacation
* Visit
address string true none Address
postalCode string true none Postal code
postalPlace string true none Postal place
country string true none Country
person Person false none A physical person

PersonAddressIEnumerableODataValue

{
  "value": []
}

Properties

Name Type Required Restrictions Description
value [PersonAddress] false none [Person's address details]

PersonChild

{
  "sk": 0,
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "personSk": 0,
  "firstName": "string",
  "lastName": "string",
  "fullName": "string",
  "birthDate": "2019-08-24T14:15:22Z",
  "age": "string",
  "gender": "string",
  "livesWithPerson": "string",
  "isSharedCustody": "string",
  "sharedCustodyPercentageAssignment": 0,
  "isChronicallyIll": "string",
  "isStepchild": "string",
  "comment": "string",
  "person": {}
}

Person's child details

Properties

Name Type Required Restrictions Description
sk integer(int32) true none Unique identifier of the entity (a Surrogate Key used in analytics API)
id string(uuid) true none System GUID of person next of kin entity as used in Simployer HRM
personSk integer(int32) true none Identifier of the person whose child is represented by this entity
firstName string¦null true none First name
lastName string¦null true none Last name
fullName string true none Full name
birthDate string(date-time)¦null true none Date of birth (or null if not set)
age string true none Age in full years
gender string true none Gender

Values:
* Female
* Male
livesWithPerson string true none If the person and child live together

Values:
* Yes
* No
isSharedCustody string true none If the person shares custody with other parent

Values:
* Yes
* No
sharedCustodyPercentageAssignment number(double)¦null true none Shared custody percentage assigment

Values:
* between 0 and 1; 1 meaning person is the only child's caregiver
* null if not applicable
isChronicallyIll string true none If the child is chronically ill or disabled

Values:
* Yes
* No
isStepchild string true none If it's a stepchild

Values:
* Yes
* No
comment string true none Comment
person Person false none A physical person

PersonChildIEnumerableODataValue

{
  "value": []
}

Properties

Name Type Required Restrictions Description
value [PersonChild] false none [Person's child details]

PersonElectronicAddress

{
  "sk": 0,
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "personSk": 0,
  "type": "string",
  "address": "string",
  "person": {}
}

Person's electronic address details

Properties

Name Type Required Restrictions Description
sk integer(int32) true none Unique identifier of the entity (a Surrogate Key used in analytics API)
id string(uuid) true none System GUID of person electronic address entity as used in Simployer HRM
personSk integer(int32) true none Identifier of the person whose electronic address is represented by this entity
type string true none Address type

Values:
* Undefined
* Homepage
* Email primary
* Messenger
* Email alternative
* Twitter
* ExternalId
* ExternalId alternative
* LinkedIn
address string true none Address
person Person false none A physical person

PersonElectronicAddressIEnumerableODataValue

{
  "value": []
}

Properties

Name Type Required Restrictions Description
value [PersonElectronicAddress] false none [Person's electronic address details]

PersonIEnumerableODataValue

{
  "value": []
}

Properties

Name Type Required Restrictions Description
value [Person] false none [A physical person]

PersonNextOfKin

{
  "sk": 0,
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "personSk": 0,
  "relationType": "string",
  "firstName": "string",
  "lastName": "string",
  "fullName": "string",
  "email": "string",
  "phoneNumber": "string",
  "address": "string",
  "postalCode": "string",
  "postalPlace": "string",
  "country": "string",
  "person": {}
}

Person's next of kin details

Properties

Name Type Required Restrictions Description
sk integer(int32) true none Unique identifier of the entity (a Surrogate Key used in analytics API)
id string(uuid) true none System GUID of person next of kin entity as used in Simployer HRM
personSk integer(int32) true none Identifier of the person whose next of kin is represented by this entity
relationType string true none Person and next of kin relation type
firstName string¦null true none First name
lastName string¦null true none Last name
fullName string true none Full name
email string true none Email address
phoneNumber string true none Phone number
address string true none Address
postalCode string true none Postal code
postalPlace string true none Postal place
country string true none Country
person Person false none A physical person

PersonNextOfKinIEnumerableODataValue

{
  "value": []
}

Properties

Name Type Required Restrictions Description
value [PersonNextOfKin] false none [Person's next of kin details]

PersonPhoneNumber

{
  "sk": 0,
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "personSk": 0,
  "type": "string",
  "number": "string",
  "person": {}
}

Person's phone numbers

Properties

Name Type Required Restrictions Description
sk integer(int32) true none Unique identifier of the entity (a Surrogate Key used in analytics API)
id string(uuid) true none System GUID of person phone number entity as used in Simployer HRM
personSk integer(int32) true none Identifier of the person whose phone number is represented by this entity
type string true none Phone number type

Values:
* Home
* Call center
* Direct number
* Mobile primary
* Fax
* Mobile alternative
number string true none Phone number
person Person false none A physical person

PersonPhoneNumberIEnumerableODataValue

{
  "value": []
}

Properties

Name Type Required Restrictions Description
value [PersonPhoneNumber] false none [Person's phone numbers]

Unit

{
  "sk": 0,
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "parentUnitSk": 0,
  "unitName": "string",
  "alias": "string",
  "organizationNumber": "string",
  "unitType": "string",
  "employees": [],
  "managerSk": 0,
  "parentUnit": {},
  "subunits": [],
  "employments": [],
  "managers": []
}

A logical grouping within the company. Unit can, but doesn't have to, have a legal identity

Properties

Name Type Required Restrictions Description
sk integer(int32) true none Unique identifier of the entity (a Surrogate Key used in analytics API)
id string(uuid) true none Unique identifier of the unit as used in Simployer systems
parentUnitSk integer(int32) true none Parent unit's in default (legal) structure identifier, or -1 if there is no parent unit or unit is not a part of default structure
unitName string true none Name
alias string true none Alias
organizationNumber string true none Organization number (valid for legal units)
unitType string true none Unit type

Values:
* Enterprise
* Legal unit
* Internal department
employees [Employee]¦null false none Employees employed in this unit - can be used with $expand OData query option
managerSk integer(int32) true none First unit's manager's identifier. If no manager defined then this is ManagerSk from ParentUnit
parentUnit Unit false none A logical grouping within the company. Unit can, but doesn't have to, have a legal identity
subunits [Unit]¦null false none Subunits - can be used with $expand OData query option
employments [Employment]¦null false none Employments registered in this unit - can be used with $expand OData query option

Note that employee may be affiliated to different unit (i.e.legal unit) than the employment (unit where the employee actually works)
managers [Person]¦null false none Unit managers - can be used with $expand OData query option

Note that currently only one unit manager can be defined, thus the list consist of one element - referenced by ManagerSk

UnitIEnumerableODataValue

{
  "value": []
}

Properties

Name Type Required Restrictions Description
value [Unit] false none [A logical grouping within the company. Unit can, but doesn't have to, have a legal identity]
Curl Python