List Clients

GET
/v2/clients

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 page / per_page 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 404.

Authorization

Bearer-Auth
headerAuthorizationBearer <token>

Query Parameters

parent_id?string

Return only the direct children of this client (its UUID). Must be the authenticated client or one of its descendants, otherwise client_not_found is returned.

Formatuuid
external_reference?string

Return only the client with this exact external_reference.

query?string

Case-insensitive search across client name and external_reference.

page?number

Page number for pagination (starts at 1).

Range1 <= value
per_page?number

Number of clients per page. Falls back to the default when omitted or invalid.

Range1 <= value

Response Body

OK

application/json
  1. response
[index: integer]?

A client in your hierarchy, as returned by the /v2/clients endpoints. The authenticated client and each of its descendants are represented by this object.

The id is the client's UUID: pass it as parent_id when creating a child, or as the travel-data client_id when submitting on behalf of a descendant.

Example Request
curl -X GET 'https://api.sandbox.squake.earth/v2/clients'
Example Response
[  {    "id": "4fb3ec7a-92cb-471f-b75f-c3fe7c2a34d5",    "name": "BMW Germany",    "external_reference": "bmw-de",    "parent_id": "0f1f3d3b-2775-4cc0-885e-8d51db6d6de1",    "status": "active",    "metadata": {},    "methodology_options": [      {        "activity_type": "flight",        "methodology": "TIM",        "version": "AT_TIME_OF_TRAVEL",        "default": true      },      {        "activity_type": "flight",        "methodology": "DEFRA",        "version": "AT_TIME_OF_TRAVEL",        "default": false      },      {        "activity_type": "train",        "methodology": "DEFRA",        "version": "AT_TIME_OF_TRAVEL",        "default": true      },      {        "activity_type": "car",        "methodology": "DEFRA",        "version": "AT_TIME_OF_TRAVEL",        "default": true      },      {        "activity_type": "hotel",        "methodology": "GREENVIEW",        "version": "AT_TIME_OF_TRAVEL",        "default": true      }    ]  }]

Retrieve the Authenticated Client

Returns the public representation of the authenticated client. Use it to discover your own client `id` 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 `404`.

Update a Client

Updates the editable fields of a visible client: `name`, `external_reference`, `metadata`, and `methodology_configuration`. Only the fields you send are changed; the others keep their current values. Sending `methodology_configuration` 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 `invalid_methodology_options` (`400`), and readable but disallowed options — an unknown `activity_type` or `methodology`, two defaults for one activity type, more than three per type — with `invalid_methodology_options` (`422`). Either way nothing is written, including the other fields sent in the same request. Re-parenting is not supported. A `parent_id` that would move the client — including `null`, which reads as a request to make it a root — is rejected with `parent_id_immutable` (`400`) and nothing is written. Sending the client's current `parent_id` 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 `404`.