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
idasclient_idtoPOST /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:
| Field | Description |
|---|---|
activity_type | flight, train, car or hotel. |
methodology | A methodology available for the activity type. See the table below. |
version | AT_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. |
default | Whether 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
methodologymust be available for theactivity_type:
activity_type | Available methodologies |
|---|---|
flight | ADEME, BASE-EMPREINTE, CO2-EMISSIEFACTOREN-NL, DEFRA, GATE4, ICAO, TIM, TU-CHALMERS, US-EPA |
train | ADEME, BASE-EMPREINTE, CO2-EMISSIEFACTOREN-NL, DEFRA, GREEN-TRAVEL-DATA, REM, US-EPA |
car | ACRISS, DEFRA, EU-EEA, US-EPA |
hotel | DEFRA, 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
| Task | Endpoint | Guide |
|---|---|---|
| Find your own client ID | GET /v2/clients/me | Retrieve the authenticated client |
| List your clients | GET /v2/clients | List clients |
| Read one client | GET /v2/clients/{id} | Retrieve a client |
| Create a child client | POST /v2/clients | Create a child client |
| Rename a client or change its methodologies | PATCH /v2/clients/{id} | Update a client |
| Remove a client | DELETE /v2/clients/{id} | Delete a client |
Error codes
| Status | Code | Meaning |
|---|---|---|
400 | invalid_parent_client | The parent_id isn't the authenticated client or one of its descendants. |
400 | invalid_methodology_options | methodology_options can't be read as a list of options, for example because an entry has no boolean default. |
400 | parent_id_immutable | The update would move the client to another parent. |
404 | client_not_found | The client doesn't exist, was deleted, or is outside your hierarchy. |
422 | invalid_methodology_options | The options break a rule: an unknown activity_type or methodology, two defaults for one activity type, or more than three options for one type. |
422 | client_has_children | The client you want to delete still has child clients. |
A request that fails with one of these errors writes nothing.