Appointments API

Appointments endpoints

Base URL: https://api.web.aivapad.io/api/external/v1

Use these endpoints to manage scheduling reliably and reduce calendar conflicts across teams.

Required scopes:

• appointments:read for schedule visibility and conflict checks
• appointments:write for appointment lifecycle management

Appointment response shape (example):

{
  "_id": "eeaa0637-a55e-4f9b-9e54-ec4f9f2b9e95",
  "title": "Site Visit",
  "date": "2026-04-10",
  "startTime": "09:00",
  "endTime": "10:00",
  "status": "default",
  "clientFirstName": "Jane",
  "clientLastName": "Smith",
  "clientEmail": "jane@example.com",
  "location": "Client Office",
  "notificationEnabled": true,
  "allDay": false,
  "createdAt": "2026-04-06T20:33:50.414Z",
  "updatedAt": "2026-04-06T20:33:50.414Z"
}

1) List appointments

GET /appointments

curl -X GET "https://api.web.aivapad.io/api/external/v1/appointments" \
  -H "Authorization: Bearer aiva_YOUR_TOKEN_HERE"

Successful response (200):

{
  "success": true,
  "data": []
}

2) Get appointment by ID

GET /appointments/:id

curl -X GET "https://api.web.aivapad.io/api/external/v1/appointments/eeaa0637-a55e-4f9b-9e54-ec4f9f2b9e95" \
  -H "Authorization: Bearer aiva_YOUR_TOKEN_HERE"

Successful response (200):

{
  "success": true,
  "data": {
    "_id": "eeaa0637-a55e-4f9b-9e54-ec4f9f2b9e95",
    "title": "Site Visit"
  }
}

3) Create appointment

POST /appointments

Minimum validation:

• title is required

curl -X POST "https://api.web.aivapad.io/api/external/v1/appointments" \
  -H "Authorization: Bearer aiva_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Site Visit",
    "date": "2026-04-10",
    "startTime": "09:00",
    "endTime": "10:00",
    "clientFirstName": "Jane",
    "clientLastName": "Smith",
    "clientEmail": "jane@example.com",
    "notificationEnabled": true
  }'

Successful response (201):

{
  "success": true,
  "data": {
    "_id": "eeaa0637-a55e-4f9b-9e54-ec4f9f2b9e95",
    "title": "Site Visit"
  }
}

4) Check time conflicts

POST /appointments/check-conflict

Required fields:

• date
• startTime
• endTime

Optional:

• excludeId (use when editing an existing appointment)

curl -X POST "https://api.web.aivapad.io/api/external/v1/appointments/check-conflict" \
  -H "Authorization: Bearer aiva_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-04-10",
    "startTime": "09:00",
    "endTime": "10:00"
  }'

Successful response (200):

{
  "success": true,
  "data": {
    "hasConflict": false,
    "conflictingAppointments": []
  }
}

5) Update appointment

PUT /appointments/:id

Supports partial or full updates.

curl -X PUT "https://api.web.aivapad.io/api/external/v1/appointments/eeaa0637-a55e-4f9b-9e54-ec4f9f2b9e95" \
  -H "Authorization: Bearer aiva_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "success",
    "notes": "Client confirmed on site"
  }'

Successful response (200):

{
  "success": true,
  "data": {
    "_id": "eeaa0637-a55e-4f9b-9e54-ec4f9f2b9e95",
    "status": "success"
  }
}

6) Delete appointment

DELETE /appointments/:id

curl -X DELETE "https://api.web.aivapad.io/api/external/v1/appointments/eeaa0637-a55e-4f9b-9e54-ec4f9f2b9e95" \
  -H "Authorization: Bearer aiva_YOUR_TOKEN_HERE"

Successful response (200):

{
  "success": true
}

Error reference

Common errors across appointments endpoints:

• 403 Forbidden:
  • token missing/invalid/expired
  • token permission does not include required access
  • token is not mapped to an active account context
• 404 Not Found: appointment ID does not exist in your tenant
• 400 Bad Request: invalid payload or missing required fields
• 500 Internal Server Error: unexpected server-side failure