> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomarketbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Find suppliers + suggested/open slots for a service, location and window

> The main "when can this be booked" call. Returns two parallel, slot-centric arrays: `timeSlots`, the engine's ranked suggestions with travel between jobs taken into account, and `openSlots`, every free interval at `interval` granularity with no ranking. Show `timeSlots` to clients and keep `openSlots` for a "more times" view; they overlap by design. Identify the place with `locationId`, or with both `lat` and `lng` for in-home and travel-zone discovery — one or the other is required. `durationMinutes` is honoured only for FLEXIBLE offerings and is otherwise ignored in favour of the offering's own duration.

Failures come back inside a 200. The body carries `status` and an `errors` array, so an empty `timeSlots` with a non-empty `errors` means the search broke, not that nobody is free — check `errors` before telling a client there is no availability.

Setting `bookingType: "recurring"` changes what `timeSlots` contains: recurring time patterns rather than individual slots, so do not parse the two the same way. That branch adds two requirements, each a 400 and each guarding an input that used to return silence instead of an error — `rrule` is required, and it must carry a bounded positive COUNT (e.g. "FREQ=WEEKLY;BYDAY=TU;COUNT=3"). `lookAheadStartDate` is any ISO-8601 instant: a "Z" suffix and a numeric offset like "-04:00" are equally valid.

Every response carries a `searchId` (also the `X-MB-Search-Id` header) and `suppliers`, each supplier that appears in the slots with its 0-based `position` by first appearance. Keep `searchId` for the session if you want attribution. Two optional request headers tag the search for insights and are never acted on: `X-MB-Session-Key` (an opaque key you choose, up to 64 characters) and `X-MB-Client-Kind` (`browser`, `server`, `monitor` or `loadtest`).



## OpenAPI

````yaml /api-reference/openapi.json post /v1/projects/{projectId}/availability/search
openapi: 3.0.0
info:
  title: MarketBox 2.0 Open API
  version: 1.0.0
  description: >-
    The MarketBox public API for building booking experiences. Core model:
    create an order, then draw its order items down into bookings. Single
    bookings reference an order item per service line; package bookings draw one
    PACKAGE item down across N sessions. To schedule a package, build a slate
    (POST /availability/package-slate) and book it by slateId (POST
    /orders/{orderId}/package-bookings). See the guides for end-to-end
    walkthroughs.
  contact:
    name: MarketBox support
servers:
  - url: https://apiv2.gomarketbox.com
    description: MarketBox Open API
security:
  - ApiKeyAuth: []
paths:
  /v1/projects/{projectId}/availability/search:
    post:
      tags:
        - Availability
      summary: Find suppliers + suggested/open slots for a service, location and window
      description: >-
        The main "when can this be booked" call. Returns two parallel,
        slot-centric arrays: `timeSlots`, the engine's ranked suggestions with
        travel between jobs taken into account, and `openSlots`, every free
        interval at `interval` granularity with no ranking. Show `timeSlots` to
        clients and keep `openSlots` for a "more times" view; they overlap by
        design. Identify the place with `locationId`, or with both `lat` and
        `lng` for in-home and travel-zone discovery — one or the other is
        required. `durationMinutes` is honoured only for FLEXIBLE offerings and
        is otherwise ignored in favour of the offering's own duration.


        Failures come back inside a 200. The body carries `status` and an
        `errors` array, so an empty `timeSlots` with a non-empty `errors` means
        the search broke, not that nobody is free — check `errors` before
        telling a client there is no availability.


        Setting `bookingType: "recurring"` changes what `timeSlots` contains:
        recurring time patterns rather than individual slots, so do not parse
        the two the same way. That branch adds two requirements, each a 400 and
        each guarding an input that used to return silence instead of an error —
        `rrule` is required, and it must carry a bounded positive COUNT (e.g.
        "FREQ=WEEKLY;BYDAY=TU;COUNT=3"). `lookAheadStartDate` is any ISO-8601
        instant: a "Z" suffix and a numeric offset like "-04:00" are equally
        valid.


        Every response carries a `searchId` (also the `X-MB-Search-Id` header)
        and `suppliers`, each supplier that appears in the slots with its
        0-based `position` by first appearance. Keep `searchId` for the session
        if you want attribution. Two optional request headers tag the search for
        insights and are never acted on: `X-MB-Session-Key` (an opaque key you
        choose, up to 64 characters) and `X-MB-Client-Kind` (`browser`,
        `server`, `monitor` or `loadtest`).
      parameters:
        - schema:
            type: string
            minLength: 1
            description: >-
              The project (tenant) that owns the resource. Every resource in
              this API is scoped to a project, and your API key is restricted to
              the projects it was issued for — a project outside that scope
              returns 403.
            example: prj_01kv60qgnef2kt3pvqgwmkbzfr
          required: true
          description: >-
            The project (tenant) that owns the resource. Every resource in this
            API is scoped to a project, and your API key is restricted to the
            projects it was issued for — a project outside that scope returns
            403.
          name: projectId
          in: path
      requestBody:
        description: Service + location + window
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                serviceId:
                  type: string
                  minLength: 1
                offeringId:
                  type: string
                  minLength: 1
                locationId:
                  type: string
                lat:
                  anyOf:
                    - type: string
                    - type: number
                lng:
                  anyOf:
                    - type: string
                    - type: number
                durationMinutes:
                  type: integer
                  minimum: 0
                  exclusiveMinimum: true
                lookAheadStartDate:
                  type: string
                lookAheadDays:
                  type: integer
                  minimum: 0
                  exclusiveMinimum: true
                timezone:
                  type: string
                  minLength: 1
                distanceUnit:
                  type: string
                  enum:
                    - km
                    - mi
                order:
                  type: string
                  nullable: true
                  enum:
                    - mustBeFirst
                    - mustBeLast
                    - null
                preferredDays:
                  type: array
                  nullable: true
                  items:
                    type: integer
                preferredTimes:
                  type: array
                  nullable: true
                  items:
                    type: object
                    properties:
                      startTime:
                        type: string
                      endTime:
                        type: string
                    required:
                      - startTime
                      - endTime
                emptyDayAnchorTime:
                  type: string
                  nullable: true
                maxNumberOfBookingsPerDay:
                  type: integer
                  nullable: true
                  minimum: 0
                  exclusiveMinimum: true
                preferredTimeSlotThresholdMins:
                  type: integer
                  minimum: 0
                timeSuggestionsLimit:
                  type: integer
                  minimum: 0
                  exclusiveMinimum: true
                sortBy:
                  type: string
                  enum:
                    - leastTravelTime
                    - nearestDate
                skills:
                  type: array
                  items:
                    type: string
                    minLength: 1
                  description: >-
                    Supplier skill IDs. A supplier must hold ALL of them to be
                    considered. Omit for no skill filter.
                  example:
                    - skl_01kv60qg12e82acr78edfnjhvv
                interval:
                  type: integer
                  minimum: 0
                  exclusiveMinimum: true
                language:
                  type: string
                  description: >-
                    Preferred language for localized skill and offering NAMES.
                    Not a filter — it never affects which suppliers or services
                    match, and has no effect on this response.
                bookingType:
                  type: string
                  enum:
                    - single
                    - recurring
                  default: single
                rrule:
                  type: string
                endDate:
                  type: string
                daysOfWeek:
                  type: array
                  items:
                    type: integer
                    minimum: 0
                    maximum: 6
                package:
                  type: boolean
                consistencyAsPercentage:
                  type: boolean
                fromMb:
                  type: boolean
              required:
                - serviceId
                - offeringId
      responses:
        '200':
          description: Suggested slots + open slots
          content:
            application/json:
              schema:
                type: object
                properties:
                  searchId:
                    type: string
                    description: >-
                      The id of this search, also returned as the
                      `X-MB-Search-Id` header. Every page of a paginated search
                      carries the same id (the cursor keeps it). Keep it for the
                      session if you want attribution: pass it back as
                      `searchId` when the client books, and in the
                      `search.rendered` event when you report what you showed.
                    example: srch_01k7q3x9h4e8rb2d6m0z5a7c1n
                  status:
                    type: string
                  timeSlots:
                    type: array
                    items:
                      nullable: true
                    description: >-
                      Suggested slots, or recurring time patterns when
                      bookingType=recurring. Each entry carries
                      `timeSlotDateAndTime` (the slot instant rendered in the
                      response `timezone`, with that zone's offset at that
                      instant — R-30) and `timeSlotStartUtc` (the same instant
                      in UTC, `Z` — R-31, always present, always the same
                      instant as `timeSlotDateAndTime`). Prefer
                      `timeSlotStartUtc` as the booking anchor.
                  openSlots:
                    type: array
                    items:
                      nullable: true
                    description: >-
                      Every free interval at `interval` granularity, unranked.
                      Each entry carries `timeSlotDateAndTime` (the slot instant
                      rendered in the response `timezone`, with that zone's
                      offset at that instant — R-30) and `timeSlotStartUtc` (the
                      same instant in UTC, `Z` — R-31, always present, always
                      the same instant as `timeSlotDateAndTime`). Prefer
                      `timeSlotStartUtc` as the booking anchor.
                  timezone:
                    type: string
                    description: >-
                      The IANA timezone actually used to render
                      `timeSlotDateAndTime` and bucket days (R-32) — the request
                      `timezone`, or the project default.
                    example: America/Chicago
                  supplierZones:
                    type: object
                    additionalProperties:
                      type: string
                    description: >-
                      IANA profile zone of each supplier that appears in
                      `timeSlots`/`openSlots`, keyed by supplierId. Use it as
                      the R-10 fallback for `bookingTz` on a virtual booking
                      (location zone wins when there is one). Absent key = the
                      supplier has no profile zone; use the project default.
                    example:
                      sup_01abc: America/Toronto
                  engineEnabled:
                    type: boolean
                    description: >-
                      False when Smart Clusters is switched off for this
                      project. The engine then does not run, so `timeSlots` is
                      empty because it was not computed, not because nobody is
                      free; `openSlots` is unaffected. Check it before telling a
                      client there is no availability.
                    example: true
                  suppliers:
                    type: array
                    items:
                      type: object
                      properties:
                        supplierId:
                          type: string
                          example: sup_01kv60qh3m7wznp8s0d2rk9abc
                        position:
                          type: integer
                          minimum: 0
                          description: >-
                            0-based rank of this entry in the order the response
                            returned it. Paged results continue the count across
                            pages of the same `searchId`, so the first entry of
                            page 2 is numbered after the last of page 1.
                          example: 0
                      required:
                        - supplierId
                        - position
                      description: >-
                        Each supplier that appears in `timeSlots` or
                        `openSlots`, with its `position` — the 0-based rank of
                        its FIRST slot in the returned order (`timeSlots` first,
                        then `openSlots`). Ordered by position. The shape
                        `search.rendered` takes.
                  errors:
                    type: array
                    items:
                      type: string
                required:
                  - searchId
                  - status
                  - timeSlots
                  - openSlots
                  - suppliers
                  - errors
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: API key cannot access this project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: >-
            No offering for this serviceId/offeringId, or no location for this
            locationId (sent without lat/lng); the message names the id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
components:
  schemas:
    ErrorMessage:
      type: object
      properties:
        code:
          type: string
          description: Stable machine-readable error code, e.g. NOT_FOUND.
        message:
          type: string
          description: Human-readable description of what went wrong.
        statusCode:
          type: integer
          description: The HTTP status code of this response.
        requestId:
          type: string
          description: >-
            The id of this request, also returned as the X-Request-Id header.
            Quote it in a support ticket.
      required:
        - code
        - message
        - statusCode
        - requestId
      example:
        code: NOT_FOUND
        message: Booking not found
        statusCode: 404
        requestId: a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API key minted in the MarketBox dashboard. Scope is restricted to the
        projects you select at creation time. Every route needs the key's
        standard API access (`*`) except `POST /v1/projects/{projectId}/events`,
        which needs `events:write`; a key without `*` is refused with 403
        `CAPABILITY_NOT_GRANTED`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.