Notify API

Use the Notify API to ask CheckYout to send a WhatsApp message to a specific phone number — typically the cleaner for a given property.

Endpoint

POST/api/v1/notify

Request

Header	Value	Required
`Content-Type`	`application/json`	Yes
`X-API-Key`	Your API key	Yes

Request body

Field	Type	Required	Description
`device_id`	`string`	Yes	UUID of the CheckYout device. Must belong to your account.
`phone`	`string`	Yes	Phone number in E.164 format. Must match `^\+[1-9]\d{6,15}$`, e.g. `+41791234567`.
`name`	`string`	No	Display name of the property in the WhatsApp message. Falls back to the device property_name.

Response

Success response (200)

{
  "success": true,
  "message_sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Error responses

Status	Cause	Example
`400`	Validation failed (e.g. missing required fields, invalid phone format)	`{"error":"Validation error","issues":[{"path":"phone","message":"Phone must be in E.164 format…","code":"invalid_string"}]}`
`400`	Body is not valid JSON	`{"error":"Invalid JSON body"}`
`401`	Invalid or missing API key	`{"error":"Invalid or missing API key"}`
`404`	Device not found or does not belong to your account	`{"error":"Device not found or does not belong to your account"}`
`429`	Rate limit exceeded (30 requests/minute per IP)	`{"error":"Too many requests"}`
`500`	WhatsApp delivery failed	`{"error":"Failed to send WhatsApp","details":"..."}`

Code examples

curl -X POST https://checkyout.app/api/v1/notify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cyo_YourApiKey" \
  -d '{
    "device_id": "d4f8a2b1-3c5e-4f6a-8b9c-1d2e3f4a5b6c",
    "phone": "+41791234567",
    "name": "Alpenblick Vacation Rental"
  }'

const response = await fetch('https://checkyout.app/api/v1/notify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.CHECKYOUT_API_KEY,
  },
  body: JSON.stringify({
    device_id: 'd4f8a2b1-3c5e-4f6a-8b9c-1d2e3f4a5b6c',
    phone: '+41791234567',
    name: 'Alpenblick Vacation Rental',
  }),
});

if (!response.ok) {
  const error = await response.json();
  throw new Error(error.error);
}

const data = await response.json();
console.log('Message sent:', data.message_sid);

import requests
import os

response = requests.post(
    "https://checkyout.app/api/v1/notify",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": os.environ["CHECKYOUT_API_KEY"],
    },
    json={
        "device_id": "d4f8a2b1-3c5e-4f6a-8b9c-1d2e3f4a5b6c",
        "phone": "+41791234567",
        "name": "Alpenblick Vacation Rental",
    },
)

response.raise_for_status()
data = response.json()
print(f"Message sent: {data['message_sid']}")

<?php
$ch = curl_init('https://checkyout.app/api/v1/notify');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-API-Key: ' . getenv('CHECKYOUT_API_KEY'),
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'device_id' => 'd4f8a2b1-3c5e-4f6a-8b9c-1d2e3f4a5b6c',
        'phone' => '+41791234567',
        'name' => 'Alpenblick Vacation Rental',
    ]),
]);

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

if ($httpCode !== 200) {
    throw new Exception('Error: ' . $response);
}

$data = json_decode($response, true);
echo 'Message sent: ' . $data['message_sid'];

Notes

WhatsApp template

The message uses a CheckYout-defined WhatsApp template. Templates are available in nine languages: DE, EN, FR, ES, IT, NL, HR, EL, PT. The language is selected automatically from the host's settings.

Notification channels

Beyond WhatsApp, CheckYout also supports email and webhook channels. Channels are configured per property in the CheckYout dashboard.

Next: Events reference