Skip to main content

​
Create your first roster

1

Authenticate

Retrieve an access token from Visma Connect. See Authentication for detailed instructions on creating an application, adding the Automatic Rostering integration, and requesting a token with the automatic-rostering:full scope.
2

Specify the roster request

Build your roster request payload for the /roster/start endpoint. For your first job, feel free to use the example payload below as a starting point.
{
  "context": {
    "planId": "my-first-plan",
    "identity": {
      "tenantId": "my-tenant-id",
      "userId": "my-user-id"
    },
    "horizon": {
      "startDate": "2026-01-01",
      "endDate": "2026-01-31",
      "scheduleType": "CALENDAR"
    },
    "demandType": "SHIFT_DEMAND"
  },
  "employees": [
    {
      "id": "employee-1"
    },
    {
      "id": "employee-2"
    }
  ],
  "shifts": [
    {
      "id": "shift-1",
      "intervals": [
        {
          "startTime": "09:00",
          "endTime": "17:00",
          "dayIndicator": 0
        }
      ]
    }
  ],
  "demands": [
    {
      "days": {
        "dates": ["2026-01-01", "2026-01-02", "2026-01-03"]
      },
      "shiftDemands": [
        {
          "shiftId": "shift-1",
          "ideal": 2
        }
      ]
    }
  ]
}
3

Generate your first roster

Use the POST /roster/start endpoint to start a job. The response will contain the jobId for your roster job.
4

Check job status

The job is now running. You can poll the GET /roster/status/{jobId} endpoint to retrieve its current status and see whether it is still running or has stopped.
5

Retrieve results

Retrieve the current best result by calling the GET /roster/result/{jobId} endpoint. While the job is still processing, this endpoint can return 202 Accepted. Once the job has finished, the response will contain the latest 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 is available at /openapi.yaml.
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.yaml -g csharp