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

# Supplier-centric availability: paginated suppliers, each with open slots grouped by day

> Returns availability grouped by supplier — a paginated list of suppliers, each with its full profile (same shape as GET /suppliers) and its open slots bucketed by local day. Use this to render a wall of supplier cards with bookable times, instead of the flat, slot-centric arrays /availability/search returns. Provide serviceId + offeringId and either locationId or both lat and lng. Returns regular-interval open slots only — no clustered/travel-optimized suggestions and no recurring patterns (use /availability/search for those). Suppliers that match the service and location but have no availability in the window are still returned, with days: []. Paginate with limit (max 50) + the opaque cursor; nextCursor is null on the last page. Each slot carries a UTC anchor (startUtc/endUtc) plus *Local strings rendered in the request timezone.

Every page carries the same `searchId` (also the `X-MB-Search-Id` header; the cursor keeps it) and each supplier its 0-based `position`, continuous across pages. 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/suppliers
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/suppliers:
    post:
      tags:
        - Availability
      summary: >-
        Supplier-centric availability: paginated suppliers, each with open slots
        grouped by day
      description: >-
        Returns availability grouped by supplier — a paginated list of
        suppliers, each with its full profile (same shape as GET /suppliers) and
        its open slots bucketed by local day. Use this to render a wall of
        supplier cards with bookable times, instead of the flat, slot-centric
        arrays /availability/search returns. Provide serviceId + offeringId and
        either locationId or both lat and lng. Returns regular-interval open
        slots only — no clustered/travel-optimized suggestions and no recurring
        patterns (use /availability/search for those). Suppliers that match the
        service and location but have no availability in the window are still
        returned, with days: []. Paginate with limit (max 50) + the opaque
        cursor; nextCursor is null on the last page. Each slot carries a UTC
        anchor (startUtc/endUtc) plus *Local strings rendered in the request
        timezone.


        Every page carries the same `searchId` (also the `X-MB-Search-Id`
        header; the cursor keeps it) and each supplier its 0-based `position`,
        continuous across pages. 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 (+ pagination)
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                serviceId:
                  type: string
                  minLength: 1
                  description: The service to find supplier availability for.
                  example: srv_01kv60qg12e82acr78edfnjhvv
                offeringId:
                  type: string
                  minLength: 1
                  description: The specific offering (variant) of the service being booked.
                  example: off_01kv60qge5eh59ap0gw0pqrrys
                locationId:
                  type: string
                  description: >-
                    Where the service is delivered. Provide this OR both `lat`
                    and `lng`. A stored location id (PHYSICAL / VIRTUAL /
                    TRAVEL_ZONE).
                  example: loc_01kv60qh3m7wznp8s0d2rk9abc
                lat:
                  anyOf:
                    - type: string
                    - type: number
                  description: >-
                    Client/service latitude. Provide `lat` + `lng` together as
                    an alternative to `locationId` (in-home / travel-zone
                    discovery).
                  example: 41.881832
                lng:
                  anyOf:
                    - type: string
                    - type: number
                  description: Client/service longitude — see `lat`.
                  example: -87.623177
                durationMinutes:
                  type: integer
                  minimum: 0
                  exclusiveMinimum: true
                  description: >-
                    Override the booked duration (minutes). Only honoured for
                    FLEXIBLE offerings; otherwise the offering’s own duration is
                    used.
                  example: 60
                lookAheadStartDate:
                  type: string
                  description: >-
                    Start of the search window (ISO-8601). Defaults to now.
                    Slots before this instant are excluded.
                  example: '2025-07-07T00:00:00-05:00'
                lookAheadDays:
                  type: integer
                  minimum: 0
                  exclusiveMinimum: true
                  description: >-
                    How many days forward to search from the start. Defaults to
                    the engine’s configured window.
                  example: 7
                timezone:
                  type: string
                  minLength: 1
                  description: >-
                    IANA timezone governing day bucketing and every `*Local`
                    field in the response (R-32). Defaults to the project
                    timezone.
                  example: America/Chicago
                distanceUnit:
                  type: string
                  enum:
                    - km
                    - mi
                  description: Unit for travel/distance calculations.
                  example: km
                interval:
                  type: integer
                  minimum: 0
                  exclusiveMinimum: true
                  description: >-
                    Open-slot granularity in minutes (e.g. 15 → :00 / :15 / :30
                    / :45). Defaults to 15.
                  example: 15
                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.
                  example: en
                limit:
                  type: integer
                  minimum: 1
                  maximum: 50
                  default: 20
                  description: >-
                    Suppliers per page (1–50, default 20). Kept small because
                    each supplier’s availability is computed on demand.
                  example: 20
                cursor:
                  type: string
                  description: >-
                    Opaque pagination token from a previous response’s
                    `nextCursor`. Omit for the first page.
                preferredTimes:
                  type: array
                  nullable: true
                  items:
                    type: object
                    properties:
                      startTime:
                        type: string
                        description: Local time-of-day the window opens (HH:mm).
                        example: '17:00'
                      endTime:
                        type: string
                        description: Local time-of-day the window closes (HH:mm).
                        example: '20:00'
                    required:
                      - startTime
                      - endTime
                  description: >-
                    Time-of-day windows the caller would prefer sessions to fall
                    in (e.g. "after work"). Feeds the per-supplier match score —
                    a supplier with no availability inside these windows is
                    still returned, just ranked lower. Not a filter: no slot is
                    removed for falling outside them.
                  example:
                    - startTime: '17:00'
                      endTime: '20:00'
                daysOfWeek:
                  type: array
                  items:
                    type: integer
                    minimum: 0
                    maximum: 6
                  minItems: 1
                  maxItems: 7
                  description: >-
                    Weekdays the caller would prefer sessions to land on (0 =
                    Sunday … 6 = Saturday). On THIS route this is a ranking
                    preference, not a hard filter — unlike the same-named field
                    on /availability/package-slate, a weekday left out of this
                    list is never removed from a supplier's slots; it only
                    lowers that supplier's match score. At least one weekday is
                    required when this field is present — omit the field
                    entirely for "any day".
                  example:
                    - 1
                    - 3
                    - 5
                excludeDates:
                  type: array
                  items:
                    type: string
                    pattern: ^\d{4}-\d{2}-\d{2}$
                  maxItems: 90
                  description: >-
                    Local calendar dates (YYYY-MM-DD) that must not carry a
                    session — a holiday, a trip. Matched against each slot's own
                    local calendar date, not against a UTC instant. Pass each
                    date individually; there is no range form.
                  example:
                    - '2026-08-20'
                    - '2026-08-21'
                    - '2026-08-22'
                sessionsPerWeek:
                  type: integer
                  minimum: 1
                  maximum: 14
                  description: >-
                    How many sessions per week the caller wants to be able to
                    book with this supplier. On this route there is no package
                    and no session count to plan against, so this preference can
                    only ever feed the match score. On package-slate a package
                    supplies a creditCount, giving the planner an actual COUNT
                    to plan sessions against.
                  example: 3
              required:
                - serviceId
                - offeringId
      responses:
        '200':
          description: Suppliers, each with open slots grouped by day
          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
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        supplier:
                          type: object
                          properties:
                            supplierId:
                              type: string
                            firstName:
                              type: string
                            lastName:
                              type: string
                            email:
                              type: string
                            phone:
                              type: string
                            addressoneline:
                              type: string
                            longitude:
                              type: number
                            latitude:
                              type: number
                            city:
                              type: string
                            state:
                              type: string
                            country:
                              type: string
                            postalcode:
                              type: string
                            bio:
                              type: string
                            maxTravelTime:
                              type: number
                            externalId:
                              type: string
                            externalData:
                              type: object
                              additionalProperties:
                                nullable: true
                            active:
                              type: boolean
                            updatedAt:
                              type: string
                            timezone:
                              type: string
                              description: >-
                                The supplier's own IANA timezone. Absent when
                                none is set on the profile, in which case fall
                                back to the project's default timezone rather
                                than the caller's. Every `*Local` time this API
                                renders for this supplier is in this zone.
                              example: America/Toronto
                            avatarUrl:
                              type: string
                              nullable: true
                              format: uri
                            services:
                              type: array
                              items:
                                type: object
                                properties:
                                  serviceId:
                                    type: string
                                  name:
                                    type: object
                                    additionalProperties:
                                      type: string
                                required:
                                  - serviceId
                                  - name
                            skills:
                              type: array
                              items:
                                type: object
                                properties:
                                  skillId:
                                    type: string
                                  name:
                                    type: object
                                    additionalProperties:
                                      type: string
                                required:
                                  - skillId
                                  - name
                            locations:
                              type: array
                              items:
                                type: object
                                properties:
                                  locationId:
                                    type: string
                                  locationType:
                                    type: string
                                    enum:
                                      - PHYSICAL
                                      - VIRTUAL
                                      - TRAVEL_ZONE
                                  name:
                                    type: string
                                  country:
                                    type: string
                                    nullable: true
                                  state:
                                    type: string
                                    nullable: true
                                  city:
                                    type: string
                                    nullable: true
                                  addressOneLine:
                                    type: string
                                    nullable: true
                                  street:
                                    type: string
                                    nullable: true
                                  latitude:
                                    type: number
                                    nullable: true
                                  longitude:
                                    type: number
                                    nullable: true
                                  travelZoneType:
                                    type: string
                                    nullable: true
                                    enum:
                                      - CIRCULAR
                                      - DRAWN
                                      - null
                                required:
                                  - locationId
                                  - locationType
                                  - name
                            servedRegions:
                              type: array
                              items:
                                type: string
                              description: >-
                                The region paths this supplier is indexed under
                                — the SAME set the `country`/`state`/`city`
                                filter on `GET /suppliers` matches against, so a
                                supplier is returned by that filter exactly when
                                the query's path is in this list. Slug paths at
                                every hierarchy level, sorted: `ca/`, `ca/on/`,
                                `ca/on/toronto/`, `ca/on/scarborough/`. Derived
                                from the travel zones and physical locations on
                                their live schedules (see `locations`), resolved
                                to the locality, its borough and the wider
                                municipality. Empty when the supplier has no
                                live schedule with a geocodable zone. Region
                                rows are pruned by a daily sweep, so this can
                                lag a schedule's `endDate` by up to a day,
                                whereas `locations` is evaluated on every
                                request.
                              example:
                                - ca/
                                - ca/on/
                                - ca/on/scarborough/
                                - ca/on/toronto/
                            languages:
                              type: array
                              items:
                                type: string
                            locales:
                              type: array
                              items:
                                type: string
                            defaultLocale:
                              type: string
                          required:
                            - supplierId
                            - firstName
                            - lastName
                            - email
                            - active
                            - updatedAt
                            - avatarUrl
                            - services
                            - skills
                            - locations
                            - servedRegions
                            - languages
                            - locales
                          description: >-
                            The supplier, in the same enriched shape as `GET
                            /suppliers` (profile, `avatarUrl`, `services`,
                            `skills`, `locations`) — enough to render a card
                            without a follow-up call.
                        days:
                          type: array
                          items:
                            type: object
                            properties:
                              date:
                                type: string
                                description: >-
                                  Local calendar date (YYYY-MM-DD) in the
                                  request `timezone` — the day these slots fall
                                  on.
                                example: '2025-07-07'
                              slots:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    slotId:
                                      type: string
                                      description: >-
                                        Opaque id for this open slot. A slot is
                                        availability, not a hold — book it with
                                        the times below; it can be taken by
                                        another client until you do.
                                      example: 3f2504e0-4f89-41d3-9a0c-0305e82c3301
                                    startUtc:
                                      type: string
                                      description: >-
                                        Slot start as a UTC instant (ISO-8601,
                                        Z) — the engine's `timeSlotStartUtc`
                                        verbatim (R-31). Prefer this over
                                        `startLocal` as the booking start
                                        anchor.
                                      example: '2025-07-07T14:00:00.000Z'
                                    startLocal:
                                      type: string
                                      description: >-
                                        The slot start as a local clock in the
                                        request `timezone`, with that zone's
                                        offset at that instant (ISO-8601, R-30)
                                        — e.g. `2025-07-07T09:00:00-05:00`.
                                        Always denotes the same instant as
                                        `startUtc` (the engine's
                                        `timeSlotStartUtc`). For display.
                                      example: '2025-07-07T09:00:00-05:00'
                                    endUtc:
                                      type: string
                                      description: >-
                                        Slot end (start + the resolved service
                                        duration) as a UTC instant.
                                      example: '2025-07-07T14:30:00.000Z'
                                    endLocal:
                                      type: string
                                      description: >-
                                        Slot end rendered in the request
                                        `timezone`. For display.
                                      example: '2025-07-07T09:30:00-05:00'
                                  required:
                                    - slotId
                                    - startUtc
                                    - startLocal
                                    - endUtc
                                    - endLocal
                                description: >-
                                  Open slots on this day, ascending by
                                  `startUtc`.
                            required:
                              - date
                              - slots
                          description: >-
                            Days with open slots, ascending. Empty (`[]`) when
                            this supplier matches the service and location but
                            has no availability in the window.
                        availabilityMatch:
                          type: object
                          nullable: true
                          properties:
                            score:
                              type: number
                              description: >-
                                How well this supplier fits the schedule you
                                asked for, 0–1. The plain mean of the
                                `components` below — only the criteria you
                                actually sent are averaged, so sending one
                                preference does not cap every supplier at 0.25.
                                Unrounded. Rank suppliers by this WITHIN a page;
                                see the note on `availabilityMatch` about
                                paging.
                              example: 0.8035714285714286
                            components:
                              type: object
                              properties:
                                startDate:
                                  type: number
                                  description: >-
                                    How soon the supplier’s first open slot
                                    arrives after `lookAheadStartDate`, as `1 -
                                    (daysUntilFirstSlot / windowDays)`. 1 = free
                                    on day one. Present only when you sent
                                    `lookAheadStartDate`.
                                  example: 0.7142857142857143
                                timeOfDay:
                                  type: number
                                  description: >-
                                    Of the days this supplier has any
                                    availability, the fraction with at least one
                                    slot starting inside a `preferredTimes`
                                    window. Present only when you sent
                                    `preferredTimes`.
                                  example: 0.5
                                daysOfWeek:
                                  type: number
                                  description: >-
                                    Of the weekdays you asked for, the fraction
                                    the supplier can cover somewhere in the
                                    window. Present only when you sent
                                    `daysOfWeek`.
                                  example: 1
                                sessionsPerWeek:
                                  type: number
                                  description: >-
                                    Of the whole weeks in the window, the
                                    fraction in which the supplier has at least
                                    `sessionsPerWeek` distinct days carrying a
                                    slot. A trailing partial week is not
                                    counted. Present only when you sent
                                    `sessionsPerWeek`.
                                  example: 1
                              description: >-
                                The per-criterion breakdown behind `score` —
                                each 0–1, each a coverage RATIO rather than a
                                slot count, so a busy calendar does not
                                automatically outrank a well-fitting one. A key
                                appears only when you supplied the matching
                                request field. Use it to explain a ranking
                                ("great on Mondays, poor on afternoons") instead
                                of showing a bare number.
                              example:
                                startDate: 0.7142857142857143
                                timeOfDay: 0.5
                                daysOfWeek: 1
                                sessionsPerWeek: 1
                          required:
                            - score
                            - components
                          description: >-
                            How well this supplier matches the schedule
                            preferences on the request (`lookAheadStartDate`,
                            `preferredTimes`, `daysOfWeek`, `sessionsPerWeek`).
                            ABSENT when you supplied none of them — no
                            preferences expressed is not a perfect match, and a
                            bare request gets exactly today’s response.
                            `excludeDates` has no component: it removes slots
                            from the pool instead of scoring. Ranking is WITHIN
                            A PAGE only — page membership is decided before any
                            availability is computed, so a supplier on page 2
                            can legitimately outscore every supplier on page 1.
                        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:
                        - supplier
                        - days
                        - position
                    description: Suppliers on this page, in a stable order across pages.
                  timezone:
                    type: string
                    description: >-
                      The IANA timezone actually used for day bucketing and
                      every `*Local` field (the request `timezone`, or the
                      project default) — R-32.
                    example: America/Chicago
                  nextCursor:
                    type: string
                    nullable: true
                    description: >-
                      Pass back as `cursor` to fetch the next page of suppliers.
                      `null` on the last page.
                  errors:
                    type: array
                    items:
                      type: string
                    description: Non-fatal engine messages. Usually empty.
                required:
                  - searchId
                  - data
                  - timezone
                  - nextCursor
                  - errors
        '400':
          description: >-
            Validation error (e.g. neither locationId nor lat+lng, or a
            malformed cursor)
          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.