> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automaticrostering.visma.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Learn how to create your first roster

## Create your first roster

<Steps>
  <Step title="Authenticate">
    Retrieve an access token from Visma Connect. See [Authentication](/v2/getting-started/authentication) for detailed instructions on creating an application, adding the `Automatic Rostering` integration, and requesting a token with the `automatic-rostering:full` scope.
  </Step>

  <Step title="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.

    <Accordion title="Example payload">
      ```json theme={null}
      {
        "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
              }
            ]
          }
        ]
      }
      ```
    </Accordion>
  </Step>

  <Step title="Generate your first roster">
    Use the `POST /roster/start` endpoint to start a job. The response will contain the `jobId` for your roster job.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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.

<AccordionGroup>
  <Accordion icon="copy" title="Get the OpenAPI specification">
    The OpenAPI specification for the Automatic Rostering service is available at [`/openapi.yaml`](/openapi.yaml).
  </Accordion>

  <Accordion icon="gears" title="Generate code">
    Use the [OpenAPI Generator](https://openapi-generator.tech/) or [Swagger Codegen](https://swagger.io/tools/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:

    ```bash theme={null}
      npx @openapitools/openapi-generator-cli generate -i ./openapi.yaml -g csharp
    ```
  </Accordion>
</AccordionGroup>