1. Overview

Domain Purpose:
The Data API provides a standardized way of accessing data which is stored in various databases or data sources designed to be scalable in order to handle large volumes of data requests and flexible to accommodate various use cases and integration needs. The Data API was developed to support customer securely access and consume large volumes of data from the Youforce Data Warehouse through an asynchronous, scalable job-based model.

Typical Use Cases:

• Consume data from the Youforce Data Warehouse.
• Retrieve information to facilitate the sharing of accountability data between healthcare providers and information-requesting parties.
• Retrieve big amounts of information in an efficient way.

Base URL:
https://data.youforce.com/data/v1/

Developer Portal: Reference in the Developer portal to the Data API

2. Introduction to the basics

In this section, you will find clear definitions and short explanations of key terms and usage of this API, ensuring a common understanding to effectively function.

Key concepts

Let’s start explaining the key concepts that we will use during the rest of the documentation:

• Job: A “job” is a background process for loading data from a specific table into intermediate storage for streaming as a document upon completion in the selected format.
• Operation: An “operation” is a group of jobs, designed to simplify the management of multiple tables for customers who require consistent data sets.

How does this api work?

The system moved away from the typical entity-specific endpoints toward a catalog-driven model where customers define what they need using a configuration ID.

So to start using this API, you need to have a configuration created. In this configuration, it will be stated which specific data a consumer can retrieve from the reporting tables for a given tenant: you can select exactly which columns/fields per table to include in the response, allowing to fetch only the information really needed.

There can exist several configurations per tenant due to the fact that configurations are hardcoded and tied to a client Id, tenant Id and configuration Id to support several scenarios where a third party might consume data from multiple tenants. This allows customers to have a default configuration for regular data retrieval and create additional configurations for specific data sets or fields.

After this configuration has been created and access has been granted through Visma Connect, you can get a token to authenticate as a consumer.

Data API uses an asynchronous request pattern, where each request will be translated into an operation that is scheduled internally, processed in the background, and store the data in a temporary file storage for download in various formats (JSON, CSV). Due to the fact that customers can configure multiple tables together, when they trigger an operation, several jobs - one per table - will be scheduled in a background process. The integrator can monitor their collective status through a status endpoint, eliminating the need to manage individual jobs separately.

We also introduced the “metadata” endpoint, which allows customers to check to which tables and fields they have access, noting that only configured fields would be retrieved and displayed.

3. Security and Scopes

Our API implements several security mechanisms designed to ensure the privacy of consumers and the integrity of their data. This section highlights key features that safeguard user information:

• Add access restrictions to the data collected so it is only accessible by some groups through the internal network.
• Encryption of stored files. The files downloaded correctly in the api won’t be encrypted.
• Support DPoP (Demonstrating Proof of Possession), an advanced security mechanism that helps to prevent token theft and replay attacks by cryptographically binding access tokens to a specific client instance.

If you want more information regarding security, please, check our Security section

A layered authorization structure was introduced in the form of scopes, to ensure both security and scalability:

4. Endpoints

Metadata endpoint

This endpoint provides information related to the entities/tables configured in the current set: “tenant-clientId-configurationId”.
This means that for the configuration set for the current credentials, you have access to the information of the entities/tables returned in this endpoint.
The metadata endpoint only shows by default the default configuration if no specific configuration is provided. If you specify an concrete configuration by parameter, it will only show that one. So it will always return just one configuration.

Url: https://data.youforce.com/data/v1/metadata

GET → /data/v1/metadata

Let’s start by explaining how pagination works in this endpoint. These are the pagination fields that you can find in the Metadata endpoint:

• pageSize (integer): amount of configured mappings that the response will contain. The default value is 10.
• totalCount (integer): total amount of configured mappings in the data base.
• totalPages (integer): total amount of existing pages given the pageSize and totalCount values.
• hasPreviousPage (boolean): indicate whether there is a page with more values before the current page.
• hasNextPage (boolean): indicate whether there is a page with more values after the current page.
• currentPage (integer): page number that you want to retrieve. It can be below or equal to the ‘totalPages’ value in the response. Values ‘hasPreviousPage’ and ‘hasNextPage’ will also indicate if there is a page with more values before or after the current page. The default value is 1.

And these are some case scenarios you can find while looping through the pages:

• Send the first request without pagination parameters:
  - The currentPage is set to 1 (default value)
  - The pageSize is set to 10 (default value)
  Check the pagination metadata returned in the response:
  - totalPages will contain the total number of pages available
  - hasNextPage will contain whether another page exists after the current one
  
• Send the first request with pagination parameters:
  - Choose the desired currentPage (by default is 1)
  - Choose an appropriate pageSize (by default is 10)
  Check the pagination metadata returned in the response:
  - totalPages will contain the total number of pages available
  - hasPreviousPage will contain whether another page exists before the current one
  - hasNextPage will contain whether another page exists after the current one
  
• Loop through pages:
  - While hasNextPage is true, consumer can increment the currentPage value by 1 and make another request
  - When hasNextPage is false, you have reached the last page so consumer can stop the loop
  

Parameters

• Header parameters: Authorization (Bearer)
• Path parameters: None
• Query parameters:
  • EntityName: Explicit name of the entity which configuration needs to be retrieved. There might be several entities configured through different configurations.
  • EntityVersion: In case of existing several versions for the entities, this parameter will retrieve the configurations with entities for that version alone.
  • ConfigurationId: Id of a certain configuration for that clientId. If this parameter is not provided, the endpoint will return only the default configuration.
• Body parameters: None

curl --location 'https://data.youforce.com/data/v1/metadata?EntityName=sickness-case&EntityVersion=1&ConfigurationId=testing-default-4028868' \
--header 'Authorization: Bearer abc’

Response

If all went well it will return an OK response code → 200 OK

Explanation of the fields:

• Name: name of the entity
• Version: version of the entity
• odsName: name of the table from which you want to extract the information
• Fields: different fields that are configured along with some information about them:
  • Name: name of the field that will be shown
  • odsName: name of the field in the table from which you want to extract the information
  • Type: type of data (like string or integer)
  • isKey: it indicates whether the field is part of the key of the entity
  • isSelected: where the field is selected to be shown in the output.

{
    "items": [
        {
            "name": "person",
            "version": 1,
            "odsName": "TBL_Person",
            "fields": [
                {
                    "name": "Id",
                    "odsName": "ID",
                    "type": "Int32",
                    "isKey": true,
                    "isSelected": true
                },
                {
                    "name": "PersonBK",
                    "odsName": "Person_BK",
                    "type": "String",
                    "isKey": false,
                    "isSelected": true
                },
                {
                    "name": "FirstName",
                    "odsName": "PersonFirstName",
                    "type": "String",
                    "isKey": false,
                    "isSelected": true
                },
                {
                    "name": "LastName",
                    "odsName": "PersonLastName",
                    "type": "String",
                    "isKey": false,
                    "isSelected": true
                },
                {...}
            ],
            "configurationId": "testing-default-4028868"
        },
        {...}
    ],
    "totalCount": 7,
    "currentPage": 1,
    "pageSize": 10,
    "totalPages": 1,
    "hasPreviousPage": false,
    "hasNextPage": false
}

Full Data endpoint

This endpoint allows the consumer to start a data loader operation for configured entities to extract all the data of the configured tables in one single request.
This means that this endpoint will provide the complete data stored in our tables which is useful for initial loads of systems.
The consumer can also check the status of the operation, cancel it or delete the files created.

However, there is a limitation in the payroll table where the endpoint will only retrieve the data contained in the payroll table for the current and previous years.
Examples:

• Today is 1st November 2025 -> the api will retrieve the data from 1st January 2024.
  
• Today is 15th February 2025 -> the api will retrieve the data from 1st January 2024.
  
  

Url: https://data.youforce.com/data/v1/fulldata

POST → /data/v1/fulldata

With this action, the consumer will start a data loader operation for the selected configured entities.
It will run multiple jobs, one per entity/table configured or just one if the entity parameter is filled in.

If a new request is sent while another request is still being processed, the response will contain a 409 error.

Parameters

• Header parameters: Authorization (Bearer)
• Path parameters: None
• Query parameters: None
• Body parameters:
  • ConfigurationId: Explicit configuration that the consumer wants to apply. If no value is provided here, then the default configuration set as default in the Configuration API will be used.
  • FileFormat: Format in which the data will be returned in the file. Currently only csv and json formats are accepted.
  • Entity: Selected entity for which the operation will be performed. The operation will run just one job for that entity and the results will contain data for that entity alone. If no value is provided here, then all the entities defined for that configuration will be triggered, creating a job and an output file per entity.
  • Version: in case that a job can have multiple versions, the desired version. In case no value is provided here, then the last version will be taken.

curl --location 'https://data.youforce.com/data/v1/fulldata' \
--header 'Authorization: Bearer abc’
--header 'Content-Type: application/json' \
--data '{
  "configurationId": "testing-default-4028868",
  "fileFormat": "csv",
  "entity": "sickness-case",
  "version": 1
}'

Response

If all went well it will a created response code → 202 Accepted
The body of the response will also provide an operation ID that can be used for further queries in this API (check next endpoints).

{
    "operationId": "88549862-af91-49c1-9545-683edd948931"
}

PUT → /data/v1/fulldata/{fulldataOperationId}/retry

With this action, the consumer can retry a failed data loader operation identified by the ‘operationId’ value provided in response of the POST action when they requested the full data.
This means that if there are jobs within the operation that have failed, the api will retry just these failed jobs.
If there is an operation with no failed jobs and the retry action is triggered, the api will return a 404 Not Found code.

Parameters

• Header parameters: Authorization (Bearer)
• Path parameters:
  • OperationId: Id of the operation that was started in the POST action when creating a new Operation
• Query parameters: None
• Body parameters: None

curl --location --request PUT 'https://data.youforce.com/data/v1/fulldata/ed41e267-8cbb-4e08-b4bf-60d7a26d7fd8/retry' \
--header 'Authorization: Bearer abc’

Response

If all went well it will a created response code → 202 Accepted

POST → /data/v1/fulldata/{fulldataOperationId}/cancel

With this action, the consumer can cancel a data loader operation identified by the ‘operationId’ value provided in response of the POST action when they requested the full data.
This means that it will stop all the jobs of that concrete operation that are in progress: it cancels a job only if it is not completed yet, a job that has been completed cannot be cancelled.
In case the operation has been completed already, then it will return a 400 Bad Request code.
In case there are no jobs pending to be processed or being processed at the time, then the api will return a 404 Not Found code.

Parameters

• Header parameters: Authorization (Bearer)
• Path parameters:
  • OperationId: Id of the operation that was started in the POST action when creating a new Operation
• Query parameters: None
• Body parameters: None

curl --location --request POST 'https://data.youforce.com/data/v1/fulldata/ed41e267-8cbb-4e08-b4bf-60d7a26d7fd8/cancel' \
--header 'Authorization: Bearer abc’

Response

If all went well it will a created response code → 204 No content

DELETE → /data/v1/fulldata/{fulldataOperationId}

With this action, the consumer can delete the files created by a data loader operation identified by the ‘operationId’ value provided in response of the POST action when they requested the full data.
This means that it will delete all downloadable files of the jobs that has been completed for the specified Operation.
It will return a 400 Bad Request code in case the jobs are not completed.

Parameters

• Header parameters: Authorization (Bearer)
• Path parameters:
  • OperationId: Id of the operation that was started in the POST action when creating a new Operation
• Query parameters: None
• Body parameters: None

curl --location --request DELETE 'https://data.youforce.com/data/v1/fulldata/ed41e267-8cbb-4e08-b4bf-60d7a26d7fd8' \
--header 'Authorization: Bearer abc’

Response

If all went well it will a created response code → 204 No Content

GET → /data/v1/fulldata/{fulldataOperationId}/status

With this action, the consumer will get the status of the data loader operation identified by the ‘operationId’ value provided in response of the POST action when they requested the full data.
This means that you will receive the processing status of each job started within that concrete operation and an overall status of the operation.
When an operation contains several jobs with different status, the operation may be in a partial state:

• PartiallyFailed: when some of the jobs have failed and the rest have been completed.
• PartiallyCancelled: when some of the jobs have been cancelled but the rest have been completed.
• PartiallyDeleted: when some of the jobs have been deleted (therefore, the files deleted) but the rest have been completed.

Parameters

• Header parameters: Authorization (Bearer)
• Path parameters:
  • OperationId: Id of the operation that was started in the POST action when creating a new Operation
• Query parameters: None
• Body parameters: None

curl --location 'https://data.youforce.com/data/v1/fulldata/88549862-af91-49c1-9545-683edd948931/status' \
--header 'Authorization: Bearer abc’

Response

If all went well it will return an OK response code → 200 OK
Explanation of the fields:

• operationId: Operation Id requested
• configurationId: configuration Id applied for creating the output
• Status: status of the overall operation. Possible values are: Pending, Completed, Cancelled and Failed.
• Jobs: array with the status of the jobs individually
• Id: job Id for individual requests
  • Entity: entity related to that job
  • Version: version of the job that is being delivered
  • Status: status of that concrete job. Possible values are: Pending, Completed, Cancelled and Failed.
  • createdAt: date and time when the request was created
  • startedAt: date and time when the job was started
  • completedAt: date and time when the job was finished
  • cancelledAt: date and time when the job was cancelled
  • failedAt: date and time when the job failed
  • failedReason: reason why the job failed
  • totalCount: amount of rows that will be returned
  • processedCount: amount of rows that has been process at the time of this request
  • expirationDate: date and time when the file that contains the data retrieved will be eliminated from our systems
  • Links: array with all the link to download the files that has been processed successfully

Example of output with pending status:

{
    "operationId": "88549862-af91-49c1-9545-683edd948931",
    "configurationId": "testing-default-4028868",
    "status": "Pending",
    "jobs": [
        {
            "id": "0d629dbc-8d49-46df-8c0a-8469a67fd7d3",
            "entity": "sickness-case",
            "version": 1,
            "status": "Pending",
            "createdAt": "2025-10-30T13:24:33.078654Z"
        }
    ]
}

Example of output with finished status:

{
    "operationId": "88549862-af91-49c1-9545-683edd948931",
    "configurationId": "testing-default-4028868",
    "status": "Completed",
    "jobs": [
        {
            "id": "0d629dbc-8d49-46df-8c0a-8469a67fd7d3",
            "entity": "sickness-case",
            "version": 1,
            "status": "Completed",
            "createdAt": "2025-10-30T13:24:33.078654Z",
            "startedAt": "2025-10-30T13:25:05.183246Z",
            "completedAt": "2025-10-30T13:25:08.219779Z",
            "totalCount": 400,
            "processedCount": 400,
            "expirationDate": "2025-10-31T13:25:08.219808Z",
            "links": {
                "download": "https://data.youforce.com/data/v1/jobs/0d629dbc-8d49-46df-8c0a-8469a67fd7d3"
            }
        }
    ]
}

Jobs endpoint

This endpoint allows the consumer to download the data file for a completed data loader job.
There are two ways of getting this link:

• Once the job is complete, a request to the GET fullData status endpoint will offer the link in the response body.
• By getting the id of the job and, once it is complete, call directly to this endpoint.

In case the resulting data contains zero registers, an empty file will be created.
The file containing the data is stored in our systems for 24 hours. After this time the file is deleted. The “expirationDate” field of the GET status endpoint will provide the exact date and time when this will happen.

Url: https://data.youforce.com/data/v1/jobs

GET → /data/v1/jobs/{jobId}

Parameters

• Header parameters: Authorization (Bearer)
• Path parameters:
  • JobId: Id of the job that has been completed and it is ready to be downloaded.
• Query parameters: None
• Body parameters: None

curl --location curl --location 'https://data.youforce.com/data/v1/jobs/8a1c7cba-cbf4-43b5-9e9b-dbcb7ebb5543' \
--header 'Authorization: Bearer abc’

Response

If all went well it will return an OK response code → 200 OK

5. Good practices and possible errors

• There can only be one default configuration per tenant, clientId and configuration id.
• In the Data API, if the 'ConfigurationId' parameter is not provided, the API will automatically use the default configuration associated with the cliendId/tenant.
• Remember: configure the correct scopes to operate with this API.

6. Limitations

Currently for the full data endpoint we don’t have any restriction. This is due to the fact that we don’t many customers and it’s the only way they can get the data.
We are now working in a mechanism that allows data to be synchronized without the need to retrieve all the data. When this mechanism is in place, then we will add restrictions to the amount of request an integrator can make to the full data endpoint, so please, take this information into account when integrating with this API.

7. Swagger page

For more detailed information about the endpoints available in this API, please visit the Youforce Data API Swagger page

8. Postman collection

For a complete example, you can check our Postman collection