{ "openapi": "3.0.0", "info": { "title": "MarketBox API", "version": "1.0.0", "description": "The MarketBox API is a modular, API-first platform for building modern scheduling, booking and dispatch workflows for both mobile services and fixed locations. At its core is the Smart Clusters engine, which generates realistic, bookable availability by analyzing provider schedules, existing bookings, travel zones and real-world travel constraints. Instead of relying on static time slots or buffers, MarketBox returns appointment times that are physically feasible, route-aware and optimized to reduce travel, traffic and idle gaps.\n\n Beyond availability intelligence, the API includes a full set of resource endpoints for managing services, providers, schedules, bookings, orders and more. This allows teams to enhance an existing booking flow or build a complete, white-labeled scheduling system end-to-end. MarketBox is designed to be embedded into websites, dispatcher tools, AI chat and voice agents, or third-party platforms, with near real-time responses returned in JSON for seamless integration into any workflow. \n\nTo get started, please contact support@gomarketbox.com to get an API key." }, "x-tagGroups": [ { "name": "Smart Cluster Tools", "tags": ["Timeslots"] }, { "name": "Resources", "tags": [ "Reserved slots", "Orders", "Bookings", "Services", "Providers", "Clients" ] } ], "tags": [ { "name": "Orders", "description": "Endpoints for creating orders inside the MarketBox platform. An order may contain multiple [bookings](/api-documentation/bookings#description)." }, { "name": "Bookings", "description": "Endpoints for updating and managing bookings inside the MarketBox platform. An [order](/api-documentation/orders#description) may contain multiple bookings." }, { "name": "Reserved slots", "description": "Endpoints for creating and deleting reserved slots inside the MarketBox platform." }, { "name": "Services", "description": "Endpoints for reading Services inside the MarketBox platform." }, { "name": "Providers", "description": "Endpoints for reading Providers from the MarketBox platform." }, { "name": "Clients", "description": "Endpoints for creating and reading Clients inside the MarketBox platform." }, { "name": "Timeslots", "description": "Endpoints powered by the Smart Clusters engine, providing a set of stand-alone scheduling and route optimization tools for the field services industry – perfect for white labeling or embedding into any 3rd party software system." }, { "name": "Schemas", "description": "Endpoints for retrieving and validating data schemas used across the Cosmo Cargo platform.", "x-zudoku-collapsed": false } ], "servers": [ { "url": "https://api.gomarketbox.com/v1" } ], "paths": { "/smart-clusters/time-slots": { "post": { "summary": "Retrieves time slots", "parameters": [ { "name": "timeSuggestionsLimit", "in": "query", "required": false, "description": "The maximum number of time suggestions returned per provider.", "schema": { "type": "integer" }, "example": "15" }, { "name": "sortBy", "in": "query", "required": false, "description": "Specifies the sorting order of the timeSlots in the response. By default, the time slots are sorted by ascending travel time.", "schema": { "type": "string", "enum": ["leastTravelTime", "nearestDate"] }, "example": "leastTravelTime" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "example": 200 }, "message": { "type": "string", "example": "Successfully generated time slots" }, "timeSlots": { "type": "array", "description": "##### List of generated suggested time slot objects\n", "items": { "type": "object", "properties": { "providerId": { "type": "string", "example": "e7b9e6a8-3f64-4b91-8c4f-abcdef123456", "description": "The provider's unique identifier\n" }, "timeSlotId": { "type": "string", "example": "8582011f-204e-4e7e-8278-745ba215d28c", "description": "The time slots unique identifier \n" }, "timeSlotDateAndTime": { "type": "string", "example": "2024-12-01T09:00:00-05:00", "description": "The start date and time of the suggested time slot\n" }, "preferredTimeSlot": { "type": "boolean", "example": true, "description": "Indicates if the time slot is less than or equal to the preferredTimeSlotThresholdMins\n" }, "travelTimeMins": { "type": "number", "example": 15, "description": "Travel time in minutes between the target location and the neighboring booking’s location, if applicable.\n", "format": "float" }, "travelDistance": { "type": "number", "example": 4.1, "description": "Travel distance between the target location and the neighboring booking’s location, if applicable.\n", "format": "float" }, "travelType": { "type": "string", "enum": [ "FROM-PREVIOUS-BOOKING", "TO-NEXT-BOOKING", "SAME-LOCATION-AS-PREVIOUS", "SAME-LOCATION-AS-NEXT", "ON-EMPTY-DAY", "FROM-START-LOCATION", "TO-END-LOCATION" ], "example": "FROM-PREVIOUS-BOOKING", "description": "Indicates the type of travel required by the provider to reach the target location for a booking. This can specify whether travel is from a prior booking location, to the next\nbooking location, within the same location, or when the day has no other bookings.\n" }, "message": { "type": "string", "example": "15 mins drive from previous booking (4.1mi)", "description": "A user friendly message detailing the suggested time slot\n" }, "isFirst": { "type": "boolean", "example": true, "description": "Indicates if the suggested time slot is the first booking of the day. NOTE this attribute will only exist if the 'order' in the request was 'mustBeFirst'.\n" }, "isLast": { "type": "boolean", "example": true, "description": "Indicates if the suggested time slot is the last booking of the day. NOTE this attribute will only exist if the 'order' in the request was 'mustBeLast'.\n" } }, "required": [ "providerId", "timeSlotId", "timeSlotDateAndTime", "preferredTimeSlot", "travelTimeMins", "travelDistance", "travelType", "message" ] } }, "errors": { "type": "array", "description": "Array of error messages for individual providers. Errors for one provider do not prevent attempts for other providers.\n", "items": { "type": "string" } } }, "required": ["status", "message", "timeSlots"] }, "example": { "status": 200, "message": "Successfully generated time slots", "timeSlots": [ { "providerId": "e7b9e6a8-3f64-4b91-8c4f-abcdef123456", "timeSlotId": "8582011f-204e-4e7e-8278-745ba215d28c", "timeSlotDateAndTime": "2024-12-01T09:00:00-05:00", "preferredTimeSlot": true, "travelTimeMins": 15, "travelDistance": 4.1, "travelType": "FROM-PREVIOUS-BOOKING", "message": "15 mins drive from previous booking (4.1mi)", "isFirst": true, "isLast": true }, { "providerId": "e7b9e6a8-3f64-4b91-8c4f-abcdef123456", "timeSlotId": "8582011f-204e-4e7e-8278-745ba215d28c", "timeSlotDateAndTime": "2024-12-01T09:00:00-05:00", "preferredTimeSlot": true, "travelTimeMins": 15, "travelDistance": 4.1, "travelType": "FROM-PREVIOUS-BOOKING", "message": "15 mins drive from previous booking (4.1mi)", "isFirst": true, "isLast": true } ], "errors": [ "ProviderError (providerId: d6e3aa48-ae4e-4b91-8c4f-abcdef123456): Buffer time cannot be greater than max travel time." ] } } } }, "400": { "description": "Bad request, invalid input", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "example": 400 }, "message": { "type": "string", "example": "Invalid Input: Please verify your request body" }, "hints": { "type": "string", "example": "[object has missing required properties ([\"availability\",\"maxTravelTimeMins\"])]" } } }, "example": { "status": 400, "message": "Invalid Input: Please verify your request body", "hints": "[object has missing required properties ([\"availability\",\"maxTravelTimeMins\"])]" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number" }, "message": { "type": "string", "example": "Unauthorized Request: Please verify your api-key" } } }, "example": { "status": 401, "message": "Unauthorized Request: Please verify your api-key" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number" }, "message": { "type": "string", "example": "Forbidden Access: Please verify your api-key" } } }, "example": { "status": 403, "message": "Forbidden Access: Please verify your api-key" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "example": 500 }, "message": { "type": "string", "example": "Internal server error: An error occurred while generating your time slots" } } }, "example": { "status": 500, "message": "Internal server error: An error occurred while generating your time slots" } } } } }, "tags": ["Timeslots"], "security": [ { "ApiKeyAuth": [] } ], "description": "Endpoints powered by the Smart Clusters engine, providing a set of stand-alone scheduling and route optimization tools for the field services industry – perfect for white labeling or embedding into any 3rd party software system.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "billingId": { "type": "string", "example": "eahu28d-2ff3-4b91-8c4f-dj9928sjsd87d", "description": "###### The end user's unique identifier used for billing\n" }, "targetGeoLocation": { "type": "array", "example": [28.23068, -81.334973], "description": "###### The latitude and longitude coordinates of where the service will take place [latitude, longitude]\n", "items": { "type": "number" } }, "targetServiceDurationMins": { "type": "number", "example": 60, "description": "###### The duration of the service in minutes\n" }, "providers": { "type": "array", "description": "###### List of providers, each with their providerId, maxTravelTimeMins, bookings, and availability.\n", "items": { "type": "object", "properties": { "providerId": { "type": "string", "example": "e7b9e6a8-3f64-4b91-8c4f-abcdef123456", "description": "The provider's unique identifier\n" }, "maxTravelTimeMins": { "type": "integer", "example": 15, "description": "The provider's maxTravelTime between appointments in minutes\n" }, "availability": { "type": "array", "description": "A list of provider availabilities\n", "items": { "type": "object", "properties": { "startDateAndTime": { "type": "string", "example": "2024-12-01T09:00:00-05:00", "description": "The start date and time of the availability in ISO-8601 format\n" }, "endDateAndTime": { "type": "string", "example": "2025-05-25T20:00:00-05:00", "description": "The end date and time of the availability in ISO-8601 format\n" }, "startGeoLocation": { "type": "array", "example": [28.23068, -81.334973], "description": "###### The latitude and longitude coordinates of the schedule's starting point or departure location [latitude, longitude], e.g. head office or main depot\n", "items": { "type": "number" } }, "endGeoLocation": { "type": "array", "example": [28.23068, -81.334973], "description": "###### The latitude and longitude coordinates of the schedule's ending point or arrival location [latitude, longitude], e.g. head office or main depot \n", "items": { "type": "number" } }, "rrule": { "type": "string", "example": "FREQ=WEEKLY;INTERVAL=1;BYDAY=TU,SA,SU", "description": "The availability recurrence rule - the example rrule describes an availability that is active every week on Tuesday, Saturday, and Sunday\n" } }, "required": ["startDateAndTime", "endDateAndTime"] } }, "bookings": { "type": "array", "example": [ { "startDateAndTime": "2024-12-12T10:00:00-05:00", "durationMins": 60, "geoLocation": [28.435233, -81.893873] } ], "description": "A list of booking's the provider is scheduled for\n", "items": { "type": "object", "properties": { "startDateAndTime": { "type": "string", "example": "2024-12-12T10:00:00-05:00", "description": "The start date and time of the scheduled booking in ISO-8601 format\n" }, "durationMins": { "type": "integer", "example": 60, "description": "The duration of the scheduled booking in minutes\n" }, "geoLocation": { "type": "array", "example": [28.385233, -81.563873], "description": "The latitude and longitude coordinates of where the scheduled service is taking place [latitude, longitude]\n", "items": { "type": "number" } } }, "required": [ "startDateAndTime", "durationMins", "geoLocation" ] } }, "blockedTime": { "type": "array", "description": "A list of provider blocked times\n", "items": { "type": "object", "properties": { "startDateAndTime": { "type": "string", "example": "2024-12-01T09:00:00-05:00", "description": "The start date and time of the blocked time in ISO-8601 format\n" }, "endDateAndTime": { "type": "string", "example": "2025-05-25T20:00:00-05:00", "description": "The end date and time of the blocked time in ISO-8601 format\n" }, "rrule": { "type": "string", "example": "FREQ=WEEKLY;INTERVAL=1;BYDAY=TU", "description": "The blocked time recurrence rule - the example rrule describes a blocked time that is active every week on Tuesday\n" } }, "required": ["startDateAndTime", "endDateAndTime"] } }, "bufferTimeMins": { "type": "integer", "example": 15, "description": "###### Time added on top of travel time calculations\n" }, "maxTravelTimeFromStartGeoLocationMins": { "type": "integer", "example": 20, "description": "The provider's maxTravelTime from their startGeoLocation in minutes. Only applies to the first booking of the day and if startGeoLocation is provided\n" }, "maxTravelTimeToEndGeoLocationMins": { "type": "integer", "example": 20, "description": "The provider's maxTravelTime to their endGeoLocation in minutes. Only applies to the last booking of the day and if endGeoLocation is provided\n" } }, "required": [ "providerId", "maxTravelTimeMins", "availability" ] } }, "lookAheadStartDate": { "type": "string", "example": "2024-12-01T00:00:00-05:00", "description": "###### The date to begin the look-ahead period. By default, the date and time of the request is used.\n" }, "lookAheadDays": { "type": "integer", "example": 7, "description": "###### The number of days to search ahead from the lookAheadStartDate. Defaults to 7 days and cannot exceed a maximum of 7 days.\n" }, "travelTimeType": { "type": "string", "enum": ["rounded", "raw"], "example": "raw", "description": "###### The travel time type returned in TimeSlotResponse: \"raw\" (e.g. 12.6 min) or \"rounded\" (e.g. 15 min). By default, travel time is rounded up to the nearest 5 minutes.\n" }, "preferredTimeSlotThresholdMins": { "type": "integer", "example": 10, "description": "###### The maximum travel time threshold for a preferred time slot. Defaults to 5 minutes.\n" }, "distanceUnit": { "type": "string", "enum": ["km", "mi"], "example": "mi", "description": "###### The unit for travel distance in the response. Defaults to kilometers. \n" }, "minBookingNoticeMins": { "type": "number", "example": 60, "description": "###### Minimum advance notice from current date and time for time slot suggestions - no time slots will be suggested within the minimum booking notice window. Defaults to no minimum notice.\n" }, "emptyDayAnchorTime": { "type": "string", "example": "14:00", "description": "###### The anchor time for the first booking on an empty day, used as a base for clustering. Defaults to the first and last available slots of a schedule's time range.\n" }, "preferredDays": { "type": "array", "example": [1, 2, 3, 4, 5], "description": "###### Specifies the preferred days of the week for time slots. Days are represented numerically, where 0 = Sunday and 6 = Saturday\n", "items": { "type": "number" } }, "preferredTimes": { "type": "array", "description": "###### Specifies preferred time ranges for time slots\n", "items": { "type": "object", "properties": { "startTime": { "type": "string", "example": "09:00", "description": "The start time of the preferred time range in 24-hour format\n" }, "endTime": { "type": "string", "example": "13:00", "description": "The end time of the preferred time range in 24-hour format\n" } }, "required": ["startTime", "endTime"] } }, "order": { "type": "string", "enum": ["mustBeFirst", "mustBeLast"], "example": "mustBeFirst", "description": "###### Prioritizes suggested time slots at the start (`mustBeFirst`) or end (`mustBeLast`) of the day. Add optional `startGeoLocation` and/or `endGeoLocation` parameters in the provider availability array to make sure routes start and end at specific locations. Regular time slots will still be included in the response.\n" }, "maxNumberOfBookingsPerDay": { "type": "number", "example": 5, "description": "###### Maximum number of bookings for a single day\n" } }, "required": [ "billingId", "targetGeoLocation", "targetServiceDurationMins", "providers" ] }, "example": { "billingId": "eahu28d-2ff3-4b91-8c4f-dj9928sjsd87d", "targetGeoLocation": [28.23068, -81.334973], "targetServiceDurationMins": 60, "providers": [ { "providerId": "e7b9e6a8-3f64-4b91-8c4f-abcdef123456", "maxTravelTimeMins": 15, "availability": [ { "startDateAndTime": "2024-12-01T09:00:00-05:00", "endDateAndTime": "2025-05-25T20:00:00-05:00", "startGeoLocation": [28.23068, -81.334973], "endGeoLocation": [28.23068, -81.334973], "rrule": "FREQ=WEEKLY;INTERVAL=1;BYDAY=TU,SA,SU" }, { "startDateAndTime": "2024-12-01T09:00:00-05:00", "endDateAndTime": "2025-05-25T20:00:00-05:00", "startGeoLocation": [28.23068, -81.334973], "endGeoLocation": [28.23068, -81.334973], "rrule": "FREQ=WEEKLY;INTERVAL=1;BYDAY=TU,SA,SU" } ], "bookings": [ { "startDateAndTime": "2024-12-12T10:00:00-05:00", "durationMins": 60, "geoLocation": [28.435233, -81.893873] } ], "blockedTime": [ { "startDateAndTime": "2024-12-01T09:00:00-05:00", "endDateAndTime": "2025-05-25T20:00:00-05:00", "rrule": "FREQ=WEEKLY;INTERVAL=1;BYDAY=TU" }, { "startDateAndTime": "2024-12-01T09:00:00-05:00", "endDateAndTime": "2025-05-25T20:00:00-05:00", "rrule": "FREQ=WEEKLY;INTERVAL=1;BYDAY=TU" } ], "bufferTimeMins": 15, "maxTravelTimeFromStartGeoLocationMins": 20, "maxTravelTimeToEndGeoLocationMins": 20 }, { "providerId": "e7b9e6a8-3f64-4b91-8c4f-abcdef123456", "maxTravelTimeMins": 15, "availability": [ { "startDateAndTime": "2024-12-01T09:00:00-05:00", "endDateAndTime": "2025-05-25T20:00:00-05:00", "startGeoLocation": [28.23068, -81.334973], "endGeoLocation": [28.23068, -81.334973], "rrule": "FREQ=WEEKLY;INTERVAL=1;BYDAY=TU,SA,SU" }, { "startDateAndTime": "2024-12-01T09:00:00-05:00", "endDateAndTime": "2025-05-25T20:00:00-05:00", "startGeoLocation": [28.23068, -81.334973], "endGeoLocation": [28.23068, -81.334973], "rrule": "FREQ=WEEKLY;INTERVAL=1;BYDAY=TU,SA,SU" } ], "bookings": [ { "startDateAndTime": "2024-12-12T10:00:00-05:00", "durationMins": 60, "geoLocation": [28.435233, -81.893873] } ], "blockedTime": [ { "startDateAndTime": "2024-12-01T09:00:00-05:00", "endDateAndTime": "2025-05-25T20:00:00-05:00", "rrule": "FREQ=WEEKLY;INTERVAL=1;BYDAY=TU" }, { "startDateAndTime": "2024-12-01T09:00:00-05:00", "endDateAndTime": "2025-05-25T20:00:00-05:00", "rrule": "FREQ=WEEKLY;INTERVAL=1;BYDAY=TU" } ], "bufferTimeMins": 15, "maxTravelTimeFromStartGeoLocationMins": 20, "maxTravelTimeToEndGeoLocationMins": 20 } ], "lookAheadStartDate": "2024-12-01T00:00:00-05:00", "lookAheadDays": 7, "travelTimeType": "raw", "preferredTimeSlotThresholdMins": 10, "distanceUnit": "mi", "minBookingNoticeMins": 60, "emptyDayAnchorTime": "14:00", "preferredDays": [1, 2, 3, 4, 5], "preferredTimes": [ { "startTime": "09:00", "endTime": "13:00" }, { "startTime": "09:00", "endTime": "13:00" } ], "order": "mustBeFirst", "maxNumberOfBookingsPerDay": 5 } } } } } }, "/smart-clusters/who-is-available": { "post": { "summary": "Find best provider", "parameters": [ { "name": "sortBy", "in": "query", "required": false, "description": "Specifies the sorting order of the timeSlots in the response. By default, the time slots are sorted by ascending travel time.", "schema": { "type": "string", "enum": ["leastTravelTime", "nearestDate"] }, "example": "leastTravelTime" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "example": 200 }, "message": { "type": "string", "example": "Successfully generated time slots" }, "timeSlots": { "type": "array", "description": "##### List of generated suggested time slot objects\n", "items": { "type": "object", "properties": { "providerId": { "type": "string", "example": "e7b9e6a8-3f64-4b91-8c4f-abcdef123456", "description": "The provider's unique identifier\n" }, "timeSlotId": { "type": "string", "example": "8582011f-204e-4e7e-8278-745ba215d28c", "description": "The time slots unique identifier \n" }, "timeSlotDateAndTime": { "type": "string", "example": "2024-12-01T09:00:00-05:00", "description": "The start date and time of the suggested time slot\n" }, "preferredTimeSlot": { "type": "boolean", "example": true, "description": "Indicates if the time slot is less than or equal to the preferredTimeSlotThresholdMins\n" }, "travelTimeMins": { "type": "number", "example": 15, "description": "Travel time in minutes between the target location and the neighboring booking’s location, if applicable.\n", "format": "float" }, "travelDistance": { "type": "number", "example": 4.1, "description": "Travel distance between the target location and the neighboring booking’s location, if applicable.\n", "format": "float" }, "travelType": { "type": "string", "enum": [ "FROM-PREVIOUS-BOOKING", "TO-NEXT-BOOKING", "SAME-LOCATION-AS-PREVIOUS", "SAME-LOCATION-AS-NEXT", "ON-EMPTY-DAY", "FROM-START-LOCATION", "TO-END-LOCATION" ], "example": "FROM-PREVIOUS-BOOKING", "description": "Indicates the type of travel required by the provider to reach the target location for a booking. This can specify whether travel is from a prior booking location, to the next\nbooking location, within the same location, or when the day has no other bookings.\n" }, "message": { "type": "string", "example": "15 mins drive from previous booking (4.1mi)", "description": "A user friendly message detailing the suggested time slot\n" }, "isWithinMinBookingNotice": { "type": "boolean", "description": "Indicates if this booking is within the set minimum booking notice time\n" }, "providerFirstName": { "type": "string", "example": "John", "description": "The available providers first name\n" }, "providerLastName": { "type": "string", "example": "Smith", "description": "The available providers last name\n" } }, "required": [ "providerId", "timeSlotId", "timeSlotDateAndTime", "preferredTimeSlot", "travelTimeMins", "travelDistance", "travelType", "message", "isWithinMinBookingNotice", "providerFirstName", "providerLastName" ] } }, "openSlots": { "type": "object", "description": "All available time slots based on provider availability, shown at the increment value set at the company level. Indexed by provider ID.\n", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "providerId": { "type": "string", "example": "e2ef20d7-c6a5-4288-b9d8-68953cbf6cd6", "description": "The provider's unique identifier\n" }, "timeSlotId": { "type": "string", "example": "a61ae129-e446-4ade-87c2-436d9d38b2d0", "description": "The time slot's unique identifier\n" }, "timeSlotDateAndTime": { "type": "string", "example": "2026-02-16T09:00:00-05:00", "description": "The start date and time of the available time slot\n" }, "isWithinMinBookingNotice": { "type": "boolean", "example": true, "description": "Indicates if this booking is within the set minimum booking notice time\n" }, "providerFirstName": { "type": "string", "example": "John", "description": "The available provider's first name\n" }, "providerLastName": { "type": "string", "example": "Smith", "description": "The available provider's last name\n" } }, "required": [ "providerId", "timeSlotId", "timeSlotDateAndTime", "isWithinMinBookingNotice", "providerFirstName", "providerLastName" ] } } }, "errors": { "type": "array", "description": "Array of error messages for individual providers. Errors for one provider do not prevent attempts for other providers.\n", "items": { "type": "string" } } }, "required": ["status", "message", "timeSlots"] }, "example": { "status": 200, "message": "Successfully generated time slots", "timeSlots": [ { "providerId": "e7b9e6a8-3f64-4b91-8c4f-abcdef123456", "timeSlotId": "8582011f-204e-4e7e-8278-745ba215d28c", "timeSlotDateAndTime": "2024-12-01T09:00:00-05:00", "preferredTimeSlot": true, "travelTimeMins": 15, "travelDistance": 4.1, "travelType": "FROM-PREVIOUS-BOOKING", "message": "15 mins drive from previous booking (4.1mi)", "isWithinMinBookingNotice": false, "providerFirstName": "John", "providerLastName": "Smith" }, { "providerId": "e7b9e6a8-3f64-4b91-8c4f-abcdef123456", "timeSlotId": "8582011f-204e-4e7e-8278-745ba215d28c", "timeSlotDateAndTime": "2024-12-01T09:00:00-05:00", "preferredTimeSlot": true, "travelTimeMins": 15, "travelDistance": 4.1, "travelType": "FROM-PREVIOUS-BOOKING", "message": "15 mins drive from previous booking (4.1mi)", "isWithinMinBookingNotice": false, "providerFirstName": "John", "providerLastName": "Smith" } ], "openSlots": { "e7b9e6a8-3f64-4b91-8c4f-abcdef123456": [ { "providerId": "e7b9e6a8-3f64-4b91-8c4f-abcdef123456", "timeSlotId": "a61ae129-e446-4ade-87c2-436d9d38b2d0", "timeSlotDateAndTime": "2024-12-01T09:00:00-05:00", "isWithinMinBookingNotice": true, "providerFirstName": "John", "providerLastName": "Smith" }, { "providerId": "e7b9e6a8-3f64-4b91-8c4f-abcdef123456", "timeSlotId": "9d01a03d-37da-4618-903a-add3c9937a97", "timeSlotDateAndTime": "2024-12-01T09:10:00-05:00", "isWithinMinBookingNotice": true, "providerFirstName": "John", "providerLastName": "Smith" }, { "providerId": "e7b9e6a8-3f64-4b91-8c4f-abcdef123456", "timeSlotId": "d6141114-dddb-4ac7-8daf-47feea9acf2f", "timeSlotDateAndTime": "2024-12-01T09:20:00-05:00", "isWithinMinBookingNotice": true, "providerFirstName": "John", "providerLastName": "Smith" } ] }, "errors": [ "ProviderError (providerId: d6e3aa48-ae4e-4b91-8c4f-abcdef123456): Buffer time cannot be greater than max travel time." ] } } } }, "201": { "description": "Success Recurring Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "example": 201 }, "message": { "type": "string", "example": "Successfully generated time slots" }, "timeSlots": { "type": "array", "description": "##### List of generated sets of suggested time slots\n", "items": { "type": "object", "properties": { "providerId": { "type": "string", "example": "e7b9e6a8-3f64-4b91-8c4f-abcdef123456", "description": "The provider's unique identifier\n" }, "travelTimeMins": { "type": "number", "example": 15, "description": "Travel time in minutes between the target location and the neighboring booking’s location, if applicable.\n", "format": "float" }, "travelDistance": { "type": "number", "example": 4.1, "description": "Travel distance between the target location and the neighboring booking’s location, if applicable.\n", "format": "float" }, "travelType": { "type": "string", "enum": [ "FROM-PREVIOUS-BOOKING", "TO-NEXT-BOOKING", "SAME-LOCATION-AS-PREVIOUS", "SAME-LOCATION-AS-NEXT", "ON-EMPTY-DAY", "FROM-START-LOCATION", "TO-END-LOCATION" ], "example": "FROM-PREVIOUS-BOOKING", "description": "Indicates the type of travel required by the provider to reach the target location for a booking. This can specify whether travel is from a prior booking location, to the next\nbooking location, within the same location, or when the day has no other bookings.\n" }, "mostAvailableStartTime": { "type": "string", "example": "14:30", "description": "This is the start time that fits the most number of days in the recurring pattern, so bookings are as consistent as possible with the same start time\n" }, "startTimeConsistencyPercent": { "type": "integer", "example": 90, "description": "This is the percentage of days out of the total recurring pattern that can be booked with the `mostAvailableStartTime`\n" }, "isWithinMinBookingNotice": { "type": "boolean", "description": "Indicates if this booking is within the set minimum booking notice time\n" }, "providerFirstName": { "type": "string", "example": "John", "description": "The available providers first name\n" }, "providerLastName": { "type": "string", "example": "Smith", "description": "The available providers last name\n" }, "slots": { "type": "array", "description": "##### List of generated suggested time slot objects\n", "items": { "type": "object", "properties": { "providerId": { "type": "string", "example": "e7b9e6a8-3f64-4b91-8c4f-abcdef123456", "description": "The provider's unique identifier\n" }, "timeSlotId": { "type": "string", "example": "8582011f-204e-4e7e-8278-745ba215d28c", "description": "The time slots unique identifier \n" }, "timeSlotDateAndTime": { "type": "string", "example": "2024-12-01T09:00:00-05:00", "description": "The start date and time of the suggested time slot\n" }, "preferredTimeSlot": { "type": "boolean", "example": true, "description": "Indicates if the time slot is less than or equal to the preferredTimeSlotThresholdMins\n" }, "travelTimeMins": { "type": "number", "example": 15, "description": "Travel time in minutes between the target location and the neighboring booking’s location, if applicable.\n", "format": "float" }, "travelDistance": { "type": "number", "example": 4.1, "description": "Travel distance between the target location and the neighboring booking’s location, if applicable.\n", "format": "float" }, "travelType": { "type": "string", "enum": [ "FROM-PREVIOUS-BOOKING", "TO-NEXT-BOOKING", "SAME-LOCATION-AS-PREVIOUS", "SAME-LOCATION-AS-NEXT", "ON-EMPTY-DAY", "FROM-START-LOCATION", "TO-END-LOCATION" ], "example": "FROM-PREVIOUS-BOOKING", "description": "Indicates the type of travel required by the provider to reach the target location for a booking. This can specify whether travel is from a prior booking location, to the next\nbooking location, within the same location, or when the day has no other bookings.\n" }, "message": { "type": "string", "example": "15 mins drive from previous booking (4.1mi)", "description": "A user friendly message detailing the suggested time slot\n" } }, "required": [ "providerId", "timeSlotId", "timeSlotDateAndTime", "preferredTimeSlot", "travelTimeMins", "travelDistance", "travelType", "message" ] } } }, "required": [ "providerId", "timeSlotDateAndTime", "preferredTimeSlot", "travelTimeMins", "travelDistance", "travelType", "timePatter", "consistency", "isWithinMinBookingNotice", "providerFirstName", "providerLastName", "slots" ] } }, "errors": { "type": "array", "description": "Array of error messages for individual providers. Errors for one provider do not prevent attempts for other providers.\n", "items": { "type": "string" } } }, "required": ["status", "message", "timeSlots"] }, "example": { "status": 201, "message": "Successfully generated time slots", "timeSlots": [ { "providerId": "e7b9e6a8-3f64-4b91-8c4f-abcdef123456", "travelTimeMins": 15, "travelDistance": 4.1, "travelType": "FROM-PREVIOUS-BOOKING", "isWithinMinBookingNotice": false, "providerFirstName": "John", "providerLastName": "Smith", "slots": [ { "providerId": "e7b9e6a8-3f64-4b91-8c4f-abcdef123456", "timeSlotId": "8582011f-204e-4e7e-8278-745ba215d28c", "timeSlotDateAndTime": "2024-12-01T09:00:00-05:00", "preferredTimeSlot": true, "travelTimeMins": 15, "travelDistance": 4.1, "travelType": "FROM-PREVIOUS-BOOKING", "message": "15 mins drive from previous booking (4.1mi)" }, { "providerId": "e7b9e6a8-3f64-4b91-8c4f-abcdef123456", "timeSlotId": "8582011f-204e-4e7e-8278-745ba215d28c", "timeSlotDateAndTime": "2024-12-01T09:00:00-05:00", "preferredTimeSlot": true, "travelTimeMins": 15, "travelDistance": 4.1, "travelType": "FROM-PREVIOUS-BOOKING", "message": "15 mins drive from previous booking (4.1mi)" } ], "mostAvailableStartTime": "14:30", "startTimeConsistencyPercent": 90, "timeSlotDateAndTime": 7351.640444992612, "preferredTimeSlot": false }, { "providerId": "e7b9e6a8-3f64-4b91-8c4f-abcdef123456", "travelTimeMins": 15, "travelDistance": 4.1, "travelType": "FROM-PREVIOUS-BOOKING", "isWithinMinBookingNotice": false, "providerFirstName": "John", "providerLastName": "Smith", "slots": [ { "providerId": "e7b9e6a8-3f64-4b91-8c4f-abcdef123456", "timeSlotId": "8582011f-204e-4e7e-8278-745ba215d28c", "timeSlotDateAndTime": "2024-12-01T09:00:00-05:00", "preferredTimeSlot": true, "travelTimeMins": 15, "travelDistance": 4.1, "travelType": "FROM-PREVIOUS-BOOKING", "message": "15 mins drive from previous booking (4.1mi)" }, { "providerId": "e7b9e6a8-3f64-4b91-8c4f-abcdef123456", "timeSlotId": "8582011f-204e-4e7e-8278-745ba215d28c", "timeSlotDateAndTime": "2024-12-01T09:00:00-05:00", "preferredTimeSlot": true, "travelTimeMins": 15, "travelDistance": 4.1, "travelType": "FROM-PREVIOUS-BOOKING", "message": "15 mins drive from previous booking (4.1mi)" } ], "mostAvailableStartTime": "14:30", "startTimeConsistencyPercent": 90, "timeSlotDateAndTime": "string", "preferredTimeSlot": 9359.805474739 } ], "errors": [ "ProviderError (providerId: d6e3aa48-ae4e-4b91-8c4f-abcdef123456): Buffer time cannot be greater than max travel time." ] } } } }, "400": { "description": "Bad request, invalid input", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "example": 400 }, "message": { "type": "string", "example": "Invalid Input: Please verify your request body" }, "hints": { "type": "string", "example": "[object has missing required properties ([\"availability\",\"maxTravelTimeMins\"])]" } } }, "example": { "status": 400, "message": "Invalid Input: Please verify your request body", "hints": "[object has missing required properties ([\"availability\",\"maxTravelTimeMins\"])]" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number" }, "message": { "type": "string", "example": "Unauthorized Request: Please verify your api-key" } } }, "example": { "status": 401, "message": "Unauthorized Request: Please verify your api-key" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number" }, "message": { "type": "string", "example": "Forbidden Access: Please verify your api-key" } } }, "example": { "status": 403, "message": "Forbidden Access: Please verify your api-key" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "example": 500 }, "message": { "type": "string", "example": "Internal server error: An error occurred while generating your time slots" } } }, "example": { "status": 500, "message": "Internal server error: An error occurred while generating your time slots" } } } } }, "tags": ["Timeslots"], "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieve a list of suggested time slots based on internal schedules and existing bookings, retrieved from the MarketBox system", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "billingId": { "type": "string", "example": "eahu28d-2ff3-4b91-8c4f-dj9928sjsd87d", "description": "###### The end user's unique identifier used for billing\n" }, "targetGeoLocation": { "type": "array", "example": [28.23068, -81.334973], "description": "###### The latitude and longitude coordinates of where the service will take place [latitude, longitude]. This is not required if a valid companyLocationId is provided.\n", "items": { "type": "number" } }, "companyLocationId": { "type": "string", "example": "0adfb507-f7bf-47e5-8d31-5c7ed2bd73f6", "description": "###### The ID for the company location saved in MarketBox. This value will override the targetGeoLocation.\n" }, "targetServiceId": { "type": "string", "example": "f7ed7ed4-9fbe-4d6d-9a57-57175d5f9adb", "description": "###### The ID for the service saved in MarketBox. \n" }, "bookingType": { "type": "string", "enum": ["single", "recurring"], "example": "single", "description": "###### Specifies if the slots being searched for are for a single booking, or a recurring booking set. By marking this `recurring`, expect a `WhoIsAvailableRecurringResponse` returned. Defaults to `single`.\n" }, "startDateAndTime": { "type": "string", "example": "2025-01-01T00:00:00-05:00", "description": "###### This is the date range AND time range of when the \"Who is available\" API will generate suggested time slots for.\n" }, "endDateAndTime": { "type": "string", "example": "2025-01-07T20:00:00-05:00", "description": "###### This is the date range AND time range of when the \"Who is available\" API will generate suggested time slots for – the time range is calculated on EACH of the day of the date range, e.g. if you send Oct 22, 14:00 until Oct 24, 18:00, this will mean 14:00-18:00 on each of the 3 days, and NOT a continuous period of 52 hours.\n" }, "daysOfWeek": { "type": "array", "example": [1, 2, 3, 4, 5], "description": "###### If `bookingType` is set to `single`, the days of the week specify which days to return time slots for (e.g. the client can only do Mondays, so only return time slots for Mondays); if `bookingType` is set to `recurring`, the days of the week are NOT taken into consideration, as this information will be provided in the `rrule` attribute.\n", "items": { "type": "number" } }, "skills": { "type": "array", "example": ["5efe490b-ea04-439d-89ba-24976dcac796"], "description": "###### This is a list of required skills for the provider to have in order to be eligible for the booking (defaults to none, i.e. no skill constraints).\n", "items": { "type": "string" } }, "rrule": { "type": "string", "example": "FREQ=WEEKLY;INTERVAL=1;BYDAY=TU,SA,SU", "description": "###### This is the recurring pattern for bookings - `bookingType` must be set to `recurring` for this to be considered; The days of week provided in the rrule indicate the repeating cadence and if included, all of the days are considered as required, e.g. if you send every week Tuesday, Saturday and Sunday, we will ONLY suggest time slots that are available on all 3 of those days, so if a provider can do Tuesdays and Saturdays, but not Sundays, then they will not be included in the response.\n" }, "travelTimeType": { "type": "string", "enum": ["rounded", "raw"], "example": "raw", "description": "###### The travel time type returned in TimeSlotResponse: \"raw\" (e.g. 12.6 min) or \"rounded\" (e.g. 15 min). By default, travel time is rounded up to the nearest 5 minutes.\n" }, "minBookingNoticeMins": { "type": "number", "example": 60, "description": "###### Minimum advance notice from current date and time for time slot suggestions - no time slots will be suggested within the minimum booking notice window. Defaults to no minimum notice.\n" }, "preferredTimeSlotThresholdMins": { "type": "integer", "example": 10, "description": "###### The maximum travel time threshold for a preferred time slot. Defaults to 5 minutes.\n" }, "distanceUnit": { "type": "string", "enum": ["km", "mi"], "example": "mi", "description": "###### The unit for travel distance in the response. Defaults to kilometers. \n" } }, "required": [ "billingId", "targetGeoLocation", "targetServiceId" ] }, "example": { "billingId": "eahu28d-2ff3-4b91-8c4f-dj9928sjsd87d", "targetGeoLocation": [28.23068, -81.334973], "targetServiceId": "f7ed7ed4-9fbe-4d6d-9a57-57175d5f9adb", "companyLocationId": "0adfb507-f7bf-47e5-8d31-5c7ed2bd73f6", "bookingType": "single", "startDateAndTime": "2025-01-01T00:00:00-05:00", "endDateAndTime": "2025-01-07T20:00:00-05:00", "daysOfWeek": [1, 2, 3, 4, 5], "skills": ["5efe490b-ea04-439d-89ba-24976dcac796"], "rrule": "FREQ=WEEKLY;INTERVAL=1;BYDAY=TU,SA,SU", "travelTimeType": "raw", "minBookingNoticeMins": 60, "preferredTimeSlotThresholdMins": 10, "distanceUnit": "mi" } } } } } }, "/smart-clusters/usage": { "get": { "summary": "Get usage statistics for clusters", "x-internal": true, "parameters": [ { "name": "startDate", "in": "query", "required": false, "description": "Start date for the usage data range (YYYY-MM-DD). Defaults to the beginning of the current month if not provided.", "schema": { "type": "string", "format": "date" }, "example": "2025-01-01" }, { "name": "endDate", "in": "query", "required": false, "description": "End date for the usage data range (YYYY-MM-DD). Defaults to the current date if not provided.", "schema": { "type": "string", "format": "date" }, "example": "2025-01-15" }, { "name": "billingId", "in": "query", "required": false, "description": "A unique identifier for the billing account to retrieve usage data. By default, usage data for all billing ids will be returned.", "schema": { "type": "string" }, "example": "12345-abcde" } ], "responses": { "200": { "description": "Successful response with usage statistics for the specified date range.", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalRequests": { "type": "integer", "example": 850, "description": "Total number of requests made." }, "totalTimeSlotsGenerated": { "type": "integer", "example": 1125, "description": "Total number of time slots generated." }, "totalBookings": { "type": "integer", "example": 2200, "description": "Total number of provider bookings provided in the requests." }, "avgProvidersPerRequest": { "type": "number", "example": 6, "description": "Average number of providers per request.", "format": "float" }, "byBillingId": { "type": "array", "description": "Breakdown of usage by billing ID.", "items": { "type": "object", "properties": { "billingId": { "type": "string", "example": "12345-abcde", "description": "Unique identifier for the billing entity." }, "requests": { "type": "integer", "example": 270, "description": "Number of requests made by this billing ID." }, "timeSlotsGenerated": { "type": "integer", "example": 357, "description": "Total number of time slots generated for this billing ID." }, "bookings": { "type": "integer", "example": 733, "description": "Total number of bookings made by this billing ID." }, "avgProvidersPerRequest": { "type": "number", "example": 6, "description": "Average number of providers per request for this billing ID.", "format": "float" } } } }, "startDate": { "type": "string", "example": "2025-01-01", "description": "Start date for the usage data range.", "format": "date" }, "endDate": { "type": "string", "example": "2025-01-15", "description": "End date for the usage data range.", "format": "date" } } }, "example": { "totalRequests": 850, "totalTimeSlotsGenerated": 1125, "totalBookings": 2200, "avgProvidersPerRequest": 6, "byBillingId": [ { "billingId": "12345-abcde", "requests": 270, "timeSlotsGenerated": 357, "bookings": 733, "avgProvidersPerRequest": 6 }, { "billingId": "12345-abcde", "requests": 270, "timeSlotsGenerated": 357, "bookings": 733, "avgProvidersPerRequest": 6 } ], "startDate": "2025-01-01", "endDate": "2025-01-15" } } } }, "400": { "description": "Bad request, invalid input params", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "example": 400 }, "message": { "type": "string", "example": "Invalid Input: Please verify your input params" } } }, "example": { "status": 400, "message": "Invalid Input: Please verify your input params" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number" }, "message": { "type": "string", "example": "Unauthorized Request: Please verify your api-key" } } }, "example": { "status": 401, "message": "Unauthorized Request: Please verify your api-key" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number" }, "message": { "type": "string", "example": "Forbidden Access: Please verify your api-key" } } }, "example": { "status": 403, "message": "Forbidden Access: Please verify your api-key" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "example": 500 }, "message": { "type": "string", "example": "Internal server error: An error occurred while generating usage statistics" } } }, "example": { "status": 500, "message": "Internal server error: An error occurred while generating usage statistics" } } } } }, "tags": ["Timeslots"], "security": [ { "ApiKeyAuth": [] } ] } }, "/resources/health": { "get": { "summary": "/resources/health", "x-internal": true, "responses": { "200": { "description": "API health check with environment configuration", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } } }, "example": { "status": "string", "message": "string" } } } } }, "tags": ["System"] } }, "/resources/services": { "get": { "summary": "Get Services", "tags": ["Services"], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^\\d+$", "default": 100, "example": 20 }, "required": false, "description": "Maximum number of items to return per page (default: 20, max: 100). Note: The actual number of items returned may be less than this value due to DynamoDB pagination, server-side filtering, or data availability. Always check 'pagination.nextCursor' to determine if more results are available.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "example": "eyJpZCI6IjEyMyIsInNrIjoiYWJjIn0=" }, "required": false, "description": "Pagination cursor from a previous response. Pass the 'nextCursor' value from the previous response here to fetch the next page of results. Omit this parameter for the first page.", "name": "nextCursor", "in": "query" } ], "responses": { "200": { "description": "The list of serivces", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [true], "description": "Indicates the request was successful" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceResponse" }, "description": "Array of items for the current page. The length may be less than the requested 'limit' due to filtering or data availability." }, "pagination": { "type": "object", "properties": { "nextCursor": { "type": "string", "description": "Cursor for fetching the next page of results. Pass this value as the 'nextCursor' query parameter in the next request. If this field is absent or undefined, there are no more results available.", "example": "eyJpZCI6IjEyMyIsInNrIjoiYWJjIn0=" } } } }, "required": ["success", "data", "pagination"] } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } } } } }, "/resources/providers": { "get": { "summary": "Get Providers", "description": "Use this endpoint to get all your proividers. You may also use query params to get the providers within a specific country, or state or city.", "tags": ["Providers"], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^\\d+$", "default": 100, "example": 20 }, "required": false, "description": "Maximum number of items to return per page (default: 20, max: 100). Note: The actual number of items returned may be less than this value due to DynamoDB pagination, server-side filtering, or data availability. Always check 'pagination.nextCursor' to determine if more results are available.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "example": "eyJpZCI6IjEyMyIsInNrIjoiYWJjIn0=" }, "required": false, "description": "Pagination cursor from a previous response. Pass the 'nextCursor' value from the previous response here to fetch the next page of results. Omit this parameter for the first page.", "name": "nextCursor", "in": "query" }, { "schema": { "type": "string", "minLength": 2, "maxLength": 2, "example": "US" }, "required": false, "description": "ISO-3166-1 alpha-2 country code. ", "name": "country", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "example": "TX" }, "required": false, "description": "State or province code. Query param 'country' must also be passed in if 'state' is being passed in.", "name": "state", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "example": "Austin" }, "required": false, "description": "City name. Query params 'country' and 'state' must also be passed in if 'city' is being passed in.", "name": "city", "in": "query" } ], "responses": { "200": { "description": "The list of providers", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [true], "description": "Indicates the request was successful" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderResponse" }, "description": "Array of items for the current page. The length may be less than the requested 'limit' due to filtering or data availability." }, "pagination": { "type": "object", "properties": { "nextCursor": { "type": "string", "description": "Cursor for fetching the next page of results. Pass this value as the 'nextCursor' query parameter in the next request. If this field is absent or undefined, there are no more results available.", "example": "eyJpZCI6IjEyMyIsInNrIjoiYWJjIn0=" } } } }, "required": ["success", "data", "pagination"] } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } } } } }, "/resources/providers/{id}": { "get": { "summary": "Get Provider", "tags": ["Providers"], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-1234-567890abcdef" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The provider details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderResponse" } } } }, "400": { "description": "Bad request - validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "404": { "description": "Not Found - Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } } } } }, "/resources/orders": { "post": { "summary": "Create order", "tags": ["Orders"], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^application\\/json", "example": "application/json" }, "required": true, "name": "content-type", "in": "header" }, { "schema": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "required": true, "name": "idempotency-key", "in": "header", "description": "Unique identifier for idempotent request handling. Must be a valid UUID. Use the same key to safely retry requests." } ], "requestBody": { "description": "Order creation request", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderRequest" } } } }, "responses": { "201": { "description": "Order created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderResponse" } } } }, "400": { "description": "Bad request - validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "404": { "description": "Not Found - Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "409": { "description": "Conflict - Concurrent request timeout", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "422": { "description": "Unprocessable Entity - Idempotency key reused with different request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } } } } }, "/resources/bookings": { "patch": { "summary": "Update booking", "description": "Request should include only the fields that need to be updated. The request must include bookingId or externalBookingId.", "tags": ["Bookings"], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^application\\/json", "example": "application/json" }, "required": true, "name": "content-type", "in": "header" }, { "schema": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "required": true, "name": "idempotency-key", "in": "header", "description": "Unique identifier for idempotent request handling. Must be a valid UUID. Use the same key to safely retry requests." } ], "requestBody": { "description": "Booking update request", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBookingRequest" } } } }, "responses": { "200": { "description": "Booking updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBookingResponse" } } } }, "400": { "description": "Bad request - validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "404": { "description": "Not Found - Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "409": { "description": "Conflict - Concurrent request timeout", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "422": { "description": "Unprocessable Entity - Idempotency key reused with different request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } } } } }, "/resources/reservedslots": { "post": { "summary": "Create reserved slot", "tags": ["Reserved slots"], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^application\\/json", "example": "application/json" }, "required": true, "name": "content-type", "in": "header" }, { "schema": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "required": true, "name": "idempotency-key", "in": "header", "description": "Unique identifier for idempotent request handling. Must be a valid UUID. Use the same key to safely retry requests." } ], "requestBody": { "description": "Reserved slot creation request", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReservedSlotRequest" } } } }, "responses": { "201": { "description": "Reserved slot created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReservedSlotResponse" } } } }, "400": { "description": "Bad request - validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "404": { "description": "Not Found - Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "409": { "description": "Conflict - Concurrent request timeout", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "422": { "description": "Unprocessable Entity - Idempotency key reused with different request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } } } } }, "/resources/reservedslots/{reservedSlotId}": { "delete": { "summary": "Remove reserved slot", "tags": ["Reserved slots"], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "reservedSlotId", "in": "path" } ], "responses": { "204": { "description": "Reserved slot deleted successfully" }, "400": { "description": "Bad request - validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "404": { "description": "Not Found - Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } } } } }, "/resources/clients": { "post": { "summary": "Create Client", "description": "Send only the fields that need to be updated along with either the clientId or externalClientId", "tags": ["Clients"], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^application\\/json", "example": "application/json" }, "required": true, "name": "content-type", "in": "header" }, { "schema": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "required": true, "name": "idempotency-key", "in": "header", "description": "Unique identifier for idempotent request handling. Must be a valid UUID. Use the same key to safely retry requests." } ], "requestBody": { "description": "Client creation request", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateClientRequest" } } } }, "responses": { "201": { "description": "Client created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientResponse" } } } }, "400": { "description": "Bad request - validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "404": { "description": "Not Found - Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "409": { "description": "Conflict - Concurrent request timeout", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "422": { "description": "Unprocessable Entity - Idempotency key reused with different request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } } } }, "get": { "summary": "Get Clients", "tags": ["Clients"], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^\\d+$", "default": 100, "description": "Maximum number of items to return per page (default: 20, max: 100). Note: The actual number of items returned may be less than this value due to DynamoDB pagination, server-side filtering, or data availability. Always check 'pagination.nextCursor' to determine if more results are available.", "example": 20 }, "required": false, "description": "Maximum number of items to return per page (default: 20, max: 100). Note: The actual number of items returned may be less than this value due to DynamoDB pagination, server-side filtering, or data availability. Always check 'pagination.nextCursor' to determine if more results are available.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Pagination cursor from a previous response. Pass the 'nextCursor' value from the previous response here to fetch the next page of results. Omit this parameter for the first page.", "example": "eyJpZCI6IjEyMyIsInNrIjoiYWJjIn0=" }, "required": false, "description": "Pagination cursor from a previous response. Pass the 'nextCursor' value from the previous response here to fetch the next page of results. Omit this parameter for the first page.", "name": "nextCursor", "in": "query" }, { "schema": { "type": "string", "format": "email", "description": "Filter by client email address", "example": "john.doe@example.com" }, "required": false, "description": "Filter by client email address", "name": "emailadress", "in": "query" } ], "responses": { "200": { "description": "Clients retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedClientsResponse" } } } }, "400": { "description": "Bad request - validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "404": { "description": "Not Found - Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } } } }, "patch": { "summary": "Update Client", "description": "Request should include only the fields that need to be updated. The request must include clientId or externalClientId.", "tags": ["Clients"], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^application\\/json", "example": "application/json" }, "required": true, "name": "content-type", "in": "header" }, { "schema": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "required": true, "name": "idempotency-key", "in": "header", "description": "Unique identifier for idempotent request handling. Must be a valid UUID. Use the same key to safely retry requests." } ], "requestBody": { "description": "Client update request", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateClientRequest" } } } }, "responses": { "200": { "description": "Client updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientResponse" } } } }, "400": { "description": "Bad request - validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "404": { "description": "Not Found - Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "409": { "description": "Conflict - Concurrent request timeout", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "422": { "description": "Unprocessable Entity - Idempotency key reused with different request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } } } } }, "/resources/clients/{id}": { "get": { "summary": "Get Client", "tags": ["Clients"], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-1234-567890abcdef" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Client retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientResponse" } } } }, "400": { "description": "Bad request - validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "404": { "description": "Not Found - Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" } }, "required": ["code", "path"] } }, "name": { "type": "string" } }, "required": ["issues", "name"], "example": { "name": "ZodError", "issues": [ { "code": "invalid_type", "path": ["message"], "message": "Invalid input: expected string, received undefined" } ] } } }, "required": ["success", "error"] } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "schemas": { "TimeSlotsRequest": { "type": "object", "required": [ "billingId", "targetGeoLocation", "targetServiceDurationMins", "providers" ], "properties": { "billingId": { "type": "string", "description": "###### The end user's unique identifier used for billing\n", "example": "eahu28d-2ff3-4b91-8c4f-dj9928sjsd87d" }, "targetGeoLocation": { "type": "array", "description": "###### The latitude and longitude coordinates of where the service will take place [latitude, longitude]\n", "items": { "type": "number", "format": "float" }, "example": [28.23068, -81.334973] }, "targetServiceDurationMins": { "description": "###### The duration of the service in minutes\n", "type": "number", "format": "(mins)", "example": 60 }, "providers": { "type": "array", "description": "###### List of providers, each with their providerId, maxTravelTimeMins, bookings, and availability.\n", "items": { "type": "object", "required": ["providerId", "maxTravelTimeMins", "availability"], "properties": { "providerId": { "type": "string", "description": "The provider's unique identifier\n", "example": "e7b9e6a8-3f64-4b91-8c4f-abcdef123456" }, "maxTravelTimeMins": { "type": "integer", "description": "The provider's maxTravelTime between appointments in minutes\n", "example": 15 }, "availability": { "type": "array", "description": "A list of provider availabilities\n", "items": { "type": "object", "required": ["startDateAndTime", "endDateAndTime"], "properties": { "startDateAndTime": { "type": "string", "description": "The start date and time of the availability in ISO-8601 format\n", "format": "ISO-8601", "example": "2024-12-01T09:00:00-05:00" }, "endDateAndTime": { "type": "string", "description": "The end date and time of the availability in ISO-8601 format\n", "format": "ISO-8601", "example": "2025-05-25T20:00:00-05:00" }, "startGeoLocation": { "type": "array", "description": "###### The latitude and longitude coordinates of the schedule's starting point or departure location [latitude, longitude], e.g. head office or main depot\n", "items": { "type": "number", "format": "float" }, "example": [28.23068, -81.334973] }, "endGeoLocation": { "type": "array", "description": "###### The latitude and longitude coordinates of the schedule's ending point or arrival location [latitude, longitude], e.g. head office or main depot \n", "items": { "type": "number", "format": "float" }, "example": [28.23068, -81.334973] }, "rrule": { "type": "string", "description": "The availability recurrence rule - the example rrule describes an availability that is active every week on Tuesday, Saturday, and Sunday\n", "default": "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR,SA,SU", "example": "FREQ=WEEKLY;INTERVAL=1;BYDAY=TU,SA,SU" } } } }, "bookings": { "type": "array", "description": "A list of booking's the provider is scheduled for\n", "default": "provider has no scheduled bookings", "items": { "type": "object", "required": [ "startDateAndTime", "durationMins", "geoLocation" ], "properties": { "startDateAndTime": { "type": "string", "description": "The start date and time of the scheduled booking in ISO-8601 format\n", "format": "ISO-8601", "example": "2024-12-12T10:00:00-05:00" }, "durationMins": { "type": "integer", "description": "The duration of the scheduled booking in minutes\n", "example": 60 }, "geoLocation": { "type": "array", "description": "The latitude and longitude coordinates of where the scheduled service is taking place [latitude, longitude]\n", "items": { "type": "number", "format": "float" }, "example": [28.385233, -81.563873] } } }, "example": [ { "startDateAndTime": "2024-12-12T10:00:00-05:00", "durationMins": 60, "geoLocation": [28.435233, -81.893873] } ] }, "blockedTime": { "type": "array", "description": "A list of provider blocked times\n", "items": { "type": "object", "required": ["startDateAndTime", "endDateAndTime"], "properties": { "startDateAndTime": { "type": "string", "description": "The start date and time of the blocked time in ISO-8601 format\n", "format": "ISO-8601", "example": "2024-12-01T09:00:00-05:00" }, "endDateAndTime": { "type": "string", "description": "The end date and time of the blocked time in ISO-8601 format\n", "format": "ISO-8601", "example": "2025-05-25T20:00:00-05:00" }, "rrule": { "type": "string", "description": "The blocked time recurrence rule - the example rrule describes a blocked time that is active every week on Tuesday\n", "default": "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR,SA,SU", "example": "FREQ=WEEKLY;INTERVAL=1;BYDAY=TU" } } } }, "bufferTimeMins": { "type": "integer", "format": "(mins)", "description": "###### Time added on top of travel time calculations\n", "example": 15, "default": 0 }, "maxTravelTimeFromStartGeoLocationMins": { "type": "integer", "description": "The provider's maxTravelTime from their startGeoLocation in minutes. Only applies to the first booking of the day and if startGeoLocation is provided\n", "example": 20 }, "maxTravelTimeToEndGeoLocationMins": { "type": "integer", "description": "The provider's maxTravelTime to their endGeoLocation in minutes. Only applies to the last booking of the day and if endGeoLocation is provided\n", "example": 20 } } } }, "lookAheadStartDate": { "type": "string", "format": "ISO-8601", "description": "###### The date to begin the look-ahead period. By default, the date and time of the request is used.\n", "example": "2024-12-01T00:00:00-05:00", "default": "date of the request" }, "lookAheadDays": { "type": "integer", "description": "###### The number of days to search ahead from the lookAheadStartDate. Defaults to 7 days and cannot exceed a maximum of 7 days.\n", "example": 7, "default": 7 }, "travelTimeType": { "type": "string", "description": "###### The travel time type returned in TimeSlotResponse: \"raw\" (e.g. 12.6 min) or \"rounded\" (e.g. 15 min). By default, travel time is rounded up to the nearest 5 minutes.\n", "example": "raw", "enum": ["rounded", "raw"], "default": "rounded" }, "preferredTimeSlotThresholdMins": { "type": "integer", "description": "###### The maximum travel time threshold for a preferred time slot. Defaults to 5 minutes.\n", "example": 10, "default": 5 }, "distanceUnit": { "type": "string", "description": "###### The unit for travel distance in the response. Defaults to kilometers. \n", "example": "mi", "enum": ["km", "mi"], "default": "km" }, "minBookingNoticeMins": { "type": "number", "format": "(mins)", "description": "###### Minimum advance notice from current date and time for time slot suggestions - no time slots will be suggested within the minimum booking notice window. Defaults to no minimum notice.\n", "example": 60, "default": 0 }, "emptyDayAnchorTime": { "type": "string", "format": "(HH:MM)", "description": "###### The anchor time for the first booking on an empty day, used as a base for clustering. Defaults to the first and last available slots of a schedule's time range.\n", "example": "14:00", "default": "first and last available slot of a schedule's time range" }, "preferredDays": { "type": "array", "description": "###### Specifies the preferred days of the week for time slots. Days are represented numerically, where 0 = Sunday and 6 = Saturday\n", "items": { "type": "number", "format": "integer" }, "example": [1, 2, 3, 4, 5] }, "preferredTimes": { "type": "array", "description": "###### Specifies preferred time ranges for time slots\n", "items": { "type": "object", "required": ["startTime", "endTime"], "properties": { "startTime": { "type": "string", "description": "The start time of the preferred time range in 24-hour format\n", "format": "ISO-8601", "example": "09:00" }, "endTime": { "type": "string", "description": "The end time of the preferred time range in 24-hour format\n", "format": "ISO-8601", "example": "13:00" } } } }, "order": { "type": "string", "description": "###### Prioritizes suggested time slots at the start (`mustBeFirst`) or end (`mustBeLast`) of the day. Add optional `startGeoLocation` and/or `endGeoLocation` parameters in the provider availability array to make sure routes start and end at specific locations. Regular time slots will still be included in the response.\n", "example": "mustBeFirst", "enum": ["mustBeFirst", "mustBeLast"] }, "maxNumberOfBookingsPerDay": { "type": "number", "description": "###### Maximum number of bookings for a single day\n", "example": 5 } } }, "TimeSlotsResponse": { "type": "object", "required": ["status", "message", "timeSlots"], "properties": { "status": { "type": "number", "example": 200 }, "message": { "type": "string", "example": "Successfully generated time slots" }, "timeSlots": { "type": "array", "description": "##### List of generated suggested time slot objects\n", "items": { "type": "object", "required": [ "providerId", "timeSlotId", "timeSlotDateAndTime", "preferredTimeSlot", "travelTimeMins", "travelDistance", "travelType", "message" ], "properties": { "providerId": { "type": "string", "description": "The provider's unique identifier\n", "example": "e7b9e6a8-3f64-4b91-8c4f-abcdef123456" }, "timeSlotId": { "type": "string", "description": "The time slots unique identifier \n", "example": "8582011f-204e-4e7e-8278-745ba215d28c" }, "timeSlotDateAndTime": { "description": "The start date and time of the suggested time slot\n", "type": "string", "format": "ISO-8601", "example": "2024-12-01T09:00:00-05:00" }, "preferredTimeSlot": { "description": "Indicates if the time slot is less than or equal to the preferredTimeSlotThresholdMins\n", "type": "boolean", "example": true }, "travelTimeMins": { "type": "number", "description": "Travel time in minutes between the target location and the neighboring booking’s location, if applicable.\n", "format": "float", "example": 15 }, "travelDistance": { "type": "number", "description": "Travel distance between the target location and the neighboring booking’s location, if applicable.\n", "format": "float", "example": 4.1 }, "travelType": { "type": "string", "description": "Indicates the type of travel required by the provider to reach the target location for a booking. This can specify whether travel is from a prior booking location, to the next\nbooking location, within the same location, or when the day has no other bookings.\n", "enum": [ "FROM-PREVIOUS-BOOKING", "TO-NEXT-BOOKING", "SAME-LOCATION-AS-PREVIOUS", "SAME-LOCATION-AS-NEXT", "ON-EMPTY-DAY", "FROM-START-LOCATION", "TO-END-LOCATION" ], "example": "FROM-PREVIOUS-BOOKING" }, "message": { "type": "string", "description": "A user friendly message detailing the suggested time slot\n", "example": "15 mins drive from previous booking (4.1mi)" }, "isFirst": { "description": "Indicates if the suggested time slot is the first booking of the day. NOTE this attribute will only exist if the 'order' in the request was 'mustBeFirst'.\n", "type": "boolean", "example": true }, "isLast": { "description": "Indicates if the suggested time slot is the last booking of the day. NOTE this attribute will only exist if the 'order' in the request was 'mustBeLast'.\n", "type": "boolean", "example": true } } } }, "errors": { "type": "array", "description": "Array of error messages for individual providers. Errors for one provider do not prevent attempts for other providers.\n", "items": { "type": "string", "example": "ProviderError (providerId: d6e3aa48-ae4e-4b91-8c4f-abcdef123456): Buffer time cannot be greater than max travel time." } } } }, "WhoIsAvailableRequest": { "type": "object", "required": ["billingId", "targetGeoLocation", "targetServiceId"], "properties": { "billingId": { "type": "string", "description": "###### The end user's unique identifier used for billing\n", "example": "eahu28d-2ff3-4b91-8c4f-dj9928sjsd87d" }, "targetGeoLocation": { "type": "array", "description": "###### The latitude and longitude coordinates of where the service will take place [latitude, longitude]. This is not required if a valid companyLocationId is provided.\n", "items": { "type": "number", "format": "float" }, "example": [28.23068, -81.334973] }, "companyLocationId": { "type": "string", "description": "###### The ID for the company location saved in MarketBox. This value will override the targetGeoLocation.\n", "format": "uuidv4", "example": "0adfb507-f7bf-47e5-8d31-5c7ed2bd73f6" }, "targetServiceId": { "description": "###### The ID for the service saved in MarketBox. \n", "type": "string", "format": "uuidv4", "example": "f7ed7ed4-9fbe-4d6d-9a57-57175d5f9adb" }, "bookingType": { "type": "string", "description": "###### Specifies if the slots being searched for are for a single booking, or a recurring booking set. By marking this `recurring`, expect a `WhoIsAvailableRecurringResponse` returned. Defaults to `single`.\n", "default": "single", "example": "single", "enum": ["single", "recurring"] }, "startDateAndTime": { "type": "string", "format": "ISO-8601", "description": "###### This is the date range AND time range of when the \"Who is available\" API will generate suggested time slots for.\n", "example": "2025-01-01T00:00:00-05:00", "default": "date of the request" }, "endDateAndTime": { "type": "string", "format": "ISO-8601", "description": "###### This is the date range AND time range of when the \"Who is available\" API will generate suggested time slots for – the time range is calculated on EACH of the day of the date range, e.g. if you send Oct 22, 14:00 until Oct 24, 18:00, this will mean 14:00-18:00 on each of the 3 days, and NOT a continuous period of 52 hours.\n", "example": "2025-01-07T20:00:00-05:00", "default": "7 days from the `startDateAndTime`" }, "daysOfWeek": { "type": "array", "description": "###### If `bookingType` is set to `single`, the days of the week specify which days to return time slots for (e.g. the client can only do Mondays, so only return time slots for Mondays); if `bookingType` is set to `recurring`, the days of the week are NOT taken into consideration, as this information will be provided in the `rrule` attribute.\n", "items": { "type": "number", "format": "integer" }, "example": [1, 2, 3, 4, 5], "default": [0, 1, 2, 3, 4, 5, 6] }, "skills": { "type": "array", "description": "###### This is a list of required skills for the provider to have in order to be eligible for the booking (defaults to none, i.e. no skill constraints).\n", "items": { "type": "string", "format": "uuidv4" }, "example": ["5efe490b-ea04-439d-89ba-24976dcac796"] }, "rrule": { "type": "string", "description": "###### This is the recurring pattern for bookings - `bookingType` must be set to `recurring` for this to be considered; The days of week provided in the rrule indicate the repeating cadence and if included, all of the days are considered as required, e.g. if you send every week Tuesday, Saturday and Sunday, we will ONLY suggest time slots that are available on all 3 of those days, so if a provider can do Tuesdays and Saturdays, but not Sundays, then they will not be included in the response.\n", "default": "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR,SA,SU", "example": "FREQ=WEEKLY;INTERVAL=1;BYDAY=TU,SA,SU" }, "travelTimeType": { "type": "string", "description": "###### The travel time type returned in TimeSlotResponse: \"raw\" (e.g. 12.6 min) or \"rounded\" (e.g. 15 min). By default, travel time is rounded up to the nearest 5 minutes.\n", "example": "raw", "enum": ["rounded", "raw"], "default": "rounded" }, "minBookingNoticeMins": { "type": "number", "format": "(mins)", "description": "###### Minimum advance notice from current date and time for time slot suggestions - no time slots will be suggested within the minimum booking notice window. Defaults to no minimum notice.\n", "example": 60, "default": 0 }, "preferredTimeSlotThresholdMins": { "type": "integer", "description": "###### The maximum travel time threshold for a preferred time slot. Defaults to 5 minutes.\n", "example": 10, "default": 5 }, "distanceUnit": { "type": "string", "description": "###### The unit for travel distance in the response. Defaults to kilometers. \n", "example": "mi", "enum": ["km", "mi"], "default": "km" } } }, "WhoIsAvailableResponse": { "type": "object", "required": ["status", "message", "timeSlots"], "properties": { "status": { "type": "number", "example": 200 }, "message": { "type": "string", "example": "Successfully generated time slots" }, "timeSlots": { "type": "array", "description": "##### List of generated suggested time slot objects\n", "items": { "type": "object", "required": [ "providerId", "timeSlotId", "timeSlotDateAndTime", "preferredTimeSlot", "travelTimeMins", "travelDistance", "travelType", "message", "isWithinMinBookingNotice", "providerFirstName", "providerLastName" ], "properties": { "providerId": { "type": "string", "description": "The provider's unique identifier\n", "example": "e7b9e6a8-3f64-4b91-8c4f-abcdef123456" }, "timeSlotId": { "type": "string", "description": "The time slots unique identifier \n", "example": "8582011f-204e-4e7e-8278-745ba215d28c" }, "timeSlotDateAndTime": { "description": "The start date and time of the suggested time slot\n", "type": "string", "format": "ISO-8601", "example": "2024-12-01T09:00:00-05:00" }, "preferredTimeSlot": { "description": "Indicates if the time slot is less than or equal to the preferredTimeSlotThresholdMins\n", "type": "boolean", "example": true }, "travelTimeMins": { "type": "number", "description": "Travel time in minutes between the target location and the neighboring booking’s location, if applicable.\n", "format": "float", "example": 15 }, "travelDistance": { "type": "number", "description": "Travel distance between the target location and the neighboring booking’s location, if applicable.\n", "format": "float", "example": 4.1 }, "travelType": { "type": "string", "description": "Indicates the type of travel required by the provider to reach the target location for a booking. This can specify whether travel is from a prior booking location, to the next\nbooking location, within the same location, or when the day has no other bookings.\n", "enum": [ "FROM-PREVIOUS-BOOKING", "TO-NEXT-BOOKING", "SAME-LOCATION-AS-PREVIOUS", "SAME-LOCATION-AS-NEXT", "ON-EMPTY-DAY", "FROM-START-LOCATION", "TO-END-LOCATION" ], "example": "FROM-PREVIOUS-BOOKING" }, "message": { "type": "string", "description": "A user friendly message detailing the suggested time slot\n", "example": "15 mins drive from previous booking (4.1mi)" }, "isWithinMinBookingNotice": { "type": "boolean", "description": "Indicates if this booking is within the set minimum booking notice time\n" }, "providerFirstName": { "description": "The available providers first name\n", "type": "string", "example": "John" }, "providerLastName": { "description": "The available providers last name\n", "type": "string", "example": "Smith" } } } }, "errors": { "type": "array", "description": "Array of error messages for individual providers. Errors for one provider do not prevent attempts for other providers.\n", "items": { "type": "string", "example": "ProviderError (providerId: d6e3aa48-ae4e-4b91-8c4f-abcdef123456): Buffer time cannot be greater than max travel time." } } } }, "WhoIsAvailableRecurringResponse": { "type": "object", "required": ["status", "message", "timeSlots"], "properties": { "status": { "type": "number", "example": 201 }, "message": { "type": "string", "example": "Successfully generated time slots" }, "timeSlots": { "type": "array", "description": "##### List of generated sets of suggested time slots\n", "items": { "type": "object", "required": [ "providerId", "timeSlotDateAndTime", "preferredTimeSlot", "travelTimeMins", "travelDistance", "travelType", "timePatter", "consistency", "isWithinMinBookingNotice", "providerFirstName", "providerLastName", "slots" ], "properties": { "providerId": { "type": "string", "description": "The provider's unique identifier\n", "example": "e7b9e6a8-3f64-4b91-8c4f-abcdef123456" }, "travelTimeMins": { "type": "number", "description": "Travel time in minutes between the target location and the neighboring booking’s location, if applicable.\n", "format": "float", "example": 15 }, "travelDistance": { "type": "number", "description": "Travel distance between the target location and the neighboring booking’s location, if applicable.\n", "format": "float", "example": 4.1 }, "travelType": { "type": "string", "description": "Indicates the type of travel required by the provider to reach the target location for a booking. This can specify whether travel is from a prior booking location, to the next\nbooking location, within the same location, or when the day has no other bookings.\n", "enum": [ "FROM-PREVIOUS-BOOKING", "TO-NEXT-BOOKING", "SAME-LOCATION-AS-PREVIOUS", "SAME-LOCATION-AS-NEXT", "ON-EMPTY-DAY", "FROM-START-LOCATION", "TO-END-LOCATION" ], "example": "FROM-PREVIOUS-BOOKING" }, "mostAvailableStartTime": { "type": "string", "description": "This is the start time that fits the most number of days in the recurring pattern, so bookings are as consistent as possible with the same start time\n", "example": "14:30" }, "startTimeConsistencyPercent": { "type": "integer", "description": "This is the percentage of days out of the total recurring pattern that can be booked with the `mostAvailableStartTime`\n", "example": 90 }, "isWithinMinBookingNotice": { "type": "boolean", "description": "Indicates if this booking is within the set minimum booking notice time\n" }, "providerFirstName": { "description": "The available providers first name\n", "type": "string", "example": "John" }, "providerLastName": { "description": "The available providers last name\n", "type": "string", "example": "Smith" }, "slots": { "type": "array", "description": "##### List of generated suggested time slot objects\n", "items": { "type": "object", "required": [ "providerId", "timeSlotId", "timeSlotDateAndTime", "preferredTimeSlot", "travelTimeMins", "travelDistance", "travelType", "message" ], "properties": { "providerId": { "type": "string", "description": "The provider's unique identifier\n", "example": "e7b9e6a8-3f64-4b91-8c4f-abcdef123456" }, "timeSlotId": { "type": "string", "description": "The time slots unique identifier \n", "example": "8582011f-204e-4e7e-8278-745ba215d28c" }, "timeSlotDateAndTime": { "description": "The start date and time of the suggested time slot\n", "type": "string", "format": "ISO-8601", "example": "2024-12-01T09:00:00-05:00" }, "preferredTimeSlot": { "description": "Indicates if the time slot is less than or equal to the preferredTimeSlotThresholdMins\n", "type": "boolean", "example": true }, "travelTimeMins": { "type": "number", "description": "Travel time in minutes between the target location and the neighboring booking’s location, if applicable.\n", "format": "float", "example": 15 }, "travelDistance": { "type": "number", "description": "Travel distance between the target location and the neighboring booking’s location, if applicable.\n", "format": "float", "example": 4.1 }, "travelType": { "type": "string", "description": "Indicates the type of travel required by the provider to reach the target location for a booking. This can specify whether travel is from a prior booking location, to the next\nbooking location, within the same location, or when the day has no other bookings.\n", "enum": [ "FROM-PREVIOUS-BOOKING", "TO-NEXT-BOOKING", "SAME-LOCATION-AS-PREVIOUS", "SAME-LOCATION-AS-NEXT", "ON-EMPTY-DAY", "FROM-START-LOCATION", "TO-END-LOCATION" ], "example": "FROM-PREVIOUS-BOOKING" }, "message": { "type": "string", "description": "A user friendly message detailing the suggested time slot\n", "example": "15 mins drive from previous booking (4.1mi)" } } } } } } }, "errors": { "type": "array", "description": "Array of error messages for individual providers. Errors for one provider do not prevent attempts for other providers.\n", "items": { "type": "string", "example": "ProviderError (providerId: d6e3aa48-ae4e-4b91-8c4f-abcdef123456): Buffer time cannot be greater than max travel time." } } } }, "ClustersUsageResponse": { "type": "object", "properties": { "totalRequests": { "type": "integer", "description": "Total number of requests made.", "example": 850 }, "totalTimeSlotsGenerated": { "type": "integer", "description": "Total number of time slots generated.", "example": 1125 }, "totalBookings": { "type": "integer", "description": "Total number of provider bookings provided in the requests.", "example": 2200 }, "avgProvidersPerRequest": { "type": "number", "format": "float", "description": "Average number of providers per request.", "example": 6 }, "byBillingId": { "type": "array", "description": "Breakdown of usage by billing ID.", "items": { "type": "object", "properties": { "billingId": { "type": "string", "description": "Unique identifier for the billing entity.", "example": "12345-abcde" }, "requests": { "type": "integer", "description": "Number of requests made by this billing ID.", "example": 270 }, "timeSlotsGenerated": { "type": "integer", "description": "Total number of time slots generated for this billing ID.", "example": 357 }, "bookings": { "type": "integer", "description": "Total number of bookings made by this billing ID.", "example": 733 }, "avgProvidersPerRequest": { "type": "number", "format": "float", "description": "Average number of providers per request for this billing ID.", "example": 6 } } } }, "startDate": { "type": "string", "format": "date", "description": "Start date for the usage data range.", "example": "2025-01-01" }, "endDate": { "type": "string", "format": "date", "description": "End date for the usage data range.", "example": "2025-01-15" } } }, "BaseService": { "type": "object", "properties": { "name": { "type": "string", "example": "Window cleaning" }, "desc": { "type": "string", "example": "Professional window cleaning service" }, "categoryId": { "type": "string" }, "categoryName": { "type": "string" }, "minutes": { "type": "integer" }, "price": { "type": "number" }, "active": { "type": "boolean" }, "deleted": { "type": "boolean" }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "location-id-1" }, "name": { "type": "string", "example": "Downtown Office" } }, "required": ["id", "name"] }, "example": [ { "id": "location-id-1", "name": "Downtown Office" }, { "id": "location-id-2", "name": "Uptown Branch" } ] } }, "required": ["name", "desc"] }, "ServiceResponse": { "allOf": [ { "$ref": "#/components/schemas/BaseService" }, { "type": "object", "properties": { "id": { "type": "string", "example": "a1b2c3d4-e5f6-7890-1234-167890abcdef" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": ["id", "createdAt", "updatedAt"] } ] }, "PictureObject": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Signed S3 URL for the provider picture" }, "expiresAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the signed URL expires" } }, "required": ["url", "expiresAt"], "description": "Signed URL for profile picture with expiration" }, "ProviderService": { "type": "object", "properties": { "id": { "type": "string", "example": "service-uuid-1" }, "name": { "type": "string", "example": "Haircut" }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "location-id-1" }, "name": { "type": "string", "example": "Downtown Office" } }, "required": ["id", "name"] }, "example": [ { "id": "loc-1", "name": "Downtown Office" }, { "id": "loc-2", "name": "Uptown Branch" } ] } }, "required": ["id", "name"] }, "SkillResponse": { "type": "object", "properties": { "id": { "type": "string", "example": "skill-uuid-123" }, "name": { "type": "string", "example": "Advanced Color Techniques" } }, "required": ["id", "name"] }, "ProviderResponse": { "type": "object", "properties": { "providerId": { "type": "string", "example": "a1b2c3d4-e5f6-7890-1234-567890abcdef" }, "firstname": { "type": "string", "example": "John" }, "lastname": { "type": "string", "example": "Doe" }, "emailaddress": { "type": "string", "format": "email", "example": "john.doe@example.com" }, "phone": { "type": "string", "example": "+1234567890" }, "timezone": { "type": "string", "example": "America/New_York" }, "bio": { "type": "string", "example": "Experienced professional with 10 years of service" }, "picture": { "$ref": "#/components/schemas/PictureObject" }, "offersMobileServices": { "type": "boolean", "example": true }, "active": { "type": "boolean", "example": true }, "deleted": { "type": "boolean", "example": false }, "ratingstarsavg": { "type": "number", "description": "Average rating in stars (formatted to 2 decimal places)", "example": 4.35 }, "numberofratings": { "type": "integer", "example": 142 }, "offersVirtualServices": { "type": "boolean", "example": false }, "maxTravelTime": { "type": "integer", "example": 30, "description": "Maximum travel time allowed between bookings in minutes" }, "externalId": { "type": "string", "description": "External system identifier", "example": "ext-12345" }, "externalData": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Additional external data as key-value pairs", "example": { "source": "external-system", "customField": "value", "syncedAt": "2026-01-09" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderService" }, "description": "Serivces provided by the provider", "example": [ { "id": "service-uuid-1", "name": "Haircut", "locations": [ { "id": "loc-1", "name": "Downtown Office" } ] } ] }, "skills": { "type": "array", "items": { "$ref": "#/components/schemas/SkillResponse" }, "description": "Skills of the provider", "example": [ { "id": "skill-1", "name": "Advanced Color Techniques" }, { "id": "skill-2", "name": "Balayage Specialist" } ] } }, "required": ["providerId", "createdAt", "updatedAt"] }, "OrderAddress": { "type": "object", "properties": { "addressOneLine": { "type": "string", "minLength": 2, "description": "Full address", "example": "100 Yonge street, Toronto, ON M1T 3N3, Canada" }, "state": { "type": "string", "minLength": 1, "description": "State code or province code", "example": "FL" }, "country": { "type": "string", "minLength": 1, "description": "Country name", "example": "Canada" }, "countryCode": { "type": "string", "minLength": 2, "description": "Country code", "example": "CA" }, "postalCode": { "type": "string", "minLength": 1, "description": "Zip code or postal code", "example": "94043" }, "latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude coordinate", "example": 49.2827 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude coordinate", "example": -123.1207 } }, "required": ["addressOneLine"] }, "OrderResponse": { "type": "object", "properties": { "orderId": { "type": "string", "format": "uuid" }, "serviceName": { "type": "string" }, "type": { "type": "string", "nullable": true, "enum": ["SINGLE", "PACKAGE", "RECURRING", "GROUP"] }, "orderNumber": { "type": "integer" }, "clientId": { "type": "string" }, "providerId": { "type": "string" }, "currency": { "type": "string" }, "status": { "type": "string", "nullable": true, "enum": ["CONFIRMED", "PAID", "UNPAID", "PAIDBYPKGCRE"] }, "address": { "$ref": "#/components/schemas/OrderAddress" }, "externalOrderId": { "type": "string" }, "externalOrderData": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Additional external data as key-value pairs", "example": { "source": "external-system", "customField": "value", "syncedAt": "2026-01-09" } }, "orderTotal": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "orderId", "serviceName", "clientId", "providerId", "createdAt", "updatedAt" ] }, "BookingResponse": { "type": "object", "properties": { "bookingId": { "type": "string", "format": "uuid" }, "serviceName": { "type": "string" }, "orderId": { "type": "string" }, "serviceId": { "type": "string" }, "providerId": { "type": "string" }, "clientId": { "type": "string" }, "startDateAndTime": { "type": "string", "format": "date-time", "description": "Booking date and time with timezone offset", "example": "2025-12-15T16:30:00-05:00" }, "durationMins": { "type": "integer" }, "serviceLocation": { "type": "string" }, "status": { "type": "string", "nullable": true, "enum": ["SCHEDULED", "ARRIVED", "COMPLETED", "CANCELLED", "NOSHOW"] }, "timezone": { "type": "string" }, "orderType": { "type": "string", "nullable": true, "enum": ["SINGLE", "PACKAGE", "RECURRING", "GROUP"] }, "externalBookingId": { "type": "string" }, "externalBookingData": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Additional external data as key-value pairs", "example": { "source": "external-system", "customField": "value", "syncedAt": "2026-01-09" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "bookingId", "serviceName", "orderId", "providerId", "clientId", "startDateAndTime", "durationMins" ] }, "CreateOrderResponse": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/OrderResponse" }, "booking": { "$ref": "#/components/schemas/BookingResponse" } }, "required": ["order", "booking"] }, "ClientRequest": { "type": "object", "properties": { "firstName": { "type": "string", "minLength": 1, "description": "Client's first name" }, "lastName": { "type": "string", "minLength": 1, "description": "Client's last name" }, "email": { "type": "string", "format": "email", "description": "Client's email address", "example": "client@example.com" }, "phone": { "type": "string", "description": "Phone number in E.164 format without spaces", "example": "+17069805493" } }, "required": ["firstName", "lastName", "email", "phone"] }, "PaymentDetails": { "type": "object", "properties": { "orderTotal": { "type": "number", "minimum": 0, "exclusiveMinimum": true }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code", "example": "USD" } }, "required": ["orderTotal", "currency"], "example": { "orderTotal": 100.99, "currency": "USD" } }, "CreateOrderRequest": { "type": "object", "properties": { "reservedSlotId": { "type": "string", "description": "Reserved slot ID obtained from POST /reservedslots endpoint", "example": "550e8400-e29b-41d4-a716-446655440000" }, "serviceId": { "type": "string", "format": "uuid", "description": "Service unique identifier", "example": "123e4567-e89b-12d3-a456-426614174000" }, "client": { "$ref": "#/components/schemas/ClientRequest" }, "paymentDetails": { "$ref": "#/components/schemas/PaymentDetails" }, "externalOrderId": { "type": "string", "description": "This is the unique identifier of the order inside your system – MarketBox will store and map this internally. If your system does not have a distinction between orders and bookings, then send the same booking or order ID in both externalBookingId and externalOrderId fields", "examples": [ "1234567879abcdEF_-", "d535ad37-047f-4624-be76-c19b19aece9d" ] }, "externalBookingId": { "type": "string", "description": "This is the unique identifier of the booking inside your system – MarketBox will store and map this internally", "examples": [ "1234567879abcdEF_-", "d535ad37-047f-4624-be76-c19b19aece9d" ] }, "externalOrderData": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Additional external data for the order", "example": { "source": "external-system", "customField": "value", "syncedAt": "2026-01-09" } }, "externalBookingData": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Additional external data for the booking", "example": { "source": "external-system", "customField": "value", "syncedAt": "2026-01-09" } }, "sendProviderEmailNotification": { "type": "boolean", "default": true } }, "required": ["reservedSlotId", "serviceId", "client"] }, "UpdateBookingResponse": { "type": "object", "properties": { "bookingId": { "type": "string" }, "externalBookingId": { "type": "string" }, "status": { "type": "string", "enum": ["SCHEDULED", "ARRIVED", "COMPLETED", "CANCELLED", "NOSHOW"] }, "startDateAndTime": { "type": "string", "format": "date-time", "description": "Booking date and time with timezone offset", "example": "2025-12-15T16:30:00-05:00" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": ["bookingId", "updatedAt"] }, "UpdateBookingRequest": { "type": "object", "properties": { "bookingId": { "type": "string", "description": "MarketBox booking id of the booking to be updated", "example": "550e8400-e29b-41d4-a716-446655440000" }, "externalBookingId": { "type": "string", "description": "This is the unique identifier of the booking inside your system that needs to be updated in MarketBox. You can provide either bookingId or externalBookingId", "examples": [ "1234567879abcdEF_-", "d535ad37-047f-4624-be76-c19b19aece9d" ] }, "startDateAndTime": { "type": "string", "format": "date-time", "description": "Booking date and time with timezone offset. Provide this value, if you want to reschedule the booking.", "example": "2025-12-15T16:30:00-05:00" }, "timezone": { "type": "string", "description": "IANA timezone identifier (required if startDateAndTime is provided)", "example": "America/New_York" }, "status": { "type": "string", "enum": [ "SCHEDULED", "ARRIVED", "COMPLETED", "CANCELLED", "NOSHOW" ], "description": "Booking status. Provide this value when you want to update the status of booking.", "example": "SCHEDULED" } } }, "CreateReservedSlotResponse": { "type": "object", "properties": { "reservedSlotId": { "type": "string", "description": "Unique identifier (UUID) for the reserved slot mapping record", "example": "550e8400-e29b-41d4-a716-446655440000" } }, "required": ["reservedSlotId"] }, "Address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "description": "Street address", "example": "602 Victor way" }, "city": { "type": "string", "minLength": 1, "description": "Name of the city", "example": "Mountain View" }, "state": { "type": "string", "minLength": 1, "description": "State code or province code", "example": "FL" }, "country": { "type": "string", "minLength": 1, "description": "Country name", "example": "Canada" }, "postalCode": { "type": "string", "minLength": 1, "description": "Zip code or postal code", "example": "94043" }, "latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude coordinate", "example": 49.2827 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude coordinate", "example": -123.1207 } }, "required": [ "street", "city", "state", "country", "postalCode", "latitude", "longitude" ] }, "ServiceLocation": { "type": "object", "properties": { "address": { "$ref": "#/components/schemas/Address" }, "companyLocationId": { "type": "string", "format": "uuid", "description": "Unique identifier of the company location in MarketBox. If address is not provided, companyLocationId must be provided.", "example": "89baf2e3-604d-4d98-8d45-75203bd3e93b" } }, "description": "Provide either the address object OR a companyLocationId; if both are provided, the companyLocationId will override the address", "examples": [ { "address": { "street": "220 Castlefrank Rd", "city": "Stittsville", "state": "ON", "country": "Canada", "postalCode": "K2L 1T5", "latitude": 45.2867248, "longitude": -75.8836231 } }, { "companyLocationId": "89baf2e3-604d-4d98-8d45-75203bd3e93b" } ] }, "CreateReservedSlotRequest": { "type": "object", "properties": { "providerId": { "type": "string", "format": "uuid", "description": "Provider unique identifier", "example": "123e4567-e89b-12d3-a456-426614174000" }, "serviceId": { "type": "string", "format": "uuid", "description": "Service unique identifier", "example": "123e4567-e89b-12d3-a456-426614174000" }, "serviceLocation": { "$ref": "#/components/schemas/ServiceLocation" }, "timezone": { "type": "string", "description": "IANA timezone", "example": "America/Vancouver" }, "startDateAndTime": { "type": "string", "format": "date-time", "description": "Booking date and time with timezone offset", "example": "2025-12-15T16:30:00-05:00" }, "reservationTimeoutMins": { "type": "integer", "minimum": 5, "maximum": 1440, "description": "The number of minutes MarketBox will hold the reservation before releasing it." } }, "required": [ "providerId", "serviceId", "serviceLocation", "timezone", "startDateAndTime", "reservationTimeoutMins" ] }, "ClientAddress": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "description": "Street address", "example": "123 Main St" }, "city": { "type": "string", "minLength": 1, "description": "City name", "example": "Toronto" }, "state": { "type": "string", "minLength": 1, "description": "State or province code", "example": "ON" }, "country": { "type": "string", "minLength": 1, "description": "Country name", "example": "Canada" }, "postalcode": { "type": "string", "minLength": 1, "description": "Postal code or ZIP code", "example": "M5H 2N2" } } }, "ClientResponse": { "type": "object", "properties": { "clientId": { "type": "string", "format": "uuid", "description": "Unique identifier for the client", "example": "550e8400-e29b-41d4-a716-446655440000" }, "firstname": { "type": "string", "description": "Client's first name", "example": "John" }, "lastname": { "type": "string", "description": "Client's last name", "example": "Doe" }, "emailaddress": { "type": "string", "format": "email", "description": "Client's email address", "example": "john.doe@example.com" }, "phone": { "type": "string", "description": "Client's phone number", "example": "+14165551234" }, "notes": { "type": "string", "description": "Notes about the client" }, "address": { "$ref": "#/components/schemas/ClientAddress" }, "longitude": { "type": "number", "description": "Longitude coordinate" }, "latitude": { "type": "number", "description": "Latitude coordinate" }, "externalClientId": { "type": "string", "description": "External system identifier", "example": "ext-12345" }, "externalData": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Additional external data as key-value pairs", "example": { "source": "external-system", "customField": "value", "syncedAt": "2026-01-09" } } }, "required": [ "clientId", "firstname", "lastname", "emailaddress", "phone" ] }, "CreateClientRequest": { "type": "object", "properties": { "firstname": { "type": "string", "minLength": 1, "description": "Client's first name", "example": "John" }, "lastname": { "type": "string", "minLength": 1, "description": "Client's last name", "example": "Doe" }, "emailaddress": { "type": "string", "format": "email", "description": "Client's email address (will be converted to lowercase)", "example": "john.doe@example.com" }, "phone": { "type": "string", "description": "Phone number in E.164 format without spaces", "example": "+14165551234" }, "notes": { "type": "string", "description": "Notes about the client", "example": "Prefers morning appointments" }, "address": { "$ref": "#/components/schemas/ClientAddress" }, "longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude coordinate", "example": -79.3832 }, "latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude coordinate", "example": 43.6532 }, "externalClientId": { "type": "string", "description": "External system identifier", "example": "ext-12345" }, "externalData": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Additional external data as key-value pairs", "example": { "source": "external-system", "customField": "value", "syncedAt": "2026-01-09" } } }, "required": ["firstname", "lastname", "emailaddress", "phone"] }, "PaginatedClientsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [true], "description": "Indicates the request was successful" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ClientResponse" }, "description": "Array of items for the current page. The length may be less than the requested 'limit' due to filtering or data availability." }, "pagination": { "type": "object", "properties": { "nextCursor": { "type": "string", "description": "Cursor for fetching the next page of results. Pass this value as the 'nextCursor' query parameter in the next request. If this field is absent or undefined, there are no more results available.", "example": "eyJpZCI6IjEyMyIsInNrIjoiYWJjIn0=" } } } }, "required": ["success", "data", "pagination"] }, "UpdateClientRequest": { "type": "object", "properties": { "clientId": { "type": "string", "format": "uuid", "description": "MarketBox client ID", "example": "550e8400-e29b-41d4-a716-446655440000" }, "externalClientId": { "type": "string", "description": "External system's client ID. Either clientId or externalClientId must be provided.", "example": "ext-client-123" }, "firstname": { "type": "string", "minLength": 1, "description": "Client's first name", "example": "Jane" }, "lastname": { "type": "string", "minLength": 1, "description": "Client's last name", "example": "Smith" }, "emailaddress": { "type": "string", "format": "email", "description": "Client's email address (will be converted to lowercase)", "example": "jane.smith@example.com" }, "phone": { "type": "string", "description": "Phone number in E.164 format without spaces", "example": "+14165559999" }, "notes": { "type": "string", "nullable": true, "description": "Notes about the client. Set to null to clear existing notes.", "example": "Prefers afternoon appointments" }, "address": { "$ref": "#/components/schemas/ClientAddress" }, "longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude coordinate", "example": -79.3832 }, "latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude coordinate", "example": 43.6532 }, "externalData": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Additional external data as key-value pairs", "example": { "source": "external-system", "customField": "value", "syncedAt": "2026-01-09" } } } } } } }