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

# Suppliers

> The people or units that fulfill bookings in a project, and the two endpoints that describe them.

A **supplier** is the entity that fulfills a booking — typically a person, but
conceptually any unit of capacity (a stylist, a doctor, a tutor, a meeting room).

There are two ways to read one, and picking the right one matters:

| You are building | Call | You get |
| - | - | - |
| A directory or picker | `GET /v1/projects/{projectId}/suppliers` | A page of suppliers, each with services, skills and locations |
| One supplier's profile page | `GET /v1/projects/{projectId}/suppliers/{supplierId}` | The same shape, **plus** the supplier's rating and working hours |

The detail endpoint is a superset. The list omits `rating` and `availability`
on purpose — each costs an extra read per supplier, and a 200-row page should
not pay for data a directory does not show.

Both answer for **your application**, with the API key alone. A supplier
managing their own profile, bookings and hours through your portal uses the
**supplier plane** instead — `/v1/projects/{projectId}/suppliers/me`, with the
supplier's user token. See [The supplier's own view](#the-supplier’s-own-view).

## Booking identity

A supplier response is not just display content. These are the fields you need
to actually book against a supplier, and where each one lives:

| What you need | Field | Notes |
| - | - | - |
| Stable supplier id | `supplierId` | Send as `supplierId` when creating a booking or a hold. |
| Whether they take bookings | `active` | See the warning below — `active: true` alone does not mean bookable. |
| What they can deliver | `services[].serviceId` + `services[].name` | Ids to book with, and localized labels to render. |
| Timezone | `timezone` | Their own IANA zone. May be absent — see [Timezone](#timezone). |
| Where they work | `locations[].locationId` | Includes travel zones. This is the id you send as `locationId`. |
| Regions served | `servedRegions` | The exact set the list's `country`/`state`/`city` filter matches against. See [Regions served](#regions-served). |
| Country and market | `country`, `state`, `postalcode` | The inputs [regional price rules](https://docs.gomarketbox.com/concepts/regional-pricing.md) resolve against. |
| Public profile | `firstName`, `lastName`, `bio`, `avatarUrl`, `languages`, `locales` | Everything a card renders. |
| Reputation | `rating.averageRating`, `rating.reviewCount` | Detail endpoint only. |
| Working hours | `availability.schedules[]` | Detail endpoint only. **Not** bookable times. |

> [!WARNING]
>
> `active` and bookability are set independently. A supplier can be `active:
>     true` and still be impossible to book, because they have no live schedule.
> The reliable check is `availability.schedules.length > 0`, and the only
> authoritative one is asking the availability engine for real times.

## Anatomy

Every supplier response — list row or detail — carries these.

**Profile fields**, selected from the full supplier record:

| Field | Notes |
| - | - |
| `supplierId` | Stable identifier. |
| `firstName`, `lastName` | Display name. |
| `email`, `phone` | Contact details. `phone` is stored as E.164 (`+14165550134`) for any supplier created or edited through the API since September 2026; rows that predate that hold whatever was typed until they are next edited. |
| `addressoneline`, `city`, `state`, `country`, `postalcode` | Address. Note the lowercase spelling of `addressoneline`. |
| `longitude`, `latitude` | Geolocation for travel-time logic. |
| `timezone` | IANA timezone. Absent when unset on the profile. |
| `bio` | Free-form bio text. |
| `avatarUrl` | Ready-to-use image URL, or `null` when no avatar is set. |
| `languages` | ISO 639-1 codes the supplier speaks, e.g. `["en","fr"]`. |
| `locales` | Server-derived from `languages` × `country`, e.g. `["en-CA","fr-CA"]`. |
| `defaultLocale` | The supplier's own preferred locale, BCP-47 (`fr-CA`). Staff-set, never inferred from a booking. **Absent when unset** — fall back to your project default. One tag, unlike the derived `locales` array. |
| `maxTravelTime` | For mobile suppliers — maximum travel time they will accept, in minutes. |
| `active` | Whether the supplier is taking bookings. |
| `externalId`, `externalData` | Pass-through fields for your own ids and metadata. |
| `updatedAt` | Last modification timestamp. |

**Enriched mappings**, joined against the project's catalog and schedules:

| Field | Shape |
| - | - |
| `services` | Array of `{ serviceId, name: { en, fr, … } }`. |
| `skills` | Array of `{ skillId, name: { en, fr, … } }`. |
| `locations` | Array of location records. See [Locations](#locations). |
| `servedRegions` | Array of slug region paths, e.g. `["ca/","ca/on/","ca/on/toronto/"]`. See [Regions served](#regions-served). |

Both `services` and `skills` carry **localized name maps**. If your project's
services are named in several languages, the response contains all of them —
pick the locale you want client-side.

> [!NOTE]
>
> Only bookable catalog is joined in. A mapping to a service that is not `LIVE`,
> or to an inactive skill, is **dropped from the array entirely** rather than
> returned with a blank name. So `services` is what this supplier can actually
> be booked for today, not a historical record of what they were ever assigned.

## Timezone

`timezone` is the supplier's own IANA zone, and it is **optional on the
profile** — a project whose suppliers all work in one place often leaves it
unset.

On create and update it must be an IANA identifier such as `America/Toronto`;
an abbreviation like `EST` or an offset is a `400 VALIDATION_ERROR` (see
[Timezones](https://docs.gomarketbox.com/concepts/timezones.md#valid-timezones)). The value does real work:
it decides when the supplier's daily agenda email fires, and availability
responses report it in `supplierZones` as the fallback `bookingTz` for
virtual bookings. Unset inherits the project's default timezone.

The list endpoint returns it as-is, absent and all. The detail endpoint
additionally resolves it for you:

```json theme={null}
"availability": {
  "timezone": "America/Toronto",
  "timezoneSource": "SUPPLIER"
}
```

`timezoneSource` tells you whether that value is real. `SUPPLIER` means it came
from the profile. `PROJECT` means the profile had none and the project default
was substituted — a sensible display default, but not a statement about where
this supplier works. Do not derive travel logic from a `PROJECT`-sourced zone.

See [Timezones](https://docs.gomarketbox.com/concepts/timezones.md) for how booking times are rendered.

## Locations

The `locations[]` array is **derived from the supplier's schedules** — not
stored on the supplier record. A location nobody is scheduled at is not
somewhere you can book, so it does not appear.

Each schedule contributes locations through three reference shapes:

| Source on the schedule | Resolves against |
| - | - |
| `locationRefs[]` | Locations |
| `physicalLocationIdsInsideTravelZone[]` | Locations |
| `travelZoneRef` | The schedule's own travel zone |

Locations are **deduped by `locationId`**. References that do not resolve (a
deleted location, a missing travel zone) are skipped silently rather than
surfaced as nulls.

Each location record:

| Field | Notes |
| - | - |
| `locationId` | Stable identifier. For a supplier-owned travel zone this is the `stz_` id. |
| `locationType` | `PHYSICAL`, `VIRTUAL`, or `TRAVEL_ZONE`. |
| `name` | Display name. |
| `country`, `state`, `city`, `street`, `addressOneLine` | Address fields. Any may be `null`. |
| `latitude`, `longitude` | Geolocation. May be `null`. |
| `travelZoneType` | `CIRCULAR` or `DRAWN`. Only set on `TRAVEL_ZONE` locations. |

Only **live** schedules contribute. A schedule is live when it is `ACTIVE`, not
deleted, and its `endDate` has not passed in the schedule's own timezone. That is
the same rule the list's region filter, `servedRegions` and the detail endpoint's
`availability.schedules` use, so the four never disagree about whether a
supplier can be booked. A supplier with no live schedule has `locations: []` —
including one whose only schedule ended last week.

## Regions served

`servedRegions` is the answer to "why is this supplier (not) returned by
`country=CA&state=ON&city=Toronto`?". It is the list of region paths the
supplier is indexed under — the **same set** the list's location filter
matches against, so a supplier is returned by that filter exactly when the
query's path is in this array.

```json theme={null}
"servedRegions": ["ca/", "ca/on/", "ca/on/scarborough/", "ca/on/toronto/"]
```

* Slug paths at **every level** of the hierarchy, sorted. A zone in Toronto
  contributes `ca/`, `ca/on/` and `ca/on/toronto/`, so `country=CA` alone
  matches it.
* Derived from the travel zones and physical locations on the supplier's
  **live** schedules — the same sources as `locations[]`.
* A zone inside a borough is indexed under the locality, the borough **and**
  the wider municipality. A Scarborough zone carries both
  `ca/on/scarborough/` and `ca/on/toronto/`, so `city=Scarborough` and
  `city=Toronto` both return it.
* `[]` when the supplier has no live schedule with a geocodable zone.

> [!NOTE]
>
> `locations[]` is evaluated on every request; `servedRegions` is maintained by
> an index that a daily sweep prunes. For up to a day after a schedule's
> `endDate` passes, a supplier can therefore still carry the region in
> `servedRegions` (and still match the filter) while `locations[]` has already
> dropped it. Treat `locations[]` as the fresher of the two.

## Reading one supplier

```
GET /v1/projects/{projectId}/suppliers/{supplierId}
```

```bash theme={null}
curl "$MARKETBOX_API_URL/v1/projects/$MARKETBOX_PROJECT_ID/suppliers/sup_01kv60qgnef2kt3pvqgwmkbzfr" \
  -H "x-api-key: $MARKETBOX_API_KEY"
```

```json theme={null}
{
  "data": {
    "supplierId": "sup_01kv60qgnef2kt3pvqgwmkbzfr",
    "firstName": "Jane",
    "lastName": "Okonkwo",
    "email": "jane@example.com",
    "phone": "+14165550142",
    "addressoneline": "120 Adelaide St W, Toronto, ON",
    "city": "Toronto",
    "state": "CA-ON",
    "country": "CA",
    "postalcode": "M5H 1T1",
    "latitude": 43.6489,
    "longitude": -79.3839,
    "timezone": "America/Toronto",
    "bio": "Fifteen years of clinical massage therapy.",
    "avatarUrl": "https://example.com/media/suppliers/sup_01kv60qgnef2kt3pvqgwmkbzfr/256.webp",
    "languages": ["en", "fr"],
    "locales": ["en-CA", "fr-CA"],
    "defaultLocale": "en-CA",
    "maxTravelTime": 45,
    "active": true,
    "updatedAt": "2026-08-01T14:22:10.000Z",
    "services": [
      { "serviceId": "srv_01kv60qg12e82acr78edfnjhvv", "name": { "en": "Deep tissue massage" } }
    ],
    "skills": [{ "skillId": "skl_01kv60qg44f01bzz51gjmqp8tt", "name": { "en": "Prenatal" } }],
    "locations": [
      {
        "locationId": "stz_01kv60qgnef2kt3pvqgwmkbzfr",
        "locationType": "TRAVEL_ZONE",
        "name": "Downtown Toronto",
        "country": "CA",
        "state": "CA-ON",
        "city": "Toronto",
        "travelZoneType": "CIRCULAR"
      }
    ],
    "servedRegions": ["ca/", "ca/on/", "ca/on/toronto/"],
    "rating": {
      "averageRating": 4.7,
      "reviewCount": 128,
      "recent": [
        {
          "reviewId": "rev_01kv7q41n2hbqxwm03ymn7bxl9",
          "supplierId": "sup_01kv60qgnef2kt3pvqgwmkbzfr",
          "clientId": "cli_01kv6r83j9fmquwl81xkm5bwj6",
          "ratingStars": 5,
          "reviewText": "Booked twice already.",
          "direction": "CLIENT_TO_SUPPLIER",
          "subjectType": "SUPPLIER",
          "subjectId": "sup_01kv60qgnef2kt3pvqgwmkbzfr",
          "createdAt": "2026-08-20T18:04:00.000Z"
        }
      ]
    },
    "availability": {
      "timezone": "America/Toronto",
      "timezoneSource": "SUPPLIER",
      "schedules": [
        {
          "scheduleId": "sch_01kv60qgnef2kt3pvqgwmkbzfr",
          "timezone": "America/Toronto",
          "startDate": "2026-01-01",
          "endDate": "2026-12-31",
          "rrule": "FREQ=WEEKLY;INTERVAL=1",
          "exdates": ["2026-07-01"],
          "weeklyHours": [
            { "dayOfWeek": "MO", "startTime": "09:00", "endTime": "17:00", "crossesMidnight": false },
            { "dayOfWeek": "WE", "startTime": "09:00", "endTime": "17:00", "crossesMidnight": false }
          ],
          "appliesToAllOfferings": true,
          "offeringIds": [],
          "locationIds": [],
          "travelZone": {
            "locationId": "stz_01kv60qgnef2kt3pvqgwmkbzfr",
            "source": "SUPPLIER_TRAVEL_ZONE"
          },
          "summary": {
            "days": "Mon, Wed",
            "times": "9:00 AM – 5:00 PM",
            "dateRange": "Jan 1 – Dec 31, 2026",
            "coverageArea": "Downtown Toronto",
            "offerings": "All offerings"
          }
        }
      ]
    },
    "access": {
      "userId": "usr_01kv5z8m3c7qdx4hw2ne6ta9pk",
      "invitationStatus": "LINKED",
      "roles": ["CLIENT", "SUPPLIER"],
      "membershipStatus": "ACTIVE",
      "accessEndedAt": null
    }
  }
}
```

> [!WARNING]
>
> The response carries the supplier's `email`, `phone` and address. Don't pass
> it straight to a browser: copy the fields your page renders.

To assemble a public profile from this response, see
[Build a supplier profile page](https://docs.gomarketbox.com/guides/build-a-supplier-profile-page.md).

An **inactive** supplier is returned, with `active: false`, so a profile page
for a paused supplier still renders. This differs from the list, which hides
them. A `404` means the id is unknown in this project, belongs to another
project, or has been deleted — those three are not distinguished.

### Who can sign in as this supplier

Only the detail read carries `access`. `GET /suppliers` and
`POST /availability/suppliers` don't. It says whether the record is linked to a
person who can sign in to your portal, and what that person holds on the
project:

| Field | Meaning |
| - | - |
| `userId` | The MarketBox user linked to the record, or `null`. |
| `invitationStatus` | `NONE` (never invited, or unlinked since), `INVITED` (invited, not yet accepted) or `LINKED`. |
| `roles` | Every role the linked person holds on the project. `[]` when the record isn't linked, or the membership isn't `ACTIVE`. |
| `membershipStatus` | `ACTIVE` or `INACTIVE` for the linked person's membership; `null` when the record isn't linked. |
| `accessEndedAt` | When the record was last unlinked from a person, or `null`. Cleared when someone accepts a new invitation. |

Removing a supplier's `SUPPLIER` role unlinks the record, so `invitationStatus`
goes back to `NONE`. **`accessEndedAt` tells the two `NONE`s apart:** set means
the supplier was removed, `null` means they were never invited. A supplier
removed before November 5, 2026 has `null`. See
[Removed, or never a supplier](https://docs.gomarketbox.com/guides/supplier-portal-sign-in-and-access.md#removed-or-never-a-supplier).

`access` is read-only. The business invites and removes suppliers in the
dashboard.

## Rating and reviews

`rating` is read from an aggregate maintained in the same atomic write that
records each review, so it never disagrees with the rows behind it.

| Field | Notes |
| - | - |
| `averageRating` | Mean stars, rounded to one decimal place. |
| `reviewCount` | How many reviews the average is based on. |
| `recent` | The five newest reviews, for a profile card. |

A supplier nobody has reviewed returns `averageRating: 0` and `reviewCount: 0`
— check `reviewCount` before rendering stars, or an unrated supplier displays
as a zero-star one.

`recent` is a **preview, not the full set**. To page through every review, call
`GET /v1/projects/{projectId}/reviews` with `supplierId`. See
[Reviews](https://docs.gomarketbox.com/resources/reviews.md). No email address is returned for either party.

If the rating badge is all you need and you are not rendering a whole profile,
`GET /v1/projects/{projectId}/suppliers/{supplierId}/review-summary` returns
just the aggregate. See
[Collect reviews and show ratings](https://docs.gomarketbox.com/guides/collect-reviews-and-show-ratings.md#show-supplier-ratings)
for a badge, a profile page and the full list.

## Availability is a pattern, not a list of times

This is the single most expensive thing to get wrong on this endpoint.

`availability.schedules[]` describes **when and where this supplier works**. It
is the recurring pattern an operator configured. It knows nothing about:

* bookings already on the calendar,
* time off,
* how long the offering you want to sell actually takes.

So it cannot tell you a time is free. **Never present a time built from
`weeklyHours` as available.** For times you can genuinely book, call
`POST /v1/projects/{projectId}/availability/suppliers` with a service, an
offering and a location — see
[Search suppliers by availability](https://docs.gomarketbox.com/guides/search-suppliers-by-availability.md).

What the pattern is good for: rendering "Mon, Wed 9–5" on a profile, deciding
whether to show a supplier at all, and telling a client the earliest week worth
asking about.

### Reading a schedule

| Field | Notes |
| - | - |
| `scheduleId` | Stable identifier. |
| `timezone` | The zone **this schedule's** times are in. Usually matches the parent `availability.timezone`, but a supplier working across zones can differ — always read against this one. |
| `startDate`, `endDate` | The window the schedule is in effect, `YYYY-MM-DD`. |
| `rrule` | Which weeks inside that window it runs. `FREQ=WEEKLY;INTERVAL=1` is every week, `INTERVAL=2` fortnightly. |
| `exdates` | Individual excluded dates — holidays, one-off closures. |
| `weeklyHours` | The working windows that repeat each covered week. |
| `appliesToAllOfferings` | When `true`, `offeringIds` is empty and the schedule covers everything. |
| `offeringIds` | The offerings covered. Empty means **all**, not none — read `appliesToAllOfferings` first. |
| `locationIds` | Fixed locations worked at. Each also appears in `locations[]` with its address. |
| `travelZone` | `{ locationId, source }`, or `null` for a fixed-location schedule. |
| `summary` | Pre-rendered English display strings. Not localized — build your own from the structured fields if you serve several locales. |

Two traps in `weeklyHours`:

* **The weekdays come from `weeklyHours`, not from `rrule`.** The rule decides
  which weeks; the array decides which days. A weekday absent from the array is
  a day this supplier does not work.
* **`crossesMidnight` must be checked before comparing times.** A night shift is
  `startTime: "22:00"`, `endTime: "02:00"`, `crossesMidnight: true`. Compare the
  two strings without it and you get a negative-length day.

`travelZone.source` distinguishes a zone drawn for this supplier alone
(`SUPPLIER_TRAVEL_ZONE`, an `stz_` id) from a project-wide zone several
suppliers share (`PROJECT_LOCATION`, a `loc_` id). Search finds a supplier in
either kind of zone, but only a supplier's own zone can be booked at a client's
address: a `TRAVEL_ZONE` booking's `locationId` must be an `stz_` id, and a
`loc_` id is `404 NOT_FOUND`. See
[Set up a mobile supplier's service area](https://docs.gomarketbox.com/guides/set-up-a-mobile-supplier-service-area.md#the-supplier’s-own-zone-or-a-project-zone).

Only **live** schedules are returned — `ACTIVE`, not deleted, and `endDate` not
yet passed in the schedule's own `timezone`. `schedules: []` means the supplier
cannot currently be booked at all, whatever `active` says.

A schedule's start and end of day locations are never returned here, or in
any availability response. In the public API, you read and write them on the
[supplier plane](https://docs.gomarketbox.com/guides/supplier-portal-availability.md#start-and-end-of-day-locations).

## Listing suppliers

```
GET /v1/projects/{projectId}/suppliers
```

| Param | Default | Notes |
| - | - | - |
| `limit` | 50 | Page size. Max 200. |
| `cursor` | — | Pagination cursor. See [Pagination](https://docs.gomarketbox.com/concepts/pagination.md). |
| `services` | — | Comma-separated service ids. |
| `skills` | — | Comma-separated skill ids. |
| `country` | — | ISO 3166-1 alpha-2, e.g. `CA`. |
| `state` | — | ISO 3166-2, `CA-ON` or `ON`. Requires `country`. |
| `city` | — | Requires `country` and `state`. |
| `lat` | — | Latitude of a point to be covered, decimal degrees. Requires `lng`. |
| `lng` | — | Longitude of that point. Requires `lat`. |

Every filter is **AND**, both within a parameter and across them.
`services=srv_a,srv_b` means a supplier offering *both*, never either.

There are two ways to filter by place, and they are **exclusive**:

* **By region** — `country`, then `state`, then `city`. Hierarchical, and each
  level requires the one above: `state` without `country` is a `400`, as is
  `city` without both.
* **By point** — `lat` + `lng`, both or neither. Returns every supplier whose
  live travel zone **contains that point**, tested against the zone's actual
  polygon or radius rather than a place name, and AND-combined with
  `services`/`skills`.

Sending `lat`/`lng` together with any of `country`/`state`/`city` is a `400`.

```bash theme={null}
# who covers this address in Scarborough?
curl "$MARKETBOX_API_URL/v1/projects/$MARKETBOX_PROJECT_ID/suppliers?lat=43.7462&lng=-79.2191&services=srv_01kv60qg12e82acr78edfnjhvv" \
  -H "x-api-key: $MARKETBOX_API_KEY"
```

> [!NOTE]
>
> Both filters match the regions a supplier **serves** — derived from the travel
> zones and physical locations on their **live** schedules — not the address on
> their profile. A mobile supplier based in Barrie whose travel zone covers
> Toronto matches `city=Toronto`. A supplier with an address but no live
> schedule matches nothing, because they cannot be booked. Coverage resolves to
> the locality, its borough and the wider municipality, so a Scarborough zone is
> returned by `city=Scarborough` and by `city=Toronto`. Each row's
> `servedRegions` is the exact list the region filter checked — see
> [Regions served](#regions-served).

> [!WARNING]
>
> A point only matches **travel zones**. A supplier whose live schedules are all
> at fixed locations has no zone and is never returned by `lat`/`lng`, even if
> the point is their own studio. Use the region filter, or
> `POST /v1/projects/{projectId}/availability/suppliers` with a `locationId`,
> for fixed-location suppliers.

Only active suppliers are listed; inactive and deleted ones never appear, on
any combination of filters. With no filter, results are in name order (last
name, then first name). With a service, skill or `lat`/`lng` filter, they are
ordered by supplier id. With only a country, state or city filter, they follow
the location index, so don't rely on any particular order.

Treat `nextCursor: null` as the **only** end-of-results signal — never stop on
a page that merely looks short. A cursor is valid only against the filter set
that produced it; change a filter mid-walk and restart.

Every page of one listing carries the same `searchId` (also the
`X-MB-Search-Id` header; the cursor keeps it), and each row a 0-based
`position`, continuous across pages. If you draw the list for clients, report
it with that `searchId` so suppliers' insights count it. See
[Report site events](https://docs.gomarketbox.com/guides/report-site-events.md#search-ids).

## Managing suppliers

Supplier management is normally done in the MarketBox dashboard, but the public
API exposes it too, so you can keep a roster in sync from your own system:

| Operation | Endpoint |
| - | - |
| Create | `POST /v1/projects/{projectId}/suppliers` |
| Update | `PUT /v1/projects/{projectId}/suppliers/{supplierId}` |
| Soft-delete (see below) | `DELETE /v1/projects/{projectId}/suppliers/{supplierId}` |
| Add a service | `POST /v1/projects/{projectId}/suppliers/{supplierId}/services/{serviceId}` |
| Remove a service | `DELETE /v1/projects/{projectId}/suppliers/{supplierId}/services/{serviceId}` |
| Add a skill | `POST /v1/projects/{projectId}/suppliers/{supplierId}/skills/{skillId}` |
| Remove a skill | `DELETE /v1/projects/{projectId}/suppliers/{supplierId}/skills/{skillId}` |
| Get an avatar upload URL | `POST /v1/projects/{projectId}/suppliers/{supplierId}/avatar/upload-url` |
| Attach an uploaded avatar | `PUT /v1/projects/{projectId}/suppliers/{supplierId}/avatar` |
| Remove an avatar | `DELETE /v1/projects/{projectId}/suppliers/{supplierId}/avatar` |

Use `externalId` to carry your own primary key onto the supplier, so you can
reconcile without storing a second id map.

For the whole setup in order, from service to bookable supplier, see
[Provision your catalog and suppliers](https://docs.gomarketbox.com/guides/provision-catalog-and-suppliers.md).

Three profile fields have write rules worth knowing:

| Field | On `POST` | On `PUT` |
| - | - | - |
| `phone` | Optional. E.164 or a national NANP number (`(416) 555-0134`); stored as E.164 (`+14165550134`). Numbers outside North America must carry `+` and a country code. | Omit to keep, `null` to clear, anything else is validated and normalized. |
| `defaultLocale` | Optional BCP-47 tag (`fr-CA`), normalized (`fr-ca` is stored as `fr-CA`). Omit to inherit the project default. | Omit to keep, `null` to clear. |
| `bio` | Optional free text. | Omit to keep, `null` to clear. |

An unparseable phone or a malformed locale is a `400 VALIDATION_ERROR` — the
row is not written.

`email` is unique within the project. A `POST` or `PUT` that uses another
supplier's email is `409 CONFLICT`, "A supplier with this email already exists
in the project", and nothing is written.

A `PUT` that sends `active` is also `409 CONFLICT` when `active` changed
between the update's read and its write: "This supplier's Active setting
changed while it was being saved. Reload and try again." Read the supplier
again, then retry if your change still applies.

The avatar routes answer the same way. A `PUT` or `DELETE` on
`/suppliers/{supplierId}/avatar` is `409 CONFLICT` when another confirm or
remove changed the photo while this one was being saved:

```json theme={null}
{
  "code": "CONFLICT",
  "message": "This supplier's photo changed while it was being saved. Reload and try again.",
  "statusCode": 409,
  "requestId": "5b8e2d1f-7c4a-4e36-9a0b-2f6d8c1e3a57"
}
```

Read the supplier again, then retry if the photo still isn't the one you
want.

A `DELETE` is permanent around the edges, even though the profile itself is
only soft-deleted and stays readable to the bookings that reference it:

* Every service and skill mapping is hard-deleted, and the avatar images are
  removed.
* The supplier's sign-in loses its supplier role.
* Existing bookings are **not** cancelled or reassigned. Deal with the
  supplier's diary first.
* There is no undelete. To take a supplier off the roster for a while, set
  `active: false` with `PUT` instead.

A `DELETE` that races a change to the supplier's sign-in, such as the supplier
accepting an invitation at that moment, is `409 CONFLICT`, "This supplier's
sign-in changed while it was being deleted. Try again." Nothing was deleted;
send the `DELETE` again. A `PUT` with `"phone": "(416) 555-0134"` reads back as
`"phone": "+14165550134"`.

Schedules are **not** writable with the API key alone. A supplier created here
has no schedule, so `availability.schedules` is `[]` and they cannot be booked
until working hours are set — by an operator in the dashboard, or by the
supplier themselves through your portal, on the
[supplier plane](https://docs.gomarketbox.com/guides/supplier-portal-availability.md#hours-and-blocked-time).

## The supplier's own view

The **supplier plane** lets a supplier who signs in to your portal act on their
own record: their profile and photo, their bookings and attendance reports,
cancelling and moving bookings when the service allows it, their working hours,
blocked time and travel zones, their demand and search insights, and their
alerts.

Every route sits under `/v1/projects/{projectId}/suppliers/me` and takes both
the API key and the supplier's user token. The API never takes a supplier id
there: `me` is the supplier the token belongs to. See
[Build a supplier portal](https://docs.gomarketbox.com/guides/build-a-supplier-portal.md).

`GET /v1/projects/{projectId}/suppliers/me` returns the supplier's own record
as the MarketBox dashboard shows it. It adds `serviceIds` and `skillIds`, the
raw assignments, where the public endpoints return only the joined `services`
and `skills`.

`GET /v1/projects/{projectId}/suppliers/me/access` tells your portal, on
sign-in, whether the person may use the supplier plane at all, and why not.
See [Check access first](https://docs.gomarketbox.com/guides/supplier-portal-sign-in-and-access.md#check-access-first).

## Bookings for one supplier

```
GET /v1/projects/{projectId}/suppliers/{supplierId}/bookings
```

See [Bookings](https://docs.gomarketbox.com/resources/bookings.md).

## Endpoint index

* `GET /v1/projects/{projectId}/suppliers`
* `GET /v1/projects/{projectId}/suppliers/{supplierId}`
* `POST /v1/projects/{projectId}/suppliers`
* `PUT /v1/projects/{projectId}/suppliers/{supplierId}`
* `DELETE /v1/projects/{projectId}/suppliers/{supplierId}`
* `GET /v1/projects/{projectId}/suppliers/{supplierId}/bookings`
* `GET /v1/projects/{projectId}/suppliers/{supplierId}/review-summary`
* `POST /v1/projects/{projectId}/suppliers/{supplierId}/services/{serviceId}`
* `DELETE /v1/projects/{projectId}/suppliers/{supplierId}/services/{serviceId}`
* `POST /v1/projects/{projectId}/suppliers/{supplierId}/skills/{skillId}`
* `DELETE /v1/projects/{projectId}/suppliers/{supplierId}/skills/{skillId}`
* `POST /v1/projects/{projectId}/suppliers/{supplierId}/avatar/upload-url`
* `PUT /v1/projects/{projectId}/suppliers/{supplierId}/avatar`
* `DELETE /v1/projects/{projectId}/suppliers/{supplierId}/avatar`
* `POST /v1/projects/{projectId}/availability/suppliers`
* `GET /v1/projects/{projectId}/skills` — see [Locations and skills](https://docs.gomarketbox.com/resources/locations.md#skills)
* The supplier plane, `/v1/projects/{projectId}/suppliers/me` and below — see [Build a supplier portal](https://docs.gomarketbox.com/guides/build-a-supplier-portal.md#reference)


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