> ## 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">
    Create a `POST` request to the Visma Connect API to retrieve an access token. See [Authentication](/getting-started/authentication) for detailed instructions.
  </Step>

  <Step title="Specify the roster request">
    Build your roster request payload. See the [API Reference](/api-reference/roster/start-job) for detailed instructions. For your first job, feel free to use the example payload below as a starting point.

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

  <Step title="Generate your first roster">
    Use the [/jobs](/api-reference/roster/start-job) endpoint to start a job. The response will contain a
    `statusCode` and a `jobId` for your job.
  </Step>

  <Step title="Check job status">
    The job is now running. You can poll the [/jobs/\{jobId}](/api-reference/roster/get-job-status) endpoint to retrieve the status of the job. This will let you know whether the job is still running or has stopped.
  </Step>

  <Step title="Retrieve results">
    At any point in time, you can retrieve the current best result of the job by calling the [/jobs/\{jobId}/result](/api-reference/roster/get-result) endpoint. This will always be updated with the best result. Once the job has stopped, the result will be the final best 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 can be found [here](https://docs.optimization-rostering.prod.visma.net/openapi.yml).
  </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.yml -g csharp
    ```

    <Warning>
      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.
    </Warning>
  </Accordion>
</AccordionGroup>