{ "openapi" : "3.1.0", "info" : { "description" : "
This document provides a reference to the Expense SPI. This document includes a series of notes and instructions that outline the Expense SPI.
\nThis document is aimed for the Egencia Expense SPI customers, partners and software developers who would like to consume the Expense SPI.
\nThe user must implement a web service in compliance with this specification and service contract. Egencia will call this web service for each transaction (each booking, fee when applicable). Each transaction will be sent in JSON format to the consumer through a POST message to the provided endpoint according to the following payload.
\n\nEgencia provides an \"Expense capability\" that will push the update in near real-time to the connected client system. Expense SPI will notify the partner when a booking is created or updated in Egencia.
\nThe Expense SPI uses API keys to authenticate requests. An application programming interface key (API key) is a unique identifier used to authenticate a user, developer, or calling program to an API.
\nThe partner provides API Key. This API Key is securely stored in our Vault and will be used for authenticating with the partner every time we make a call.
\nYou can authenticate the requests by validating the API Key when you receive an incoming request call from Expense SPI. We will pass the API key with every request and you (The Partner) will validate the API Key, if the API key is valid then you can accept and process request. If the API Key provided is invalid, then the authentication fails and we will receive an Authentication Failure error.
\n\n| Request Method | \nPOST | \n
|---|---|
| Host | \nany.client-of-expense.com | \n
| Base path | \n/some.base.path | \n
| Schemes | \nHTTP, HTTPS | \n
Below are the supported authentication mechanisms by the SPI
\n| Type | \nName | \nIn | \n
|---|---|---|
| Api Key | \nx-api-key | \nHeader | \n
Egencia will notify the Client about the availability of new major versions and provide the timeframe for the upgrades. Major version is a new version of the software with a significant change(s). Minor version is a new version of the software with possible backward compatibility and with a minor degree of change. The changes can be structural, and can contain enhancements, major bug fixes, or change of behaviour, endpoint changes, new fields added, or fields removed. The version change log will list all the changes included in the corresponding version from the previous one.
\nYou can also see a full API version change log under this heading.
\n| API | \nCurrent Version | \nWhat has changed? | \n
|---|---|---|
| Expense SPI | \nVersion 1 | \nFirst stable version. | \n
The SPI handles all the standard HTTP return codes. The 'Responses' below shows the codes that will trigger an automatic retry mechanism on our side in order to enhance the success of the delivery. For any other error or when the maximum retries has been reached, it will need a manual intervention and we might contact your technical service if the issue comes from your server.
\n", "operationId" : "pushExpense", "parameters" : [ { "description" : "Time Stamp in format ISO DATE TIME", "example" : "2011-12-03T10:15:30", "in" : "header", "name" : "message_timestamp", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Expense" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "examples" : { "Expense message for a Car booking" : { "description" : "Expense message for a Car booking", "value" : { "uuid" : "109279f6-c8d8-4a7b-9630-b32e3ec690e2", "expense_id" : "CR-5062d617d50fce1db44d72225419bff237322e79", "expense_version" : 1, "expense_type" : "CAR", "booking_status" : "BOOKED", "rate_type" : { "code" : "EGENCIA", "name" : "E1D09" }, "point_of_sale" : { "country_code" : "GB" }, "policy_compliance" : { "is_compliant" : true }, "approval_triggered" : false, "egencia_trip_id" : "0600-2504-064", "egencia_trip_link" : "https://www.egencia.eu/trip-webapp/0600-2504-064?auth_gpid=41543", "company" : { "id" : 41543, "name" : "Test Auto Airfusion FR", "organization_parent_id" : 1234567890 }, "travelers" : [ { "id" : 5328422, "first_name" : "Test", "is_guest" : false, "last_name" : "User", "email" : "test.user@example.com", "preferred_language" : "fr" } ], "booker" : { "email" : "test.user@example.com", "first_name" : "Test", "last_name" : "User", "id" : 5328421, "is_agent" : false }, "custom_data_fields" : [ { "label" : "Legal Entity", "value" : "Wise 42" }, { "label" : "Mission number", "value" : "123gdf" } ], "receipt_provision_available" : false, "price" : { "amount" : 46.27, "currency" : "EUR", "cost_to_customer" : 46.27, "breakdowns" : [ { "amount" : 37.33, "currency" : "EUR", "type" : "BASE" }, { "amount" : 8.94, "currency" : "EUR", "type" : "FEES" } ] }, "vehicle" : { "acriss_code" : "MBMR", "mileage_limit" : "UNLIMITED", "name" : "Group A - Fiat 500", "category" : "M" }, "vendor" : { "code" : "ZI", "name" : "Avis" }, "drop_off" : { "date_time" : "2019-11-14T09:00:00.000Z", "location" : { "address" : { "city_name" : "MANCHESTER", "country_code" : "GBR", "country_name" : "Great Britain", "postal_code" : "2345", "street_name" : "manchester street1 manchester street2" }, "code" : "MANCHESTER", "name" : "MANCHESTER airport avis agency", "type" : "ADDRESS" } }, "pick_up" : { "date_time" : "2019-11-13T09:00:00.000Z", "location" : { "address" : { "city_name" : "LONDON", "country_code" : "GBR", "country_name" : "Great Britain", "postal_code" : "TW6 2QA", "street_name" : "LONDON HEATHROW AIRPORT\nLONDON HEATHROW AIRPORT T3-4" }, "code" : "LONDON", "name" : "London airport avis agency", "type" : "ADDRESS" } }, "is_pick_up_delivery" : true, "is_drop_off_collection" : false, "number_of_drivers" : 1, "amenities" : [ "ACD" ], "rules_and_regulations" : { "details" : [ "Guarantee Information\n\nRATE GUARANTEED 108 DAYS FROM BOOKING ", "Extra charge - EUR47.99 per day." ] }, "booking_reference" : "JQPIHQ", "gds_reference" : "22736607DE5", "vendor_reference" : "22736607DE5", "payment_method" : "CREDIT_CARD", "credit_card" : { "first6_digits" : "411111", "last4_digits" : "1111" }, "mission_number" : "123gdf", "booking_date_time" : "2021-09-30T12:35:20.000Z", "_links" : { "self" : { "href" : "https://apis.egencia.eu/openconnect/api/v1/bookings/0600-2504-064/items/6450a5b869d5bd432ab9cca7" }, "trip" : { "href" : "https://www.egencia.eu/trip-webapp/0600-2504-064?auth_gpid=41543" } } } }, "Expense message for a Car cancellation (Agent Assisted, Agency)" : { "description" : "Expense message for a Car cancellation (Agent Assisted, Agency)", "value" : { "uuid" : "d57433e2-a458-4809-86a2-d6bb188f39a1", "expense_id" : "CR-8b2b195f5a0aa462a7da2a4e6660656f1ee4df61", "expense_version" : 2, "point_of_sale" : { "country_code" : "FR" }, "company" : { "id" : 64143, "name" : "caspianTestCompany_FR", "organization_parent_id" : 6556965 }, "travelers" : [ { "id" : 7819084, "first_name" : "Test", "last_name" : "User", "email" : "test.user@example.com", "preferred_language" : "fr", "custom_data_fields" : [ { "label" : "Main cost centre", "value" : "CC1" }, { "label" : "Employee ID", "value" : "2222" } ] } ], "booker" : { "id" : 7805999, "first_name" : "Test", "last_name" : "Agent", "email" : "test.agent@example.com", "is_agent" : true }, "partner" : { "name" : "xxx" }, "price" : { "currency" : "EUR", "amount" : 76.8, "cost_to_customer" : 0.0, "breakdowns" : [ { "type" : "Base price", "currency" : "EUR", "amount" : 48.0 }, { "type" : "Taxes and fees", "currency" : "EUR", "amount" : 28.8 } ], "refunds" : [ { "type" : "Complete Refund", "currency" : "EUR", "amount" : 76.8 } ] }, "egencia_item_id" : "68e67a5a772f0921253cd6f4", "egencia_trip_id" : "2000-3177-352", "egencia_trip_link" : "https://www.egencia.eu/trip-webapp/2000-3177-352?auth_gpid=64143", "approval_triggered" : false, "payment_method" : "PAY_AT_COUNTER", "expense_type" : "CAR", "gds_reference" : "ZJNAOQ (SGP)", "vendor_reference" : "2003153466COUNT", "booking_reference" : "ZJNAOQ", "custom_data_fields" : [ { "label" : "Main cost centre", "value" : "CC1" }, { "label" : "Employee ID", "value" : "2222" } ], "rate_type" : { "name" : "ED2FR", "code" : "EGENCIA" }, "rules_and_regulations" : { "details" : [ "GENERAL SURCHARGE", "ONE WAY CHARGE", "TAX", "COLLISION DAMAGE WAIVER - EUR18.0 per day.", "SUPER PERSONAL ACCIDENT INSURANCE - EUR10.03 per day.", "PERSONAL ACCIDENT INSURANCE - EUR6.02 per day.", "EP - EUR15.0 per day.", "S/DW1 - EUR10.03 per day." ] }, "policy_compliance" : { "is_compliant" : true }, "booking_date_time" : "2025-10-08T00:00:00.000Z", "cancellation_date_time" : "2025-10-20T14:47:55.917Z", "booking_status" : "CANCELLED", "vendor" : { "code" : "ET", "name" : "Enterprise" }, "vehicle" : { "name" : "CITROEN C3 OR SIMILAR", "acriss_code" : "EDMR", "category" : "E", "mileage_limit" : "Unlimited" }, "pick_up" : { "location" : { "type" : "ADDRESS", "code" : "PAR", "address" : { "street_name" : "TERMINAL 1 ET 2 ROISSY APT BP 332 CEDE", "country_code" : "FRA", "city_name" : "ROISSY", "state_province_name" : "J", "postal_code" : "95716" } }, "date_time" : "2025-10-31T09:00:00.000+01:00" }, "drop_off" : { "location" : { "type" : "ADDRESS", "code" : "PAR", "address" : { "street_name" : "AEROGARE ORLY OUEST BP 447", "country_code" : "FRA", "city_name" : "ORLY", "state_province_name" : "J", "postal_code" : "94947" } }, "date_time" : "2025-11-01T13:30:00.000+01:00" }, "number_of_drivers" : 1, "_links" : { "self" : { "href" : "https://apis.egencia.eu/openconnect/api/v1/bookings/2000-3177-352/items/68e67a5a772f0921253cd6f4" }, "trip" : { "href" : "https://www.egencia.eu/trip-webapp/2000-3177-352?auth_gpid=64143" } } } }, "Expense message for a Flight booking (Agent Assisted)" : { "description" : "Expense message for a Flight booking (Agent Assisted)", "value" : { "uuid" : "b49f8299-e779-4897-8914-a3f7b3566a45", "expense_id" : "FT-4f1e0a11d29287683124630f9f8aa996b2ff1e5c", "expense_version" : 3, "point_of_sale" : { "country_code" : "US" }, "company" : { "id" : 64139, "name" : "CaspianUSCompany", "organization_parent_id" : 6556964 }, "travelers" : [ { "id" : 7854234, "first_name" : "Test", "last_name" : "User", "email" : "test.user@example.com", "preferred_language" : "en", "custom_data_fields" : [ ], "is_guest" : false } ], "booker" : { "id" : 7798007, "first_name" : "Test", "last_name" : "Agent", "email" : "test.agent@example.com", "is_agent" : true }, "partner" : { "name" : "xxx" }, "price" : { "currency" : "USD", "amount" : 264.19, "cost_to_customer" : 264.19, "breakdowns" : [ { "type" : "BASE", "currency" : "USD", "amount" : 264.19 }, { "type" : "TAXES", "currency" : "USD", "amount" : 264.19 } ] }, "egencia_item_id" : "6a3170346cd5e06ad2673e0b", "egencia_trip_id" : "0000-3903-531", "egencia_trip_link" : "https://www.egencia.com/trip-webapp/0000-3903-531?auth_gpid=64139", "approval_triggered" : false, "payment_method" : "COMPANY_FORM_OF_PAYMENT", "expense_type" : "FLIGHT", "gds_reference" : "B7MCNC", "vendor_reference" : "B7MCNC", "booking_reference" : "21894966357", "custom_data_fields" : [ ], "policy_compliance" : { "is_compliant" : true }, "booking_date_time" : "2026-06-16T08:48:04.000Z", "receipt_provision_available" : true, "receipt_info" : { "id" : "6a3170c7f91c659fa8355b41", "status" : "AVAILABLE", "version" : 1, "receipt_number" : "21894966357", "receipt_date" : "2026-06-16", "total_amount" : { "currency" : "USD", "amount" : 299.4 }, "payments" : [ { "date" : "2026-06-16", "date_time" : "2026-06-16T15:48:32.422490956", "net_amount" : { "currency" : "USD", "amount" : 299.4 }, "credit_card_info" : { "last4_digits" : "4448", "first6_digits" : "444444", "card_type" : "VISA" }, "breakdowns" : [ { "type" : "BaseFare", "currency" : "USD", "amount" : 264.19, "name" : "BaseFare" }, { "type" : "Taxes", "currency" : "USD", "amount" : 35.21, "name" : "Taxes" } ], "line_type" : "PRODUCT" }, { "date" : "2026-06-16", "date_time" : "2026-06-16T15:48:32.422490956", "net_amount" : { "currency" : "USD", "amount" : 22.0 }, "credit_card_info" : { "last4_digits" : "4448", "first6_digits" : "444444", "card_type" : "VISA" }, "breakdowns" : [ { "type" : "Agent assisted air purchase fee", "currency" : "USD", "amount" : 22.0, "name" : "Agent assisted air purchase fee" } ], "line_type" : "EGENCIA_FEE" } ], "document_type" : "RECEIPT", "traveler_id" : 7854234, "central_bill" : true, "_links" : { "receipt_pdf" : { "href" : "https://apis.egencia.com/openconnect/api/v2/bookings/0000-3903-531/items/6a3170346cd5e06ad2673e0b/receipts/6a3170c7f91c659fa8355b41?traveler_id=7854234" } } }, "booking_status" : "BOOKED", "origin_destinations" : [ { "segments" : [ { "provider" : { "code" : "WN", "name" : "Southwest Airlines" }, "rules_and_regulations" : { "details" : [ "