---
title: "Create an appointment (job)"
method: POST
path: "/jobs"
tags: ["Jobs"]
---

# Create an appointment (job)

`POST /jobs`

## Request

- Base URL: `https://api3.autarc.energy/v1`
- URL: `https://api3.autarc.energy/v1/jobs`
- Auth: API key in header `X-Api-Key`

Creates an appointment in the company's planner, e.g. a consultation for a lead you hand over. It appears in the assigned team members' calendars, and they are notified as for an appointment created in the app. Changes and cancellations afterwards happen in autarc.

The request is rejected with `409` when the appointment falls into an assigned team member's busy time, exactly as `GET /team-members/{profileId}/availability` reports it: another appointment, an absence that is not declined, a company holiday, a connected Google or Outlook calendar, or time outside their working hours (or the company's opening hours). Send `allowConflicts: true` to create it anyway.

## Request body

- CreateJobRequest: A new appointment (job). The company is inferred from the API key / access token; projects, customers and team members must belong to it.
  - `title` string, required
  - `jobType` 'consultation' | 'maintenance' | 'repair' | 'emergency' | 'complaint' | 'other': Built-in appointment category. Defaults to `other`.
  - `startAt` string, date-time, required: RFC 3339 timestamp with an explicit timezone offset.
  - `endAt` string, date-time, required: RFC 3339 timestamp with an explicit timezone offset, after `startAt` and at most 31 days later.
  - `address` string, nullable: Free-text address of the appointment. With a `projectId`, the appointment also gets a copy of the project's site address (else the customer's), as when it is scheduled in autarc.
  - `contactPerson` string, nullable
  - `description` string, nullable
  - `projectId` string, uuid, nullable: Project the appointment belongs to. When `customerId` is omitted, the project's customer is used. A `consultation` on a project that has no scheduled consultation yet becomes the appointment shown in the project's On Site tab; an existing one is kept and the new appointment is added beside it.
  - `customerId` string, uuid, nullable: Customer the appointment is for. Must match the project's customer when both are sent.
  - `assignedProfileIds` string[]: Team members (profile ids, see `GET /team-members`) assigned to the appointment. They see it in their calendar and are notified as for an appointment created in the app.
  - `allowConflicts` boolean: Create the appointment even if it falls into an assigned team member's busy time (see `GET /team-members/{profileId}/availability`). By default the request is rejected with `409`.

## Response `201`

One appointment

- Job: An appointment (job) in the company's planner — a site visit, maintenance, repair, etc. Canceled appointments are included; check `canceledAt`.
  - `id` string, uuid, required
  - `title` string, required
  - `description` string, nullable
  - `jobType` 'consultation' | 'maintenance' | 'repair' | 'emergency' | 'complaint' | 'other', required: Built-in appointment category.
  - `jobTypeId` string, uuid, nullable: The company's custom appointment type, when one is set.
  - `startAt` string, date-time, nullable
  - `endAt` string, date-time, nullable
  - `address` string, nullable: Free-text address of the appointment.
  - `contactPerson` string, nullable
  - `color` string, nullable
  - `projectId` string, uuid, nullable
  - `customerId` string, uuid, nullable
  - `assignedProfileIds` string[], required: Team members (profile ids, see `GET /team-members`) assigned to the appointment.
  - `createdByProfileId` string, uuid, nullable
  - `canceledAt` string, date-time, nullable
  - `cancellationReason` 'customer_canceled' | 'customer_unavailable' | 'no_access' | 'weather' | 'staff_unavailable' | 'rescheduled' | 'other' | 'null', nullable
  - `cancellationNote` string, nullable
  - `companyId` string, uuid, required
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required

## Other responses

- `400`: Invalid request — a malformed id, filter, pagination parameter or body. The body is a plain-text message naming the problem.
- `403`: The access token's user may not create appointments.
- `404`: The project or customer was not found in the company.
- `409`: An assigned team member is busy at that time. Nothing was created.

---

[API](https://skmtc.dev/autarc/apis/autarc-2-0-api.md) - [All operations](https://skmtc.dev/autarc/apis/autarc-2-0-api/llms.txt) - [OpenAPI document](https://skmtc.dev/autarc/apis/autarc-2-0-api/revisions/adfb20a40efc?raw)