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

# Create Appointment

> Create an appointment

Create an appointment using a time slot from the [Search Open Times](/api-reference/open-times/search) endpoint.

## Workflow

1. Call [Search Open Times](/api-reference/open-times/search) to get available slots
2. Use the `uuid` from a result as the `slot_id` in this request
3. Identify the client and patient using one of the supported lookup methods

## Client Identification

Provide **one** of the following to identify the client:

* `client_id` — internal Oliver ID
* `client_remote_id` — PIMS remote ID
* `first_name` + `last_name` + (`phone` or `email`) — name-based lookup

## Patient Identification

Provide **one** of the following to identify the patient:

* `patient_id` — internal Oliver ID
* `patient_remote_id` — PIMS remote ID


## OpenAPI

````yaml POST /services/core/open_api/v1/appointments
openapi: 3.1.0
info:
  title: Oliver Partner API
  description: API for partners to interact with Oliver
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://partner-api.getoliver.com
security:
  - bearerAuth: []
paths:
  /services/core/open_api/v1/appointments:
    post:
      description: Create an appointment
      requestBody:
        description: Appointment to create
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAppointmentRequest'
      responses:
        '200':
          description: Appointment created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAppointmentResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignInError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
components:
  schemas:
    CreateAppointmentRequest:
      type: object
      required:
        - slot_id
      properties:
        slot_id:
          type: string
          description: >-
            The slot identifier returned from the Search Open Times endpoint
            (the `uuid` field). Encodes the appointment type, provider, room,
            and time.
        client_id:
          type: integer
          description: >-
            The internal Oliver ID of the client. Provide this,
            `client_remote_id`, or name + contact fields.
        client_remote_id:
          type: string
          description: The PIMS remote ID of the client. Alternative to `client_id`.
        first_name:
          type: string
          description: >-
            Client first name. Must be combined with `last_name` and either
            `phone` or `email`.
        last_name:
          type: string
          description: >-
            Client last name. Must be combined with `first_name` and either
            `phone` or `email`.
        phone:
          type: string
          description: >-
            Client phone number. Used with `first_name` + `last_name` to look up
            the client.
        email:
          type: string
          description: >-
            Client email. Used with `first_name` + `last_name` to look up the
            client.
        patient_id:
          type: integer
          description: >-
            The internal Oliver ID of the patient. Provide this or
            `patient_remote_id`.
        patient_remote_id:
          type: string
          description: The PIMS remote ID of the patient. Alternative to `patient_id`.
        note:
          type: string
          description: A note for the appointment.
        status:
          type: string
          description: >-
            Appointment status override. If omitted, the clinic's auto-accept
            setting determines the status.
          enum:
            - REQUESTED
            - ACCEPTED
            - CONFIRMED
    CreateAppointmentResponse:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
        data:
          type: object
          required:
            - id
          properties:
            id:
              type: integer
              description: The internal Oliver ID of the appointment
            remote_id:
              type: string
              nullable: true
              description: The PIMS remote ID of the appointment, if synced
            remote_client_id:
              type: string
              nullable: true
              description: The PIMS remote ID of the client
            remote_patient_id:
              type: string
              nullable: true
              description: The PIMS remote ID of the patient
            status:
              type: string
              description: The appointment status
              enum:
                - REQUESTED
                - ACCEPTED
                - CONFIRMED
                - IN_PROGRESS
                - DONE
                - DELETED
                - DECLINED
            booking_date:
              type: string
              format: date-time
              description: The start date/time of the appointment in ISO 8601 format
            end_date:
              type: string
              format: date-time
              description: The end date/time of the appointment in ISO 8601 format
            created_at:
              type: string
              format: date-time
              description: When the appointment was created in ISO 8601 format
            updated_at:
              type: string
              format: date-time
              description: When the appointment was last updated in ISO 8601 format
            referral_source:
              type: string
              nullable: true
            referral_campaign:
              type: string
              nullable: true
            referral_medium:
              type: string
              nullable: true
            client_first_name:
              type: string
              description: The client's first name
            client_last_name:
              type: string
              description: The client's last name
            client_email:
              type: string
              nullable: true
              description: The client's email address
            client_phone:
              type: string
              nullable: true
              description: The client's phone number
            client_type:
              type: string
              description: Whether the client is NEW or RETURNING
            patient_name:
              type: string
              description: The patient's name
        message:
          type: string
          description: A human-readable message, e.g. 'Appointment created successfully'
    SignInError:
      type: object
      required:
        - success
        - message
      properties:
        success:
          type: boolean
        data:
          type: object
        message:
          type: string
          description: Incorrect email
    GeneralError:
      type: object
      required:
        - success
        - message
      properties:
        success:
          type: boolean
        message:
          type: string
        data:
          type: object
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````