# Clients

Manage a hierarchy of clients and submit travel data on their behalf. One authenticated integration
can create child clients and act for any of its descendants — no separate credential per child.

To use these endpoints you need to have this feature enabled for your account — please contact us.
Until then, every `/v2/clients` endpoint responds with `404`.

**Environment isolation:** sandbox and production hierarchies are entirely separate. Clients created
in sandbox exist only in sandbox, `id`s and `external_reference`s have no parity across environments,
and there is no sync in either direction (the same test/live model you may know from other providers).


## List Clients

 - [GET /v2/clients](https://docs-v2.squake.earth/docs/openapi/clients/get-v2-clients.md): Returns the authenticated client together with all of its descendants. Only clients you can act
for are ever returned — never a parent, sibling, or unrelated client.

Results are paginated with the standard  /  query parameters; pagination
metadata is returned in the response headers.

Requires this feature to be enabled for your account (contact us); otherwise this endpoint responds with .


## Create Child Client

 - [POST /v2/clients](https://docs-v2.squake.earth/docs/openapi/clients/post-v2-clients.md): Creates a new child client under the authenticated client (or under a visible descendant via
). The child is created for travel-data ingestion only: it inherits address, tax,
currency, and methodology defaults from its parent, but has no credentials, no billing or
purchasing capability, and no product or project access.

Submit travel data for the new client by passing its  as the  on
. The child is usable on the very next request after creation.

Send  to configure the child's methodologies in the same request
instead of inheriting the parent's. Omit it and the child gets a copy of the parent's current
options — a copy, not a link: later changes on the parent never propagate to the child.

Options that cannot be read as a list at all are rejected with 
(); options that are readable but not allowed — an unknown  or
, two defaults for one activity type, more than three per type — are rejected
with  (). In both cases no client is created.

Requires this feature to be enabled for your account (contact us); otherwise this endpoint responds with .


## Retrieve the Authenticated Client

 - [GET /v2/clients/me](https://docs-v2.squake.earth/docs/openapi/clients/get-v2-clients-me.md): Returns the public representation of the authenticated client. Use it to discover your own
client  before creating children or submitting travel data on behalf of a descendant.

Requires this feature to be enabled for your account (contact us); otherwise this endpoint responds with .


## Retrieve a Client

 - [GET /v2/clients/{id}](https://docs-v2.squake.earth/docs/openapi/clients/get-v2-clients-id.md): Returns a single visible client by  (the authenticated client or one of its descendants).
Clients outside your hierarchy are indistinguishable from missing ones: both return
 ().

Requires this feature to be enabled for your account (contact us); otherwise this endpoint responds with .


## Update a Client

 - [PATCH /v2/clients/{id}](https://docs-v2.squake.earth/docs/openapi/clients/patch-v2-clients-id.md): Updates the editable fields of a visible client: , , , and
. Only the fields you send are changed; the others keep their
current values.

Sending  replaces the client's methodology options in full — send
every option the client should keep, not just the ones that change. When the resulting list
differs from the current one, the activities already stored for this client are recalculated
with the new methodologies in the background; the response returns as soon as the
configuration is written.

The whole update is atomic: options that cannot be read as a list are rejected with
 (), and readable but disallowed options — an unknown
 or , two defaults for one activity type, more than three per
type — with  (). Either way nothing is written, including
the other fields sent in the same request.

Re-parenting is not supported. A  that would move the client — including ,
which reads as a request to make it a root — is rejected with  ()
and nothing is written. Sending the client's current  is accepted and ignored, so
you can read a client, change a field, and send the whole object back unchanged in shape.

Requires this feature to be enabled for your account (contact us); otherwise this endpoint responds with .


## Delete a Client

 - [DELETE /v2/clients/{id}](https://docs-v2.squake.earth/docs/openapi/clients/delete-v2-clients-id.md): Soft-deletes a descendant client and removes it from the client hierarchy. Only leaf clients
can be deleted. If the client still has children, this endpoint returns 
(); delete its descendants first, from the bottom of the hierarchy upwards.

The authenticated client cannot delete itself. The authenticated client, an unknown or already
deleted client, and a client outside your hierarchy all return  ().

Requires this feature to be enabled for your account (contact us); otherwise this endpoint responds with .