Skip to main content

​
Create your first roster

1

Authenticate

Create a POST request to the Visma Connect API to retrieve an access token. See Authentication for detailed instructions.
2

Specify the roster request

Build your roster request payload. See the API Reference for detailed instructions. For your first job, feel free to use the example payload below as a starting point.
{
  "jobInfo": {
    "id": "my-first-job",
    "organisationId": "my-organisation-id",
    "scheduleType": "CALENDAR",
    "demandType": "SHIFT_DEMAND",
    "planningHorizon": {
      "startDate": "2026-01-01",
      "endDate": "2026-01-31"
    }
  },
  "employees": [
    {
      "id": "employee-1",
    },
    {
      "id": "employee-2",
    }
  ],
  "shifts": [
    {
      "id": "shift-1",
    },
  ],
  "demands": [
    {
      "shiftDemands": [
        {
          "shiftId": "shift-1",
          "ideal": 2
        },
      ]
    }
  ]
}
3

Generate your first roster

Use the /jobs endpoint to start a job. The response will contain a statusCode and a jobId for your job.
4

Check job status

The job is now running. You can poll the /jobs/{jobId} endpoint to retrieve the status of the job. This will let you know whether the job is still running or has stopped.
5

Retrieve results

At any point in time, you can retrieve the current best result of the job by calling the /jobs/{jobId}/result endpoint. This will always be updated with the best result. Once the job has stopped, the result will be the final best result.

​
Generate types from the specification

The Automatic Rostering API is built on the OpenAPI Specification. You can generate code for your preferred programming language using the OpenAPI Specification. Once you have some experience with designing the payloads, we highly recommend using code-generation tools to help you get started with the API through the OpenAPI specification.
The OpenAPI specification for the Automatic Rostering service can be found here.
Use the OpenAPI Generator or Swagger Codegen to generate code for your preferred programming language.For example, to generate a C# client with the OpenAPI Generator, you can use the following command:
npx @openapitools/openapi-generator-cli generate -i ./openapi.yml -g csharp
There seems to be some conflicts if attempting to use the hosted resource directly (i.e., calling with the input: -i https://docs.optimization-rostering.prod.visma.net/openapi.yml), so it is recommended to download the file and use it locally.