---
agentTools:
  projectIndex: https://docs.oncallhealth.io/llms.txt
---

# Create a new appointment

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "oncall",
    "version": "1.2"
  },
  "servers": [
    {
      "url": "https://api.oncallhealth.ca"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "oauth2",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://example.com/oauth2/token",
            "scopes": {}
          }
        }
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/appointments/": {
      "post": {
        "summary": "Create a new appointment",
        "description": "",
        "operationId": "create-appointment",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "title",
                  "type",
                  "participants",
                  "duration",
                  "division"
                ],
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "The title of the appointment."
                  },
                  "type": {
                    "type": "string",
                    "description": "The type of appointment. Accepted values are (\"online\", \"inperson\", \"phone\", \"message\")."
                  },
                  "participants": {
                    "type": "array",
                    "description": "A list of participants to invite to the appointment. Maximum 25 participants per appointment.",
                    "items": {
                      "properties": {
                        "email": {
                          "type": "string",
                          "description": "Email address of the participant"
                        },
                        "name": {
                          "type": "string",
                          "description": "Full name of the patient"
                        },
                        "fee": {
                          "type": "number",
                          "description": "The fee to charge the patient upon successfully completing the appointment. Optional and only available if your account has patient billing enabled.",
                          "default": 0,
                          "format": "float"
                        }
                      },
                      "required": [
                        "email",
                        "name",
                        "fee"
                      ],
                      "type": "object"
                    }
                  },
                  "duration": {
                    "type": "integer",
                    "description": "The length of the appointment in minutes.",
                    "format": "int32"
                  },
                  "division": {
                    "type": "string",
                    "description": "The URL to the division in which to create this appointment. This will be https://api.oncallhealth.ca/divisions/{division_id}/."
                  },
                  "provider": {
                    "type": "string",
                    "description": "The URL of the provider. This will be in the form of https://api.oncallhealth.ca/providers/{provider_id}/ and can be obtained using the Providers API. Defaults to the requesting user, so it is optional for providers, but not for coordinators."
                  },
                  "datetime": {
                    "type": "string",
                    "description": "ISO8601 representation of the datetime when the appointment should be scheduled for. This field is required if \"type\" is one of (\"online\", \"inperson\", \"phone\").",
                    "format": "date"
                  },
                  "metadata": {
                    "type": "string",
                    "description": "A freeform metadata object. Use this to attach your unique identifiers to an appointment.",
                    "format": "json"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "201",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"url\": \"https://api.oncallhealth.ca/appointments/1234/\",\n    \"title\": \"Sample API appointment\",\n    \"datetime\": \"2026-01-15T00:00:00Z\",\n    \"duration\": 60,\n    \"type\": \"online\",\n    \"status\": \"Incomplete\",\n    \"cancelled\": false,\n    \"division\": \"https://api.oncallhealth.ca/divisions/123/\",\n    \"participants\": [\n        {\n          \t\"url\": \"https://api.oncallhealth.ca/participants/56/\",\n          \t\"answers\": \"https://api.oncallhealth.ca/appointmentfieldanswers/?participant_id=56\",\n            \"appointment\": \"https://api.oncallhealth.ca/appointments/1234/\",\n            \"name\": \"Test Patient\",\n            \"first_name\": \"Test\",\n   \t\t\t\t\t\"last_name\": \"Patient\",\n            \"email\": \"admin@oncallhealth.ca\",\n            \"fee\": 70.0,\n            \"cancelled\": false,\n          \t\"user_id\": 2\n        }\n    ],\n    \"answers\": \"https://api.oncallhealth.ca/appointmentfieldanswers/?appointment_id=1234\",\n    \"metadata\": null\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string",
                      "example": "https://api.oncallhealth.ca/appointments/1234/"
                    },
                    "title": {
                      "type": "string",
                      "example": "Sample API appointment"
                    },
                    "datetime": {
                      "type": "string",
                      "example": "2026-01-15T00:00:00Z"
                    },
                    "duration": {
                      "type": "integer",
                      "example": 60,
                      "default": 0
                    },
                    "type": {
                      "type": "string",
                      "example": "online"
                    },
                    "status": {
                      "type": "string",
                      "example": "Incomplete"
                    },
                    "cancelled": {
                      "type": "boolean",
                      "example": false,
                      "default": true
                    },
                    "division": {
                      "type": "string",
                      "example": "https://api.oncallhealth.ca/divisions/123/"
                    },
                    "participants": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "url": {
                            "type": "string",
                            "example": "https://api.oncallhealth.ca/participants/56/"
                          },
                          "answers": {
                            "type": "string",
                            "example": "https://api.oncallhealth.ca/appointmentfieldanswers/?participant_id=56"
                          },
                          "appointment": {
                            "type": "string",
                            "example": "https://api.oncallhealth.ca/appointments/1234/"
                          },
                          "name": {
                            "type": "string",
                            "example": "Test Patient"
                          },
                          "first_name": {
                            "type": "string",
                            "example": "Test"
                          },
                          "last_name": {
                            "type": "string",
                            "example": "Patient"
                          },
                          "email": {
                            "type": "string",
                            "example": "admin@oncallhealth.ca"
                          },
                          "fee": {
                            "type": "integer",
                            "example": 70,
                            "default": 0
                          },
                          "cancelled": {
                            "type": "boolean",
                            "example": false,
                            "default": true
                          },
                          "user_id": {
                            "type": "integer",
                            "example": 2,
                            "default": 0
                          }
                        }
                      }
                    },
                    "answers": {
                      "type": "string",
                      "example": "https://api.oncallhealth.ca/appointmentfieldanswers/?appointment_id=1234"
                    },
                    "metadata": {}
                  }
                }
              }
            }
          }
        },
        "deprecated": false,
        "x-readme": {
          "code-samples": [
            {
              "language": "curl",
              "code": "curl --request POST 'https://api.oncallhealth.ca/appointments/' \\\n--header 'Authorization: Token YOUR_PROVIDER_TOKEN' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n\t\"division\":\"https://api.oncallhealth.ca/divisions/123/\",\n\t\"participants\": [{\n\t\t\"email\":\"patient@email.com\",\n\t\t\"name\": \"Test Patient\",\n\t\t\"fee\": 10\n\t}],\n\t\"datetime\": \"2026-01-15T0:00:00Z\",\n\t\"duration\": 60,\n\t\"title\": \"Sample API appointment\",\n\t\"type\": \"online\"\n}'"
            }
          ],
          "samples-languages": [
            "curl"
          ]
        }
      }
    }
  },
  "x-readme": {
    "headers": [
      {
        "key": "Authorization",
        "value": "Token YOUR_PROVIDER_TOKEN"
      }
    ],
    "explorer-enabled": false,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true,
  "_id": "62e03e9f2e494c003d6f7e00:62e03e9f2e494c003d6f7e14"
}
```