Kennisbank Youforce API & bestandsuitwisseling

Choose an API product Youforce has several API products available, you find more information here:  https://developer.visma.com/api/youforce   Every API covers a different use cases, for example The IAM API is intended for identity & access management systems and enables the provisioning of users in other systems like Active Directory or IDP.  The Learning API provides employee data that is relevant for applications in the learning, development, appraisal domain, etc.   The File API allows you to download or upload files directly from Youforce. In this way we help to achieve ‘purpose binding’ required to safeguard the privacy of employees and to comply with GDPR legislation. It furthermore allows us to tailor and grow the API supporting specific needs in that domain   Create an account and application 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. A step by step manual is availible here.   Get the access token In order to grant access to a target API, Apps must first authenticate against our Authorization Server.    This token will provide access to a particular tenant in a specific application. Hence, this step will require knowing the client-id, client-secret and tenant-id.   curl -X POST   'https://connect.visma.com/connect/token'  -H 'Cache-Control: no-cache'   -H 'Content-Type: application/x-www-form-urlencoded'   -d 'client_secret=xxxxxxx      &client_id=xxxxxxxx      &tenant_id=xxxxxxxx      &grant_type=client_credentials'     Below, a response example containing the access token, the authorized scopes and the expiration time which is 1 hour max. After that time Apps need to re-authenticate to get a new access token.   {     'access_token':'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',     'expires_in': '3600',     'token_type': 'Bearer',     "scope": "youforce-fileapi:files:list youforce-fileapi:files:upload" }     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 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   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)        

API Statuses   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 partners Connections of a 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 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   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.

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