Skip to main content

API Reference

PayrollDetect API (1.0)

Download OpenAPI specification:Download

Welcome to the Resolve PayrollDetect API.

Upload data

Get Presigned URL

Obtain a presigned URL to upload data to the platform. This URL allows you to make a PUT request with the data in the request body. Depending on the optional 'type' query parameter, the uploaded data can either trigger a prediction job or be stored for general use.

The URL is valid for 60 minutes. The user must specify the Tenant-ID, which is required in the request header.

  • Use 'prediction' as the type to trigger processing that initiates a prediction job with the uploaded data.
  • Use 'raw_data' as the type for standard data uploads. This is the default behavior if the type parameter is not specified.

Authorizations:
visma_connect
query Parameters
type
string
Default: "raw_data"
Enum: "prediction" "raw_data"

Determines the type of data the presigned URL will be used for. "prediction" indicates prediction data; "raw_data" indicates that it will be used as training data. Defaults to "raw_data" if not provided.

header Parameters
tenantId
required
string

The ID of the tenant.

Responses

Response samples

Content type
application/json
{
  • "url": "string",
  • "jobId": "string",
  • "message": "string"
}

Get Job Status

Get the status for a validation, training, or prediction job. Use the job ID that was returned when the job was created. If the job runs with multiple datasets, the status for each dataset's process is returned.

Authorizations:
visma_connect
header Parameters
tenantId
required
string

The ID of the tenant.

jobId
required
string

The ID of the job to check the status for.

Responses

Response samples

Content type
application/json
{
  • "status": "inProgress",
  • "datasetsStatus": [
    ],
  • "message": "string"
}

Upload Data or Trigger Prediction Jobs via Presigned URL

This endpoint allows you to upload datasets for training, or trigger prediction jobs by using a presigned URL. The first step is to retrieve a presigner URL from the GET /presigned_url endpoint. If you want to upload data for training, set the `type=raw_data. If you want to trigger a prediction job, set the `type=prediction`.

When you have retrieved a presigned URL from the GET /presigned_url endpoint, the next step is to make a PUT request to the URL.

The body of the PUT request should contain the datasets that you want to upload, following the exact schema defined below. Please make sure that all keys in the JSON body are in camelCase (like you see in the schema), and that the values are of the correct type and following the defined requirements.

A 200 response code is typically returned after the PUT request, even if the data is invalid, as validation happens only during job processing. To confirm success, monitor the job's status using the jobId provided in the initial response.

Usage Overview

  1. Prepare a JSON file containing the data to be uploaded or prediction input:
    1. Follow the required JSON schema for data uploads or prediction requests, ensuring all keys are in camelCase and values conform to data type requirements.
  2. Use the GET /presigned_url endpoint to retrieve a presigned URL and a unique jobId:
    1. Set the type parameter to specify either "data upload" or "prediction".
  3. Perform a PUT request to the retrieved presigned URL with the JSON data in the request body.
  4. Monitor the job's status to verify successful execution:
    1. Periodically check the job status by calling GET /status with the jobId to confirm the outcome as "success".
    2. Alternatively, include a webhook URL in the PUT request to receive automatic status updates when the job completes.
  5. In cases of data validation failure, the job status will be "invalid". This means the provided data did not meet schema or format requirements, and affected datasets will not be processed. Review the error message for troubleshooting guidance, or reach out for support if additional assistance is needed.
Authorizations:
None
Request Body schema: application/json
required

JSON payload containing the required data for model training or prediction. Must adhere to one of the specified schemas.

One of
required
Array of objects (Raw Data Upload Request Dataset) non-empty

Datasets containing raw data for training.

object

Details for the webhook endpoint to call when a job finishes.

Responses

Callbacks

Request samples

Content type
application/json
Example
{
  • "datasets": [
    ],
  • "webhook": {}
}

Callback payload samples

Callback
POST: Notification of Job Completion
Content type
application/json
{
  • "status": "success",
  • "jobId": "7720a8c02c664d80a69ed2141b731ee3",
  • "message": "The job has been completed successfully"
}

Training

Get Job Status

Get the status for a validation, training, or prediction job. Use the job ID that was returned when the job was created. If the job runs with multiple datasets, the status for each dataset's process is returned.

Authorizations:
visma_connect
header Parameters
tenantId
required
string

The ID of the tenant.

jobId
required
string

The ID of the job to check the status for.

Responses

Response samples

Content type
application/json
{
  • "status": "inProgress",
  • "datasetsStatus": [
    ],
  • "message": "string"
}

Start Trainer

Starts a new trainer job.

Step-by-step instructions

  1. Determine the tenant and dataset(s) to run the trainer job for.
  2. Create the parametersArray with parameters for each dataset.
  3. Send a `POST` request to this endpoint, following the schema below.
    1. The endpoint will return a jobId.
  4. Do one of the following...
    1. Call GET /status with the tenantId and jobId in the header until the status is “success”.
    2. Provide a webhook in the body of the `POST` request in step 3 to receive a request when the job is finished running. See the Callbacks below for details about this request.
Authorizations:
visma_connect
header Parameters
tenantId
required
string

Tenant ID

Request Body schema: application/json
required
datasetIds
required
Array of strings non-empty

List of unique IDs of the datasets on which the training should be run. The models will be trained from scratch on all uploaded information in the dataset.

object

Details for the webhook endpoint to call when a job finishes.

Responses

Callbacks

Request samples

Content type
application/json
{
  • "datasetIds": [
    ],
  • "webhook": {}
}

Response samples

Content type
application/json
{
  • "jobId": "string",
  • "message": "string"
}

Callback payload samples

Callback
POST: Sends a notification that a job has ended
Content type
application/json
{
  • "status": "success",
  • "jobId": "7720a8c02c664d80a69ed2141b731ee3",
  • "message": "The training job finished successfully"
}

Predictions

Get Job Status

Get the status for a validation, training, or prediction job. Use the job ID that was returned when the job was created. If the job runs with multiple datasets, the status for each dataset's process is returned.

Authorizations:
visma_connect
header Parameters
tenantId
required
string

The ID of the tenant.

jobId
required
string

The ID of the job to check the status for.

Responses

Response samples

Content type
application/json
{
  • "status": "inProgress",
  • "datasetsStatus": [
    ],
  • "message": "string"
}

Create Prediction

Starts a prediction job which computes and stores anomaly scores for each datasetId included in the request body. Fetch the results from the results endpoint.

Step-by-step instructions

  1. Determine the tenant and dataset(s) to create predictions for.
  2. Create the parametersArray with parameters for each dataset.
  3. Send a `POST` request to this endpoint following the schema below.
    1. The endpoint will return a jobId.
  4. Do one of the following...
    1. Call GET /status with the tenantId and jobId in the header until the status is “success”.
    2. Provide a webhook in the body of the PUT request in step 3 to receive a request when the job is finished running.
  5. If the job status is "success", send a `GET` request to the /result endpoint with the jobId in the header to fetch the predictions.
Authorizations:
visma_connect
header Parameters
tenantId
required
string

Tenant ID

Request Body schema: application/json
required

The body should contain the datasetIds that predictions should be computed for, in addition to required inventory-related data.

required
Array of objects (Prediction Dataset) non-empty

Prediction datasets for which predictions should be made.

object

Details for the webhook endpoint to call when a job finishes.

Responses

Callbacks

Request samples

Content type
application/json
{
  • "datasets": [
    ],
  • "webhook": {}
}

Response samples

Content type
application/json
{
  • "jobId": "string",
  • "message": "string"
}

Callback payload samples

Callback
POST: Sends a notification that a job has ended
Content type
application/json
{
  • "status": "success",
  • "jobId": "7720a8c02c664d80a69ed2141b731ee3",
  • "message": "The prediction job finished successfully"
}

Real-Time Prediction

Computes and returns anomaly scores for each datasetId provided in the parametersArray of the requestBody in real time.

As the forecast is provided in the request, the forecasting functionality is bypassed to start the inventory suggestion calculation directly. This is a fast process, which is why this endpoint can be executed in real-time.

Authorizations:
visma_connect
header Parameters
tenantId
required
string

Tenant ID

Request Body schema: application/json
required

The body should contain the datasetIds that suggestions should be computed for, a sales forecast for each dataset, and required inventory-related data.

required
Array of objects (Prediction Dataset) non-empty

Prediction parameters for each dataset.

Array (non-empty)
id
required
string non-empty

The unique identifier of the dataset that this prediction should be based on. Make sure that you have uploaded training dataset with this id before and have trained the model on it.

required
Array of objects (Payslip)

The payslips to make predictions on.

Responses

Request samples

Content type
application/json
{
  • "datasets": [
    ]
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "code": "CLIENT_ID_MISSING",
  • "message": "string",
  • "details": "string",
  • "timestamp": "string",
  • "error_uuid": "string"
}

Real-Time Prediction

Computes and returns anomaly scores for each datasetId provided in the parametersArray of the requestBody in real time.

As the forecast is provided in the request, the forecasting functionality is bypassed to start the inventory suggestion calculation directly. This is a fast process, which is why this endpoint can be executed in real-time.

Authorizations:
visma_connect
header Parameters
tenantId
required
string

Tenant ID

Request Body schema: application/json
required

The body should contain the datasetIds that suggestions should be computed for, a sales forecast for each dataset, and required inventory-related data.

required
Array of objects (Prediction Dataset) non-empty

Prediction parameters for each dataset.

Array (non-empty)
id
required
string non-empty

The unique identifier of the dataset that this prediction should be based on. Make sure that you have uploaded training dataset with this id before and have trained the model on it.

required
Array of objects (Payslip)

The payslips to make predictions on.

Responses

Request samples

Content type
application/json
{
  • "datasets": [
    ]
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "code": "CLIENT_ID_MISSING",
  • "message": "string",
  • "details": "string",
  • "timestamp": "string",
  • "error_uuid": "string"
}

Get Prediction Results

Get the results of a prediction job.

Authorizations:
visma_connect
header Parameters
tenantId
required
string

Tenant ID

jobId
required
string

The unique ID of the job

page
integer >= 1
Default: 1

The page number

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "page": 1,
  • "pages": 1,
  • "datasetResults": [
    ]
}

Upload Data or Trigger Prediction Jobs via Presigned URL

This endpoint allows you to upload datasets for training, or trigger prediction jobs by using a presigned URL. The first step is to retrieve a presigner URL from the GET /presigned_url endpoint. If you want to upload data for training, set the `type=raw_data. If you want to trigger a prediction job, set the `type=prediction`.

When you have retrieved a presigned URL from the GET /presigned_url endpoint, the next step is to make a PUT request to the URL.

The body of the PUT request should contain the datasets that you want to upload, following the exact schema defined below. Please make sure that all keys in the JSON body are in camelCase (like you see in the schema), and that the values are of the correct type and following the defined requirements.

A 200 response code is typically returned after the PUT request, even if the data is invalid, as validation happens only during job processing. To confirm success, monitor the job's status using the jobId provided in the initial response.

Usage Overview

  1. Prepare a JSON file containing the data to be uploaded or prediction input:
    1. Follow the required JSON schema for data uploads or prediction requests, ensuring all keys are in camelCase and values conform to data type requirements.
  2. Use the GET /presigned_url endpoint to retrieve a presigned URL and a unique jobId:
    1. Set the type parameter to specify either "data upload" or "prediction".
  3. Perform a PUT request to the retrieved presigned URL with the JSON data in the request body.
  4. Monitor the job's status to verify successful execution:
    1. Periodically check the job status by calling GET /status with the jobId to confirm the outcome as "success".
    2. Alternatively, include a webhook URL in the PUT request to receive automatic status updates when the job completes.
  5. In cases of data validation failure, the job status will be "invalid". This means the provided data did not meet schema or format requirements, and affected datasets will not be processed. Review the error message for troubleshooting guidance, or reach out for support if additional assistance is needed.
Authorizations:
None
Request Body schema: application/json
required

JSON payload containing the required data for model training or prediction. Must adhere to one of the specified schemas.

One of
required
Array of objects (Raw Data Upload Request Dataset) non-empty

Datasets containing raw data for training.

object

Details for the webhook endpoint to call when a job finishes.

Responses

Callbacks

Request samples

Content type
application/json
Example
{
  • "datasets": [
    ],
  • "webhook": {}
}

Callback payload samples

Callback
POST: Notification of Job Completion
Content type
application/json
{
  • "status": "success",
  • "jobId": "7720a8c02c664d80a69ed2141b731ee3",
  • "message": "The job has been completed successfully"
}

Data management

Get Data

This endpoint returns list of dataset IDs that have been uploaded for the given tenant.

Authorizations:
visma_connect
header Parameters
tenantId
required
string

The ID of the tenant.

Responses

Response samples

Content type
application/json
{
  • "countOfDatasets": 1,
  • "datasetIds": [
    ]
}

Get Data for Dataset

This endpoint allows you to get information about specific dataset.

Authorizations:
visma_connect
path Parameters
datasetId
required
string

The dataset ID to delete data for.

header Parameters
tenantId
required
string

The ID of the tenant.

Responses

Response samples

Content type
application/json
Example
{
  • "startDate": "2022-04-01",
  • "endDate": "2022-04-08",
  • "intervalGranularity": "D",
  • "numberOfIntervalsWithRecords": 5,
  • "numberOfIntervalsWithoutRecords": 3,
  • "numberOfIntervalsTotal": 8
}

Delete Data

Delete uploaded data for a specific dataset ID.

Authorizations:
visma_connect
path Parameters
datasetId
required
string

The dataset ID to delete data for.

query Parameters
fromDate
string

Earliest data point to be deleted. If not specified, all data until the "toDate" will be deleted.

toDate
string

The latest data point to be deleted. If not specified, all data from the "fromDate" will be deleted.

header Parameters
tenantId
required
string

The ID of the tenant.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Feedback

Upload Feedback

This endpoint allows users to upload feedback for predictions made by the AI model. The feedback helps improve the model by providing insights into the accuracy of its predictions.

Authorizations:
visma_connect
header Parameters
tenantId
required
string

Tenant ID

Request Body schema: application/json
required

The body should contain the datasets for which feedback is being provided, including the dataset ID, job ID, and feedback for each prediction.

required
Array of objects
Array
datasetId
required
string

Unique identifier for the dataset

jobId
required
string

Unique identifier for the job that generated the predictions

required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "datasets": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Feedback successfully uploaded"
}

Subscription management

Get Subscriptions

This endpoint provides an overview of the subscriptions for a tenant, with optional filtering by dataset ID and subscription IDs.

Authorizations:
visma_connect
query Parameters
datasetId
string

Optional dataset ID to filter subscriptions.

subscriptionIds
string

Optional comma-separated list of subscription IDs to filter within the dataset.

header Parameters
tenantId
required
string

The ID of the tenant.

Responses

Response samples

Content type
application/json
{
  • "countOfDatasets": 0,
  • "countOfSubscriptionIds": 0,
  • "subscriptionObjects": [
    ]
}

Unsubscribe

Unsubscribe for a list of subscription objects.

Authorizations:
visma_connect
header Parameters
tenantId
required
string

The ID of the tenant.

Request Body schema: application/json
required

The dataset IDs and optionally subscription IDs to unsubscribe.

required
Array of objects (Subscription Object)

List of subscription objects.

Array
datasetId
required
string

The dataset ID.

subscriptionIds
Array of strings

Responses

Request samples

Content type
application/json
{
  • "subscriptionObjects": [
    ]
}

Response samples

Content type
application/json
{
  • "countOfUnsubscribedDatasets": 0,
  • "countOfUnsubscribedSubscriptionIds": 0,
  • "unsubscribedSubscriptionObjects": [
    ]
}

Health check

Health Check

Check the health of the service.

Responses