Kennisbank Youforce API & bestandsuitwisseling

Note: De Recruitment api heeft de status Controlled Available en is enkel nog beschikbaar in overleg met Visma Raet.   Artikel inhoud   Domein model  De Recruitment api bevat uitsluitend de basis medewerker- en organisatiegegevens. Middels deze API heeft de recruitment system inzicht in de organisatiestructuur en de huidige medewerker als mogelijk potentiële kandidaten binnen het recruitment proces.   Note: De vacature en het onboarden van de nieuwe medewerker maken nog geen onderdeel uit van deze API.   Het model   Entiteiten en velden   Person (Persoon) Id / personId Technical and unique id. the Id is unique within the entity and tenant. The id is owned by the core system and can not changed by a user P01001 - Persoonsnummer PersonCode The logical code or number of the employee. P01001 - Persoonsnummer Initials The initials of the employee. Format depends P00303 - Voorletters firstNames The official given names of the employee as stored in the HR Core system P01002 - Voornamen KnownAs 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. The assemble order is depending on the core system and the logic behind it. 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 conform the ISO/IEC 5128 standard (0) Not known (1) Male (2) Female (9) Not applicable P00330 - Geslacht M = Man / Male V = Vrouw / Female dateOfBirth Date of Birth P00321 -Geboorte datum deceased Indicated if the employee deceased Note: most core systems have a date field. In the API this will be translated to boolean P01005 - Datum overlijden UserUID Digital Identity of the user from the portal PORTAL : Ping ID emailAddresses List of the email addresses of the employee. The fields are: type like Business, Private, etc. address Business: P01035 - E-mail adres werk Private: P01034 - E-mail adres prive phoneNumbers 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 FaxBusiness : P01039 Faxnr werk FaxHome : P01038 Faxnr prive Addresses list of addresses of the employee. The address fields are: addressType like Home, Post, etc. streetName Number streetNumberAdditional postalCode city country Home: P01014 straatnaam P01016 Huisnummer P01018 Huisnummer toev P01020 Postcode P01022 Plaatsnaam P01024 Land Postal: P00365 straatnaam P00367 huisnummer P00368 huisnummer toev P00313 postcode P00308 plaatsnaam P00847 land     Employment (Dienstverband) Id / employmentId Technical and unique id. the Id is unique within the entity and tenant. The id is generated by the system and can not changed by a user. Object Id = "PersonCode" + ContractCode PersonCode / PersonId Person code to which the employment is related P01001 - Persoonsnummer employmentCode / ContractCode / ContractId Code of the contract P01101 - volgnr dienstverband PayrollClientCode Logical code of the payroll client. Filter option for Row Authorisation (configuration API) [P01103 Opdrachtgever] PayrollInstitutionCode Logical code of the payroll Institution. Filter option for Row Authorisation (configuration API) [P01104 Instelling] hireDate The hire date of the employment P00322 - Datum in dienst dischargeDate The end date or discharge date of the employment. This is always an "up to and including" date. In unknown the field will not be visible in the API P00830 - Datum uit dienst originalHireDate The first hire date of original hire date of an employee within the organization. This date is important for the tenure or working anniversary of an employee P00834 -Datum in dienst CAO employmentType Type of employment like Internal employee, contractor, "Wachtgelder" Filter option for Row Authorisation (configuration API) P01102 - Soort arbeidsrelatie contractType Type of the contact like indefinite period ('Onbepaalde tijd') or given time ('bepaalde tijd') P08259 - Code contract (on)bepaalde tijd jobProfile Official job title or job profile of the employment. The Job profile contains the following details: shortName: Code or short name of the job profile P01107 - Primaire functie classification group or classification of the employment. Generic field Filter option for Row Authorisation (configuration API) P01110 - Code doelgroep organizationUnit organization unit Id of employment. The Id is a reference to the entity org units P01106 - Hierarchische org. eenheid workingAmount Work amount of employment. amountOfWork: the amount of work unitOfWork: Unit of work that specifies the amount of work like "hours", "days", et cetera periodOfWork: Period of work like "week" or "month" parttimePercentage P01109 - Uren per week P00404 percentage deelbetrekking   Organisation unit (Organisatie-eenheid) id Technical and unique id of the organization Unit. the Id is unique within the entity and tenant. The id is generated by the system and can not changed by a user. ID shortName Code or short name of the organizational unit OE Code fullName Name of the organization unit OE naam parentOrgUnit reference to the parent organizational unit. Empty means that it is organizational unit on the highest level in the company ParentID organisationUnitTpe Type of the organization Unit   address Address of the organisation Unit - Address - street - number - numberAdditional - postalCode - city OE Adres costCenter default cost center of the organisation unit. Kostenplaats IsBlocked Indicates if the Organization unit is block for adding new employees. note: it is possible there are still employee referring to this Org Unit. blocked/inactive   Role assignment (roltoewijzing) id Technical and unique id of the role assigment. the Id is unique within the entity and tenant. The id is generated by the system and can not changed by a user. object ID PersonID / personCode Technical ID of the Person Persoonsnummer shortName Short name of the role the person will have for this organization, like Manager, HR Professional, Director. P01062 - Rol organisationUnit Id of the organisation Unit P01061 - Operationele org.eenheid startDate Start date from which the role assignment is valid for that employee P01063 - ingangsdatum roltoewijzing endDate end date until when the role assignment is valid P01064 - einddatum roltoewijzing   Job profile (functie) id / shortName Unique id of the Job profile. the Id is unique within the entity and tenant. P02301 - Code functie fullName Name of the Job Profile P02302 - Omschrijving functie jobFamily Job family to which the job profile belongs P02305 - Code Functiegroep   User (Youforce user account) Id / UserUID Ping Id or User Id which be used for the SSO solution of Visma Raet Ping ID SourceId Youforce user name Gebruikersnaam IdentityId Identity of the user on the local network Identity

De learning API beschikt over een autorisatie mechanisme waarmee bepaald kan worden tot welke medewerkers en datasets een learning systeem toegang heeft.  Het autorisatie mechanisme bestaat uit de volgende onderdelen:   Autorisatie op basis van API scopes Door het activeren van scopes kunnen externe systemen toegang krijgen tot één of meerdere endpoint en dataset. De scopes zijn vooraf door Visma Raet bepaald en omvatten één of meerdere endpoints, dataset en/of acties. Autorisatie op medewerkers  Met behulp van autorisaties filters kan worden bepaald welke medewerkers in de API beschikbaar komen.  Met dit document willen wij u informeren over de mogelijkheden van deze autorisatievormen in de API. Beide autorisatie mechanismes moeten door een consultant ingericht worden.     Autorisatie op basis van API scopes In de Visma developer portal zijn per API één of meerdere scopes gedefinieerd.  Door het activeren van deze scope krijgt een extern systeem toegang tot één of meerdere endpoint en/of data set. Binnen de API worden de volgende scopes onderscheiden.     Scope Omschrijving Endpoints Invitation_only Scope noodzakelijk om de API te kunnen activeren. Tijdens het activering proces wordt de contractafspraken gecontroleerd en vastgelegd.  Deze scope geeft nog geen toegang tot enige vorm van data maar is noodzakelijk voor de onboarding van klanten op de API of applicatie - Get_Basic Get basic data zoals medewerker- & organisatiedata GET persons GET employments GET employees GET assignments GET organizationUnits GET roleAssignments GET jobProfiles Upload_documents Upload van documenten zoals certificaten, diploma's, etc naar het Youforce personeelsdossier van de medewerker POST documents/xxxxx zoals  POST documents/diploma POST documents/certifcate ect GET documents/{ticketId}/status  GetPrivateContactDetails Voegt de privé contactgegevens aan de endpoint Person & Employee, zoals post- en woonadres, telefoonnummer vast & mobiel en het email adres. GET persons GET Employees   Dit betreft de volgende gegevens: ADRESGEVENS Home: P01014 straatnaam P01016 Huisnummer P01018 Huisnummer toev P01020 Postcode P01022 Plaatsnaam P01024 Land Postal: P00365 straatnaam P00367 huisnummer P00368 huisnummer toev P00313 postcode P00308 plaatsnaam P00847 land TELEFOONNUMMERS Home: P01027 - telefoonnr woonadres Mobile : P01036 - Telefoonnr mobiel EMAILADRES Prive: P01034 - E-mail adres prive   Uw consultant kan u helpen bij het activeren / deactiveren van deze scopes binnen de API.     Autorisatie op basis van autorisatie filters De autorisatie filters hebben betrekking op welke medewerkers zichtbaar zijn in de API. Standaard worden altijd alle medewerkers getoond in de API. Bij het activeren van de API kan een consultant filters inrichten zodat maar een beperkte groep medewerkers via de API beschikbaar komen.   Filteren in de API is mogelijk op de volgende Beaufort velden: P01102- Soort Arbeidsrelatie  P01103- Opdrachtgever  P01104- Instelling  P01110 - Code doelgroep  P05041 - Selectie rubriek Domain API - Learning  Een veel voorkomen filter is bijvoorbeeld op Soort Arbeidsrelatie waarbij alleen eigen medewerkers in het extern systeem opgenomen worden.  Maar ook een filter op de combinatie Opdrachtgever / Instelling geeft u de mogelijkheid om de medewerkers van één of meerdere specifieke instellingen in de API op te nemen.   Uw consultant kan u helpen bij het inrichten of wijzigen van de autorisatie filters.        

Note: De WFM api  is controlled available en is nog niet beschikbaar voor algemeen gebruik. De WFM API beschikt over een autorisatie mechanisme waarmee bepaald kan worden tot welke medewerkers en datasets een Workforce Management systeem toegang heeft.  Het autorisatie mechanisme bestaat uit de volgende onderdelen:   Autorisatie op basis van API scopes Door het activeren van scopes kunnen externe systemen toegang krijgen tot één of meerdere endpoint en dataset. De scopes zijn vooraf door Visma Raet bepaald en omvatten één of meerdere endpoints, dataset en/of acties. Autorisatie op medewerkers  Met behulp van autorisaties filters kan worden bepaald welke medewerkers in de API beschikbaar komen.  Met dit document willen wij u informeren over de mogelijkheden van deze autorisatievormen in de API. Beide autorisatie mechanismes moeten door een consultant ingericht worden.     Autorisatie op basis van API scopes In de Visma developer portal zijn per API één of meerdere scopes gedefinieerd.  Door het activeren van deze scope krijgt een extern systeem toegang tot één of meerdere endpoint en/of data set. Binnen de API worden de volgende scopes onderscheiden.     Scope Omschrijving Endpoints Invitation_only Scope noodzakelijk om de API te kunnen activeren. Tijdens het activering proces wordt de contractafspraken gecontroleerd en vastgelegd.  Deze scope geeft nog geen toegang tot enige vorm van data maar is noodzakelijk voor de onboarding van klanten op de API of applicatie - Get_Basic Get basic data zoals medewerker- & organisatiedata GET persons GET employments GET employmentTimelines GET assignments GET organizationUnits GET roleAssignments GET jobProfiles GetPrivateContactDetails Voegt de privé contactgegevens aan de endpoint Person & Employee, zoals post- en woonadres, telefoonnummer vast & mobiel en het email adres. GET persons GET Employees   Dit betreft de volgende gegevens: ADRESGEVENS Home: P01014 straatnaam P01016 Huisnummer P01018 Huisnummer toev P01020 Postcode P01022 Plaatsnaam P01024 Land Postal: P00365 straatnaam P00367 huisnummer P00368 huisnummer toev P00313 postcode P00308 plaatsnaam P00847 land TELEFOONNUMMERS Home: P01027 - telefoonnr woonadres Mobile : P01036 - Telefoonnr mobiel EMAILADRES Prive: P01034 - E-mail adres privé Get salaryDetails Lezen van de salarisgevens van medewerkers GET SalaryDetails GET SalaryDetailTimelines Get_maternitityLeave Lezen van zwangerschapverlof van medewerkers GET maternityLeave Get_sicknessLeave Lezen van ziekmeldingen van medewerkers GET sickLeave Get_leave Lezen van verlofrechten en verlofopnames van medewerkers GET leaveEntitlements GET leaveHours   Uw consultant kan u helpen bij het activeren / deactiveren van deze scopes binnen de API.     Autorisatie op basis van autorisatie filters De autorisatie filters hebben betrekking op welke medewerkers zichtbaar zijn in de API. Standaard worden altijd alle medewerkers getoond in de API. Bij het activeren van de API kan een consultant filters inrichten zodat maar een beperkte groep medewerkers via de API beschikbaar komen.   Filteren in de API is mogelijk op de volgende Beaufort velden: P01102- Soort Arbeidsrelatie  P01103- Opdrachtgever  P01104- Instelling  P01110 - Code doelgroep  P05042 - Selectie rubriek Domain API - WFM  Een veel voorkomen filter is bijvoorbeeld op Soort Arbeidsrelatie waarbij alleen eigen medewerkers in het extern systeem opgenomen worden.  Maar ook een filter op de combinatie Opdrachtgever / Instelling geeft u de mogelijkheid om de medewerkers van één of meerdere specifieke instellingen in de API op te nemen.   Uw consultant kan u helpen bij het inrichten of wijzigen van de autorisatie filters.

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": [] }

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

A step-by-step guide that helps you to select and test an API and after that how to get support and access to data of a Youforce customer.

The File API allows you to download or upload files directly from Youforce, over HTTPS using the tool of your choice.    This API is controlled available and has consumption limitations. See API statuses   Concepts Concept Description File API Public endpoint to upload/list/download the files. In the request to File API, application id, business type and tenant are being identified. Once the files are uploaded to File API by a publisher application, the authorized subscriber application can list, download and delete the files. Business Type The files which are related to the same “business” are functionally grouped in File types called “Business types”. File types are represented by an integer called Business Type Id. Client Application Client Applications are the users of the system. They are identified by an application Id. Client Applications are also authorized to tenantId(s).Client application needs to obtain a authentication token by using credentials (client id and client secret).The token includes application id, tenant and permission of the application. Client Applications could be authorized either as publisher or subscriber of a business type. Publisher Publisher is a Client Application that can upload files of authorized business types and authorized tenants. Subscriber Subscriber is a Client Application that can download/list the files of authorized business types and authorized tenants. Tenant HR Core Client. Tenants are represented by tenant ids. Authentication We follow current industry standards and best practices. Authentication/authorization is not an exception. As part of the Identity and Access Management Strategy for system-to-system integrations, the File API is based on 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.   Tenant Authorization Client Applications (apps) need to be authorized to the corresponding Tenant (HR Core Client) in order to consume the API. By default, the applications are authorized to TenantId: sandbox.   File Type Authorization Client applications (apps) need to be authorized as publisher or subscriber of business types By default,sandbox apps are authorized to the Sandbox File Types.   Supported File Types The File API has been designed to support a specific set of use cases. This may be extended over time, based on customer feedback. See list of Supported File Types.   Retention Period The files will be physically deleted from Storage automatically after the retention period expires (1 month). The metadata of the files (FileName, tenantId , BusinessTypeId, etc) is deleted after 6 months.   Samples Here is an example of downloading a file using curl, available on most operating systems:  curl.exe https://api.raet.com/mft/v1.0/files/%fileid%?role=subscriber ^ --header "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." ^ --header "x-raet-tenant-id: 1234567" ^ --header "Accept: application/octet-stream"  ^ --output @C:\Youforce\somefile.xml   See complete examples for curl (Batch), Powershell and .Net in Github. Getting started See the File API documentation to get started  

  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)    

  General Access to the Visma|Raet support desk When Partner first starts using the Youforce API’s, Visma|Raet will create one end-user (hereinafter: Administrator) for Partner, who is given access to the Ticket system of Visma|Raet. An Administrator is an authorized person by Partner who uses the Youforce API’s and subsequently is able to create new Administrators.  The Visma|Raet Ticket system is accessible through this link: Log Support Ticket Service Support Questions about the functioning of Youforce API’s s are answered by Visma| Raet’s Service Center. We also process reports about malfunctions and deal with it adequately and ensure proper feedback. We offer these services to the registered, professional contact persons of Partner. The designated contact persons of Partner, are able to report detected incidents to Visma Raet’s Service Center. This is possible via accessing the Visma|Raet Ticket system.  In the case of escalation, you can contact us by telephone  The ticket system of Visma|Raet grants access and information about the progress of submitted questions and the offered solutions. Contact persons are during the support process able to add information and react to the offered solutions by Visma|Raet. Access by telephone of the Service Center  Access by telephone of the Service Center is meant for those situations where direct contact is needed to provide a solution or in case of escalation. The Service Center can be reached by telephone on workdays between 8:00 am and 6:00 pm.  We kindly ask you to enter your partner number and to choose between the Service on which the question is related to. Our Stand-by Service can be reached by telephone outside work hours, for reports with respect to the availability of the Youforce APIs. The Stand-by Service is available on workdays between 6:00 am and 8:00 am and between 6:00 pm and 10:00 pm and during weekends between 6:00 am and 10:00 pm.   Note: The Stand-by Service is only for reports on malfunctions in the availability of the Youforce API’s applications and is not meant for substantive questions or for reporting other malfunctions.  FAQ Who can get support? Partners only. See How to become an Access Partner How can I log a ticket on an API on login? You will receive instructions for this as part of your access partner contract. How long does it take before my ticket is picked up? Visma | Raet applies four Support Level Codes to give the right priority to the malfunction and the corresponding response time. The distinction in Support Level Codes is based on the type, severity, the corresponding initial response time and the expected recovery time of the reported malfunction.  Code Meaning Description 1 High The malfunction has a far-reached and immediate effect on the activities in the organization of the customer: activities cannot continue. There is no alternative solution that offers similar results.  2 Medium The malfunction has a significant effect on the activities in the organization of the customer: An alternative solution is available, whether or not with some limitations. 3 Low The malfunction has limited or no effect on the activities in the organization of the customer The following resolution times relate to the Service Level Code, depending on the Service Code Meaning Maximum duration 1 High Solution by means of a workaround 90% within 24 hours 100% within 48 hours Structural solution: Within 30 calendar days 2 Medium Structural solution: Between 30-90 calendar days 3 Low Solution The solution shall be included in the release calendar How do get a login to the support tool? You will receive instructions for this as part of your access partner contract.

Dit document beschrijft de ‘ProActive - Visma Raet IAM API’-connector. Een koppeling gebaseerd op de Visma Raet IAM 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 ‘AppicalNow - Visma|Raet Learning API’-connector. Een koppeling gebaseerd op de Visma Raet Learning API.

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.

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