MarketBox API

Schemas

TimeSlotsRequest

billingId

string · required

The end user's unique identifier used for billing

Example: eahu28d-2ff3-4b91-8c4f-dj9928sjsd87d

targetGeoLocation

number[] · required

The latitude and longitude coordinates of where the service will take place [latitude, longitude]

Example: [28.23068,-81.334973]

targetServiceDurationMins

number · (mins) · required

The duration of the service in minutes

Example: 60

object[] · required

List of providers, each with their providerId, maxTravelTimeMins, bookings, and availability.

lookAheadStartDate

string · ISO-8601

The date to begin the look-ahead period. By default, the date and time of the request is used.

Example: 2024-12-01T00:00:00-05:00

Default: date of the request

lookAheadDays

integer

The number of days to search ahead from the lookAheadStartDate. Defaults to 7 days and cannot exceed a maximum of 7 days.

Example: 7

Default: 7

travelTimeType

string · enum

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.

Enum values:

rounded

raw

Example: raw

Default: rounded

preferredTimeSlotThresholdMins

integer

The maximum travel time threshold for a preferred time slot. Defaults to 5 minutes.

Example: 10

Default: 5

distanceUnit

string · enum

The unit for travel distance in the response. Defaults to kilometers.

Enum values:

Example: mi

Default: km

minBookingNoticeMins

number · (mins)

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.

Example: 60

Default: 0

emptyDayAnchorTime

string · (HH:MM)

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.

Example: 14:00

Default: first and last available slot of a schedule's time range

preferredDays

number[]

Specifies the preferred days of the week for time slots. Days are represented numerically, where 0 = Sunday and 6 = Saturday

Example: [1,2,3,4,5]

object[]

Specifies preferred time ranges for time slots

order

string · enum

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.

Enum values:

mustBeFirst

mustBeLast

Example: mustBeFirst

maxNumberOfBookingsPerDay

number

Maximum number of bookings for a single day

Example: 5

TimeSlotsResponse

status

number · required

message

string · required

object[] · required

List of generated suggested time slot objects

errors

string[]

Array of error messages for individual providers. Errors for one provider do not prevent attempts for other providers.

WhoIsAvailableRequest

billingId

string · required

The end user's unique identifier used for billing

Example: eahu28d-2ff3-4b91-8c4f-dj9928sjsd87d

targetGeoLocation

number[] · required

The latitude and longitude coordinates of where the service will take place [latitude, longitude]. This is not required if a valid companyLocationId is provided.

Example: [28.23068,-81.334973]

targetServiceId

string · uuidv4 · required

The ID for the service saved in MarketBox.

Example: f7ed7ed4-9fbe-4d6d-9a57-57175d5f9adb

companyLocationId

string · uuidv4

The ID for the company location saved in MarketBox. This value will override the targetGeoLocation.

Example: 0adfb507-f7bf-47e5-8d31-5c7ed2bd73f6

bookingType

string · enum

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`.

Enum values:

single

recurring

Example: single

Default: single

startDateAndTime

string · ISO-8601

This is the date range AND time range of when the "Who is available" API will generate suggested time slots for.

Example: 2025-01-01T00:00:00-05:00

Default: date of the request

endDateAndTime

string · ISO-8601

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.

Example: 2025-01-07T20:00:00-05:00

Default: 7 days from the `startDateAndTime`

daysOfWeek

number[]

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.

Example: [1,2,3,4,5]

Default: [0,1,2,3,4,5,6]

skills

string[]

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).

Example: ["5efe490b-ea04-439d-89ba-24976dcac796"]

rrule

string

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.

Example: FREQ=WEEKLY;INTERVAL=1;BYDAY=TU,SA,SU

Default: FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR,SA,SU

travelTimeType

string · enum

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.

Enum values:

rounded

raw

Example: raw

Default: rounded

minBookingNoticeMins

number · (mins)

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.

Example: 60

Default: 0

preferredTimeSlotThresholdMins

integer

The maximum travel time threshold for a preferred time slot. Defaults to 5 minutes.

Example: 10

Default: 5

distanceUnit

string · enum

The unit for travel distance in the response. Defaults to kilometers.

Enum values:

Example: mi

Default: km

WhoIsAvailableResponse

status

number · required

message

string · required

object[] · required

List of generated suggested time slot objects

errors

string[]

Array of error messages for individual providers. Errors for one provider do not prevent attempts for other providers.

WhoIsAvailableRecurringResponse

status

number · required

message

string · required

object[] · required

List of generated sets of suggested time slots

errors

string[]

Array of error messages for individual providers. Errors for one provider do not prevent attempts for other providers.

ClustersUsageResponse

totalRequests

integer

Total number of requests made.

Example: 850

totalTimeSlotsGenerated

integer

Total number of time slots generated.

Example: 1125

totalBookings

integer

Total number of provider bookings provided in the requests.

Example: 2200

avgProvidersPerRequest

number · float

Average number of providers per request.

Example: 6

object[]

Breakdown of usage by billing ID.

startDate

string · date

Start date for the usage data range.

Example: 2025-01-01

endDate

string · date

End date for the usage data range.

Example: 2025-01-15

BaseService

name

string · required

desc

string · required

categoryId

string

categoryName

string

minutes

integer

price

number

active

boolean

deleted

boolean

object[]

ServiceResponse

name

string · required

desc

string · required

id

string · required

createdAt

string · date-time · required

updatedAt

string · date-time · required

categoryId

string

categoryName

string

minutes

integer

price

number

active

boolean

deleted

boolean

object[]

PictureObject

Signed URL for profile picture with expiration

url

string · uri · required

Signed S3 URL for the provider picture

expiresAt

string · date-time · required

ISO 8601 timestamp when the signed URL expires

ProviderService

id

string · required

name

string · required

object[]

SkillResponse

id

string · required

name

string · required

ProviderResponse

providerId

string · required

createdAt

string · date-time · required

updatedAt

string · date-time · required

firstname

string

lastname

string

emailaddress

string · email

phone

string

timezone

string

bio

string

object

Signed URL for profile picture with expiration

offersMobileServices

boolean

active

boolean

deleted

boolean

ratingstarsavg

number

Average rating in stars (formatted to 2 decimal places)

Example: 4.35

numberofratings

integer

offersVirtualServices

boolean

maxTravelTime

integer

Maximum travel time allowed between bookings in minutes

Example: 30

externalId

string

External system identifier

Example: ext-12345

object

Additional external data as key-value pairs

Example: {"source":"external-system","customField":"value","syncedAt":"2026-01-09"}

object[]

Serivces provided by the provider

Example: [{"id":"service-uuid-1","name":"Haircut","locations":[{"id":"loc-1","name":"Downtown Office"}]}]

object[]

Skills of the provider

Example: [{"id":"skill-1","name":"Advanced Color Techniques"},{"id":"skill-2","name":"Balayage Specialist"}]

OrderAddress

addressOneLine

string · minLength: 2 · required

Full address

Example: 100 Yonge street, Toronto, ON M1T 3N3, Canada

state

string · minLength: 1

State code or province code

Example: FL

country

string · minLength: 1

Country name

Example: Canada

countryCode

string · minLength: 2

Country code

Example: CA

postalCode

string · minLength: 1

Zip code or postal code

Example: 94043

latitude

number · min: -90 · max: 90

Latitude coordinate

Example: 49.2827

longitude

number · min: -180 · max: 180

Longitude coordinate

Example: -123.1207

OrderResponse

orderId

string · uuid · required

serviceName

string · required

clientId

string · required

providerId

string · required

createdAt

string · date-time · required

updatedAt

string · date-time · required

type

string | null · enum

Enum values:

SINGLE

PACKAGE

RECURRING

GROUP

orderNumber

integer

currency

string

status

string | null · enum

Enum values:

CONFIRMED

PAID

UNPAID

PAIDBYPKGCRE

object

externalOrderId

string

object

Additional external data as key-value pairs

Example: {"source":"external-system","customField":"value","syncedAt":"2026-01-09"}

orderTotal

number

BookingResponse

bookingId

string · uuid · required

serviceName

string · required

orderId

string · required

providerId

string · required

clientId

string · required

startDateAndTime

string · date-time · required

Booking date and time with timezone offset

Example: 2025-12-15T16:30:00-05:00

durationMins

integer · required

serviceId

string

serviceLocation

string

status

string | null · enum

Enum values:

SCHEDULED

ARRIVED

COMPLETED

CANCELLED

NOSHOW

timezone

string

orderType

string | null · enum

Enum values:

SINGLE

PACKAGE

RECURRING

GROUP

externalBookingId

string

object

Additional external data as key-value pairs

Example: {"source":"external-system","customField":"value","syncedAt":"2026-01-09"}

createdAt

string · date-time

updatedAt

string · date-time

CreateOrderResponse

object · required

ClientRequest

firstName

string · minLength: 1 · required

Client's first name

lastName

string · minLength: 1 · required

Client's last name

email

string · email · required

Client's email address

Example: client@example.com

phone

string · required

Phone number in E.164 format without spaces

Example: +17069805493

PaymentDetails

orderTotal

number · required

currency

string · minLength: 3 · maxLength: 3 · pattern: ^[A-Z]{3}$ · required

ISO 4217 currency code

Example: USD

CreateOrderRequest

reservedSlotId

string · required

Reserved slot ID obtained from POST /reservedslots endpoint

Example: 550e8400-e29b-41d4-a716-446655440000

serviceId

string · uuid · required

Service unique identifier

Example: 123e4567-e89b-12d3-a456-426614174000

object · required

object

externalOrderId

string

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

Example: 1234567879abcdEF_-

externalBookingId

string

This is the unique identifier of the booking inside your system – MarketBox will store and map this internally

Example: 1234567879abcdEF_-

object

Additional external data for the order

Example: {"source":"external-system","customField":"value","syncedAt":"2026-01-09"}

object

Additional external data for the booking

Example: {"source":"external-system","customField":"value","syncedAt":"2026-01-09"}

sendProviderEmailNotification

boolean

Default: true

UpdateBookingResponse

bookingId

string · required

updatedAt

string · date-time · required

externalBookingId

string

status

string · enum

Enum values:

SCHEDULED

ARRIVED

COMPLETED

CANCELLED

NOSHOW

startDateAndTime

string · date-time

Booking date and time with timezone offset

Example: 2025-12-15T16:30:00-05:00

UpdateBookingRequest

bookingId

string

MarketBox booking id of the booking to be updated

Example: 550e8400-e29b-41d4-a716-446655440000

externalBookingId

string

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

Example: 1234567879abcdEF_-

startDateAndTime

string · date-time

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

string

IANA timezone identifier (required if startDateAndTime is provided)

Example: America/New_York

status

string · enum

Booking status. Provide this value when you want to update the status of booking.

Enum values:

SCHEDULED

ARRIVED

COMPLETED

CANCELLED

NOSHOW

Example: SCHEDULED

CreateReservedSlotResponse

reservedSlotId

string · required

Unique identifier (UUID) for the reserved slot mapping record

Example: 550e8400-e29b-41d4-a716-446655440000

Address

street

string · minLength: 1 · required

Street address

Example: 602 Victor way

city

string · minLength: 1 · required

Name of the city

Example: Mountain View

state

string · minLength: 1 · required

State code or province code

Example: FL

country

string · minLength: 1 · required

Country name

Example: Canada

postalCode

string · minLength: 1 · required

Zip code or postal code

Example: 94043

latitude

number · min: -90 · max: 90 · required

Latitude coordinate

Example: 49.2827

longitude

number · min: -180 · max: 180 · required

Longitude coordinate

Example: -123.1207

ServiceLocation

Provide either the address object OR a companyLocationId; if both are provided, the companyLocationId will override the address

object

companyLocationId

string · uuid

Unique identifier of the company location in MarketBox. If address is not provided, companyLocationId must be provided.

Example: 89baf2e3-604d-4d98-8d45-75203bd3e93b

CreateReservedSlotRequest

providerId

string · uuid · required

Provider unique identifier

Example: 123e4567-e89b-12d3-a456-426614174000

serviceId

string · uuid · required

Service unique identifier

Example: 123e4567-e89b-12d3-a456-426614174000

object · required

Provide either the address object OR a companyLocationId; if both are provided, the companyLocationId will override the address

Example: {"address":{"street":"220 Castlefrank Rd","city":"Stittsville","state":"ON","country":"Canada","postalCode":"K2L 1T5","latitude":45.2867248,"longitude":-75.8836231}}

timezone

string · required

IANA timezone

Example: America/Vancouver

startDateAndTime

string · date-time · required

Booking date and time with timezone offset

Example: 2025-12-15T16:30:00-05:00

reservationTimeoutMins

integer · min: 5 · max: 1440 · required

The number of minutes MarketBox will hold the reservation before releasing it.

ClientAddress

street

string · minLength: 1

Street address

Example: 123 Main St

city

string · minLength: 1

City name

Example: Toronto

state

string · minLength: 1

State or province code

Example: ON

country

string · minLength: 1

Country name

Example: Canada

postalcode

string · minLength: 1

Postal code or ZIP code

Example: M5H 2N2

ClientResponse

clientId

string · uuid · required

Unique identifier for the client

Example: 550e8400-e29b-41d4-a716-446655440000

firstname

string · required

Client's first name

Example: John

lastname

string · required

Client's last name

Example: Doe

emailaddress

string · email · required

Client's email address

Example: john.doe@example.com

phone

string · required

Client's phone number

Example: +14165551234

notes

string

Notes about the client

object

longitude

number

Longitude coordinate

latitude

number

Latitude coordinate

externalClientId

string

External system identifier

Example: ext-12345

object

Additional external data as key-value pairs

Example: {"source":"external-system","customField":"value","syncedAt":"2026-01-09"}

CreateClientRequest

firstname

string · minLength: 1 · required

Client's first name

Example: John

lastname

string · minLength: 1 · required

Client's last name

Example: Doe

emailaddress

string · email · required

Client's email address (will be converted to lowercase)

Example: john.doe@example.com

phone

string · required

Phone number in E.164 format without spaces

Example: +14165551234

notes

string

Notes about the client

Example: Prefers morning appointments

object

longitude

number · min: -180 · max: 180

Longitude coordinate

Example: -79.3832

latitude

number · min: -90 · max: 90

Latitude coordinate

Example: 43.6532

externalClientId

string

External system identifier

Example: ext-12345

object

Additional external data as key-value pairs

Example: {"source":"external-system","customField":"value","syncedAt":"2026-01-09"}

PaginatedClientsResponse

success

boolean · enum · required

Indicates the request was successful

Enum values:

object[] · required

Array of items for the current page. The length may be less than the requested 'limit' due to filtering or data availability.

object · required

UpdateClientRequest

clientId

string · uuid

MarketBox client ID

Example: 550e8400-e29b-41d4-a716-446655440000

externalClientId

string

External system's client ID. Either clientId or externalClientId must be provided.

Example: ext-client-123

firstname

string · minLength: 1

Client's first name

Example: Jane

lastname

string · minLength: 1

Client's last name

Example: Smith

emailaddress

string · email

Client's email address (will be converted to lowercase)

Example: jane.smith@example.com

phone

string

Phone number in E.164 format without spaces

Example: +14165559999

notes

string | null

Notes about the client. Set to null to clear existing notes.

Example: Prefers afternoon appointments

object

longitude

number · min: -180 · max: 180

Longitude coordinate

Example: -79.3832

latitude

number · min: -90 · max: 90

Latitude coordinate

Example: 43.6532

object

Additional external data as key-value pairs

Example: {"source":"external-system","customField":"value","syncedAt":"2026-01-09"}

MarketBox API

Schemas

TimeSlotsRequest

billingId

string · required

The end user's unique identifier used for billing

Example: eahu28d-2ff3-4b91-8c4f-dj9928sjsd87d

targetGeoLocation

number[] · required

The latitude and longitude coordinates of where the service will take place [latitude, longitude]

Example: [28.23068,-81.334973]

targetServiceDurationMins

number · (mins) · required

The duration of the service in minutes

Example: 60

object[] · required

List of providers, each with their providerId, maxTravelTimeMins, bookings, and availability.

lookAheadStartDate

string · ISO-8601

The date to begin the look-ahead period. By default, the date and time of the request is used.

Example: 2024-12-01T00:00:00-05:00

Default: date of the request

lookAheadDays

integer

The number of days to search ahead from the lookAheadStartDate. Defaults to 7 days and cannot exceed a maximum of 7 days.

Example: 7

Default: 7

travelTimeType

string · enum

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.

Enum values:

rounded

raw

Example: raw

Default: rounded

preferredTimeSlotThresholdMins

integer

The maximum travel time threshold for a preferred time slot. Defaults to 5 minutes.

Example: 10

Default: 5

distanceUnit

string · enum

The unit for travel distance in the response. Defaults to kilometers.

Enum values:

Example: mi

Default: km

minBookingNoticeMins

number · (mins)

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.

Example: 60

Default: 0

emptyDayAnchorTime

string · (HH:MM)

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.

Example: 14:00

Default: first and last available slot of a schedule's time range

preferredDays

number[]

Specifies the preferred days of the week for time slots. Days are represented numerically, where 0 = Sunday and 6 = Saturday

Example: [1,2,3,4,5]

object[]

Specifies preferred time ranges for time slots

order

string · enum

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.

Enum values:

mustBeFirst

mustBeLast

Example: mustBeFirst

maxNumberOfBookingsPerDay

number

Maximum number of bookings for a single day

Example: 5

TimeSlotsResponse

status

number · required

message

string · required

object[] · required

List of generated suggested time slot objects

errors

string[]

Array of error messages for individual providers. Errors for one provider do not prevent attempts for other providers.

WhoIsAvailableRequest

billingId

string · required

The end user's unique identifier used for billing

Example: eahu28d-2ff3-4b91-8c4f-dj9928sjsd87d

targetGeoLocation

number[] · required

The latitude and longitude coordinates of where the service will take place [latitude, longitude]. This is not required if a valid companyLocationId is provided.

Example: [28.23068,-81.334973]

targetServiceId

string · uuidv4 · required

The ID for the service saved in MarketBox.

Example: f7ed7ed4-9fbe-4d6d-9a57-57175d5f9adb

companyLocationId

string · uuidv4

The ID for the company location saved in MarketBox. This value will override the targetGeoLocation.

Example: 0adfb507-f7bf-47e5-8d31-5c7ed2bd73f6

bookingType

string · enum

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`.

Enum values:

single

recurring

Example: single

Default: single

startDateAndTime

string · ISO-8601

This is the date range AND time range of when the "Who is available" API will generate suggested time slots for.

Example: 2025-01-01T00:00:00-05:00

Default: date of the request

endDateAndTime

string · ISO-8601

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.

Example: 2025-01-07T20:00:00-05:00

Default: 7 days from the `startDateAndTime`

daysOfWeek

number[]

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.

Example: [1,2,3,4,5]

Default: [0,1,2,3,4,5,6]

skills

string[]

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).

Example: ["5efe490b-ea04-439d-89ba-24976dcac796"]

rrule

string

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.

Example: FREQ=WEEKLY;INTERVAL=1;BYDAY=TU,SA,SU

Default: FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR,SA,SU

travelTimeType

string · enum

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.

Enum values:

rounded

raw

Example: raw

Default: rounded

minBookingNoticeMins

number · (mins)

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.

Example: 60

Default: 0

preferredTimeSlotThresholdMins

integer

The maximum travel time threshold for a preferred time slot. Defaults to 5 minutes.

Example: 10

Default: 5

distanceUnit

string · enum

The unit for travel distance in the response. Defaults to kilometers.

Enum values:

Example: mi

Default: km

WhoIsAvailableResponse

status

number · required

message

string · required

object[] · required

List of generated suggested time slot objects

errors

string[]

Array of error messages for individual providers. Errors for one provider do not prevent attempts for other providers.

WhoIsAvailableRecurringResponse

status

number · required

message

string · required

object[] · required

List of generated sets of suggested time slots

errors

string[]

Array of error messages for individual providers. Errors for one provider do not prevent attempts for other providers.

ClustersUsageResponse

totalRequests

integer

Total number of requests made.

Example: 850

totalTimeSlotsGenerated

integer

Total number of time slots generated.

Example: 1125

totalBookings

integer

Total number of provider bookings provided in the requests.

Example: 2200

avgProvidersPerRequest

number · float

Average number of providers per request.

Example: 6

object[]

Breakdown of usage by billing ID.

startDate

string · date

Start date for the usage data range.

Example: 2025-01-01

endDate

string · date

End date for the usage data range.

Example: 2025-01-15

BaseService

name

string · required

desc

string · required

categoryId

string

categoryName

string

minutes

integer

price

number

active

boolean

deleted

boolean

object[]

ServiceResponse

name

string · required

desc

string · required

id

string · required

createdAt

string · date-time · required

updatedAt

string · date-time · required

categoryId

string

categoryName

string

minutes

integer

price

number

active

boolean

deleted

boolean

object[]

PictureObject

Signed URL for profile picture with expiration

url

string · uri · required

Signed S3 URL for the provider picture

expiresAt

string · date-time · required

ISO 8601 timestamp when the signed URL expires

ProviderService

id

string · required

name

string · required

object[]

SkillResponse

id

string · required

name

string · required

ProviderResponse

providerId

string · required

createdAt

string · date-time · required

updatedAt

string · date-time · required

firstname

string

lastname

string

emailaddress

string · email

phone

string

timezone

string

bio

string

object

Signed URL for profile picture with expiration

offersMobileServices

boolean

active

boolean

deleted

boolean

ratingstarsavg

number

Average rating in stars (formatted to 2 decimal places)

Example: 4.35

numberofratings

integer

offersVirtualServices

boolean

maxTravelTime

integer

Maximum travel time allowed between bookings in minutes

Example: 30

externalId

string

External system identifier

Example: ext-12345

object

Additional external data as key-value pairs

Example: {"source":"external-system","customField":"value","syncedAt":"2026-01-09"}

object[]

Serivces provided by the provider

Example: [{"id":"service-uuid-1","name":"Haircut","locations":[{"id":"loc-1","name":"Downtown Office"}]}]

object[]

Skills of the provider

Example: [{"id":"skill-1","name":"Advanced Color Techniques"},{"id":"skill-2","name":"Balayage Specialist"}]

OrderAddress

addressOneLine

string · minLength: 2 · required

Full address

Example: 100 Yonge street, Toronto, ON M1T 3N3, Canada

state

string · minLength: 1

State code or province code

Example: FL

country

string · minLength: 1

Country name

Example: Canada

countryCode

string · minLength: 2

Country code

Example: CA

postalCode

string · minLength: 1

Zip code or postal code

Example: 94043

latitude

number · min: -90 · max: 90

Latitude coordinate

Example: 49.2827

longitude

number · min: -180 · max: 180

Longitude coordinate

Example: -123.1207

OrderResponse

orderId

string · uuid · required

serviceName

string · required

clientId

string · required

providerId

string · required

createdAt

string · date-time · required

updatedAt

string · date-time · required

type

string | null · enum

Enum values:

SINGLE

PACKAGE

RECURRING

GROUP

orderNumber

integer

currency

string

status

string | null · enum

Enum values:

CONFIRMED

PAID

UNPAID

PAIDBYPKGCRE

object

externalOrderId

string

object

Additional external data as key-value pairs

Example: {"source":"external-system","customField":"value","syncedAt":"2026-01-09"}

orderTotal

number

BookingResponse

bookingId

string · uuid · required

serviceName

string · required

orderId

string · required

providerId

string · required

clientId

string · required

startDateAndTime

string · date-time · required

Booking date and time with timezone offset

Example: 2025-12-15T16:30:00-05:00

durationMins

integer · required

serviceId

string

serviceLocation

string

status

string | null · enum

Enum values:

SCHEDULED

ARRIVED

COMPLETED

CANCELLED

NOSHOW

timezone

string

orderType

string | null · enum

Enum values:

SINGLE

PACKAGE

RECURRING

GROUP

externalBookingId

string

object

Additional external data as key-value pairs

Example: {"source":"external-system","customField":"value","syncedAt":"2026-01-09"}

createdAt

string · date-time

updatedAt

string · date-time

CreateOrderResponse

object · required

ClientRequest

firstName

string · minLength: 1 · required

Client's first name

lastName

string · minLength: 1 · required

Client's last name

email

string · email · required

Client's email address

Example: client@example.com

phone

string · required

Phone number in E.164 format without spaces

Example: +17069805493

PaymentDetails

orderTotal

number · required

currency

string · minLength: 3 · maxLength: 3 · pattern: ^[A-Z]{3}$ · required

ISO 4217 currency code

Example: USD

CreateOrderRequest

reservedSlotId

string · required

Reserved slot ID obtained from POST /reservedslots endpoint

Example: 550e8400-e29b-41d4-a716-446655440000

serviceId

string · uuid · required

Service unique identifier

Example: 123e4567-e89b-12d3-a456-426614174000

object · required

object

externalOrderId

string

Example: 1234567879abcdEF_-

externalBookingId

string

This is the unique identifier of the booking inside your system – MarketBox will store and map this internally

Example: 1234567879abcdEF_-

object

Additional external data for the order

Example: {"source":"external-system","customField":"value","syncedAt":"2026-01-09"}

object

Additional external data for the booking

Example: {"source":"external-system","customField":"value","syncedAt":"2026-01-09"}

sendProviderEmailNotification

boolean

Default: true

UpdateBookingResponse

bookingId

string · required

updatedAt

string · date-time · required

externalBookingId

string

status

string · enum

Enum values:

SCHEDULED

ARRIVED

COMPLETED

CANCELLED

NOSHOW

startDateAndTime

string · date-time

Booking date and time with timezone offset

Example: 2025-12-15T16:30:00-05:00

UpdateBookingRequest

bookingId

string

MarketBox booking id of the booking to be updated

Example: 550e8400-e29b-41d4-a716-446655440000

externalBookingId

string

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

Example: 1234567879abcdEF_-

startDateAndTime

string · date-time

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

string

IANA timezone identifier (required if startDateAndTime is provided)

Example: America/New_York

status

string · enum

Booking status. Provide this value when you want to update the status of booking.

Enum values:

SCHEDULED

ARRIVED

COMPLETED

CANCELLED

NOSHOW

Example: SCHEDULED

CreateReservedSlotResponse

reservedSlotId

string · required

Unique identifier (UUID) for the reserved slot mapping record

Example: 550e8400-e29b-41d4-a716-446655440000

Address

street

string · minLength: 1 · required

Street address

Example: 602 Victor way

city

string · minLength: 1 · required

Name of the city

Example: Mountain View

state

string · minLength: 1 · required

State code or province code

Example: FL

country

string · minLength: 1 · required

Country name

Example: Canada

postalCode

string · minLength: 1 · required

Zip code or postal code

Example: 94043

latitude

number · min: -90 · max: 90 · required

Latitude coordinate

Example: 49.2827

longitude

number · min: -180 · max: 180 · required

Longitude coordinate

Example: -123.1207

ServiceLocation

Provide either the address object OR a companyLocationId; if both are provided, the companyLocationId will override the address

object

companyLocationId

string · uuid

Unique identifier of the company location in MarketBox. If address is not provided, companyLocationId must be provided.

Example: 89baf2e3-604d-4d98-8d45-75203bd3e93b

CreateReservedSlotRequest

providerId

string · uuid · required

Provider unique identifier

Example: 123e4567-e89b-12d3-a456-426614174000

serviceId

string · uuid · required

Service unique identifier

Example: 123e4567-e89b-12d3-a456-426614174000

object · required

Provide either the address object OR a companyLocationId; if both are provided, the companyLocationId will override the address

Example: {"address":{"street":"220 Castlefrank Rd","city":"Stittsville","state":"ON","country":"Canada","postalCode":"K2L 1T5","latitude":45.2867248,"longitude":-75.8836231}}

timezone

string · required

IANA timezone

Example: America/Vancouver

startDateAndTime

string · date-time · required

Booking date and time with timezone offset

Example: 2025-12-15T16:30:00-05:00

reservationTimeoutMins

integer · min: 5 · max: 1440 · required

The number of minutes MarketBox will hold the reservation before releasing it.

ClientAddress

street

string · minLength: 1

Street address

Example: 123 Main St

city

string · minLength: 1

City name

Example: Toronto

state

string · minLength: 1

State or province code

Example: ON

country

string · minLength: 1

Country name

Example: Canada

postalcode

string · minLength: 1

Postal code or ZIP code

Example: M5H 2N2

ClientResponse

clientId

string · uuid · required

Unique identifier for the client

Example: 550e8400-e29b-41d4-a716-446655440000

firstname

string · required

Client's first name

Example: John

lastname

string · required

Client's last name

Example: Doe

emailaddress

string · email · required

Client's email address

Example: john.doe@example.com

phone

string · required

Client's phone number

Example: +14165551234

notes

string

Notes about the client

object

longitude

number

Longitude coordinate

latitude

number

Latitude coordinate

externalClientId

string

External system identifier

Example: ext-12345

object

Additional external data as key-value pairs

Example: {"source":"external-system","customField":"value","syncedAt":"2026-01-09"}

CreateClientRequest

firstname

string · minLength: 1 · required

Client's first name

Example: John

lastname

string · minLength: 1 · required

Client's last name

Example: Doe

emailaddress

string · email · required

Client's email address (will be converted to lowercase)

Example: john.doe@example.com

phone

string · required

Phone number in E.164 format without spaces

Example: +14165551234

notes

string

Notes about the client

Example: Prefers morning appointments

object

longitude

number · min: -180 · max: 180

Longitude coordinate

Example: -79.3832

latitude

number · min: -90 · max: 90

Latitude coordinate

Example: 43.6532

externalClientId

string

External system identifier

Example: ext-12345

object

Additional external data as key-value pairs

Example: {"source":"external-system","customField":"value","syncedAt":"2026-01-09"}

PaginatedClientsResponse

success

boolean · enum · required

Indicates the request was successful

Enum values:

object[] · required

Array of items for the current page. The length may be less than the requested 'limit' due to filtering or data availability.

object · required

UpdateClientRequest

clientId

string · uuid

MarketBox client ID

Example: 550e8400-e29b-41d4-a716-446655440000

externalClientId

string

External system's client ID. Either clientId or externalClientId must be provided.

Example: ext-client-123

firstname

string · minLength: 1

Client's first name

Example: Jane

lastname

string · minLength: 1

Client's last name

Example: Smith

emailaddress

string · email

Client's email address (will be converted to lowercase)

Example: jane.smith@example.com

phone

string

Phone number in E.164 format without spaces

Example: +14165559999

notes

string | null

Notes about the client. Set to null to clear existing notes.

Example: Prefers afternoon appointments

object

longitude

number · min: -180 · max: 180

Longitude coordinate

Example: -79.3832

latitude

number · min: -90 · max: 90

Latitude coordinate

Example: 43.6532

object

Additional external data as key-value pairs

Example: {"source":"external-system","customField":"value","syncedAt":"2026-01-09"}

Schemas

TimeSlotsRequest

The end user's unique identifier used for billing

The latitude and longitude coordinates of where the service will take place [latitude, longitude]

The duration of the service in minutes

List of providers, each with their providerId, maxTravelTimeMins, bookings, and availability.

The date to begin the look-ahead period. By default, the date and time of the request is used.

The number of days to search ahead from the lookAheadStartDate. Defaults to 7 days and cannot exceed a maximum of 7 days.

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.

The maximum travel time threshold for a preferred time slot. Defaults to 5 minutes.

The unit for travel distance in the response. Defaults to kilometers.

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.

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.

Specifies the preferred days of the week for time slots. Days are represented numerically, where 0 = Sunday and 6 = Saturday

Specifies preferred time ranges for time slots

Maximum number of bookings for a single day

TimeSlotsResponse

List of generated suggested time slot objects

WhoIsAvailableRequest

The end user's unique identifier used for billing

The latitude and longitude coordinates of where the service will take place [latitude, longitude]. This is not required if a valid companyLocationId is provided.

The ID for the service saved in MarketBox.

The ID for the company location saved in MarketBox. This value will override the targetGeoLocation.

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.

This is the date range AND time range of when the "Who is available" API will generate suggested time slots for.

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).

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.

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.

The maximum travel time threshold for a preferred time slot. Defaults to 5 minutes.

The unit for travel distance in the response. Defaults to kilometers.

WhoIsAvailableResponse

List of generated suggested time slot objects

WhoIsAvailableRecurringResponse

List of generated sets of suggested time slots

ClustersUsageResponse

BaseService

ServiceResponse

PictureObject

ProviderService

SkillResponse

ProviderResponse

OrderAddress

OrderResponse

BookingResponse

CreateOrderResponse

ClientRequest

PaymentDetails

CreateOrderRequest

UpdateBookingResponse

UpdateBookingRequest

CreateReservedSlotResponse

Address

ServiceLocation

CreateReservedSlotRequest

ClientAddress

ClientResponse

CreateClientRequest

PaginatedClientsResponse

UpdateClientRequest

Schemas

TimeSlotsRequest

The end user's unique identifier used for billing

The latitude and longitude coordinates of where the service will take place [latitude, longitude]

The duration of the service in minutes

List of providers, each with their providerId, maxTravelTimeMins, bookings, and availability.

The date to begin the look-ahead period. By default, the date and time of the request is used.

The number of days to search ahead from the lookAheadStartDate. Defaults to 7 days and cannot exceed a maximum of 7 days.

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.

The maximum travel time threshold for a preferred time slot. Defaults to 5 minutes.

The unit for travel distance in the response. Defaults to kilometers.

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.

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.

Specifies the preferred days of the week for time slots. Days are represented numerically, where 0 = Sunday and 6 = Saturday

Specifies preferred time ranges for time slots

Maximum number of bookings for a single day

TimeSlotsResponse

List of generated suggested time slot objects

WhoIsAvailableRequest

The end user's unique identifier used for billing

The latitude and longitude coordinates of where the service will take place [latitude, longitude]. This is not required if a valid companyLocationId is provided.

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`.

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`.