American Express Global Business Travel Expense SPI API

openapi: 3.2.0
info:
  description: "<h1>Introduction to the Document</h1>\n<p>This document provides a reference to the Expense SPI. This document includes a series of notes and instructions that outline the Expense SPI.</p>\n<h2>Audience</h2>\n<p>This document is aimed for the Egencia Expense SPI customers, partners and software developers who would like to consume the Expense SPI.</p>\n<h2>Overview</h2>\n<p>The 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.</p>\n\n<h1>Expense SPI</h1>\n\n<p>Egencia 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. </p>\n<ol>\n    <li>When a booking is created or updated in Egencia the Expense SPI will push a message to the connected Partner system (web service).</li>\n    <li>The web service to consume this data has to be built by the client consumer. This web service allows Egencia to notify the partner when a booking is created or updated in the Egencia tools by sending the booking details.</li>\n    <li>The web service returns a success message if the message has been taken into account or not. </li>\n</ol>\n\n<h2>Authentication</h2>\n\n<h3><u>API Key Authentication scheme</u></h3>\n\n<p>The 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.</p>\n<p>The 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.</p>\n<p>You 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.</p>\n\n<h2>URI Scheme</h2>\n<div>\n    <table style=\"width:50%; border-spacing:5px\"  border=\"1\" cellpadding=\"5px\">\n        <tbody>\n            <tr >\n                <th style=\"padding:10px;text-align: left;\">Request Method</th>\n                <td style=\"padding:10px;\">POST</td>\n            </tr>\n            <tr>\n                <th style=\"padding:10px;text-align: left;\">Host</th>\n                <td style=\"padding:10px;\">any.client-of-expense.com</td>\n            </tr>\n            <tr>\n                <th style=\"padding:10px;text-align: left;\">Base path</th>\n                <td style=\"padding:10px;\">/some.base.path</td>\n            </tr>\n            <tr>\n                <th style=\"padding:10px;text-align: left;\">Schemes</th>\n                <td style=\"padding:10px;\">HTTP, HTTPS</td>\n            </tr>\n        </tbody>\n    </table>\n</div>\n\n<h2>Security</h2>\n<p>Below are the supported authentication mechanisms by the SPI</p>\n<div>\n    <table style=\"width:50%; border-spacing:5px\"  border=\"1\" cellpadding=\"5px\">\n        <thead>\n            <tr >\n                <th style=\"padding:10px;\">Type</th>\n                <th style=\"padding:10px;\">Name</th>\n                <th style=\"padding:10px;\">In</th>\n            </tr>\n        </thead>\n        <tbody>\n            <tr>\n                <td style=\"padding:10px;\">Api Key</td>\n                <td style=\"padding:10px;\">x-api-key</td>\n                <td style=\"padding:10px;\">Header</td>\n            </tr>\n        </tbody>\n    </table>\n</div>\n\n<h2>Versioning</h2>\n<p>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.</p>\n<h3>Version Change Log</h3>\n<p>You can also see a full API version change log under this heading.</p>\n<div>\n    <table style=\"width:50%; border-spacing:5px\"  border=\"1\" cellpadding=\"5px\">\n        <thead>\n            <tr >\n                <th style=\"padding:10px;\">API</th>\n                <th style=\"padding:10px;\">Current Version</th>\n                <th style=\"padding:10px;\">What has changed?</th>\n            </tr>\n        </thead>\n        <tbody>\n        <tr>\n                <td style=\"padding:10px;\">Expense SPI</td>\n                <td style=\"padding:10px;\">Version 1</td>\n                <td style=\"padding:10px;\">First stable version.</td>\n            </tr>\n        </tbody>\n    </table>\n</div>\n\n<h2>Expense SPI Details</h2>"
  title: Expense SPI API
  version: v1.0
servers:
- url: https://apis.egencia.com/openconnect-expensestream-service
  description: Generated server url
tags:
- description: Push Expense and Subscription Operation. This is only an example. The path and the host are specific for each implementor. However, the model is fixed and versioned.
  name: Expense SPI
paths:
  /some.base.path/some.path:
    post:
      description: '<p>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.</p>

        '
      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

                            LONDON 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


                        RATE 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:
                          - <ul><li><b>Before Departure</b><ul><li>Changeable without penalty.</li><li>Refundable without penalty.</li></ul></li></ul>
                        rate_type:
                          name: PUBLIC
                          code: PUBLIC
                        status: BOOKED
                        co2_emission:
                          value: 618
                          unit: LB
                          equivalencies:
                          - type: SMART_PHONE_CHARGES
                            value: 35840.0
                          - type: HOMES_ELECTRICITY
                            value: 0.06
                          - type: SMARTPHONE_CHARGES
                            value: 35840.0
                          - type: HOME_ELECTRICITY
                            value: 0.06
                          - type: DISTANCE_DRIVEN_BY_CAR
                            value: 700.0
                        booking_class: Economy
                        departure:
                          location:
                            type: AIRPORT
                            code: HOU
                            name: Houston, TX, United States of America (HOU-William P. Hobby)
                            address:
                              country_code: US
                              city_name: Houston
                          date_time: '2026-09-08T09:35:00.000-05:00'
                        arrival:
                          location:
                            type: AIRPORT
                            code: LAX
                            name: Los Angeles, CA, United States of America (LAX-Los Angeles Intl.)
                            address:
                              country_code: US
                              city_name: Los Angeles
                          date_time: '2026-09-08T11:05:00.000-07:00'
                        operating_carrier:
                          name: Southwest Airlines
                          code: WN
                          number: '1942'
                          low_cost_carrier: false
                        marketing_carrier:
                          name: Southwest Airlines
                          code: WN
                          number: '1942'
                          low_cost_carrier: false
                        traveler_segment_info:
                        - traveler_id: 7854234
                          ticket:
                            number: '5262150903018'
                    ticket_number:
                    - '5262150903018'
                    _links:
                      self:
                        href: https://apis.egencia.com/openconnect/api/v1/bookings/0000-3903-531/items/6a3170346cd5e06ad2673e0b
                      trip:
                        href: https://www.egencia.com/trip-webapp/0000-3903-531?auth_gpid=64139
                      receipt:
                        href: https://apis.egencia.com/openconnect/api/v2/bookings/0000-3903-531/items/6a3170346cd5e06ad2673e0b/receipts
                Expense message for a Flight booking (MultiCity):
                  description: Expense message for a Flight booking (MultiCity)
                  value:
                    uuid: 6ac27d6b-dc68-47fa-a9be-42795e5937b5
                    expense_id: FT-752942dc3b52d6d6a0cecb44020e102c153c59ee
                    expense_version: 4
                    point_of_sale:
                      country_code: US
                    company:
                      id: 64139
                      name: CaspianTestUSCompany
                      organization_parent_id: 6556964
                    travelers:
                    - id: 7805149
                      first_name: Test
                      last_name: User
                      email: test.user@example.com
                      preferred_language: en
                      custom_data_fields: []
                    booker:
                      id: 7805149
                      first_name: Test
                      last_name: User
                      email: test.user@example.com
                      is_agent: false
                    partner:
                      name: xxx
                    price:
                      currency: USD
                      amount: 1031.59
                      cost_to_customer: 1031.59
                      breakdowns:
                      - type: BASE
                        currency: USD
                        amount: 911.43
                      - type: TAXES
                        currency: USD
                        amount: 120.16
                      - type: CC_FEES
                        currency: USD
                        amount: 0.0
                    egencia_item_id: 68efb8024b169cd84f931833
                    egencia_trip_id: 0000-3673-471
                    egencia_trip_link: https://www.egencia.com/trip-webapp/0000-3673-471?auth_gpid=64139
                    approval_triggered: false
                    payment_method: COMPANY_FORM_OF_PAYMENT
                    credit_card:
                      last4_digits: '4242'
                      first6_digits: '424242'
                    expense_type: FLIGHT
                    gds_reference: ENPQZD
                    vendor_reference: KFQLGB
                    booking_reference: '21876264442'
                    custom_data_fields: []
                    policy_compliance:
                      is_compliant: true
                    booking_date_time: '2025-10-15T00:00:00.000Z'
                    cancellation_date_time: '2025-10-17T11:46:38.933Z'
                    receipt_info:
                      id: '112576'
                      status: AVAILABLE
                      version: 4
                      document_type: RECEIPT
                      _links:
                        receipt_pdf:
                          href: https://apis.egencia.com/openconnect/api/v1/bookings/0000-3673-471/items/68efb8024b169cd84f931833/receipts
                    booking_status: CANCELLED
                    origin_destinations:
                    - segments:
                      - provider:
                          code: AS
                          name: Alaska Airlines
                        rules_and_regulations:
                          details:
                          - '<ul><li><b>Before Departure</b><ul><li>Changeable without penalty</li><li>Refundable with a penalty: $737.00.</li></ul></li></ul>'
                        rate_type:
                          name: EGENCIA
                          code: EGENCIA
                        status: CANCELLED
                        co2_emission:
                          value: 1013
                          unit: LB
                          equivalencies:
                          - type: SMART_PHONE_CHARGES
                            value: 58752.0
                          - type: HOMES_ELECTRICITY
                            value: 0.09
                          - type: SMARTPHONE_CHARGES
                            value: 58752.0
                          - type: HOME_ELECTRICITY
                            value: 0.09
                          - type: DISTANCE_DRIVEN_BY_CAR
                            value: 1147.5
                        booking_class: Economy
                        departure:
                          location:
                            type: AIRPORT
                            code: JFK
                            name: New York, NY, United States of America (JFK-John F. Kennedy Intl.)
                            address:
                              country_code: US
                              city_name: New York
                          date_time: '2026-08-05T10:00:00.000-04:00'
                        arrival:
                          location:
                            type: AIRPORT
                            code: SAN
                            name: San Diego, CA, United States of America (SAN-San Diego Intl.)
                            address:
                              country_code: US
                              city_name: San Diego
                          date_time: '2026-08-05T12:54:00.000-07:00'
                        operating_carrier:
                          name: Alaska Airlines
                          code: AS
                          number: '35'
                          low_cost_carrier: false
                        marketing_carrier:
                          name: Alaska Airlines
                          code: AS
                          number: '35'
                          low_cost_carrier: false
                        traveler_segment_info:
                        - traveler_id: 7805149
                          ticket:
                            number: 0277340678555
                      - provider:
                          code: AS
                          name: Alaska Airlines
                        rules_and_regulations:
                          details:
                          - '<ul><li><b>Before 05-Aug-2026 14:00</b><ul><li>Changeable without penalty</li><li>Refundable with a penalty: $737.00.</li></ul></li></ul>'
                        rate_type:
                          name: EGENCIA
                          code: EGENCIA
                        status: CANCELLED
                        co2_emission:
                          value: 363
                          unit: LB
                          equivalencies:
                          - type: SMART_PHONE_CHARGES
                            value: 21120.0
                          - type: HOMES_ELECTRICITY
                            value: 0.03
                          - type: SMARTPHONE_CHARGES
                            value: 21120.0
                          - type: HOME_ELECTRICITY
                            value: 0.03
                          - type: DISTANCE_DRIVEN_BY_CAR
                            value: 412.5
                        booking_class: Economy
                        departure:
                          location:
                            type: AIRPORT
                            code: SAN
                            name: San Diego, CA, United States of America (SAN-San Diego Intl.)
                            address:
                              country_code: US
                              city_name: San Diego
                          date_time: '2026-08-05T16:49:00.000-07:00'
                        arrival:
                          location:
                            type: AIRPORT
                            code: SFO
                            name: San Francisco, CA, United States of America (SFO-San Francisco Intl.)
                            address:
                              country_code: US
                              city_name: San Francisco
                          date_time: '2026-08-05T18:29:00.000-07:00'
                        operating_carrier:
                          name: Alaska Airlines
                          code: AS
                          number: '3473'
                          low_cost_carrier: false
                        marketing_carrier:
                          name: Alaska Airlines
                

# --- truncated at 32 KB (186 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/amex-gbt/refs/heads/main/openapi/amex-gbt-expense-spi-api-openapi.yml