Introduction

Welcome to the Yellow Schedule API documentation. Yellow Schedule provides a secure, RESTful API that allows developers to integrate appointment scheduling, contact management, and availability checking into their applications.

Key Features

Authentication

The Yellow Schedule API uses JWT (JSON Web Token) bearer authentication. Include your API key in the Authorization header of every request.

Authentication Header Format

Example Request

curl -X GET "https://www.yellowschedule.com/app/api/v2/services" \
  -H "Authorization: bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

// Using cURL in PHP
$apiKey = "YOUR_API_KEY";
$url = "https://www.yellowschedule.com/app/api/v2/services";

$headers = [
    'Authorization: bearer ' . $apiKey,
    'Content-Type: application/json'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);

// Using Fetch API
const apiKey = 'YOUR_API_KEY';
const url = 'https://www.yellowschedule.com/app/api/v2/services';

fetch(url, {
  method: 'GET',
  headers: {
    'Authorization': `bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

import requests

api_key = "YOUR_API_KEY"
url = "https://www.yellowschedule.com/app/api/v2/services"

headers = {
    "Authorization": f"bearer {api_key}",
    "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
data = response.json()

API Keys

API keys control access to your Yellow Schedule account. Follow the principle of least privilege by creating keys with only the permissions your integration requires.

Creating an API Key

1. Log in to your Yellow Schedule account
2. Navigate to Settings (top right menu)
3. Select API Keys
4. Click Create New Key
5. Select the specific functions and HTTP methods you need
6. Save and securely store your API key

Permission Examples

Quick Start

Get up and running in minutes with this simple example that retrieves your contacts.

Live Example: Fetch Contacts

curl -X GET "https://www.yellowschedule.com/app/api/v2/contacts" \
  -H "Authorization: bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhIjp7ImNvbiI6InIifSwibSI6IjE2NDcxIiwidCI6MTQ4MDU5NzE5NCwiaWQiOjV9.9aExba9qw5rYr0b01dy01VezBJGb1pF-IsR9jSldO5Q"

$apiKey = "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhIjp7ImNvbiI6InIifSwibSI6IjE2NDcxIiwidCI6MTQ4MDU5NzE5NCwiaWQiOjV9.9aExba9qw5rYr0b01dy01VezBJGb1pF-IsR9jSldO5Q";
$url = "https://www.yellowschedule.com/app/api/v2/contacts";

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: bearer ' . $apiKey
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$contacts = json_decode($response, true);
print_r($contacts);

import requests

api_key = "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhIjp7ImNvbiI6InIifSwibSI6IjE2NDcxIiwidCI6MTQ4MDU5NzE5NCwiaWQiOjV9.9aExba9qw5rYr0b01dy01VezBJGb1pF-IsR9jSldO5Q"
url = "https://www.yellowschedule.com/app/api/v2/contacts"

headers = {"Authorization": f"bearer {api_key}"}
response = requests.get(url, headers=headers)
contacts = response.json()
print(contacts)

Expected Response

{
  "contacts": [
    {
      "contact_id": "con_xxxxxxxxx",
      "created_utc": "2016-01-15 12:45:56",
      "edited_utc": "2016-01-15 13:00:00",
      "firstname": "john",
      "lastname": "doe",
      "email": "test1@test.com",
      "cellphone": "123456789",
      "dob": "2000-12-25",
      "notes": "Client notes..."
    }
  ],
  "paginginfo": {
    "this_page": 1,
    "total_record_count": 1,
    "page_size": 100
  }
}

Error Handling

The Yellow Schedule API uses conventional HTTP response codes to indicate success or failure. Codes in the 2xx range indicate success, 4xx indicate client errors, and 5xx indicate server errors.

HTTP Status Codes

Error Response Format

All errors include a JSON response with details about what went wrong:

{
  "error": "invalid token or token was revoked or changed",
  "code": 401,
  "details": "The provided API key is not valid"
}

Rate Limits

To ensure fair usage and system stability, the Yellow Schedule API implements rate limiting. If you exceed your quota, you'll receive a 429 response.

Best Practices

• Implement exponential backoff when retrying failed requests
• Cache responses when appropriate to reduce API calls
• Use webhooks instead of polling for real-time updates
• Batch operations when possible

HTTP Methods (CRUD Operations)

The Yellow Schedule API follows RESTful conventions using standard HTTP methods to perform Create, Read, Update, and Delete (CRUD) operations.

Available API Endpoints

Pagination

List endpoints that return multiple results are automatically paginated. Use the page parameter to navigate through result sets.

Pagination Parameters

Pagination Response

All paginated endpoints include a paginginfo object in the response:

{
  "contacts": [ ... ],
  "paginginfo": {
    "result": "records found",
    "this_page": 1,
    "record_start_count": 1,
    "record_end_count": 100,
    "total_record_count": 127,
    "page_size": 100,
    "page_count": 2,
    "developer_notes": "Pagesize for this recordset is '100'. To view the next page, pass parameter 'page=2'"
  }
}

Example: Fetching Multiple Pages

# First page (implicit page=1)
curl "https://www.yellowschedule.com/app/api/v2/contacts" \
  -H "Authorization: bearer YOUR_API_KEY"

# Second page
curl "https://www.yellowschedule.com/app/api/v2/contacts?page=2" \
  -H "Authorization: bearer YOUR_API_KEY"

$page = 1;
$allContacts = [];

do {
    $url = "https://www.yellowschedule.com/app/api/v2/contacts?page=" . $page;
    $response = /* ... make API call ... */;
    $data = json_decode($response, true);

    $allContacts = array_merge($allContacts, $data['contacts']);
    $page++;
} while ($page <= $data['paginginfo']['page_count']);

Passing Parameters

Parameters are passed differently depending on the HTTP method:

URL Query String (GET/DELETE)

curl -G "https://www.yellowschedule.com/app/api/v2/appointments" \
  -H "Authorization: bearer YOUR_API_KEY" \
  --data-urlencode "range_start=2024-01-01 09:00:00" \
  --data-urlencode "range_end=2024-01-31 17:00:00" \
  --data-urlencode "user_id=usr_xxxxx"

$params = [
    'range_start' => '2024-01-01 09:00:00',
    'range_end' => '2024-01-31 17:00:00',
    'user_id' => 'usr_xxxxx'
];
$url = 'https://www.yellowschedule.com/app/api/v2/appointments?' . http_build_query($params);

JSON Request Body (POST/PUT)

curl -X POST "https://www.yellowschedule.com/app/api/v2/appointments" \
  -H "Authorization: bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start": "2024-01-15 10:00:00",
    "end": "2024-01-15 11:00:00",
    "title": "Initial Consultation",
    "user_id": "usr_xxxxx",
    "contact_id": "con_xxxxx"
  }'

$data = [
    'start' => '2024-01-15 10:00:00',
    'end' => '2024-01-15 11:00:00',
    'title' => 'Initial Consultation',
    'user_id' => 'usr_xxxxx',
    'contact_id' => 'con_xxxxx'
];

curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

Webhooks

Webhooks allow your application to receive real-time notifications when events occur in your Yellow Schedule account, eliminating the need for polling.

Setting Up Webhooks

1. Navigate to Settings → Webhooks
2. Enter your webhook endpoint URL (must be HTTPS)
3. Select the events you want to receive
4. Save your configuration

Available Webhook Events

Webhook Payload

For security reasons, webhook payloads contain only IDs. Use the API to fetch full details.

{
  "webhook_id": "ys_apt70a47393ce381a5f42",
  "webhook_created": 1494422644,
  "type": "appointment.created",
  "appointment_id_list": [
    {"id": "apt_90TQnJjVwVET0RjcVR0YHF3YK9UY1MzN"},
    {"id": "apt_90TU4BXMUV0T0ZHVNpVVDdWeN10VTRUM"}
  ],
  "livemode": true
}

Webhook Payload Fields

Handling Webhooks

Retry Policy

If your endpoint doesn't return a 200 status code, Yellow Schedule will retry the webhook:

• Up to 15 retry attempts
• Exponential backoff between retries
• First retry after 1 minute, increasing exponentially

Example Webhook Handler

// webhook-handler.php
$payload = json_decode(file_get_contents('php://input'), true);

// Return 200 immediately
http_response_code(200);

// Process asynchronously
if ($payload['type'] === 'appointment.created') {
    foreach ($payload['appointment_id_list'] as $item) {
        // Fetch full appointment details
        $appointmentId = $item['id'];
        // Process appointment...
    }
}

// Express.js webhook handler
app.post('/webhooks/yellowschedule', (req, res) => {
  const payload = req.body;

  // Return 200 immediately
  res.status(200).send('OK');

  // Process asynchronously
  if (payload.type === 'appointment.created') {
    payload.appointment_id_list.forEach(async (item) => {
      // Fetch full appointment details
      const appointment = await fetchAppointment(item.id);
      // Process appointment...
    });
  }
});

Appointments

Manage appointments including creation, retrieval, updates, and deletion. Appointments can be associated with contacts, services, locations, and resources.

GET Retrieve Appointments

Retrieve a specific appointment by ID, or fetch a list of appointments within a date range.

Parameters

Example Request

curl -G "https://www.yellowschedule.com/app/api/v2/appointments" \
  -H "Authorization: bearer YOUR_API_KEY" \
  --data-urlencode "range_start=2024-01-01 09:00:00" \
  --data-urlencode "range_end=2024-01-31 17:00:00" \
  --data-urlencode "user_id=usr_xxxxx"

$params = [
    'range_start' => '2024-01-01 09:00:00',
    'range_end' => '2024-01-31 17:00:00',
    'user_id' => 'usr_xxxxx'
];
$url = 'https://www.yellowschedule.com/app/api/v2/appointments?' . http_build_query($params);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: bearer YOUR_API_KEY']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$data = json_decode($response, true);

Response

{
  "appointments": [
    {
      "id": "apt_90TQnJjVwVET0RjcVR0YHF3YK9UY1MzN",
      "user_id": "usr_90TU4BXMUV0T0ZHVNpVVDdWeN10VTRUM",
      "title": "Initial Consultation",
      "service_id": "ser_90TUspnNlV2YKV3MsVkSMl2VxljW4V3a",
      "created": "24|01|15|10|30",
      "start": "24|01|20|09|00",
      "end": "24|01|20|10|00",
      "loc_id": "0",
      "note": "First time patient",
      "tz": "America/New_York",
      "color": "b04efc",
      "contact_count": "1",
      "contact_status": "confirmed"
    }
  ],
  "paginginfo": {
    "this_page": 1,
    "total_record_count": 1,
    "page_size": 100
  }
}

POST Create Appointment

Create a new appointment. Appointments must have a user, start time, and end time. Optionally include contacts, services, locations, and resources.

Parameters

Example Request

curl -X POST "https://www.yellowschedule.com/app/api/v2/appointments" \
  -H "Authorization: bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_xxxxx",
    "start": "2024-01-20 09:00:00",
    "end": "2024-01-20 10:00:00",
    "title": "Initial Consultation",
    "contact_id": "con_xxxxx",
    "service_id": "ser_xxxxx",
    "reminders": true
  }'

$data = [
    'user_id' => 'usr_xxxxx',
    'start' => '2024-01-20 09:00:00',
    'end' => '2024-01-20 10:00:00',
    'title' => 'Initial Consultation',
    'contact_id' => 'con_xxxxx',
    'service_id' => 'ser_xxxxx',
    'reminders' => true
];

$ch = curl_init('https://www.yellowschedule.com/app/api/v2/appointments');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);

Response

{
  "status": "success",
  "created_appointment_id": "apt_90TU4BXMUV0T0ZHVNpVVDdWeN10VTRUM"
}

PUT Update Appointment

Update an existing appointment. Only include the fields you want to change. Send an empty string to clear a field.

Parameters

Example Request

curl -X PUT "https://www.yellowschedule.com/app/api/v2/appointments" \
  -H "Authorization: bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "appointment_id": "apt_xxxxx",
    "start": "2024-01-20 10:00:00",
    "end": "2024-01-20 11:00:00",
    "title": "Follow-up Consultation"
  }'

Response

{
  "status": "success",
  "updated_appointment_id": "apt_xxxxx"
}

DELETE Delete Appointment

Permanently delete an appointment.

Parameters

Example Request

curl -X DELETE "https://www.yellowschedule.com/app/api/v2/appointments?appointment_id=apt_xxxxx" \
  -H "Authorization: bearer YOUR_API_KEY"

Response

{
  "status": "success",
  "deleted_appointment_id": "apt_xxxxx"
}

Available Slots

Check availability and find open time slots for users. Perfect for building booking interfaces.

GET Get Available Slots

Retrieve available time slots for one or more users within a specified date range.

Parameters

Example Request

curl -G "https://www.yellowschedule.com/app/api/v2/availableSlots" \
  -H "Authorization: bearer YOUR_API_KEY" \
  --data-urlencode "user_id=usr_xxxxx" \
  --data-urlencode "range_start=2024-01-20 09:00:00" \
  --data-urlencode "range_end=2024-01-27 17:00:00" \
  --data-urlencode "service_id=ser_xxxxx"

Response

{
  "available_slots": [
    {
      "user_id": "usr_xxxxx",
      "start": "2024-01-20 09:00:00",
      "end": "2024-01-20 10:00:00",
      "duration_minutes": 60
    },
    {
      "user_id": "usr_xxxxx",
      "start": "2024-01-20 14:00:00",
      "end": "2024-01-20 15:00:00",
      "duration_minutes": 60
    }
  ]
}

Contacts

Manage contacts (clients/patients). All contact data is encrypted in transit and at rest.

GET Retrieve Contacts

Retrieve a specific contact by ID or get a list of all contacts.

Parameters

POST Create Contact

Create a new contact record.

Parameters

Example Request

curl -X POST "https://www.yellowschedule.com/app/api/v2/contacts" \
  -H "Authorization: bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstname": "Jane",
    "lastname": "Smith",
    "email": "jane.smith@example.com",
    "cellphone": "+1234567890",
    "dob": "1990-05-15"
  }'

Response

{
  "status": "success",
  "created_contact_id": "con_90TU4BXMUV0T0ZHVNpVVDdWeN10VTRUM"
}

PUT Update Contact

Update an existing contact. Include contact_id and any fields to update.

DELETE Delete Contact

Permanently delete a contact by providing contact_id.

Services

Retrieve the list of appointment services configured in your account (e.g., "X-Ray", "Consultation", "Follow-up").

GET List Services

Get all services available on your account.

Example Request

curl "https://www.yellowschedule.com/app/api/v2/services" \
  -H "Authorization: bearer YOUR_API_KEY"

Response

{
  "services": [
    {
      "service_id": "ser_xxxxx",
      "name": "Initial Consultation",
      "duration": 60,
      "description": "First time patient consultation",
      "color": "3498db"
    },
    {
      "service_id": "ser_yyyyy",
      "name": "Follow-up",
      "duration": 30,
      "description": "Return visit",
      "color": "2ecc71"
    }
  ]
}

Users

Retrieve users (staff members) on your Yellow Schedule account.

GET List Users

Get all users configured on your account.

Example Request

curl "https://www.yellowschedule.com/app/api/v2/users" \
  -H "Authorization: bearer YOUR_API_KEY"

Response

{
  "users": [
    {
      "user_id": "usr_xxxxx",
      "firstname": "Dr. John",
      "lastname": "Doe",
      "email": "john.doe@clinic.com",
      "title": "General Practitioner",
      "active": true
    }
  ]
}