- shows and edits the client’s name and phone;
- manages their saved service addresses, and which one is the default;
- lists their bookings and orders.
clientId in the path and need only the API key, so your
server must make sure the signed-in client only ever sees their own.
This guide assumes you have hosted sign-in and the
BFF pattern working, and that you
already call POST /clients/me after sign-in. See
Onboard the client. For the
client profile and every client route on one page, see
Clients.
The client plane at a glance
Each path above is relative to the project:
POST /clients/me is
POST /v1/projects/{projectId}/clients/me. Every one takes both credentials: x-api-key from your server, and Authorization: Bearer with
the client’s access token. There is no GET /clients/me. Read the profile by
calling POST /clients/me again: it’s idempotent, writes nothing when you
send no body, and returns 200 with the profile.
Every route except POST /clients/me needs the client to be onboarded first.
Before that, the person has no membership of the project, and each returns
403:
404 NOT_FOUND, No client profile for this project, comes back only for
someone who is a member of the project, such as staff, but has no client
profile there. Call POST /clients/me for them: it adds the CLIENT role to
their membership, keeps their other roles, and creates the profile.
Show the profile
emailcomes from the client’s sign-in. No client-plane route changes it.lastPaymentis a display-only snapshot of the card they last paid with. See Show the card a client last paid with.addresses[].sourceisMANUALfor an address saved through the routes below, andBOOKINGfor one MarketBox saved from an in-home booking.latitudeandlongitudemay be absent ornull. An address typed by hand may never have been geocoded. Treat a missing pair as unknown, not as a location.
Edit the name and phone
PATCH /clients/me changes firstName, lastName or phone. Send only the
fields to change:
- Names are trimmed and must be 1–80 characters. You can change a name but
not clear it, so a blank or
nullname is a400. phone: nullclears the phone. The phone is stored in E.164 form (+14165550199). A North American number may be sent in national form; any other must start with+and the country code.- A body with none of
firstName,lastNameorphoneis a400 VALIDATION_ERROR. Sending the values already stored is a200that writes nothing.
200.
Make the change before you create an order, so the order and booking
emails carry the new name. Full rules:
Change the name or phone later.
Manage saved addresses
Save an address
POST /clients/me/addresses takes one structured address. The fields are the
same as a booking’s address: see
The address object.
201 response carries the whole profile in data, and the address you
just saved beside it in address:
country is stored as an ISO 3166-1 alpha-2 code. You can send "CA",
"CAN" or "Canada". Anything else is refused:
state is coerced to an ISO 3166-2 code when it can be, and kept as you typed
it when it can’t.
An address id is derived from the address
An address id starts withaddr_ and is a hash of the structured fields:
street number, street name, unit, city, state, country and zip code. It isn’t
a random id. Three things follow from that:
- Saving the same address twice is an upsert. You get the same id back and
the client still has one record.
addressOneLineisn’t part of the hash, so the same street address formatted differently is still one record. - Editing an address can change its id. If a
PATCHchanges any hashed field, the record moves to a new id and the old id stops existing. If that address was the default, the default moves with it. Edit onlyaddressOneLineand the id stays. - An edit can merge two addresses. Edit one address until it matches another saved address, and they become one record.
PATCH. Don’t keep
an addressId in your own database across edits. A stale id is a 404:
Change or remove an address
PATCH /clients/me/addresses/{addressId} takes any subset of the address
fields and merges them over the stored address. It returns the whole profile.
DELETE /clients/me/addresses/{addressId} removes it for good: there is no
soft delete. Bookings already made at that address keep their own copy, so
they’re unaffected. It returns the whole profile too.
You can delete the default address. MarketBox then promotes the oldest
remaining address to default, or clears defaultAddressId when none is left.
Read defaultAddressId off the response rather than assuming which address
won.
Choose the default address
PUT /clients/me/addresses/{addressId}/default points defaultAddressId at an
address the client has already saved. It takes no body and returns the whole
profile. An id that isn’t one of theirs is 404 Address not found.
The first address a client saves with POST /clients/me/addresses becomes
their default. Later ones don’t replace it, so set the default on purpose
when the client picks one.
Use the client’s saved addresses to pre-fill the in-home address step of your
checkout. A saved address with latitude and longitude is ready to search
with. One without them needs geocoding first, because travel zones match on
coordinates, not postal codes.
Show booking and order history
There is no client-plane route for history. Use the API-key routes, with theclientId your server resolved from the client’s token:
The two lists are paginated with
limit and cursor. See
Pagination. The two aggregates return one record.
signedInClientId is the helper from
Create a single booking. It
calls POST /clients/me with the client’s token and returns data.clientId.
For the list, put the resolved clientId in the path yourself:
Reference
Endpoints used in this guide
Errors and edge cases
See Errors for the envelope.