Skip to content
Developers
Voxbi Cockpit APIs
API Guides
All endpoints

Create a schedule

Creates a schedule for the calling PBX. Requires the schedules scope on an Integrations API key (a user bearer token also passes).

Send the schedule's time rules in steps, the same list the cockpit edit page shows: weekly windows (days_of_the_week), specific calendar dates (fixed_dates), yearly dates (recurring_dates) and date-time ranges (specific_period). The schedule and all of its steps are written in one transaction: if any step is invalid the request responds 422 and nothing is created. A schedule created without steps has none and matches nothing until steps are added. Step ids are assigned by the server; sending one here responds 422.

pbx_id is forced from the authenticated principal (a user's PBX, or the Pbx-owned API key itself) and is never read from the request body: sending another tenant's id has no effect. Schedule names are not required to be unique within a PBX.

The response is the created schedule, unwrapped (no data envelope), and is identical to what a subsequent GET of the same id returns.

HTTP: bearerAuth

User bearer token. Default authentication for customer-facing endpoints. Obtain a token by calling POST /login with your credentials, then send it on every subsequent request as Authorization: Bearer <token>. The token inherits the permissions and PBX scope of the authenticated user.

HTTP Authorization Scheme
bearer
Bearer format
Bearer <token>
HTTP: IntegrationApiKey

API key created on the Cockpit Integrations page (an "API key" integration). It is a bearer token owned by the customer's PBX and limited to the scopes selected when the key was created (e.g. phone-numbers, push-configuration).

Send it in the Authorization header:

Authorization: Bearer <api_key>

Manage keys (create / reveal / revoke) from Integrations → New integration → API key.

HTTP Authorization Scheme
bearer
accept header · string
example: application/json

Request body · required · application/json

Request schema
name*string
Human-readable label for the schedule, shown in the cockpit and when selecting the schedule in a call flow.
length: 1–255
example: Business hours
descriptionstring | null
Optional free-text note describing the purpose or coverage of the schedule. Omit or send null for none.
length: 0–255
example: Monday to Friday, 09:00 to 18:00
stepsarray<object>
The schedule's time rules (the list on the cockpit edit page). Optional on every write: omit it to leave the steps as they are. When sent, the steps become exactly this list: an item with an `id` updates that step, an item without one creates a step, and any existing step not listed is deleted (an administrator can restore it from the cockpit trash). Send `[]` to remove every step. At most 100 steps. Each item is one of the ScheduleStepInput variants.
items: 0–100
[]object
One step (time rule) in a schedule write. Pick the variant that matches `type`. Keys that belong to another type are ignored, not stored. - `id`: include it to UPDATE that existing step of this schedule (it may even change type). Leave it out to CREATE a new step. Not allowed on `POST /schedules`. An id that is not a live step of this schedule responds 422. Sending back exactly what GET returned changes nothing (no rewrite, no `updated_at` bump). - `status`: `enabled` (default when omitted or null) or `disabled`. `true`, `1`, `"1"`, `"true"` and `false`, `0`, `"0"`, `"false"` are accepted as aliases. - Times are 24-hour `HH:MM` in the PBX's local time. `HH:MM:SS` is accepted and the seconds are dropped. Equivalent inputs that are also accepted (and normalized to the documented shape): `days_of_the_week` as a list of enabled day names (`["monday", "friday"]`) or as the JSON string the cockpit stores; `fixed_dates` and `recurring_dates` as one comma-separated string; recurring dates as `M-D` or `YYYY-MM-DD` (the year is ignored); `specific_period` as flat `specific_period_start` and `specific_period_end` keys, and its date-times with a `T` separator or seconds.

Responses

Response schema
id*string · uuid
Unique identifier of the schedule.
read-only
example: 550e8400-e29b-41d4-a716-446655440000
pbx_id*string · uuid
Identifier of the owning tenant (Pbx). Every schedule is scoped to exactly one tenant.
example: 550e8400-e29b-41d4-a716-446655440001
name*string
Human-readable label for the schedule, shown in the cockpit and used when selecting the schedule in call flows.
length: 0–255
example: Business hours
descriptionstring | null
Optional free-text note describing the purpose or coverage of the schedule. Null when no description was provided.
length: 0–255
example: Monday to Friday, 09:00 to 18:00
steps*array<object>
The schedule's time rules, the list on the cockpit edit page. Ordered by type (`days_of_the_week`, `fixed_dates`, `recurring_dates`, `specific_period`) and then by creation. Empty when the schedule has no steps, in which case it matches nothing.
Each item — One time rule of a schedule, as listed on the schedule's cockpit edit page. A call flow's schedule step matches when ANY enabled step of the schedule matches the current date and time. Every rule key is always present. Only the one that matches `type` is filled and the others are null: | `type` | Filled keys | |---|---| | `days_of_the_week` | `start_time`, `end_time`, `days_of_the_week` | | `fixed_dates` | `start_time`, `end_time`, `fixed_dates` | | `recurring_dates` | `start_time`, `end_time`, `recurring_dates` | | `specific_period` | `specific_period` (`start_time` and `end_time` are null) | This is the same shape the write endpoints accept in `steps`, so a client can read a schedule, edit its `steps` and send them back unchanged.
id*string · uuid
Unique identifier of the step. Send it back in `steps` to update this step instead of replacing it.
read-only
example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
type*string
Kind of rule. `days_of_the_week`: a weekly time window. `fixed_dates`: a time window on specific calendar dates. `recurring_dates`: a time window on the same day and month every year. `specific_period`: one continuous range between two date-times.
enum: days_of_the_week fixed_dates recurring_dates specific_period
example: days_of_the_week
status*string
A disabled step is kept but never matches.
enum: enabled disabled
example: enabled
start_time*string | null
Start of the daily window, 24-hour `HH:MM`, in the PBX's local time. Null for `specific_period`.
pattern: ^\d{2}:\d{2}$
example: 09:00
end_time*string | null
End of the daily window, 24-hour `HH:MM`, in the PBX's local time. Null for `specific_period`.
pattern: ^\d{2}:\d{2}$
example: 18:00
days_of_the_week*object | null
For `days_of_the_week` steps, one flag per weekday; `true` means the window applies on that day. Null for other types.
monday*boolean
tuesday*boolean
wednesday*boolean
thursday*boolean
friday*boolean
saturday*boolean
sunday*boolean
fixed_dates*array<string>
For `fixed_dates` steps, the calendar dates (`YYYY-MM-DD`) the window applies on, in the order they were saved. Null for other types.
[]string · date
recurring_dates*array<string>
For `recurring_dates` steps, the days (`MM-DD`) the window applies on every year, in the order they were saved, each once. Null for other types.
[]string
pattern: ^\d{2}-\d{2}$
specific_period*object | null
For `specific_period` steps, the inclusive range (`YYYY-MM-DD HH:MM`, PBX local time). Null for other types.
start*string
example: 2026-08-03 08:00
end*string
example: 2026-08-17 18:00
created_atstring | null · date-time
Timestamp (ISO 8601, UTC) when the step was created.
read-only
example: 2024-03-01T08:29:07.000000Z
updated_atstring | null · date-time
Timestamp (ISO 8601, UTC) when the step was last modified.
read-only
example: 2024-03-01T08:29:07.000000Z
created_atstring | null · date-time
Timestamp (ISO 8601, UTC) when the schedule was created.
read-only
example: 2024-03-01T08:29:07Z
updated_atstring | null · date-time
Timestamp (ISO 8601, UTC) when the schedule was last modified.
read-only
example: 2024-03-01T08:29:07Z
Unauthenticated. The `Authorization: Bearer <token>` header was missing, malformed, or names a token that has been revoked or deleted.
Response schema
messagestring
Forbidden. The bearer token authenticated successfully but does not carry the scope this endpoint requires. Re-create the Integrations API key with the missing scope selected (Integrations > New integration > API key).
Response schema
messagestring
Unprocessable Entity. The request body failed validation. `errors` maps each rejected field to its messages, and `message` repeats the first one. Nothing was written.
Response schema
messagestring
The first validation message, repeated for convenience.
errorsobject
Step errors are keyed by their path in the body, zero-based (`steps.1.days_of_the_week`, `steps.2.fixed_dates.0`), and every message names the step by its one-based position ("Step 2: ...").
namearray<string>
[]string
descriptionarray<string>
[]string
Too Many Requests. The rate limit for this action has been exceeded. Retry after the window indicated by the Retry-After header.
Response schema
messagestring
Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue.
Response schema
messagestring
exceptionstring
Only present in non-production environments.
filestring
Only present in non-production environments.
lineinteger
Only present in non-production environments.
post https://cockpit.voxbi.com/api/v1/schedules
Base URL
Request sample 
curl -X POST 'https://cockpit.voxbi.com/api/v1/schedules' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"name":"Business hours","description":"Monday to Friday, 09:00 to 18:00","steps":[{"type":"days_of_the_week","start_time":"09:00","end_time":"18:00","days_of_the_week":{"monday":true,"tuesday":true,"wednesday":true,"thursday":true,"friday":true,"saturday":false,"sunday":false}},{"type":"fixed_dates","start_time":"00:00","end_time":"23:59","fixed_dates":["2026-12-24","2026-12-31"]},{"type":"recurring_dates","status":"disabled","start_time":"00:00","end_time":"23:59","recurring_dates":["01-01","05-01","12-25"]},{"type":"specific_period","specific_period":{"start":"2026-08-03 08:00","end":"2026-08-17 18:00"}}]}'
const response = await fetch('https://cockpit.voxbi.com/api/v1/schedules', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${YOUR_TOKEN}`,
  },
  body: JSON.stringify({
    "name": "Business hours",
    "description": "Monday to Friday, 09:00 to 18:00",
    "steps": [
        {
            "type": "days_of_the_week",
            "start_time": "09:00",
            "end_time": "18:00",
            "days_of_the_week": {
                "monday": true,
                "tuesday": true,
                "wednesday": true,
                "thursday": true,
                "friday": true,
                "saturday": false,
                "sunday": false
            }
        },
        {
            "type": "fixed_dates",
            "start_time": "00:00",
            "end_time": "23:59",
            "fixed_dates": [
                "2026-12-24",
                "2026-12-31"
            ]
        },
        {
            "type": "recurring_dates",
            "status": "disabled",
            "start_time": "00:00",
            "end_time": "23:59",
            "recurring_dates": [
                "01-01",
                "05-01",
                "12-25"
            ]
        },
        {
            "type": "specific_period",
            "specific_period": {
                "start": "2026-08-03 08:00",
                "end": "2026-08-17 18:00"
            }
        }
    ]
}),
});

const data = await response.json();
console.log(data);
import requests

response = requests.post('https://cockpit.voxbi.com/api/v1/schedules',
    headers={'Authorization': f'Bearer {YOUR_TOKEN}'},
    json={
    "name": "Business hours",
    "description": "Monday to Friday, 09:00 to 18:00",
    "steps": [
        {
            "type": "days_of_the_week",
            "start_time": "09:00",
            "end_time": "18:00",
            "days_of_the_week": {
                "monday": true,
                "tuesday": true,
                "wednesday": true,
                "thursday": true,
                "friday": true,
                "saturday": false,
                "sunday": false
            }
        },
        {
            "type": "fixed_dates",
            "start_time": "00:00",
            "end_time": "23:59",
            "fixed_dates": [
                "2026-12-24",
                "2026-12-31"
            ]
        },
        {
            "type": "recurring_dates",
            "status": "disabled",
            "start_time": "00:00",
            "end_time": "23:59",
            "recurring_dates": [
                "01-01",
                "05-01",
                "12-25"
            ]
        },
        {
            "type": "specific_period",
            "specific_period": {
                "start": "2026-08-03 08:00",
                "end": "2026-08-17 18:00"
            }
        }
    ]
}
)
response.raise_for_status()
data = response.json()
print(data)
<?php
$context = stream_context_create([
    'http' => [
        'method'  => 'POST',
        'header'  => "Content-Type: application/json\r\nAuthorization: Bearer YOUR_TOKEN",
        'content' => '{
    \"name\": \"Business hours\",
    \"description\": \"Monday to Friday, 09:00 to 18:00\",
    \"steps\": [
        {
            \"type\": \"days_of_the_week\",
            \"start_time\": \"09:00\",
            \"end_time\": \"18:00\",
            \"days_of_the_week\": {
                \"monday\": true,
                \"tuesday\": true,
                \"wednesday\": true,
                \"thursday\": true,
                \"friday\": true,
                \"saturday\": false,
                \"sunday\": false
            }
        },
        {
            \"type\": \"fixed_dates\",
            \"start_time\": \"00:00\",
            \"end_time\": \"23:59\",
            \"fixed_dates\": [
                \"2026-12-24\",
                \"2026-12-31\"
            ]
        },
        {
            \"type\": \"recurring_dates\",
            \"status\": \"disabled\",
            \"start_time\": \"00:00\",
            \"end_time\": \"23:59\",
            \"recurring_dates\": [
                \"01-01\",
                \"05-01\",
                \"12-25\"
            ]
        },
        {
            \"type\": \"specific_period\",
            \"specific_period\": {
                \"start\": \"2026-08-03 08:00\",
                \"end\": \"2026-08-17 18:00\"
            }
        }
    ]
}',
    ],
]);

$response = file_get_contents('https://cockpit.voxbi.com/api/v1/schedules', false, $context);
$data = json_decode($response, true);
print_r($data);
Sample request
{ … }
"name": "Business hours",
"description": "Monday to Friday, 09:00 to 18:00",
"steps": [ … ]
{ … },
"type": "days_of_the_week",
"start_time": "09:00",
"end_time": "18:00",
"days_of_the_week": { … }
"monday": true,
"tuesday": true,
"wednesday": true,
"thursday": true,
"friday": true,
"saturday": false,
"sunday": false
}
},
{ … },
"type": "fixed_dates",
"start_time": "00:00",
"end_time": "23:59",
"fixed_dates": [ … ]
"2026-12-24",
"2026-12-31"
]
},
{ … },
"type": "recurring_dates",
"status": "disabled",
"start_time": "00:00",
"end_time": "23:59",
"recurring_dates": [ … ]
"01-01",
"05-01",
"12-25"
]
},
{ … }
"type": "specific_period",
"specific_period": { … }
"start": "2026-08-03 08:00",
"end": "2026-08-17 18:00"
}
}
]
}
{ … }
"id": "550e8400-e29b-41d4-a716-446655440000",
"pbx_id": "550e8400-e29b-41d4-a716-446655440001",
"name": "Business hours",
"description": "Monday to Friday, 09:00 to 18:00",
"steps": [ … ],
{ … },
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"type": "days_of_the_week",
"status": "enabled",
"start_time": "09:00",
"end_time": "18:00",
"days_of_the_week": { … },
"monday": true,
"tuesday": true,
"wednesday": true,
"thursday": true,
"friday": true,
"saturday": false,
"sunday": false
},
"fixed_dates": null,
"recurring_dates": null,
"specific_period": null,
"created_at": "2024-03-01T08:29:07.000000Z",
"updated_at": "2024-03-01T08:29:07.000000Z"
},
{ … },
"id": "9b2f4c1e-3d5a-4e8b-9c7d-1a2b3c4d5e6f",
"type": "fixed_dates",
"status": "enabled",
"start_time": "00:00",
"end_time": "23:59",
"days_of_the_week": null,
"fixed_dates": [ … ],
"2026-12-24",
"2026-12-31"
],
"recurring_dates": null,
"specific_period": null,
"created_at": "2024-03-01T08:29:07.000000Z",
"updated_at": "2024-03-01T08:29:07.000000Z"
},
{ … },
"id": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f",
"type": "recurring_dates",
"status": "disabled",
"start_time": "00:00",
"end_time": "23:59",
"days_of_the_week": null,
"fixed_dates": null,
"recurring_dates": [ … ],
"01-01",
"05-01",
"12-25"
],
"specific_period": null,
"created_at": "2024-03-01T08:29:07.000000Z",
"updated_at": "2024-03-01T08:29:07.000000Z"
},
{ … }
"id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
"type": "specific_period",
"status": "enabled",
"start_time": null,
"end_time": null,
"days_of_the_week": null,
"fixed_dates": null,
"recurring_dates": null,
"specific_period": { … },
"start": "2026-08-03 08:00",
"end": "2026-08-17 18:00"
},
"created_at": "2024-03-01T08:29:07.000000Z",
"updated_at": "2024-03-01T08:29:07.000000Z"
}
],
"created_at": "2024-03-01T08:29:07.000000Z",
"updated_at": "2024-03-01T08:29:07.000000Z"
}
Host string
example: cockpit.voxbi.com
Date string
example: Mon, 16 Oct 2023 14:08:48 GMT
Connection string
example: close
Cache-Control string
example: no-cache, private
Content-Type string
example: application/json
X-RateLimit-Limit integer
example: 60
X-RateLimit-Remaining integer
example: 59
Vary string
example: Origin
{ … }
"message": "Unauthenticated."
}
Content-Type string
example: application/json
{ … }
"message": "Invalid ability provided."
}
Content-Type string
example: application/json
{ … }
"message": "The name field is required.",
"errors": { … }
"name": [ … ]
"The name field is required."
]
}
}
Content-Type string
example: application/json
{ … }
"message": "Too Many Attempts."
}
Retry-After integer
Seconds to wait before retrying.
example: 60
Content-Type string
example: application/json
{ … }
"message": "Server Error"
}