Kennisbank Youforce API & bestandsuitwisseling

Dit document beschrijft de 'Ubeeo ATS - Visma Raet Learning API’-connector. Een koppeling gebaseerd op de Visma Raet Learning API.

Dit document beschrijft de ‘ProActive - Visma Raet IAM API’-connector. Een koppeling gebaseerd op de Visma Raet IAM API.

Dit document beschrijft de ‘PlusPort - Visma Raet Learning API’-connector. Een koppeling gebaseerd op de Visma Raet Learning API.

This document described the ‘mijnLMS - Visma Raet Learning API’-connector. This connector has been built on top of the Visma Raet Learning API.

This document describes the ‘De leerrekening (EduBookers) - Visma Raet Learning API’ - connector. This connector has been built on top of the Visma Raet Learning API.

Dit document beschrijft de ‘Dialog - Visma Raet Learning API’-connector. Een koppeling gebaseerd op de Visma Raet Learning API.

Dit document beschrijft de ‘AppicalNow - Visma|Raet Learning API’-connector. Een koppeling gebaseerd op de Visma Raet Learning API.

With the documents endpoint files like certificates and other kind of documents can be uploaded for an employee to the Visma Personal File System (Personeelsdossier).  The API supports the following types of documents certificate (Certificaat) diploma (Diploma) career agreement (Loopbaan afspraak) career mail (Correspondentie loopbaan) career other (Overige loonbaan documenten) appraisal Review (Beoordelingsgesprek) performance Review (Functioneringsgesprek)  As-synchronized file upload Learning systems can upload files, like certificates, diplomas for individual employees to the Personal File System of Visma Raet. The file upload is an a-synchronized process. After the file is uploaded the consumer will receive a ticket Id, which can be used to monitor the process of the file upload.     Endpoints The API supports the following type of documents: API endpoint Personal file system endpoint Document type Description learning/v1.0/employees/ {personCode}/documents/certificate certificaat Certificaat learning/v1.1/employees/ {personCode}/documents/certificate certificaat Certificaat learning/v1.1/employees/ {personCode}/documents/diploma diploma Diploma learning/v1.1/employees/ {personCode}/documents/appraisalReview beoordelingsGesprek Beoordelingsgesprek learning/v1.1/employees/ {personCode}/documents/performanceReview functioneringsGesprek Functioneringsgesprek learning/v1.1/employees/ {personCode}/documents/careerAgreement loopbaanafspraken Loonbaan afspraken learning/v1.1/employees/ {personCode}/documents/careerMail corrLoopbaan Correnspondentie loopbaan learning/v1.1/employees/ {personCode}/documents/careerOther ovLoopbaan Overige loonbaan documenten   Note: v1.1 is using Content-Type: multipart/form-data and supports the other document types as well. v1.0 is using Content-Type: multipart/related and supports only certificates. We are advice you the use the latest version of an endpoint   To upload a document you need to use the POST method. For example  POST https://api.youforce.com//learning/v1.1/employees/{personCode}/documents/diploma for uploading a diploma to the Personal File System of Visma Raet. The endpoint returns a  ticketId  . The file will be stored in a standard folder for diplomas (see table for the other endpoints) The API will automatically upload the file to the Personal File System. This is an a-synchronized process with an automatic retry mechanism in case the file systems is not available. The retry mechanism will try to upload the file in a maximum of 6 hours. After this period the file will be rejected with a message. Also if the file is too big (maximum 4 Mb) or isn’t a PDF file, the upload will be rejected. GET documents/{TicketId}/status Endpoint for getting the status of the file upload. The endpoint will return the status of the file. After the file is processed successfully the status Complete is returned. Examples version 1.1 (all document types) Use POST request with multipart/form-data content type. Replace the PersonCode in the URL with the Id of the employee Use the authentication token received from the authentication endpoint Replace the tenant code with the tenant code of the client Give the document a proper description The field validFrom is optional. If it's empty the system date will be used as default The content-type for the file is  application/pdf Other type of files will be rejected by the API. The file size is also limited to a maximum of 4 Mb   Response Example of the response. HTTP/1.1 200 Content-Type: application/json { "ticketId": "7ca486f6-c730-4d50-a2ec-31a3a1373366", "description": "Example description", "size": 77491, "tenantId": "4028868", "creationDateTime": "2022-04-01T13:53:30.3985949", "status": "InProgress", "errorMessages": [] }   version 1.0 (certificates only) Use POST request with multipart/related content type with the first part having metadata in json format and the second one having a file. Replace the PersonCode in the URL with the Id of the employee Use the authentication token received from the authentication endpoint Replace the tenant code with the tenant code of the client Give the document a proper description The content-type of the metadata is application/json The content-type for the file is  application/pdf Other type of files will be rejected by the API. The file size is also limited to a maximum of 4 Mb     POST https://api.youforce.com/learning/V1.0/api/employees//documents/certificate Authorization: Bearer [YOUR_AUTH_TOKEN] Content-Type: multipart/related; boundary=boundary_not_used_within_file_content --boundary_not_used_within_file_content Content-Type: application/json; charset=UTF-8 { "Description":"YOUR_OWN_DESCRIPTION", "ValidFrom" : "2021-01-01" } --boundary_not_used_within_file_content Content-Type: application/pdf [PDF Content] --boundary_not_used_within_file_content--  Upload status After the file is posted to the API, the file upload can be followed with the status endpoint. Replace the TicketId in the URL with the  ticketId  from the previous API call. GET https://api.youforce.com/learning/v1.0/employees/documents/{{TicketId}}/status The API will return the status of the file upload. If the API could not upload the file, an error is shown as well. Response { "status": "Complete", "errorMessages": [] }

Filters Person endpoint The person endpoint supports the following query string parameters: changedAfter and  changedUntil  Date Time stamp filter: Date Time should be in UTC Format: YYYY-MM-DDTHH:MM:SS.sssZ Returns (active) person records that have changed within the provided date-time range. https://api.raet.com/learning/v1.0/persons?changedAfter=2020-06-01T00:00:01.000Z&changedUntil=2020-06-30T00:00:01.000Z   Employee endpoint THIS ENDPOINT HAS BEEN DEPRECATED Use the endpoints Person and Employment.   Employment endpoint The employee endpoint supports the following query string parameters   Parameter description personCode   Returns a list of employment records filtered by personId https://api.youforce.com/learning/v1.0/employments?personCode=191166 personId Returns a list of employment records filtered by personId https://api.youforce.com/learning/v1.0/employments?personId=191166 changedAfter and  changedUnil  Date Time stamp filter: Date Time should be in UTC Format: YYYY-MM-DDTHH:MM:SS.sssZ Returns (active) person records that have changed within the provided date-time range. https://api.raet.com/learning/v1.0/employments?changedAfter=2020-06-01T00:00:01.000Z&changedUntil=2020-06-30T00:00:01.000Z​     Cost allocation endpoint The cost allocation endpoint supports the following query string parameters   Parameter Description Id Returns the cost allocation by id https://api.youforce.com/learning/v1.0/costAllocations/100028%201%200   Organization unit endpoint The organizationUnits endpoint supports the following query string parameters   Parameter Description shortName Returns a list of all organizationUnit records filtered by shortName https://api.youforce.com/learning/v1.0/organizationUnits?shortName=1010A changedAfter and  changedUnil  Date Time stamp filter: Date Time should be in UTC Format: YYYY-MM-DDTHH:MM:SS.sssZ Returns (active) person records that have changed within the provided date-time range. https://api.raet.com/learning/v1.0/organizationUnits?changedAfter=2020-06-01T00:00:01.000Z&changedUntil=2020-06-30T00:00:01.000Z​ Role assignment endpoint The roleAssignments endpoint supports the following query string parameters   Parameter Description personId Returns a list of all role assignment records filtered by personId https://api.youforce.com/learning/v1.0/roleAssignments?personId=1010A shortName Returns a list of all role assignment records filtered by shortName https://api.youforce.com/learning/v1.0/roleAssignments?shortName=MGR changedAfter and  changedUnil  Date Time stamp filter: Date Time should be in UTC Format: YYYY-MM-DDTHH:MM:SS.sssZ Returns (active) person records that have changed within the provided date-time range. https://api.raet.com/learning/v1.0/roleAssignments?changedAfter=2020-06-01T00:00:01.000Z&changedUntil=2020-06-30T00:00:01.000Z​ Job profile endpoint The jobProfiles endpoint supports the following query string parame   Parameter Description shortName Returns a list of all jobProfile records filtered by shortName https://api.youforce.com/learning/v1.0/jobProfiles?shortName=1010A changedAfter and  changedUnil  Date Time stamp filter: Date Time should be in UTC Format: YYYY-MM-DDTHH:MM:SS.sssZ Returns (active) person records that have changed within the provided date-time range. https://api.raet.com/learning/v1.0/jobProfiles?changedAfter=2020-06-01T00:00:01.000Z&changedUntil=2020-06-30T00:00:01.000Z​ Pagination of the result set To reduce the load of an endpoint each endpoint supports paging. If the results of an endpoint contain more than 500 records, the results set will end with a nextLink tag. The nextLink indicates that there are more pages to load. If there is no nextLink at the end of the page, it means that it’s the last page of the result set. The default value is 500 records, but it is possible to use less than that.   Hieronder een voorbeeld waarbij 125 records per pagina wordt opgehaald.       GET https://api.youforce.com//iam/v1.0/persons?take=125       In de nextLink wordt deze page size overgenomen, zodat ook de vervolg pagina's maximaal 125 records bevat.      U kunt een page size tot maximaal 1000 records opvragen.    Delete a record After a record is deleted in the core system, the API will return the record with his id and the flag isDelete = true. This delete means that the whole record including all version are delete. For example       { "id": "907624", "isDeleted": true, "shortName": "907624" }        

Domain model       The Learning model     Data mapping Employee person details attribute description HR Core Beaufort id Unique id for the Person row within the tenant P01001 - Persoonsnummer personId Unique id for the Person row within the tenant P01001 - Persoonsnummer personCode The logical person code of the employee P01001 - Persoonsnummer Initials The initials of the employee. P00303 - Voorletters firstNames The official given names of the employee as stored in the HR Core system P01002 - Voornamen KnowAs The name which is used by the employee as his first name P01003 - Roepnaam lastNameAtBirth The last name at birth of the employee. Also known as the family name P00301 - Geboortenaam lastNameAtBirthPrefix The prefix of the last name at birth P00302 - Geboortenaam-voorvoegsels lastName The last which is currently used  by the employee as his last name P01008 - Samengestelde naam lastNamePrefix The prefix of the last name as used currently P01009 - Samengestelde naam-voorvoegsels nameAssembleOrder Code of the assemble order that the core system uses for the last name.    value E: birthname B: partnername & birthname C: birthname & partnername P: partnername P00304 - Gebruik achternaam partnerName The partner last name P00390 - Partner-naam partnerNamePrefix The prefix of the partner last name P00391 - Partner-voorvoegsels titlePrefix The formal title which will be used as a prefix before the name like Doctor, Professor, et cetera P00305 - Titulatuur voor de naam titleSuffix The formal title which will be used as postfix after the name like MSc or Master of Science P03937 - Titulatuur achter de naam gender Gender of the person. Supported values are Male / Female. Note: other type of genders will be shown as Not Known P00330 - Geslacht Mapping details: M → Male V, F → Female Other values will shown as Not Known birthDate Date of birth P00321 -Geboorte datum deceased Indicated if the employee deceased  Based on the date of deceased. If the employee is deceased the boolean is set to True 0302568 - Datum overlijden UserUID Digital Identity of the user from the portal Ping ID directly from the portal emailAddresses type address List of the addresses of the employee.  The fields are: type like Business, Private, et cetera address   Business: P01035 - E-mail adres werk Prive: P01034 - E-mail adres prive Addresses type street houseNumber houseNumberAdditional locationDesignation postalCode city region country effectiveDate List of the addresses of the employee.  The fields are: type like Home, Post, et cetera street name house number house number additional Location designation Postal code City Region Country code   Home: P01014 straatnaam P01016 Huisnummer P01018 Huisnummer toev P01020 Postcode P01022 Plaatsnaam P01024 Land P01012 adres m.i.v. Postal: P00365 straatnaam P00367 huisnummer P00368 huisnummer toev P00313 postcode P00308 plaatsnaam P00847 land P01011 Adres m.i.v. phoneNumbers type number list of phone numbers of the employee type like Business, Home, Mobile, et cetera number   Home: P01027 - telefoonnr woonadres Mobile : P01036 - Telefoonnr mobiel Business :P01037 - Telefoonnr werk     Employee employment details     HR Core Beaufort hireDate The hire date of the employment P00322 - Datum in dienst dischargeDate The end date or discharge date of the employment. P00830 - Datum uit dienst originalHireDate The first hire date or original hire date of an employee within the organization. P00834 -Datum in dienst CAO employmentType Type of employment with a short name for type like Internal employee, contractor, "Wachtgelder" P01102 - Soort arbeidsrelatie jobProfile job profile code of the employment The job profile is a code that refers to the entity job profile P01107 - Primaire functie organizationUnit organization unit of employment. The organization unit is a code that refers to the entity organization units P01106 - Hierarchische org. eenheid workingAmount amountOfWork unitOfWork periodOfWork Work amount of employment.  The amount of work Unit of work that specifies the amount of work like "hours", "days", et cetera Period of work like "week" or "month" amount of work = P01109 - Uren per week* *Beaufort supports only the amount of work in "hours" a "week" contractType Contract type of the employee. It is the code that refers to the entity contract type. P08259 - Code contract (on)bepaalde tijd classification Classification of the employee. It is the code that refers to the entity Classification. P01110 - Code doelgroep Payroll Client Code   P01103 - CEA-nummer Payroll Institution Code    P01104 - Instelling nummer Company PayrollClientCode and PayrollInsituationCode combined   bigNumber   P09165 - Big nummer   Cost allocations       Id Unique id of the cost allocation. the Id is unique within the entity and tenant. The id is generated by the system and can not changed by a user. Unique id of the cost allocation row PersonCode The unique id assigned to the employee Persoonsnummer employmentCode The code of the employment of the person Dienstverband volgnummer sequenceNumber Unique sequence number or row number of the cost allocation within the employee P01131 -regelnummer loonverdeling costTypeCode code of the cost type  P01133 - Kostensoort loonverdeling CostTypeName full name of the cost type Omschrijving kostensoort (referentie tabel) costCenterCode code of the cost center P01134 -Kostenplaats loonverdeling costCenterName full name of the cost center Omschrijving kostenplaats (referentie tabel) costUnitCode code of the cost unit P01135 - Kostendrager loonverdeling costUnitName full name of the cost unit Omschrijving kostendrager (referentie tabel) percentage percentage of the cost allocation P01132 - loonverdeling loonverdeling   Organisation units Attribute Description HR Core Beaufort id Technical ID of the organisation unit   P01061 shortName Code or short name of the Organization Unit P01061 fullName Name or full title of the Organization Unit FullName parentOrgUnit Code of the parent organization unit Organisatie eenheid > Onderdeel van organizationUnitType type or organisation unit code orgUnit Type isBlocked True of false   Address     PhoneNumber     CostCenterCode     Role assignment Attribute description HR Core Beaufort id Unique id of the role assignment. the Id is unique within the entity and tenant. The id is generated by the system and can not changed by a user. Id van het record OrganizationUnitCode Code van organisatorische eenheid P01061 - Operationele org.eenheid shortName The code of the role P01062 - Rol roleName Description of the role P01062 - Rol personCode reference to the person Reference to Person code personID reference to the person Reference to Person ID startDate  start date of the role assignment startDate endDate   endDate    Job Profile Attribute Description HR Core Beaufort shortName Job profile code or short name functie code fullName Job profile name functie naam JobFamily Job family code functiegroep code    

Swagger documentation The following swagger pages gives an overview of the endpoint: IAM endpoints    Filters Person endpoint The person endpoint supports the following query string parameters Parameter Description from and to  Date Time stamp filter: Date Time should be in UTC Format: YYYY-MM-DDTHH:MM:SS.sssZ Returns (active) person records that have changed within the provided date-time range. https://api.youforce.com/iam/v1.0/persons? from=2020-01-01T09:00:00.000Z&to=2020-01-01T14:00:00.000Z     Employee endpoint   THIS ENDPOINT HAS BEEN DEPRECATED Use the endpoints Person and Employment.   The employee endpoint supports the following query string parameters Parameter Description personCode    Returns a list of employee records filtered by personId https://api.youforce.com/iam/v1.0/employees?personCode=191166 personId Returns a list of employee records filtered by personId https://api.youforce.com/iam/v1.0/employees?personId=191166   organizationUnit Returns a list of all employee records filtered by organizationUnit id https://api.youforce.com/iam/v1.0/employees? organizationUnit=13612345 from and to Date Time stamp filter: Date Time should be in UTC Format: YYYY-MM-DDTHH:MM:SS.sssZ Returns (active) employee records that have changed within the provided date-time range. https://api.youforce.com/iam/v1.0/employees? from=2020-01-01T09:00:00.000Z&to=2020-01-01T14:00:00.000Z   Employment endpoint The employee endpoint supports the following query string parameters Parameter Description personCode   Returns a list of employment records filtered by personId https://api.youforce.com/iam/v1.0/employments?personCode=191166 personId Returns a list of employment records filtered by personId https://api.youforce.com/iam/v1.0/employments?personId=191166 organizationUnit Returns a list of all employment records filtered by organizationUnit id https://api.youforce.com/iam/v1.0/employments? organizationUnit=13612345   from and to Date Time stamp filter: Date Time should be in UTC Format: YYYY-MM-DDTHH:MM:SS.sssZ Returns (active) employment records that have changed within the provided date-time range. https://api.youforce.com/iam/v1.0/employments? from=2020-01-01T09:00:00.000Z&to=2020-01-01T14:00:00.000Z   Assignment endpoint The assignments endpoint supports the following query string parameters   Parameter Description personId Returns a list of assignment records filtered by personId https://api.youforce.com/iam/v1.0/assignments?personId=191166 from and to Date Time stamp filter: Date Time should be in UTC Format: YYYY-MM-DDTHH:MM:SS.sssZ Returns (active) assignment records that have changed within the provided date-time range. https://api.youforce.com/iam/v1.0/assignments? from=2020-01-01T09:00:00.000Z&to=2020-01-01T14:00:00.000Z   Cost allocation endpoint The cost allocation endpoint supports the following query string parameters   Parameter Description   Id Returns the cost allocation by id https://api.youforce.com/iam/v1.0/costAllocations/100028%201%200   Person code Returns a list of cost allocations for a specific person. The list could contain records for different employments of the employee https://api.youforce.com/iam/v1.0/costAllocations?personCode=100028     Organization unit endpoint The organizationUnits endpoint supports the following query string parameters Parameter Description shortName Returns a list of all organizationUnit records filtered by shortName https://api.youforce.com/iam/v1.0/organizationUnits?company=1010A from and to Date Time stamp filter: Date Time should be in UTC Format: YYYY-MM-DDTHH:MM:SS.sssZ Returns (active) organization unit records that have changed within the provided date-time range. https://api.youforce.com/iam/v1.0/organizationUnits? from=2020-01-01T09:00:00.000Z&to=2020-01-01T14:00:00.000Z   Role assignment endpoint The roleAssignments endpoint supports the following query string parameters     Parameter Description personId Returns a list of all role assignment records filtered by personId https://api.youforce.com/iam/v1.0/roleAssignments?personId=1010A shortName Returns a list of all role assignment records filtered by shortName https://api.youforce.com/iam/v1.0/roleAssignments?shortName=MGR from and to Date Time stamp filter: Date Time should be in UTC Format: YYYY-MM-DDTHH:MM:SS.sssZ Returns (active) employee records that have changed within the provided date-time range. https://api.youforce.com/iam/v1.0/roleAssignments? from=2020-01-01T09:00:00.000Z&to=2020-01-01T14:00:00.000Z   Job profile endpoint The jobProfiles endpoint supports the following query string parameters Parameter Description shortName Returns a list of all jobProfile records filtered by shortName https://api.youforce.com/iam/v1.0/jobProfiles?shortName=1010A from and to Date Time stamp filter: Date Time should be in UTC Format: YYYY-MM-DDTHH:MM:SS.sssZ Returns (active) jobProfile records that have changed within the provided date-time range. https://api.youforce.com/iam/v1.0/jobProfiles? from=2020-01-01T09:00:00.000Z&to=2020-01-01T14:00:00.000Z  

Domain model   The IAM model       Data mapping Person  The personal details of an employee. This could also contains person without a (active) employment. HR Core Beaufort: Persoon id The globally unique id assigned to an employee 32789 P01001 Persoonsnummer personCode The unique id assigned to the employee 32789 P01001 Persoonsnummer personId The globally unique id assigned to an employee 32789 P01001 Persoonsnummer initials The initials of the employee A.B. P00303 Voorletters firstNames The official given names of the employee Amy Beatrice P01002 Voornamen knownAs The name which is used by the employee as first name Amy P01003 Roepnaam lastNameAtBirth The last name at birth of the employee. Also known as the family name Vries P00301 Geboortenaam lastNameAtBirth Prefix The prefix of the employee's last name at birth de P00302 Geboortenaam voorvoegsels lastName The last name used by the employee at present Vries - Van Eijck P01008 Samengestelde naam lastNamePrefix The prefix of the employee's last name at present de P01009 Samengestelde naam voorvoegsel nameAssemble Order Code of the assemble order used by the core system for the last name. C P00304 Gebruik achternaam partnerName The last name of the employee's partner Eijck P00390 Partner naam partnerName Prefix The prefix of the partner's last name Van P00391 Voorvoegsel partner titlePrefix Formal title prefix drs. P00305 Titulatuur voor de naam titleSuffix Formal title suffix Msc P03937 Titulatuur achter de naam gender Gender of the employee Female P00330  Geslacht dateOfBirth Date of birth 1986-12-02 P00321 Geboorte datum deceased This field indicates if an employee is deceased when false the property is not returned true P01005  Datum overlijden UserUID Digital Identity of the user from the portal bdd38fd2-FAKE-4313-FAKE-671c786d0758   Ping ID directly from the portal youforceAccount Indicaties if the person do have a user account J P15013 Youforce gebruiker phoneNumbers List of phone numbers and types Home +3188 123 45 67 P01027 Telefoonnummer woonadres Business +3188 345 67 89 P01037  Telefoonnummer werk Mobile +316 12 34 56 78 P01036 Telefoonnummer mobiel emailAddresses List of email addresses of the employee Business b.user@example.com P01035 E-mail adres werk Private p.user@example.com P01034 E-mail adres privé Addresses List of addresses   type Home street Kerkstraat P01014  Straat houseNumber 1 P01016 Huisnummer houseNumber Addition C P01018  Huisnummer toevoeging postalCode 1234 AB P01020  Postcode city Amersfoort P01022  Woonplaats country NL P01024 Woonland effectiveDate 2023-08-01 P01012  Adres m.i.v.   type Postal street Poststraat P00365 Straatnaam houseNumber 1 P00367 Huisnummer houseNumber Addition A P00368 Huisnummer toevoeging postalCode 1234 AB P00313 Postcode city Amersfoort P00308 Plaatsnaam country NL P00847 Land effectiveDate 2023-08-01 P00847 Adres m.i.v.     Employments  The employment of the employee. A person can have multiple employments at the same time.   HR Core Beaufort: Dienstverband employmentCode The code of the employment 1 P01101  Volgnummer dienstverband originalHireDate The first hire date or original hire date of an employee within the organization. This date is important for the tenure or working anniversary of an employee 2010-10-01 P00834 Datum in dienst CAO dischargeDate The end date or discharge date of the employment. This is always an "up to and including" date. In case of no values the field will not be returned as part of te response body 2018-12-31 P00830  Datum uitdienst hireDate Date of hire for the employment 2017-05-01 P00322 Datum in dienst classification Cost allocation of the employment 123 P01110 Code doelgroep employmentType Code of the employment type 4 P01102 Soort arbeidsrelatie workingAmount Working amount of the employment. amountOfWork: numeric value representing the work amount 40   P01109 Uren per week unitOfWork: unit of work that specifies the unit for the amount Hours P01109 Uren per week periodOfwork: indicates the period for which amountOfWork and unitOfWork are defined Day Week Month Quarter P01109 Uren per week jobProfile The job profile code 9909 DEV P01107 Primaire functie organizationUnit The organization unit id 1234567 ZKH P01106 Hiërarchisch organisatorische eenheid Payroll Client Code     P01103  CEA-nummer Payroll Institution Code      P01104 Instelling nummer Company PayrollClientCode and PayrollInsituationCode combined       Assignments  The possible assignments of an employee for their employment. In example, employee works is assigned to a different department as temporary replacement or to help another department without changing his own employment. HR Core Beaufort: Inzet id Unique id of the role assignment. the Id is unique within the entity and tenant. The id is generated by the system and can not changed by a user.   100 1 12 1234 20200923 system field Unique id of the assignment personCode The unique id assigned to the employee 32789 P01001 Persoonsnummer personId The globally unique id assigned to an employee 32789 P01001 Persoonsnummer employmentCode The code of the employment of the person 1 P01101  Volgnummer dienstverband startDate The start date of the assignments 2017-05-01 P01125 Ingang inzet endDate The end date of the assignment. This is always an "up to and including" date. In case of no values the field will not be returned as part of te response body 2017-11-30 P01126 Einde inzet jobProfile Job title or job profile code of the assignment. DEV P01122 Operationele functie organizationUnit The organization unit id of the assignment. PD P01121 Operationele organisatorische eenheid workingAmount Working amount of the employment.. amountOfWork: numeric value representing the work amount 40   P01123 Uren inzet per week unitOfWork: unit of work that specifies the unit for the amount Hours P01123 Uren inzet per week periodOfwork: indicates the period for which amountOfWork and unitOfWork are defined Week P01123 Uren inzet per week costCenter The cost center of a Assignment     P01128 - Kostenplaats Inzet costUnit The cost unit of an Assignment     P01129 - Kostendrager Inzet costType The cost type of an Assignment     P01127 - Kostensoort Inzet type Type of assignment     P01123 - Soort Inzet   Cost allocation  The cost allocation of an employee. The cost allocations are generated by Beaufort. An employee can multiple cost allocations. Mostly the cost allocation with sequence number 0 or the one with the highest percentages  is the main cost allocation.  HR Core Beaufort: Loonverdeling id Unique id of the cost allocation. the Id is unique within the entity and tenant. The id is generated by the system and can not changed by a user.   32789 1 0 system field Unique id of the assignment PersonCode The unique id assigned to the employee 32789   Persoonsnummer employmentCode The code of the employment of the person 1   Dienstverband volgnummer sequenceNumber Unique sequence number or row number of the cost allocation within the employee 0 P01131 regelnummer loonverdeling costTypeCode code of the cost type  4004 P01133 Kostensoort loonverdeling CostTypeName full name of the cost type Loonkosten   Omschrijving kostensoort (referentie tabel) costCenterCode code of the cost center 4000 P01134 Kostenplaats loonverdeling costCenterName full name of the cost center KNO Operaties   Omschrijving kostenplaats (referentie tabel) costUnitCode code of the cost unit 4100 P01135 Kostendrager loonverdeling costUnitName full name of the cost unit KNO   Omschrijving kostendrager (referentie tabel) percentage percentage of the cost allocation 100 P01132 loonverdeling loonverdeling   Organization Units  The organization structure describes the organization in terms of business unit, departments, divisions, etc. and how these are related to each other. Based on the organization structure it's clear “how” units are related and "which" department is responsible for "what". HR Core Beaufort: Organisatie eenheden validFrom The date from which the record is valid 2020-04-01 N/A Data niet beschikbaar in de API validUntil The date from which the record is no longer valid. Will contains a default date in case no “end date“ has been defined for the record. 2020-05-01 9999-12-31 N/A Data niet beschikbaar in de API id Unique id of the organization unit PD P01061 Code organisatorische eenheid shortName Code or short name of the Organization Unit PD P01061 Code organisatorische eenheid fullName Name or full title of the Organization Unit Product Development   Naam organisatorische eenheid parentOrgUnit Code of the parent organization unit PD_EU   Organisatie eenheid > Onderdeel van organizationUnitType Type of organization unit Divisie   Type organisatorische eenheid   Role Assignments  The role assignment describes "who" is responsible for “what“ and “when“ within the organization unit. HR Core Beaufort: Rol toewijzing validFrom The date from which the record is valid 2020-04-01 N/A Data niet beschikbaar in de API validUntil The date from which the record is no longer valid. Will contains a default date in case no “end date“ has been defined for the record. 2020-05-01 9999-12-31 N/A Data niet beschikbaar in de API id Unique id of the role assignment. the Id is unique within the entity and tenant. The id is generated by the system and can not changed by a user. R1 - N/A BO4 - 78000 1877 MGR 20200101   Id van het record personId The unique id assigned to the employee 10017   Persoonsnummer van de houder van de rol organizationUnit The organization unit id of the assignment. 459   Code van organisatorische eenheid shortName The code of the role MGR   Code van de rol personCode The code of the person 12345   Persoonsnummer van de houder van de rol (gelijk aan personID) startDate Start date of role assignment 2013-04-17 N/A Data niet beschikbaar in de API endDate End date of role assignment 2020-01-31 N/A Data niet beschikbaar in de API   Job Profiles  All job profiles that have been defined within the tenant. HR Core Beaufort: Functie shortName Code or short name of the Job Profile SE Functie code fullName Name or full title of the Job Profile Software Engineer 5 Functie omschrijving jobFamily Code or short name of the Job Family PD5 Functie groep code validFrom The date from which the record is valid 2020-04-01 Data niet beschikbaar in de API validUntil The data from which the record is no longer valid. Contains a default date in case no “end date“ has been defined for the record. 9999-12-31 2020-05-01 Data niet beschikbaar in de API  

What is the Youforce API? Through the Youforce API you can in integrate data and therefore giving your customers: an up-to-date list of the latest HR information in your application automatic on- and off-boarding of employees in your application HR Core system Youforce consists of different HR modules. There is always an HR Core system in the center of every customer implementation storing the employee data. With the API's we only support  HR Core Public Online (a.k.a HR Core Beaufort Online)   For HR Core Public (a.ka. HR Core Beaufort On-premise) we offer access to data using the File API. Please contact a technical consultant. API library You can find the APIs at https://developers.youforce.com/api-library   

API Statuses Concept APIs with this status are still under development and the development team is still making changes. Only a sandbox is available to start testing and the API cannot be used with customer environments.  Controlled Available (CA) APIs (or API versions) with this status are not ready yet to be rolled out to the complete customer base: It is available to a few access partners Connections of an access partner to the customer environment (tenant) are put on a waiting list, and it will take time before the connection is accepted There can be functional limitations of these APIs Controlled Available APIs have the usual security and support level. General Available (GA) APIs (or API versions) with this status are available to all access partners. The API can be used by all customers who use any of the HR Core systems that are supported by this API. Deprecated The API (or API version) is being phased out. We do not accept any new connections on this API (version). We will ask our access partners to move to another interface API. See also your Service Level Agreement   Life cycle policy We aim to provide you with a policy for releases and support for older versions for a consistent and predictable experience. You can also find this information in the Service Level Agreement. Different types of changes The life cycle of any API products has dependencies on underlying products. Changes in those products may require changes to the API to support it. We distinguish between breaking changes and non-breaking changes. A breaking change is one that breaks the contract an API consumer depends on, either by a change in structure, behavior or semantics. The release and support strategy makes a clear distinction in how these are managed. Major releases At times Raet may need to make larger changes to the API. Reasons may be changes to legal requirements, adding a large new feature to the API or an change in other products the API depends on. In these cases Raet may create a new major release of the API. We strive to also keep major releases backward compatible as much as possible but this may not always be possible. In case of breaking changes In general Raet aims to have a maximum of one major release per year. Each major release will be supported for at least 24 months after releasing the next major version. As a client to our API you will have to adjust your software to follow the major releases of our API as they will impact your integration. You must update your software to support the new API version as older API versions will be decommissioned following the policy as outlined above. Minor releases A minor release will never contain breaking changes, the are used to deliver incremental changes. Minor versions will not be visible in the path of the API. Raet can install minor updates in the standard release windows or as part of a hotfix and will communicate the changes as part of the release notes. Since this does not impact any existing functionality, we do not provide side-by-side support for multiple minor versions of the same major version: a minor upgrade just replaces the previous version. As a consumer of the API it is up to you to decide if you start using the newly available features. Announcing major releases Each release of a major API version will be accompanied by communication about the support lifecycle of the current version in the release notes. When approaching the sunset-date for an API product, we will actively reach out to inform any customers still using it: Communication When Where Recipient Announcement At the release of the new major version. Includes the date of decommissioning the previous version. General release notes All recipients of general release notes.   At the release of the new major version. Includes the date of decommissioning the previous version. Developer portal Designated API contact persons 1st notification 6 months prior to decommissioning   Designated API contact persons 2nd notification 3 months prior to decommissioning   Designated API contact persons 3rd notification 1 months prior to decommissioning   Designated API contact persons   Usage limits We apply usage limits to ensure the availability of our services to all parties interacting with Youforce. These usage limits depend on your subscription. The following policies are determined per registered application:   Weekly Daily Continuous Quota - API calls* 2 hours per day   1000 API calls within the time window   7 days per month 2 hours per day   1000 API calls within the time window   40 times per month 6000 API calls per day, allowing to retrieve changes every 15 seconds Quota - authentication calls 7 successful authentication calls per month. 40 successful authentication calls per month. 400 authentication calls per month Concurrent rate-limiting (API calls in parallel) 1 1 3 Spike arrest policy (max number of API calls per minute) 100 calls per minute 100 calls per minute 100 calls per minute *For the base API the limit is 100 calls per minute Spike arrest details Spike arrest is the way we protect against traffic spikes. Our APIs and backend can handle a certain amount of traffic, and the Spike Arrest policy smooths the traffic to the general amounts. Spike Arrest’s behavior differs from what you might expect to see from the literal per minute values. Our default spike arrest is set to 100pm (100 requests per minute). That does not mean you can do 100 requests inside a 1-second. Spike Arrest smooths the number of full requests in a minute by dividing it into smaller intervals: Per-minute rates get smoothed into full requests allowed in intervals of seconds. For example, 100pm gets smoothed like this: 60 seconds (1 minute) / 100pm = 0.6-second intervals, or 1 request allowed every 0.6 seconds. A second request inside of 0.6 seconds will fail. Also, the 101st request within a minute will fail. When you exceed the policy, the API will return response code '429 - Too many requests' and you have to wait for the next time window.

  Getting started Choose an API product Go to the API Library page and select an API. The status of an API is displayed using the following labels: General: the API is available in production. Controlled: the API is available for a limited amount of users. Deprecated: the API is being phased out. We do not accept any new connections. Concept: the API is currently under development, but you are welcome to take a look. If you plan to use an API in production, view the API requirements for that API, and ensure that you comply. If you would like to know more about the different statuses of an API please go here . Create an account To use an Youforce API product, you must register and create an account. An account is quick to set up and is free of charge. You only need your phone and company address to register. To register and create an account: 1. Click Create an account. 2. Enter your details. (Please register with your company email). 3. You will receive an SMS on your mobile to confirm. Getting an application After login, you can go to Your Apps and see all applications you have access to. Creating applications on the developer portal is done at this moment with a ticket through support. Please go to the support section for details. As soon as the request is processed the application will show up in the developer portal. Authentication The received token can be different based on the identity provider used   We follow current industry standards and best practices. Authentication/authorization is no exception. As part of the Identity and Access Management Strategy for system-to-system integrations, our APIs are based OAuth 2.0 and the authorization grant Client Credentials. Every API consumer system will be provisioned in our API Gateway as a Client Application (App). Client ID and Client Secret will be provided to be used by Apps as credentials. Thus, Apps will be able then to authenticate and get an access token (JWT) within the response payload. Subsequent requests authorization will be based on that access token previously retrieved.   Get the access token In order to grant access to a target API, Apps must first authenticate against our Authorization Server. The request payload must include the content type header and the HTTP body must include the required Client Credentials. curl -X POST https://api.youforce.com/authentication/token -H 'Cache-Control: no-cache' -H 'Content-Type: application/x-www-form-urlencoded' -d 'client_secret= iPWF123nlk2XYgUHV&client_id=qX0X S456YY4kJtDY5drCeZ0XT7nS5GxA&grant_type=client_credentials' Below, a response payload example containing the access token and the expiration time which is 15 min. After that time Apps need to re-authenticate to get a new access token. { 'access_token':'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9. eyJUaWNrZXRJZCI6IitMZWhGdVh3T0V2RTdtYk c4U3IyIiwiVXNlcklkIjoiSUMxMTI2NjYiLCJNZXN zYWdlSWQiOjAsIkNvbXBhbnlJZCI6NDAyODA 5MCwiRXhwaXJhdGlvbiI6NzIwMCwibmJmIjoiMTUyMjE zMzU5MTYwOSIsImV4cCI6IjE1MjIxMz M4OTE2MDkifQ. wSZGjncy4_CH98RIBdhTr9FsMtIIkVtV 3tkRoWvlrQQ', 'token_type': 'BearerToken', 'expires_in': '899', } An authorized API request After the Apps has received a valid token, they are ready to perform requests to any of our Youforce APIs. Apps must use the Authorization header containing the access token. In addition, will need to mark every request with the Client ID, using a custom header for that purpose. Below, a fetching data request example: curl -X GET 'https://api.youforce.com/requests/v1.0/expensesRequests/' -H 'Cache-Control: no-cache' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9. eyJUaWNrZXRJZCI6IitMZWhGdVh3T0V2 RTdtYkc4U3IyIiwiVXNlcklkIjoiSUMxMTI2NjYiLCJNZXN zYWdlSWQiOjAsIkNvbXBhbnlJZCI6NDA yODA5MCwiRXhwaXJhdGlvbiI6NzIwMCwibmJmIjoiMTUyMjE zMzU5MTYwOSIsImV4cCI6IjE1MjIxMzM4OTE2MDkifQ. wSZGjncy4_CH98RIBdhTr9FsMtIIkVtV3tkRoWvlrQQ' -H 'X-Client-Id: qX0XS456YY4kJtD Y5drCeZ0XT7nS5GxA' Authentication Error Response The error payload shown below, describes the 401 error response Apps will receive in case of any authentication error. { 'message': 'Authentication Error', 'correlationId': 'rrt-0d027480041e2a148-a-de-7885-572449-1', 'issuedAt': '2018-03-27T07:44:25.554Z', 'errorCode': 'unauthorized', 'statusCode': 401 } Miss use reasons for having authentication errors are: Wrong credentials Expired credentials Unauthorized access tokens Invalid Expired HTTPs support Our API's domain is secured by using digicert (SHA2) certificates, a world wide industry-recognized provider. Protocol TLS 1.2 (only) Key exchange ECDHE RSA with X25519 Cipher AES_256_GCM All HTTP Requests will be refused with a Not Found 404 error response.   Request header & responses Request headers Our APIs have headers in common Header Name Description Cache-Control The Cache-Control general-header field is used to specify directives that MUST be obeyed by all caching mechanisms along the request/response chain. In our authentication request the header is mandatory with the value Cach-Control: no-cache Content-Type The content type of the resource in case the request content in the body. Example: Content-Type: application/x-www-form-urlencoded Authorization The information required for request authentication Accept The Accept request-header field can be used to specify certain media types which are acceptable for the response. Example: Accept: text/plain X-raet-tenant-id This header is used to specify for which tenant the data is requested. For tokens with single tenant access this header is not mandatory x-raet-tenant-id: 1234567 Response codes Our APIs have response codes in common. Type Responses Situation Succes Codes 200 OK Synchronous read, update, and delete operations 201 Created Synchronous create requests   202 Accepted A-synchronous operations   204 No Content Referring to non-existing entity (e.g. after delete)   Redirection Codes 304 Not Modified Resource has not been modified. 308 Permanent redirect Resource has permanently moved.   Invalid Request Errors 400 Bad request Bad Request (e.g. validation errors) 401 Unauthorized Not Authorized: Missing or invalid access token   403 Forbidden Not Authorized: Authenticated, but user has no access to the API   404 Not Found Invalid  URL: Item does not exist (anymore). The canonical identifier (collection/{canonical id}) cannot be found. Not Authorized:  Authenticated, access to api, but user has no access to to the resource (data authorization).  From a security standpoint we don't expose the reason why the object could not be found because an  attacker can use this to figure out the internals of our system.   409 Conflict Concurrency problem: Record changed by another user   Server Errors 500 Internal server error Server Error (e.g. database failure, event could not be send) 503 Service unavailable Server Error (resource temporary not available)