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.

Webhook Integration

From January 2021 Simployer will offer webhook integrations. To get access to the webhook admin UI please send an email to api@simployer.com

Important principles

When using webhook integrations from Simployer, you should be aware of the following principles:

at-least-once delivery

In order not to miss any important events, our Webhook Integration ensures the at-least-once delivery. It means that you could receive exactly the same event (identified by guid) more than once. Good practice to handle such cases is to ensure that event handler is idempotent - processing the same event more than once gives exactly the same result.

Webhook admin UI

Get an overview of your webhook configurations:

Simployer API Doc

Create new webhook configurations:

Simployer API Doc

Get webhook statuses:

Simployer API Doc

When are events triggered from Simployer

Person

When Event Description
Creating a person personCreated
Changing a persons name personNameChanged
Deleting a person personDeleted
Adding email to a person personEmailAdded
Changing email for a person personEmailChanged
Delete email from a person personEmailDeleted
Adding phone to a person personPhoneAdded
Changing phone for a person personPhoneChanged
Delete phone from a person personPhoneDeleted

Group

When Event Description
Creating a group unitCreated unitTypeKind = 'Group'
Deleting a group unitDeleted
Changing a groups name unitNameChanged
Changing a groups code unitAliasChanged

Unit (Department/Group)

When Event Description
Creating a department unitCreated unitTypeKind = 'Department'
Creating a group unitCreated unitTypeKind = 'Group'
Deleting a department unitDeleted
Deleting a group unitDeleted
Changing a departments code unitAliasChanged
Changing a groups code unitAliasChanged
Changing a departments name unitNameChanged
Changing a group name unitNameChanged

LegalUnit

When Event Description
Creating a legal unit legalUnitCreated Creating a Simployer unit with type legal unit
Deleting a legal unit legalUnitDeleted
Changing a legal unit name legalUnitNameChanged
Changing a legal unit org. number legalUnitOrganizationNumberChanged

Group membership

When Event Description
Adding a person as a direct member to a group personAddedToUnit If no group relationship allready exist
Removing a person (direct member) from a group personRemovedFromUnit If this is the only group relationship
Adding a position group relation personAddedToUnit For all persons with this active position, if the person does not allready have a membership
Removing a position group relation personRemovedFromUnit For all persons where this relationship is the only way for the group membership
Adding a position to a person personAddedToUnit If the position is bound and the person does not allready have a membership
Removing a position from a person personRemovedFromUnit If the position is bound to a group and this relationship is the only one giving the person membership
Adding a person as an indirect member to a group (through department) personAddedToUnit If no group relationship allready exist
Removing a person (indirect member) from a group personRemovedFromUnit If this is the only group relationship

Webhook Callback API v1.0.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.

This defines the contract an external system have to fulfill when being the target of the Simployer Webhook Integration. The URL and exact endpoint can be defined when setting up the integration within Simployer. This documentation uses /callback as the endpoint, but any endpoint can be used.

Base URLs:

Terms of service Email: Simployer API team License: License TBD

Authentication

Scope Scope Description
write:events write events to the callback

Callback

postEvents

Code samples

## You can also use wget
curl -X POST https://user-defined-custom.domain.com/callback \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('https://user-defined-custom.domain.com/callback', headers = headers)

print(r.json())

POST /callback

This endpoint is called by Simployer to deliver events. The name of the endpoint can be anything. /callback is used as an example.

The webhook must respond to the POST request within 10 seconds (TBD). Otherwise, Simployer will assume a 599 Network connect timeout error response.

Body parameter

[
  {
    "tenantId": "67cdd743-a83f-404b-93ef-29dfe5bc2e31",
    "eventId": "83e0e090-e16f-48ab-910e-96d5f3f1dd14",
    "timestamp": "2019-08-24T14:15:22Z",
    "topic": "Person",
    "kind": "Simployer.Person.Events.PersonCreated",
    "body": {
      "personId": "39ddea86-03bc-4f36-99f8-55b9981453ec",
      "firstName": "Kim",
      "lastName": "Smith"
    }
  }
]

Parameters

Name In Type Required Description
body body payload true The events. Maximum size is 256kB (TBD).

Example responses

4xx Response

{
  "code": "string",
  "message": "string"
}

Responses

Status Meaning Description Schema
200 OK All events in array received OK None
4xx Client Error An error occured. Simployer will try to send all events again. error

Schemas

payload

[
  {
    "tenantId": "67cdd743-a83f-404b-93ef-29dfe5bc2e31",
    "eventId": "83e0e090-e16f-48ab-910e-96d5f3f1dd14",
    "timestamp": "2019-08-24T14:15:22Z",
    "topic": "Person",
    "kind": "Simployer.Person.Events.PersonCreated",
    "body": {
      "personId": "39ddea86-03bc-4f36-99f8-55b9981453ec",
      "firstName": "Kim",
      "lastName": "Smith"
    }
  }
]

An array of eventEnvelope.

Properties

Name Type Required Restrictions Description
anonymous [eventEnvelope] false none An array of eventEnvelope.

eventEnvelope

{
  "tenantId": "67cdd743-a83f-404b-93ef-29dfe5bc2e31",
  "eventId": "83e0e090-e16f-48ab-910e-96d5f3f1dd14",
  "timestamp": "2019-08-24T14:15:22Z",
  "topic": "Person",
  "kind": "Simployer.Person.Events.PersonCreated",
  "body": {
    "personId": "39ddea86-03bc-4f36-99f8-55b9981453ec",
    "firstName": "Kim",
    "lastName": "Smith"
  }
}

Properties

Name Type Required Restrictions Description
tenantId string(uuid) true none none
eventId string(uuid) true none none
timestamp string(date-time) true none none
topic string true none Values:
* Person
* LegalUnit
* Unit
* UnitMembership
* Tenant
kind string true none TO BE DEFINED. Describes the schema of the Body property
body any true none none

oneOf

Name Type Required Restrictions Description
» anonymous personCreated false none none

xor

Name Type Required Restrictions Description
» anonymous personDeleted false none none

xor

Name Type Required Restrictions Description
» anonymous personEmailAdded false none none

xor

Name Type Required Restrictions Description
» anonymous personEmailChanged false none none

xor

Name Type Required Restrictions Description
» anonymous personEmailDeleted false none none

xor

Name Type Required Restrictions Description
» anonymous personNameChanged false none none

xor

Name Type Required Restrictions Description
» anonymous personPhoneAdded false none none

xor

Name Type Required Restrictions Description
» anonymous personPhoneChanged false none none

xor

Name Type Required Restrictions Description
» anonymous personPhoneDeleted false none none

xor

Name Type Required Restrictions Description
» anonymous personRequestedGDPRDeletion false none TO BE IMPLEMENTED - The person requested their right to be deleted as per GDPR article 17.

xor

Name Type Required Restrictions Description
» anonymous unitCreated false none none

xor

Name Type Required Restrictions Description
» anonymous unitDeleted false none none

xor

Name Type Required Restrictions Description
» anonymous unitNameChanged false none none

xor

Name Type Required Restrictions Description
» anonymous unitAliasChanged false none none

xor

Name Type Required Restrictions Description
» anonymous unitTypeIdChanged false none The Unit has changed type (not to be confused with the type itself changing in any way).

xor

Name Type Required Restrictions Description
» anonymous unitTypeCreated false none none

xor

Name Type Required Restrictions Description
» anonymous unitTypeDeleted false none none

xor

Name Type Required Restrictions Description
» anonymous unitTypeNameChanged false none none

xor

Name Type Required Restrictions Description
» anonymous legalUnitCreated false none none

xor

Name Type Required Restrictions Description
» anonymous legalUnitDeleted false none none

xor

Name Type Required Restrictions Description
» anonymous legalUnitNameChanged false none none

xor

Name Type Required Restrictions Description
» anonymous legalUnitOrganizationNumberChanged false none none

xor

Name Type Required Restrictions Description
» anonymous personAddedToUnit false none none

xor

Name Type Required Restrictions Description
» anonymous personRemovedFromUnit false none none

xor

Name Type Required Restrictions Description
» anonymous tenantCreated false none TO BE IMPLEMENTED

xor

Name Type Required Restrictions Description
» anonymous tenantDeleted false none TO BE IMPLEMENTED

xor

Name Type Required Restrictions Description
» anonymous tenantNameChanged false none TO BE IMPLEMENTED
Enumerated Values
Property Value
topic Person
topic LegalUnit
topic Unit
topic UnitMembership
topic Tenant
kind Simployer.Person.Events.PersonCreated
kind Simployer.Person.Events.PersonDeleted
kind Simployer.Person.Events.PersonEmailAdded
kind Simployer.Person.Events.PersonEmailChanged
kind Simployer.Person.Events.PersonEmailDeleted
kind Simployer.Person.Events.PersonNameChanged
kind Simployer.Person.Events.PersonPhoneAdded
kind Simployer.Person.Events.PersonPhoneChanged
kind Simployer.Person.Events.PersonPhoneDeleted
kind Simployer.Person.Events.PersonRequestedGDPRDeletion
kind Simployer.Unit.Events.UnitCreated
kind Simployer.Unit.Events.UnitDeleted
kind Simployer.Unit.Events.UnitNameChanged
kind Simployer.Unit.Events.UnitAliasChanged
kind Simployer.Unit.Events.UnitTypeIdChanged
kind Simployer.Unit.Events.UnitTypeCreated
kind Simployer.Unit.Events.UnitTypeDeleted
kind Simployer.Unit.Events.UnitTypeNameChanged
kind Simployer.Unit.Events.LegalUnitCreated
kind Simployer.Unit.Events.LegalUnitDeleted
kind Simployer.Unit.Events.LegalUnitNameChanged
kind Simployer.Unit.Events.LegalUnitOrganizationNumberChanged
kind Simployer.Core.Events.PersonAddedToUnit
kind Simployer.Core.Events.PersonRemovedFromUnit
kind Simployer.Tenant.Events.TenantCreated
kind Simployer.Tenant.Events.TenantDeleted
kind Simployer.Tenant.Events.TenantNameChanged

personCreated

{
  "personId": "39ddea86-03bc-4f36-99f8-55b9981453ec",
  "firstName": "Kim",
  "lastName": "Smith"
}

Properties

Name Type Required Restrictions Description
personId string(uuid) true none none
firstName string true none none
lastName string true none none

personDeleted

{
  "personId": "39ddea86-03bc-4f36-99f8-55b9981453ec"
}

Properties

Name Type Required Restrictions Description
personId string(uuid) true none none

personEmailAdded

{
  "personId": "39ddea86-03bc-4f36-99f8-55b9981453ec",
  "emailId": "0b470856-6b9d-43ea-b49b-377be18fa249",
  "emailTypeId": "26ae6698-25c1-4945-a1e0-a58629b1dcc2",
  "emailTypeKind": "2dd993f6-562c-4575-82b3-11750c6c8d82",
  "emailAddress": "user@example.com"
}

Properties

Name Type Required Restrictions Description
personId string(uuid) true none none
emailId string(uuid) true none none
emailTypeId string(uuid) true none none
emailTypeKind string(uuid) true none Types:
* 2dd993f6-562c-4575-82b3-11750c6c8d82 - Work
* d0d62c34-ca62-4281-bef9-96763103550b - Private
emailAddress string(email) true none none
Enumerated Values
Property Value
emailTypeKind 2dd993f6-562c-4575-82b3-11750c6c8d82
emailTypeKind d0d62c34-ca62-4281-bef9-96763103550b

personEmailChanged

{
  "personId": "39ddea86-03bc-4f36-99f8-55b9981453ec",
  "emailId": "0b470856-6b9d-43ea-b49b-377be18fa249",
  "emailTypeId": "26ae6698-25c1-4945-a1e0-a58629b1dcc2",
  "emailTypeKind": "2dd993f6-562c-4575-82b3-11750c6c8d82",
  "emailAddress": "user@example.com"
}

Properties

Name Type Required Restrictions Description
personId string(uuid) true none none
emailId string(uuid) true none none
emailTypeId string(uuid) true none none
emailTypeKind string(uuid) true none Types:
* 2dd993f6-562c-4575-82b3-11750c6c8d82 - Work
* d0d62c34-ca62-4281-bef9-96763103550b - Private
emailAddress string(email) true none none
Enumerated Values
Property Value
emailTypeKind 2dd993f6-562c-4575-82b3-11750c6c8d82
emailTypeKind d0d62c34-ca62-4281-bef9-96763103550b

personEmailDeleted

{
  "personId": "39ddea86-03bc-4f36-99f8-55b9981453ec",
  "emailId": "0b470856-6b9d-43ea-b49b-377be18fa249"
}

Properties

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

personNameChanged

{
  "personId": "39ddea86-03bc-4f36-99f8-55b9981453ec",
  "firstName": "Alex",
  "lastName": "Smith"
}

Properties

Name Type Required Restrictions Description
personId string(uuid) true none none
firstName string false none none
lastName string false none none

personPhoneAdded

{
  "personId": "39ddea86-03bc-4f36-99f8-55b9981453ec",
  "phoneId": "8b2bf589-2a8b-421d-af43-eb40c9ec8a70",
  "phoneTypeId": "26ae6698-25c1-4945-a1e0-a58629b1dcc2",
  "phoneTypeKind": "c62d9463-8632-4f83-a1ba-fff64146552c",
  "number": "+4799999999"
}

Properties

Name Type Required Restrictions Description
personId string(uuid) true none none
phoneId string(uuid) true none none
phoneTypeId string(uuid) true none none
phoneTypeKind string(uuid) true none Types:
* c4f39a38-838d-48c9-8ed1-3b06e1e7c0d9 - Home
* e7e17a2f-3ea4-4cc0-9b8f-e9c9acc091d8 - Centralboard
* 9cda516f-c578-4f2f-bf54-2627f4427a00 - Direct
* 16b19ab9-56e3-4fa8-a68a-10b35fa1ddf0 - Mobile
* 9c1981e3-fc45-423a-b8b4-2050119c4f25 - Fax
* 5d727065-3129-4f2f-89e5-ec797b5ae265 - Mobile alternative
number string true none none
Enumerated Values
Property Value
phoneTypeKind c4f39a38-838d-48c9-8ed1-3b06e1e7c0d9
phoneTypeKind e7e17a2f-3ea4-4cc0-9b8f-e9c9acc091d8
phoneTypeKind 9cda516f-c578-4f2f-bf54-2627f4427a00
phoneTypeKind 16b19ab9-56e3-4fa8-a68a-10b35fa1ddf0
phoneTypeKind 9c1981e3-fc45-423a-b8b4-2050119c4f25
phoneTypeKind 5d727065-3129-4f2f-89e5-ec797b5ae265

personPhoneChanged

{
  "personId": "39ddea86-03bc-4f36-99f8-55b9981453ec",
  "phoneId": "8b2bf589-2a8b-421d-af43-eb40c9ec8a70",
  "phoneTypeId": "26ae6698-25c1-4945-a1e0-a58629b1dcc2",
  "phoneTypeKind": "c62d9463-8632-4f83-a1ba-fff64146552c",
  "number": "+4799999999"
}

Properties

Name Type Required Restrictions Description
personId string(uuid) true none none
phoneId string(uuid) true none none
phoneTypeId string(uuid) true none none
phoneTypeKind string(uuid) true none Types:
* c4f39a38-838d-48c9-8ed1-3b06e1e7c0d9 - Home
* e7e17a2f-3ea4-4cc0-9b8f-e9c9acc091d8 - Centralboard
* 9cda516f-c578-4f2f-bf54-2627f4427a00 - Direct
* 16b19ab9-56e3-4fa8-a68a-10b35fa1ddf0 - Mobile
* 9c1981e3-fc45-423a-b8b4-2050119c4f25 - Fax
* 5d727065-3129-4f2f-89e5-ec797b5ae265 - Mobile alternative
number string true none none
Enumerated Values
Property Value
phoneTypeKind c4f39a38-838d-48c9-8ed1-3b06e1e7c0d9
phoneTypeKind e7e17a2f-3ea4-4cc0-9b8f-e9c9acc091d8
phoneTypeKind 9cda516f-c578-4f2f-bf54-2627f4427a00
phoneTypeKind 16b19ab9-56e3-4fa8-a68a-10b35fa1ddf0
phoneTypeKind 9c1981e3-fc45-423a-b8b4-2050119c4f25
phoneTypeKind 5d727065-3129-4f2f-89e5-ec797b5ae265

personPhoneDeleted

{
  "personId": "39ddea86-03bc-4f36-99f8-55b9981453ec",
  "phoneId": "8b2bf589-2a8b-421d-af43-eb40c9ec8a70"
}

Properties

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

personRequestedGDPRDeletion

{
  "personId": "39ddea86-03bc-4f36-99f8-55b9981453ec"
}

TO BE IMPLEMENTED - The person requested their right to be deleted as per GDPR article 17.

Properties

Name Type Required Restrictions Description
personId string(uuid) true none none

unitCreated

{
  "unitId": "63ec7ae0-14b9-4f8a-b901-1941cdf31cc5",
  "name": "Alpha team",
  "alias": 1337,
  "unitTypeId": "c4e81abe-2c9c-4887-8ffb-95c19b2b59e2",
  "unitTypeKind": "9ccedd3d-3f2e-4405-8aee-76302a379602"
}

Properties

Name Type Required Restrictions Description
unitId string(uuid) true none none
name string true none none
alias string true none none
unitTypeId string(uuid) true none none
unitTypeKind string(uuid)¦null true none Types:
* 9ccedd3d-3f2e-4405-8aee-76302a379602 - Department
* 0119a842-4470-452a-b383-0c34d5aaaaf8 - Corporation
* 55ed1c5f-24ac-43a3-8c9e-5bfe844523d5 - Legal unit
* caed9ede-ff6b-4805-bfb1-9975cd69fde3 - Group
Enumerated Values
Property Value
unitTypeKind 9ccedd3d-3f2e-4405-8aee-76302a379602
unitTypeKind 0119a842-4470-452a-b383-0c34d5aaaaf8
unitTypeKind 55ed1c5f-24ac-43a3-8c9e-5bfe844523d
unitTypeKind caed9ede-ff6b-4805-bfb1-9975cd69fde3
unitTypeKind null

unitDeleted

{
  "unitId": "63ec7ae0-14b9-4f8a-b901-1941cdf31cc5"
}

Properties

Name Type Required Restrictions Description
unitId string(uuid) true none none

unitNameChanged

{
  "unitId": "63ec7ae0-14b9-4f8a-b901-1941cdf31cc5",
  "name": "Alpha team"
}

Properties

Name Type Required Restrictions Description
unitId string(uuid) true none none
name string true none none

unitAliasChanged

{
  "unitId": "63ec7ae0-14b9-4f8a-b901-1941cdf31cc5",
  "alias": 1337
}

Properties

Name Type Required Restrictions Description
unitId string(uuid) true none none
alias string true none none

unitTypeIdChanged

{
  "unitId": "63ec7ae0-14b9-4f8a-b901-1941cdf31cc5",
  "unitTypeId": "c4e81abe-2c9c-4887-8ffb-95c19b2b59e2",
  "unitTypeKind": "9ccedd3d-3f2e-4405-8aee-76302a379602"
}

The Unit has changed type (not to be confused with the type itself changing in any way).

Properties

Name Type Required Restrictions Description
unitId string(uuid) true none none
unitTypeId string(uuid) true none none
unitTypeKind string(uuid)¦null true none Types:
* 9ccedd3d-3f2e-4405-8aee-76302a379602 - Department
* 0119a842-4470-452a-b383-0c34d5aaaaf8 - Corporation
* 55ed1c5f-24ac-43a3-8c9e-5bfe844523d5 - Legal unit
* caed9ede-ff6b-4805-bfb1-9975cd69fde3 - Group
Enumerated Values
Property Value
unitTypeKind 9ccedd3d-3f2e-4405-8aee-76302a379602
unitTypeKind 0119a842-4470-452a-b383-0c34d5aaaaf8
unitTypeKind 55ed1c5f-24ac-43a3-8c9e-5bfe844523d
unitTypeKind caed9ede-ff6b-4805-bfb1-9975cd69fde3
unitTypeKind null

unitTypeCreated

{
  "unitTypeId": "c4e81abe-2c9c-4887-8ffb-95c19b2b59e2",
  "unitTypeKind": "9ccedd3d-3f2e-4405-8aee-76302a379602",
  "name": "Team"
}

Properties

Name Type Required Restrictions Description
unitTypeId string(uuid) true none none
unitTypeKind string(uuid) true none Types:
* 9ccedd3d-3f2e-4405-8aee-76302a379602 - Department
* 0119a842-4470-452a-b383-0c34d5aaaaf8 - Corporation
* 55ed1c5f-24ac-43a3-8c9e-5bfe844523d5 - Legal unit
* caed9ede-ff6b-4805-bfb1-9975cd69fde3 - Group
name string true none none
Enumerated Values
Property Value
unitTypeKind 9ccedd3d-3f2e-4405-8aee-76302a379602
unitTypeKind 0119a842-4470-452a-b383-0c34d5aaaaf8
unitTypeKind 55ed1c5f-24ac-43a3-8c9e-5bfe844523d
unitTypeKind caed9ede-ff6b-4805-bfb1-9975cd69fde3

unitTypeDeleted

{
  "unitTypeId": "c4e81abe-2c9c-4887-8ffb-95c19b2b59e2"
}

Properties

Name Type Required Restrictions Description
unitTypeId string(uuid) true none none

unitTypeNameChanged

{
  "unitTypeId": "c4e81abe-2c9c-4887-8ffb-95c19b2b59e2",
  "name": "Team"
}

Properties

Name Type Required Restrictions Description
unitTypeId string(uuid) true none none
name string true none none

legalUnitCreated

{
  "legalUnitId": "5469e1c4-33c4-4d9c-9da9-2d5ec4f6fc48",
  "name": "The Company",
  "organizationNumber": "123456789",
  "unitId": "1fa3c045-cf5b-4ce2-801b-d58f721febc9"
}

Properties

Name Type Required Restrictions Description
legalUnitId string(uuid) true none none
name string true none none
organizationNumber string true none none
unitId string(uuid) true none none

legalUnitDeleted

{
  "legalUnitId": "5469e1c4-33c4-4d9c-9da9-2d5ec4f6fc48"
}

Properties

Name Type Required Restrictions Description
legalUnitId string(uuid) true none none

legalUnitNameChanged

{
  "legalUnitId": "5469e1c4-33c4-4d9c-9da9-2d5ec4f6fc48",
  "name": "The Company"
}

Properties

Name Type Required Restrictions Description
legalUnitId string(uuid) true none none
name string true none none

legalUnitOrganizationNumberChanged

{
  "legalUnitId": "5469e1c4-33c4-4d9c-9da9-2d5ec4f6fc48",
  "organizationNumber": "123456789"
}

Properties

Name Type Required Restrictions Description
legalUnitId string(uuid) true none none
organizationNumber string true none none

personAddedToUnit

{
  "personId": "39ddea86-03bc-4f36-99f8-55b9981453ec",
  "unitId": "63ec7ae0-14b9-4f8a-b901-1941cdf31cc5"
}

Properties

Name Type Required Restrictions Description
personId string(uuid) true none none
unitId string(uuid) true none none

personRemovedFromUnit

{
  "personId": "39ddea86-03bc-4f36-99f8-55b9981453ec",
  "unitId": "63ec7ae0-14b9-4f8a-b901-1941cdf31cc5"
}

Properties

Name Type Required Restrictions Description
personId string(uuid) true none none
unitId string(uuid) true none none

tenantCreated

{
  "tenantId": "67cdd743-a83f-404b-93ef-29dfe5bc2e31",
  "name": "The customer"
}

TO BE IMPLEMENTED

Properties

Name Type Required Restrictions Description
tenantId string(uuid) true none none
name string true none none

tenantDeleted

{
  "tenantId": "67cdd743-a83f-404b-93ef-29dfe5bc2e31"
}

TO BE IMPLEMENTED

Properties

Name Type Required Restrictions Description
tenantId string(uuid) true none none

tenantNameChanged

{
  "tenantId": "67cdd743-a83f-404b-93ef-29dfe5bc2e31",
  "name": "The customer"
}

TO BE IMPLEMENTED

Properties

Name Type Required Restrictions Description
tenantId string(uuid) true none none
name string true none none

error

{
  "code": "string",
  "message": "string"
}

TO BE IMPLEMENTED If the callback failes, this error object should be returned. When the Simployer Webhhok Integration delivery state is not OK, Simployer will provide the latest error code and message through the webhook integration management API.

Properties

Name Type Required Restrictions Description
code string false none none
message string false none none

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",
      "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",
  "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
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. Possible 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
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]