Create a visit for an existing job
curl --request POST \
--url https://api.getbreezyapp.com/v1/job-appointments \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"job_id": "11111111-1111-4111-8111-000000000501",
"window_start_at": "2026-09-08T19:00:00Z",
"window_end_at": "2026-09-08T21:00:00Z"
}
'import requests
url = "https://api.getbreezyapp.com/v1/job-appointments"
payload = {
"job_id": "11111111-1111-4111-8111-000000000501",
"window_start_at": "2026-09-08T19:00:00Z",
"window_end_at": "2026-09-08T21:00:00Z"
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
job_id: '11111111-1111-4111-8111-000000000501',
window_start_at: '2026-09-08T19:00:00Z',
window_end_at: '2026-09-08T21:00:00Z'
})
};
fetch('https://api.getbreezyapp.com/v1/job-appointments', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"data": {
"id": "11111111-1111-4111-8111-000000001109",
"number": "300",
"job_id": "11111111-1111-4111-8111-000000000501",
"type": "Other",
"description": "Air conditioner repair visit",
"window_start_at": "2026-09-08T19:00:00Z",
"window_end_at": "2026-09-08T21:00:00Z",
"confirmed": false,
"canceled": false,
"cancellation_reason": null,
"cancellation_note": null,
"created_by": {
"id": "11111111-1111-4111-8111-000000000401",
"name": "Alex Example"
},
"created_at": "2026-08-19T16:00:00Z",
"updated_at": "2026-09-08T19:00:00Z",
"kind": "APPOINTMENT",
"starts_at": "2026-09-08T19:00:00Z",
"ends_at": "2026-09-08T21:00:00Z",
"revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"job": {
"id": "11111111-1111-4111-8111-000000000501",
"number": "200",
"summary": "Repair air conditioner",
"account": {
"id": "11111111-1111-4111-8111-000000000101",
"name": "Example Household"
},
"location": {
"id": "11111111-1111-4111-8111-000000001107",
"name": "Home",
"address": "123 Example Lane, Los Angeles, CA 90001",
"latitude": 34.02,
"longitude": -118.25
},
"contact": {
"id": "11111111-1111-4111-8111-000000001101",
"name": "Jordan Example"
},
"business_unit": {
"id": "11111111-1111-4111-8111-000000000201",
"name": "Service"
},
"job_type": {
"id": "11111111-1111-4111-8111-000000000301",
"name": "HVAC Service"
},
"job_class": "SERVICE"
},
"assignments": [
{
"id": "11111111-1111-4111-8111-000000001113",
"job_id": "11111111-1111-4111-8111-000000000501",
"appointment_id": "11111111-1111-4111-8111-000000001109",
"team_member": {
"id": "11111111-1111-4111-8111-000000000401",
"name": "Alex Example"
},
"starts_at": "2026-09-08T19:30:00Z",
"ends_at": "2026-09-08T20:30:00Z",
"status": "TO_DO",
"status_updated_at": "2026-09-08T18:00:00Z",
"created_at": "2026-08-19T16:00:00Z",
"updated_at": null
},
{
"id": "11111111-1111-4111-8111-000000002001",
"job_id": "11111111-1111-4111-8111-000000000501",
"appointment_id": "11111111-1111-4111-8111-000000001109",
"team_member": {
"id": "11111111-1111-4111-8111-000000002002",
"name": "Sam Example"
},
"starts_at": "2026-09-08T19:30:00Z",
"ends_at": "2026-09-08T20:30:00Z",
"status": "TO_DO",
"status_updated_at": "2026-09-08T18:00:00Z",
"created_at": "2026-08-19T16:00:00Z",
"updated_at": null
}
],
"dispatch_status": "ASSIGNED"
},
"notification": {
"status": "NOT_REQUESTED"
},
"meta": {
"request_id": "11111111-1111-4111-8111-000000009999",
"generated_at": "2026-09-08T19:00:00Z",
"timezone": "America/Los_Angeles"
}
}{
"error": {
"code": "INVALID_REQUEST",
"message": "end_date must be later than start_date",
"request_id": "example-request",
"details": []
}
}{
"error": {
"code": "UNAUTHENTICATED",
"message": "A valid API key is required",
"request_id": "example-request",
"details": []
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Resource not found",
"request_id": "example-request",
"details": []
}
}{
"error": {
"code": "METHOD_NOT_ALLOWED",
"message": "This resource supports GET",
"request_id": "example-request",
"details": []
}
}{
"error": {
"code": "STALE_REVISION",
"message": "The visit changed; read it again before editing",
"request_id": "example-request",
"details": []
}
}{
"error": {
"code": "INVALID_REQUEST",
"message": "Request body exceeds 64 KB",
"request_id": "example-request",
"details": []
}
}{
"error": {
"code": "RATE_LIMITED",
"message": "Request limit exceeded",
"request_id": "example-request",
"details": []
}
}{
"error": {
"code": "INTERNAL_ERROR",
"message": "Unable to complete request",
"request_id": "example-request",
"details": []
}
}Scheduling
Create a visit for an existing job
Company-scoped scheduling write available to every valid API key. Requires Idempotency-Key; retries with the same caller, key and parsed request return the committed visit without repeating the change or customer notification. Reusing a key with different input returns 409. Updates require expected_revision from the schedule visit read. Omitted or null customer_notification sends nothing. Explicit notifications use the selected account contact primary channel. Notification failure does not roll back scheduling; UNKNOWN may have reached the provider and is never automatically resent. SUPPRESSED means the visit revision or recipient eligibility changed before delivery. Write timestamps support at most six fractional digits; UUIDs are case-insensitive. Assignment changes preserve the arrival window unless explicitly updated. Outside-window work requires allow_outside_window=true. No availability or double-booking guarantee. Active/completed assignment changes return 409. See the scheduling guide for replacement arrays, reminders and deferred workflows.
POST
/
job-appointments
Create a visit for an existing job
curl --request POST \
--url https://api.getbreezyapp.com/v1/job-appointments \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"job_id": "11111111-1111-4111-8111-000000000501",
"window_start_at": "2026-09-08T19:00:00Z",
"window_end_at": "2026-09-08T21:00:00Z"
}
'import requests
url = "https://api.getbreezyapp.com/v1/job-appointments"
payload = {
"job_id": "11111111-1111-4111-8111-000000000501",
"window_start_at": "2026-09-08T19:00:00Z",
"window_end_at": "2026-09-08T21:00:00Z"
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
job_id: '11111111-1111-4111-8111-000000000501',
window_start_at: '2026-09-08T19:00:00Z',
window_end_at: '2026-09-08T21:00:00Z'
})
};
fetch('https://api.getbreezyapp.com/v1/job-appointments', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"data": {
"id": "11111111-1111-4111-8111-000000001109",
"number": "300",
"job_id": "11111111-1111-4111-8111-000000000501",
"type": "Other",
"description": "Air conditioner repair visit",
"window_start_at": "2026-09-08T19:00:00Z",
"window_end_at": "2026-09-08T21:00:00Z",
"confirmed": false,
"canceled": false,
"cancellation_reason": null,
"cancellation_note": null,
"created_by": {
"id": "11111111-1111-4111-8111-000000000401",
"name": "Alex Example"
},
"created_at": "2026-08-19T16:00:00Z",
"updated_at": "2026-09-08T19:00:00Z",
"kind": "APPOINTMENT",
"starts_at": "2026-09-08T19:00:00Z",
"ends_at": "2026-09-08T21:00:00Z",
"revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"job": {
"id": "11111111-1111-4111-8111-000000000501",
"number": "200",
"summary": "Repair air conditioner",
"account": {
"id": "11111111-1111-4111-8111-000000000101",
"name": "Example Household"
},
"location": {
"id": "11111111-1111-4111-8111-000000001107",
"name": "Home",
"address": "123 Example Lane, Los Angeles, CA 90001",
"latitude": 34.02,
"longitude": -118.25
},
"contact": {
"id": "11111111-1111-4111-8111-000000001101",
"name": "Jordan Example"
},
"business_unit": {
"id": "11111111-1111-4111-8111-000000000201",
"name": "Service"
},
"job_type": {
"id": "11111111-1111-4111-8111-000000000301",
"name": "HVAC Service"
},
"job_class": "SERVICE"
},
"assignments": [
{
"id": "11111111-1111-4111-8111-000000001113",
"job_id": "11111111-1111-4111-8111-000000000501",
"appointment_id": "11111111-1111-4111-8111-000000001109",
"team_member": {
"id": "11111111-1111-4111-8111-000000000401",
"name": "Alex Example"
},
"starts_at": "2026-09-08T19:30:00Z",
"ends_at": "2026-09-08T20:30:00Z",
"status": "TO_DO",
"status_updated_at": "2026-09-08T18:00:00Z",
"created_at": "2026-08-19T16:00:00Z",
"updated_at": null
},
{
"id": "11111111-1111-4111-8111-000000002001",
"job_id": "11111111-1111-4111-8111-000000000501",
"appointment_id": "11111111-1111-4111-8111-000000001109",
"team_member": {
"id": "11111111-1111-4111-8111-000000002002",
"name": "Sam Example"
},
"starts_at": "2026-09-08T19:30:00Z",
"ends_at": "2026-09-08T20:30:00Z",
"status": "TO_DO",
"status_updated_at": "2026-09-08T18:00:00Z",
"created_at": "2026-08-19T16:00:00Z",
"updated_at": null
}
],
"dispatch_status": "ASSIGNED"
},
"notification": {
"status": "NOT_REQUESTED"
},
"meta": {
"request_id": "11111111-1111-4111-8111-000000009999",
"generated_at": "2026-09-08T19:00:00Z",
"timezone": "America/Los_Angeles"
}
}{
"error": {
"code": "INVALID_REQUEST",
"message": "end_date must be later than start_date",
"request_id": "example-request",
"details": []
}
}{
"error": {
"code": "UNAUTHENTICATED",
"message": "A valid API key is required",
"request_id": "example-request",
"details": []
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Resource not found",
"request_id": "example-request",
"details": []
}
}{
"error": {
"code": "METHOD_NOT_ALLOWED",
"message": "This resource supports GET",
"request_id": "example-request",
"details": []
}
}{
"error": {
"code": "STALE_REVISION",
"message": "The visit changed; read it again before editing",
"request_id": "example-request",
"details": []
}
}{
"error": {
"code": "INVALID_REQUEST",
"message": "Request body exceeds 64 KB",
"request_id": "example-request",
"details": []
}
}{
"error": {
"code": "RATE_LIMITED",
"message": "Request limit exceeded",
"request_id": "example-request",
"details": []
}
}{
"error": {
"code": "INTERNAL_ERROR",
"message": "Unable to complete request",
"request_id": "example-request",
"details": []
}
}Authorizations
Existing Breezy API key. Grants all published reads and scheduling writes in its associated company. No app permission scopes.
Headers
Pattern:
^[A-Za-z0-9_-]{8,128}$Body
application/json
Pattern:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,6})?(?:Z|[+-]\d{2}:?\d{2})$Pattern:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,6})?(?:Z|[+-]\d{2}:?\d{2})$Available options:
Callback, Diagnostic, FPI, Installation, Maintenance, Permit Inspection, Plumbing Call Back, Plumbing RFS, Plumbing Warranty, Pre-Install Job Walk, QCI, Quality Assurance Walkthrough, Repair, Sales Visit, Site Visit, Sales, Water Purity, Other Maximum string length:
10000Maximum array length:
100Show child attributes
Show child attributes
Show child attributes
Show child attributes
Response
Committed visit and notification outcome. Replays retain the original visit snapshot; reread for current state.
Show child attributes
Show child attributes
The scheduling change is committed regardless of notification outcome. UNKNOWN may have reached the provider and is never automatically resent. SUPPRESSED means the visit or recipient changed before delivery.
Show child attributes
Show child attributes
Generation time and company timezone. generated_at is not a snapshot or synchronization token.
Show child attributes
Show child attributes