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.
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.
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.
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 the supported File Types.
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.
Here is an example of downloading a file using curl, available on most operating systems:
The Authentication API is used to obtain the required access token. The request must include the content type header and the HTTP body must include the required Client Credentials.
Below, a response example containing the access token and the expiration time which is 2 hours. After that time Apps need to re-authenticate to get a new access token.
App must use the Authorization header containing the access token. The API always operates within the scope of one HR Core client, also called tenant. An API call cannot retrieve data from multiple tenants.
The error payload shown below, describes the 401 error response Apps will receive in case of any authentication error.
For more detailed information please refer to the request headers & responses section
Once you have a valid access token you can perform below actions as publisher of the file types:
In case you have any question or doubt during the integration, you can reach us through the Visma Developer Community in Slack. See our Support page for more information.
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:
| Quota |
Weekly |
Daily |
Continous |
| 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 |
| 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 |
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 behaviour 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.
Publishers
Recommended usage of uploading files:
- Multipart upload (<100MB: The file is uploaded in a single request. (100MB max). The metadata that describes the file is also added in this request.
- Resumable upload (>100MB): The file is uploaded by chunks. (9MB max each chunk) The metadata that describes the file is added in the first request.
Small files (<4 MB):
- Multipart upload when possible.
- Resumable upload and smaller chunks if you have strict response time restrictions or your network connection isn’t reliable.
Medium files (> 4 MB and <100 MB):
-
Resumable when possible and chunks of 4MB. If you have strict response time restrictions or your network connection isn’t reliable, you could use smaller chunks.
-
Multipart when you don’t expect your files to be bigger than 100 MB (consider the file growth over time) and most of your files are small (<4 MB)
Big files (>100 MB):
- Resumable only. When possible, use chunks of 4MB. If you have strict response time restrictions or your network connection isn’t reliable, you could use smaller chunks.
A multipart upload request allows you to send metadata along with the data to upload. Use this option if the data you send is small enough to upload again in its entirety if the connection fails.
To use multipart upload:
- Create a POST request to the method’s /files URI with the query parameter uploadType=multipart.
Example - POST request multipart
POST https://api.raet.com/mft/v1.0/files?uploadType=multipart
- Add the top-level HTTP header: Content-Type. Set to multipart/related, and include the boundary string you’re using to identify the different parts of the request
Example - Content-Type header
Content-Type: multipart/related; boundary=foo_bar_baz
- Create the body of the request. Format the body according to the multipart/related content type [RFC 2387], which contains two parts:
a) Metadata part. Must come first, and must have a Content-Type header set to application/json; charset=UTF-8. Add the file’s metadata to this part in JSON format. The required metadata fields are:
| Key |
Value |
| FileName |
[FileName] |
| BusinessTypeId |
[BusinessTypeId] |
Note: For security reasons, file names have some restrictions:
- Filenames should fulfil the following characters sets:
[a-z],[A-Z],[0-9],[-],[_],[.],[(],[)],[,],[$],[+],[`],[=],[']
- Malicious file extensions are not allowed
b) Media part. Must come second, and should contain the bytes of the files. Identify each part with a boundary delimiter. [RFC 2046] The boundary delimiter line is defined as a line consisting entirely of two hyphen characters (“-“, decimal value 45) followed by the boundary parameter value from the Content-Type header field, optional linear white-space, and a terminating CRLF. The boundary delimiter MUST occur at the beginning of a line and it is terminated by either the header fields for the next part and two additional CRLFs, or by two additional CRLFs, in case there are no header fields for the next part. Boundary delimiters must not appear within the encapsulated material, and must be no longer than 70 characters, not counting the two leading hyphens.
Example - Boundary delimiter for Metadata part:
--foo_bar_baz[CRLF]
Content-Type: application/json; charset=UTF-8[CRLF]
[CRLF]
Example - Boundary delimiter for Media part:
--foo_bar_baz[CRLF]
[CRLF]
The boundary delimiter line following the last body part is a distinguished delimiter that indicates that no further body parts will follow. Such a delimiter line is identical to the previous delimiter lines, with the addition of two more hyphens after the boundary parameter value.
Example - Boundary delimiter for last body part:
Example - Send a multipart upload request using the Sandbox File Type
POST/mft/v1.0/files
?uploadType=multipart HTTP/1.1
Host: api.raet.com
x-raet-tenant-id: sandbox
Authorization: Bearer xxxxxxxxx
Content-Type: multipart/related;boundary=foo_bar_baz
--foo_bar_baz
Content-Type: application/json; charset=UTF-8
{
"name":"TestFile.txt",
"businesstypeid":"7100"
}
--foo_bar_baz
This is a test file
--foo_bar_baz--
If the request succeeds, the server returns the HTTP 201 Created status code along with the file’s metadata:
Example - Response successful request
HTTP/1.1 201
Content-Type: application/json
{
"id": "7ff1b498-169d-4048-8459-78f7bd7905a3",
"name": "TestFile.txt",
"size": 19,
"creationDate": "2020-02-27T11:03:49.2033291Z",
"tenantId": "sandbox",
"businessType": {
"id": 7100,
"name": "7100"
},
"numChunks": 1
}
If the request fails, the server returns the HTTP 400, indicating Bad request.
Example - Response failed request
HTTP/1.1 400
Content-Type: application/json
{
"CorrelationId": "rrt-06f2e934a3cbdb710-a-de-13067-4959526-1",
"Message": "Error reading body of request. Please, check all the boundaries of the request",
"ErrorCode": "400",
"Exception": null
}
This protocol allows you to resume an upload operation after a communication failure interrupts the flow of data. Use this option if you transfer large files or if the likelihood of a network interruption or some other transmission failure is high
Initiate a resumable upload session and upload the first chunk of file
To initiate a resumable upload session:
- Create a POST request to the method’s /files URI and add the query parameter uploadType=resumable.
Example - Initial Post Request Resumable
POST https://api.raet.com/mft/v1.0/files?uploadType=resumable
- Add the top-level HTTP header: Content-Type. Set to multipart/related, and include the boundary string you’re using to identify the different parts of the request.
Example - Content-Type header
Content-Type: multipart/related; boundary=foo_bar_baz
- Create the body of the request. Format the body according to the multipart/related content type [RFC 2387], which contains two parts:
a) Metadata part. Must come first, and must have a Content-Type header set to application/json; charset=UTF-8. Add the file’s metadata to this part in JSON format. The required metadata fields are:
| Key |
Value |
| FileName |
[FileName] |
| BusinessTypeId |
[BusinessTypeId] |
Note: For security reasons, file names have some restrictions:
- Filenames should fulfill the following characters sets:
[a-z],[A-Z],[0-9],[-],[_],[.],[(],[)],[,],[$],[+],[`],[=],[']
- Malicius file extensions are not allowed
b) Media part. Must come second, and should contain the first chunk data of the file.
Create chunks of a maximum of 9MB. It’s recommended to have chunks with the same size, except for the final chunk that completes the upload. The best performance using this method is achieved with chunks of 4mb.
Identify each part with a boundary delimiter. [RFC 2046] The boundary delimiter line is defined as a line consisting entirely of two hyphen characters (“-“, decimal value 45) followed by the boundary parameter value from the Content-Type header field, optional linear white-space, and a terminating CRLF.
The boundary delimiter MUST occur at the beginning of a line and it is terminated by either the header fields for the next part and two additional CRLFs, or by two additional CRLFs, in case there are no header fields for the next part.
Boundary delimiters must not appear within the encapsulated material, and must be no longer than 70 characters, not counting the two leading hyphens.
Example - Boundary delimiter for Metadata part:
--foo_bar_baz[CRLF]
Content-Type: application/json; charset=UTF-8[CRLF]
[CRLF]
Example - Boundary delimiter for Media part:
--foo_bar_baz[CRLF]
[CRLF]
The boundary delimiter line following the last body part is a distinguished delimiter that indicates that no further body parts will follow. Such a delimiter line is identical to the previous delimiter lines, with the addition of two more hyphens after the boundary parameter value.
Example - Boundary delimiter for last body part:
Example - Initiate a resumable upload session using the sandbox File Type
POST/mft/v1.0/files
?uploadType=resumable HTTP/1.1
Host: api.raet.com
x-raet-tenant-id: sandbox
Authorization: Bearer xxxxxxxxx
Content-Type: multipart/related;boundary=foo_bar_baz
--foo_bar_baz
Content-Type: application/json; charset=UTF-8
{
"name":"TestFile.txt",
"businesstypeid":"7100"
}
--foo_bar_baz
This is the first chunk of the file
--foo_bar_baz--
If the session initiation request succeeds, the response includes a 206 Partial ContentHTTP status code, along with the upload token. Copy and save the upload token, so you can use it for uploading the next chunks of the file.
Example - Successful Response of initial request
HTTP/1.1 206
Content-Type: application/json
{
"uploadToken": "4927b6ffb51445ee982237ab6e4b3b30"
}
Note: The upload token expires after one hour.
If the request fails, the server returns the HTTP 400, indicating Bad request.
Example - Response failed request
HTTP/1.1 400
Content-Type: application/json
{
"CorrelationId": "rrt-06f2e934a3cbdb710-a-de-13067-4959526-1",
"Message": "Error reading body of request. Please, check all the boundaries of the request",
"ErrorCode": "400",
"Exception": null
}
A few checks for mitigation:
- Setting the right boundary definition for multipart/form-data body. Be mindful of setting two consecutive dashes (for example, –foo_bar_baz–) to mark the end of the boundary within the body of the HTTP request and two additional CRLFs after the boundary delimiters.
- If you are using Azure Logic Apps, go to the Logic App Code View. Within the HTTP body definition, replace every \n with \r\n. This is the key for successful file upload with multipart/form-data HTTP request using Azure Logic Apps.
To upload the file in multiple chunks follow the steps:
- Create a PUT request to the method’s /files URI.
- Add the query parameter uploadType=resumable
- Add the query parameter uploadToken=[uploadToken]
- Add the query parameter position=[position]
Example - Request to upload next chunks of the file
Put v1.0/files
?uploadType=resumable
&uploadToken=[uploadToken]
&position=[position]
-
Add the chunk’s data to the request body. Create chunks of a maximum of 9MB. It’s recommended to have chunks with the same size, except for the final chunk that completes the upload.
-
Add the top-level HTTP header Content-Type. Set to application/octet-stream
-
Send the request, and process the response. If the upload request is interrupted, or if you receive a 5xx response, send the request again. If the request succeeds, the server responds with 206 Partial Content, along with the upload token.
-
Repeat steps 1 through 7 for each chunk that remains in the file. It’s possible to parallel the upload of the intermediate chunks. The last chunk needs to be sent at the end of the requests, to close the session once that you have received confirmation that the previous chunks have been stored successfully.
Example - Upload next chunks of the file. This example shows a request that sends the next bytes of the file, and uses the upload token obtained in the previous step:
PUT/mft/v1.0/files
?uploadType=resumable
&uploadToken=4927b6ffb51445ee982237ab6e4b3b30
&position=1 HTTP/1.1
Host: api.raet.com
x-raet-tenant-id: sandbox
Authorization: Bearer xxxxxxxxx
Content-Type: application/octet-stream
And this is the second chunk of the file
If the request succeeds, the server responds with 206 Partial Content
Example - Successful response of intermediate request
There are two ways to complete a resumable upload session:
a) Add the query parameter close=true in the last PUT request.
b) Send additional Post request without bytes.
To complete a resumable upload session in the last upload request follow the steps described in section: “Upload next chunks of the file” and
- Add the query parameter close=true
- Add the top-level HTTP header: Content-Type. Set to application/octet-stream
Example - Put Request to complete a resumable upload session
Put https://api.raet.com/mft/v1.0/files
?uploadType=resumable
&uploadToken=[uploadToken]
&position=[position]
&close=true
If the request succeeds, the server responds with 201 created, along with the metadata of the file.
Example - Complete a resumable upload session in the last upload request
PUT/mft/v1.0/files
?uploadType=resumable
&uploadToken=4927b6ffb51445ee982237ab6e4b3b30
&position=2
&close=true HTTP/1.1
Host: api.raet.com
x-raet-tenant-id: sandbox
Authorization: Bearer xxxxxxxxx
Content-Type: application/octet-stream
And this is the last chunk of the file
This example shows a request that sends the last bytes of the file, and complete the upload of the file, using the upload token obtained in the previous step:
If the request succeeds, the server responds with 201 Created, along with the metadata of the file.
Example - Successful response of final request
HTTP/1.1 201
Content-Type: application/json
{
"id": "7ff1b498-169d-4048-8459-78f7bd7905a3",
"name": "TestFile.txt",
"size": 78,
"creationDate": "2020-02-27T11:03:49.2033291Z",
"tenantId": "sandbox",
"businessType": {
"id": 7100,
"name": "7100"
},
"numChunks": 2
}
To complete a resumable upload session sending an additional Post request without bytes, follow the steps:
- Create a POST request to the method’s /files URI.
- Add the query parameter uploadType=resumable
- Add the query parameter uploadToken=[uploadToken]
- Do not add the top-level HTTP header: Content-Type.
Example - Post Request to complete a resumable upload session
Post https://api.raet.com/mft/v1.0/files
?uploadType=resumable
&uploadToken=[uploadToken]
If the request succeeds, the server responds with 201 created, along with the metadata of the file.
Example - Complete a resumable upload session sending an additional Post request. This example shows a request that sends and additional Post request to complete the upload of the file, using the upload token obtained in the previous step:
Post/mft/v1.0/files
?uploadType=resumable
&uploadToken=4927b6ffb51445ee982237ab6e4b3b30 HTTP/1.1
Host: api.raet.com
x-raet-tenant-id: sandbox
Authorization: Bearer xxxxxxxxx
If the request succeeds, the server responds with 201 Created, along with the metadata of the file.
Example - Successful response of final request
HTTP/1.1 201
Content-Type: application/json
{
"id": "7ff1b498-169d-4048-8459-78f7bd7905a3",
"name": "TestFile.txt",
"size": 78,
"creationDate": "2020-02-27T11:03:49.2033291Z",
"tenantId": "sandbox",
"businessType": {
"id": 7100,
"name": "7100"
},
"numChunks": 2
}
This endpoint allows you to retrieve a paginated collection of the files that have been uploaded by you.
In order to use the list endpoint:
- Create a Get request to the method’s /files URI and add the query parameter role=publisher
Example - List Uploaded Files
GET https://api.raet.com/mft/v1.0/files?role=publisher
| Parameter Name |
Value |
Description |
| pageIndex |
integer |
The number of the page. (Default:0) |
| pageSize |
integer |
The maximum number of files to return per page. Acceptable values are 1 to 1000, inclusive. (Default: 20) |
Example - List Uploaded Files. This example shows how to list the files that have been uploaded by you (role=publisher)
GET/mft/v1.0/files
?role=publisher
&pageSize=10
HTTP/1.1
Host: api.raet.com
x-raet-tenant-id: sandbox
Authorization: Bearer xxxxxxxxx
If the request succeeds, the response includes a 200 OK HTTP status code, along with the paginated collection of the files that were uploaded by you.
By default, the paginated collection of files will be ordered by date descending.
Example - Response of List Uploaded Files
HTTP/1.1 200
Content-Type: application/json
{
"data": [
{
"fileId": "4a31f004-aab8-4419-9072-077c35074553",
"fileName": "TestFile1.txt",
"fileSize": 209715222,
"tenantId": "sandbox",
"businessType": {
"id": 7100,
"name": "7100"
},
"publisherId": "1b604f7e-d40f-466d-b9b0-ddeb3945df14",
"uploadDate": "2021-01-10T21:05:41.937"
},
{
"fileId": "62777c81-e83f-4888-8202-cf35ea2ca38b",
"fileName": "TestFile2.txt",
"fileSize": 2048,
"tenantId": "sandbox",
"businessType": {
"id": 7100,
"name": "7100"
},
"publisherId": "1b604f7e-d40f-466d-b9b0-ddeb3945df14",
"uploadDate": "2021-01-10T08:07:41.113"
}
],
"pageIndex": 0,
"pageSize": 20,
"count": 2
}
To search for a specific set of files, use the query string $filter to filter the files to return.
The format of the query string is: field operator values
Where:
-
field specifies the field to search upon.
-
operator specifies the condition for the field.
-
values are the specific values you want to use to filter your search results.
| Field |
Description |
Values |
| uploadDate |
Upload Date according to DateTime OData format |
<DateTime> |
| businessType |
Business Type ID |
<BusinessTypeId> |
| fileName |
Name of the file |
<FileName> |
| Operator |
Description |
| gt |
Great than |
| lt |
Less than |
| ge |
Great than or equal |
| le |
Less than or equal |
| eq |
Equal |
| ne |
Not equal |
| and |
And |
| or |
Or |
| ( |
Open Parenthesis |
| ) |
Close Parenthesis |
| startsWith |
parameter starts with the following substring (only for fileName) |
| endsWith |
parameter ends with the following substring (only for fileName) |
| contains |
parameter contains the following substring (only for fileName) |
| What you want to query |
Query String |
| Files greater than 2020-05-19T08:42:47.400Z |
uploadDate gt 2020-05-19T08:42:47.400Z |
| Files greater than 2020-05-19T08:42:47.400Z and lesser than 2020-05-19T16:42:47.400Z |
uploadDate gt 2020-05-19T08:42:47.400Z and uploadDate lt 2020-05-19T16:42:47.400Z |
| Files related to BusinessTypeID 7100 |
businessType eq 7100 |
| Files related to BusinessTypeID 999998 or 999999 |
businessType eq 999998 or businessType eq 999999 |
| All Files greater than 2020-05-19T08:42:47.400Z related to BusinessTypeID 7101 |
uploadDate gt 2020-05-19T08:42:47.400Z and businessType eq 7101 |
| All files with a name that starts with “payroll” |
startsWith(FileName, 'payroll') |
| All files with a name that ends with “holidays“ |
endsWith(FileName, 'holidays') |
| All files with a name that contains “test“ |
contains(fileName, 'test') |
| All files with a name that starts with “payroll“ and a BusinessTypeId 7101 |
startsWith(FileName, 'payroll') and businessType eq 7101 |
To sort the files in an specific order, use the query string $orderBy
The format of the query string is: field modifier
Where:
- field specifies the key to sort. Valid keys are ‘uploadDate’, ‘businessType’, ‘fileName’.
- modifier specifies the order of the sorting (‘asc’ and ‘desc’)
Example usage:
By default, files are sorted by UploadDate desc.
Note: The order in which files need to be downloaded may depend on the type of data and the way the receiving system needs to process it. See examples below:
| What you want query |
Query String |
| Retrieve ‘RST Functie’ files (BT: 101002. Definition of all functions/positions available in Beaufort/YouForce). You would only need the latest file so you can ignore the rest, as each file contains the complete list of functions/positions. |
$filter=businessType eq 101002.
In this case, the $OrderBy query string is not needed, as files are sorted by UploadDate desc by default. |
| Retrieve employee mutations in Bint Harmony Files (BT: 101100). Based on the default settings that Beaufort/YouForce only exports the mutations instead of the full employee dataSet, it is important that you get all the new files and download them from old to new. |
$filter=businessType eq 101100&$orderBy=uploadDate asc |
This endpoint allows you to download the files that have been uploaded by you.
In order to use this download endpoint:
- Create a Get request to the method’s /files/[fileId] URI and add the query parameter role=publisher
- Add the HTTP header Accept=application/octet-stream
Example - Download Request
GET https://api.raet.com/mft/v1.0/files/[fileId]?role=publisher
Example - Download uploaded file. This example shows how to download a file that was uploaded by you using the Sandbox Tenant
GET/mft/v1.0/files/d92ffb21-7938-488b-a405-bcbc9e0a9696
?role=publisher
HTTP/1.1
Host: api.raet.com
x-raet-tenant-id: sandbox
Authorization: Bearer xxxxxxxxx
Accept: application/octet-stream
If the request succeeds, the response includes a 200 OK HTTP status code, along with the bytes of the file.
Example - Successful response of Download uploaded File
HTTP/1.1 200
<root>
<company>Visma Raet</company>
<product>File API</product>
<content>Sample File</content>
</root>
- Setting the right boundary definition for multipart/form-data body. Be mindful of setting two consecutive dashes (for example, –foo_bar_baz–) to mark the end of the boundary within the body of the HTTP request and two additional CRLFs after the boundary delimiters.
- If you are using Azure Logic Apps, go to the Logic App Code View. Within the HTTP body definition, replace every \n with \r\n. This is the key for successful file upload with multipart/form-data HTTP request using Azure Logic Apps.
Subscribers
This endpoint allows you to retrieve a paginated collection of the files that have been delivered to you.
In order to use this list endpoint:
- Create a Get request to the method’s /files URI and add the query parameter role=subscriber
Example - List Available Files
GET https://api.raet.com/mft/v1.0/files?role=subscriber
| Parameter Name |
Value |
Description |
| pageIndex |
integer |
The number of the page. (Default:0) |
| pageSize |
integer |
The maximum number of files to return per page. Acceptable values are 1 to 1000, inclusive. (Default: 20) |
| $filter |
string |
A query for filtering the file results. See the “Search for files” guide for the supported syntax. |
| $orderBy |
string |
A query for sorting the file results. See the “Sort files” guide for the supported syntax. |
Example - List Available Files. This example shows how to list the files that have been delivered to you. (role=subscriber) using the sandbox tenant
GET/mft/v1.0/files
?role=subscriber
&pageSize=20
&$filter=businessType eq 8000
&$orderBy=uploadDate desc
HTTP/1.1
Host: api.raet.com
x-raet-tenant-id: sandbox
Authorization: Bearer xxxxxxxxx
If the request succeeds, the response includes a 200 OK HTTP status code, along with the paginated collection of the files that are available for you.
By default, only available files are shown. (Not downloaded files). In this case, the “count” field will return the total number of available files considering the query string specified in the parameter $filter. When a file is downloaded, it will not be shown by default anymore in the list, and the “count” field will be decreased to reflect the currently available files.
Example - Response of List Available Files
HTTP/1.1 200
Content-Type: application/json
{
"data": [
{
"downloaded": false,
"fileId": "d92ffb21-7938-488b-a405-bcbc9e0a9696",
"fileName": "sandbox_test_file.xml",
"fileSize": 107,
"tenantId": "sandbox",
"businessType": {
"id": 7101,
"name": "7101"
},
"publisherId": "cfc6678d-06d8-41c7-acb5-7448a14dc917",
"uploadDate": "2021-03-25T07:30:23.657Z"
},
{
"downloaded": false,
"fileId": "c5d7438e-5c29-47e7-b518-01e5a39d6711",
"fileName": "sandbox_test_file.txt",
"fileSize": 33,
"tenantId": "sandbox",
"businessType": {
"id": 7101,
"name": "7101"
},
"publisherId": "cfc6678d-06d8-41c7-acb5-7448a14dc917",
"uploadDate": "2021-03-25T07:30:23.657Z"
},
{
"downloaded": false,
"fileId": "f0d109df-b933-44f9-92d7-cca525ef120a",
"fileName": "sandbox_test_file.csv",
"fileSize": 76,
"tenantId": "sandbox",
"businessType": {
"id": 7101,
"name": "7101"
},
"publisherId": "cfc6678d-06d8-41c7-acb5-7448a14dc917",
"uploadDate": "2021-03-25T07:30:23.657Z"
}
],
"pageIndex": 0,
"pageSize": 20,
"count": 3
}
To search for a specific set of files, use the query string $filter to filter the files to return.
The format of the query string is: field operator values
Where:
-
field specifies the field to search upon.
-
operator specifies the condition for the field.
-
values are the specific values you want to use to filter your search results.
| Field |
Description |
Values |
| uploadDate |
Upload Date according to DateTime OData format |
<DateTime> |
| businessType |
Business Type ID |
<BusinessTypeId> |
| status |
Status |
'available', 'downloaded', 'all' |
| fileName |
Name of the file |
<FileName> |
| Operator |
Description |
| gt |
Great than |
| lt |
Less than |
| ge |
Great than or equal |
| le |
Less than or equal |
| eq |
Equal |
| ne |
Not equal |
| and |
And |
| or |
Or |
| ( |
Open Parenthesis |
| ) |
Close Parenthesis |
| startsWith |
parameter starts with the following substring (only for FileName) |
| endsWith |
parameter ends with the following substring (only for FileName) |
| contains |
parameter contains the following substring (only for FileName) |
| What you want to query |
Query String |
| Files greater than 2020-05-19T08:42:47.400Z |
uploadDate gt 2020-05-19T08:42:47.400Z |
| Files greater than 2020-05-19T08:42:47.400Z and lesser than 2020-05-19T16:42:47.400Z |
uploadDate gt 2020-05-19T08:42:47.400Z and uploadDate lt 2020-05-19T16:42:47.400Z |
| All Files (downloaded and available) |
status eq 'all' |
| Downloaded Files |
status eq 'downloaded' |
| Available Files |
status eq 'available' |
| Files related to BusinessTypeID 7101 |
businessType eq 7101 |
| Files related to BusinessTypeID 7100 or 7101 |
businessType eq 7100 or businessType eq 7101 |
| Downloaded Files related to BusinessTypeID 7100 or 7101 |
status eq 'downloaded' and (businessType eq 7100 or businessType eq 7101) |
| All Files greater than 2020-05-19T08:42:47.400Z related to BusinessTypeID 7101 |
uploadDate gt 2020-05-19T08:42:47.400Z and businessType eq 7101 and status eq 'all' |
| All files with a name that starts with “payroll” |
startsWith(FileName, 'payroll') |
| All files with a name that ends with “holidays“ |
endsWith(FileName, 'holidays') |
| All files with a name that contains “test“ |
contains(fileName, 'test') |
| All files with a name that starts with “payroll“ and a BusinessTypeId 7101 |
startsWith(FileName, 'payroll') and businessType eq 7101 |
To sort the files in an specific order, use the query string $orderBy
The format of the query string is: field modifier
Where:
- field specifies the key to sort. Valid keys are ‘uploadDate’, ‘businessType’, ‘status’, ‘fileName’.
- modifier specifies the order of the sorting (‘asc’ and ‘desc’)
Example usage:
By default, files are sorted by UploadDate desc.
Note: The order in which files need to be downloaded may depend on the type of data and the way the receiving system needs to process it. See examples below:
| What you want query |
Query String |
| Retrieve ‘RST Functie’ files (BT: 101002. Definition of all functions/positions available in Beaufort/YouForce). You would only need the latest file so you can ignore the rest, as each file contains the complete list of functions/positions. |
$filter=businessType eq 101002.
In this case, the $OrderBy query string is not needed, as files are sorted by UploadDate desc by default. |
| Retrieve employee mutations in Bint Harmony Files (BT: 101100). Based on the default settings that Beaufort/YouForce only exports the mutations instead of the full employee dataSet, it is important that you get all the new files and download them from old to new. |
$filter=businessType eq 101100&$orderBy=uploadDate asc |
There are two types of downloads you can perform:
This endpoint allows you to download the files that have been delivered to you.
In order to use this download endpoint:
Example - Download Request
GET https://api.raet.com/mft/v1.0/files/[fileId]?role=subscriber
Example - Download Available File. This example shows how to download a file that was delivered to you
GET/mft/v1.0/files/d92ffb21-7938-488b-a405-bcbc9e0a9696
?role=subscriber
HTTP/1.1
Host: api.raet.com
x-raet-tenant-id: sandbox
Authorization: Bearer xxxxxxxxx
Accept: application/octet-stream
If the request succeeds, the response includes a 200 OK HTTP status code, along with the bytes of the file.
Example - Successful response of Download Available File
HTTP/1.1 200
<root>
<company>Visma Raet</company>
<product>File API</product>
<content>Sample File</content>
</root>
These endpoints allow you to download chunks of files that have been delivered to you.
In order to download files by chunks you need to use these endpoints:
File API allows you to download chunks of files that have been delivered to you. This endpoint will be used to check if this capability is in place for the resource.
- Create a Head request to the method’s /files/[fileId] URI and add the query parameter role=subscriber
Example - Check Available File can be downloaded by chunks
HEAD/mft/v1.0/files/d92ffb21-7938-488b-a405-bcbc9e0a9696
?role=subscriber
HTTP/1.1
Host: api.raet.com
x-raet-tenant-id: sandbox
Authorization: Bearer xxxxxxxxx
If the request succeeds, the response includes a 200 OK HTTP status code, along with the headers:
- Content-Length with the size of the requested file
- Accept-Ranges with the range unit accepted
Example - Successful response of Check Available File can be downloaded by chunks
HTTP/1.1 200
Content-Length:107
Accept-Ranges:bytes
File API allows you to download chunks of files that have been delivered to you.
- Create a Get request to the method’s /files/[fileId] URI and add the query parameter role=subscriber
- Add the HTTP header Accept: application/octet-stream
- Add the HTTP header Range: bytes=firstByte-lastByte where firstByte is the first byte of the chunk you want to download and lastByte is the last one.
Example - Download first 50 bytes of an Available File. This example shows how to download a chunk of a file that was delivered to you
GET/mft/v1.0/files/d92ffb21-7938-488b-a405-bcbc9e0a9696
?role=subscriber HTTP/1.1
Host: api.raet.com
x-raet-tenant-id: sandbox
Authorization: Bearer xxxxxxxxx
Accept: application/octet-stream
Range: bytes=0-49
If the request succeeds, the response includes a 206 Partial Content HTTP status code, along with the bytes of the chunk and the headers:
- Content-Range with the range retrieved and total file size
- Content-Disposition with the value attachment; filename=name of the file
Example - Successful response of Download first 1024 bytes of an Available File
HTTP/1.1 206
Content-Length: 50
Content-Range: bytes 0-49/107
Content-Disposition:attachment; filename=sandbox_test_file.xml
<root>
<company>Visma Raet</company>
<product>Fi
When the lower limit of the range is bigger than the last byte of the file, the request will retrieve a 416 error. Example - Request not satisfiable range when Download Range out of Available File bounds
GET/mft/v1.0/files/d92ffb21-7938-488b-a405-bcbc9e0a9696
?role=subscriber HTTP/1.1
Host: api.raet.com
x-raet-tenant-id: sandbox
Authorization: Bearer xxxxxxxxx
Accept: application/octet-stream
Range: bytes=107-110
The response includes a 416 Range Not Satisfiable HTTP status code, along with the header:
- Content-Range with the accepted range unit and the file size
Example - Response - Error not satisfiable range when Download Range out of Available File bounds
HTTP/1.1 206
Content-Range: bytes */107
{
"correlationId": null,
"message": "Range not satisfiable.",
"errorCode": "416",
"exception": null
}
This endpoint allows to delete a file you are subscribed to. This will not delete the file for everyone, just for the app that is requesting it.
In order to use this endpoint:
- Create a Delete request to the method’s /files/[fileId] URI and add the query parameter role=subscriber
- Add the HTTP header Accept=application/octet-stream
Example - Delete File
DELETE https://api.raet.com/mft/v1.0/files/d92ffb21-7938-488b-a405-bcbc9e0a9696
?role=subscriber
HTTP/1.1
Host: api.raet.com
x-raet-tenant-id: sandbox
Authorization: Bearer xxxxxxxxx
If the request succeeds, the response includes a 204 No Content HTTP status code.
If the request succeeds, the response includes a 204 No Content HTTP status code.
Example - Response of Delete File
File types
| Owner |
Type |
Business TypeId |
Business Type Name |
| File Transfer |
Sandbox |
7101 |
File API Sandbox Downloads |
| File Transfer |
Sandbox |
7100 |
File API Sandbox Uploads |
| Owner |
Type |
Business Type Id |
Business Type Name |
File Patterns |
Remarks |
| HRCB |
Import |
113000 |
Payroll Netive Imports |
<TENANTID>_<DATE&TIME>.txt |
|
| HRCB |
Import |
113001 |
Payroll Batch Input Imports |
<TENANTID>_<OPTIONAL>.<EXTENSION> |
See Batch input imports documentation and note below (*) |
| HRCB |
Import |
113002 |
Payroll EMA Imports |
<TENANTID>_<COMPANYKEYCOD>_<OPTIONAL>.<EXTENSION> |
See note below **) |
| HRCB |
Export |
113003 |
Journaalposten Export |
RPD.<TENANTID>.*.* |
|
* Note Batch Input Imports:
The contents of the optional block are not used by the import. Please make sure there is an underscore before it so that the tenantId can be parsed correctly. The optional block may be used to make sure the filename is unique and the file is identifiable: The date and time are recommended for this. The extension could be txt or dat
** Note EMA Imports:
The contents of the optional block are not used by the import. Please make sure there is an underscore before it so that the CompanyKeyCod can be parsed correctly. The optional block may be used to make sure the filename is unique and the file is identifiable: The date and time are recommended for this. The extension is free to use, this could be txt or csv.
Here you can see the description of the External mutations Advanced as it is in the Online help of HR Core Business.
This document explains how to create a file for testing in Excel.
| Owner |
Type |
Business TypeId |
Business Type Name |
File Patterns |
| RBM |
Export |
134000 |
RBM Business Downloads |
*_SEPA.csv |
| RBM |
Export |
134001 |
RBM Business Payment Files |
*_SEPA.xml, *_SEPA.zip |
Note: See release notes to configure File API exports in Betaalmanager
| Owner |
Type |
Business Type Id |
Business Type Name |
File Patterns |
| Younifier |
Import |
105000 |
External Payslips Import |
*.zip |
| Owner |
Type |
Business TypeId |
Business Type Name |
File Patterns |
| Robotics |
Export |
137000 |
Robotics Youserve Exports |
*.* |
| Owner |
Type |
Business TypeId |
Business Type Name |
File Patterns |
| Loonaangifte |
Export |
102000 |
Loonaangifte Business Export |
*.zip |
| Owner |
Type |
Business TypeId |
Business Type Name |
File Patterns |
| Personneldossier |
Export |
107001 |
Personeels dossier Exports |
*.zip |
| Owner |
Type |
Business TypeId |
Business Type Name |
File Patterns |
Remarks |
| Salarisdossier |
Export |
136000 |
Salarisdossier Business Exports |
ExportDossier*.zip |
Payslips and Annual statement files are included |
Examples to integrate
You can integrate with our File API Net SDKs.
- The SDK to connect to the File API is available at nuget.
- Documentation about how to use the SDK and our examples is at GitHub.
- Documentation about how to use PowerShell and our examples is at GitHub.
| Date |
Changes |
| 2022-07-02 |
Database columns have been converted to improve database performance. During this maintenance activity the performance of publisher endpoints was degraded and subscriber endpoints had to be disabled. See status.visma.com for additional details about this maintenance activity |
| 2022-06-01 |
New payroll file types have been defined per core. See section Payroll File - File Types |
| 2022-05-31 |
New RBM file types have been defined per core. See section RBM File Types |
| 2022-05-27 |
- Added the possibility of filtering and sorting for publishers. See section Search uploaded files and section Sort uploaded files
- Added 403 error message when the request contains a filter by a non authorized business type |
| 2022-02-15 |
Updated FileAPI.json file, replacing “v1” by “v1.0” to support integrations using Azure API management (APIM). No action is required from your side, as File API Endpoints have not changed |
| 2022-01-21 |
Created download Endpoint for publishers. See section Download uploaded files |
Policies
Definition of our API Statuses
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.
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.
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.
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
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, behaviour or semantics. The release and support strategy makes a clear distinction in how these are managed.
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.
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.
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. |
Developers & Visma Community |
All recipients & File API contact persons |
| 1st notification |
6 months prior to decommissioning |
Developers & Visma Community |
File API contact persons |
| 2nd notification |
3 months prior to decommissioning |
Developers & Visma Community |
File API contact persons |
| 3rd notification |
1 months prior to decommissioning |
Developers & Visma Community |
File API contact persons |
In case you have any question or doubt during the integration, you can reach us through the Visma Developer Community in Slack.
Developers that use the File API or other Youforce APIs can use this community to talk with
- Visma developers that design and implement these APIs
- Visma consultant that help to connect with customer environments
- Other File API consumers
You can join here. Anyone can join!
Each Youforce API has it’s own channel starting with #youforce. The File API channel is #youforce-file-api.
Swagger
API reference can be found here.
Visma Denemarken
Visma Finland
Visma Letland
Visma Nederland
Visma Noorwegen
Visma Zweden
Visma Developers & Partners
Visma Latijns-Amerika