Clients

Manage a hierarchy of child clients, ingest travel data for them and set the methodologies they calculate with.

The Clients API manages the clients below your own account. You can create child clients, set the methodologies each of them calculates with, and submit travel data on their behalf with your own credentials. A travel management company, for example, can keep one child client per corporate customer and push each customer's trips under its own client.

The Clients API must be enabled for your account. Contact SQUAKE to enable it. Until then, every /v2/clients endpoint responds with 404.

The client hierarchy

Your authenticated client is the root of the hierarchy you see. Every client has one parent, and parent_id is null only for the root. The API only returns clients you can act for: the authenticated client and its descendants, never a parent, a sibling or an unrelated client. A client outside your hierarchy looks exactly like one that doesn't exist, and both return 404 with error code client_not_found.

Child clients exist for travel data ingestion:

  • A child inherits its address, tax, currency and methodology defaults from its parent.
  • A child has no credentials of its own, no billing or purchasing, and no access to products or projects.
  • A child is usable on the next request after you create it. Submit travel data for it by passing its id as client_id to POST /v2/travel-data. See Submitting on behalf of another client.
  • To give people access to a child client's data in the SQUAKE Dashboard, invite them with the Invitations API.

Sandbox and production hierarchies are separate, so a client ID from one environment is never valid in the other.

Methodology options

methodology_options lists the methodologies a client calculates with, one entry per activity type and methodology:

FieldDescription
activity_typeflight, train, car or hotel.
methodologyA methodology available for the activity type. See the table below.
versionAT_TIME_OF_TRAVEL uses the factor set that was valid on the travel date. null or no value uses the methodology's current version. Only CO2-EMISSIEFACTOREN-NL, DEFRA, GREENVIEW, HCMI and US-EPA publish selectable versions. For the others, the value is informational.
defaultWhether this is the methodology reported for the activity type. Required on every entry.

SQUAKE enforces three rules for each activity type:

  • At most three options for the same activity_type.
  • Exactly one option with default: true.
  • The methodology must be available for the activity_type:
activity_typeAvailable methodologies
flightADEME, BASE-EMPREINTE, CO2-EMISSIEFACTOREN-NL, DEFRA, GATE4, ICAO, TIM, TU-CHALMERS, US-EPA
trainADEME, BASE-EMPREINTE, CO2-EMISSIEFACTOREN-NL, DEFRA, GREEN-TRAVEL-DATA, REM, US-EPA
carACRISS, DEFRA, EU-EEA, US-EPA
hotelDEFRA, GREENVIEW, HCMI, NOS-GESTES-CLIMAT

A client that has never been configured reports the SQUAKE defaults: TIM and DEFRA for flights with TIM as the default, DEFRA for trains and cars, and GREENVIEW for hotels, all with AT_TIME_OF_TRAVEL.

The default methodology is the one the items array of a travel data submission reports. SQUAKE also calculates every other configured methodology and stores the results, which you can read with List the activities of a trip.

Guides

TaskEndpointGuide
Find your own client IDGET /v2/clients/meRetrieve the authenticated client
List your clientsGET /v2/clientsList clients
Read one clientGET /v2/clients/{id}Retrieve a client
Create a child clientPOST /v2/clientsCreate a child client
Rename a client or change its methodologiesPATCH /v2/clients/{id}Update a client
Remove a clientDELETE /v2/clients/{id}Delete a client

Error codes

StatusCodeMeaning
400invalid_parent_clientThe parent_id isn't the authenticated client or one of its descendants.
400invalid_methodology_optionsmethodology_options can't be read as a list of options, for example because an entry has no boolean default.
400parent_id_immutableThe update would move the client to another parent.
404client_not_foundThe client doesn't exist, was deleted, or is outside your hierarchy.
422invalid_methodology_optionsThe options break a rule: an unknown activity_type or methodology, two defaults for one activity type, or more than three options for one type.
422client_has_childrenThe client you want to delete still has child clients.

A request that fails with one of these errors writes nothing.

On this page