Kennisbank Youforce API & bestandsuitwisseling

Developer portal, een account aanmaken, applicatie registreren en toegang tot de klantgegevens

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.

  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.

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