Emburse expense-controller-v3 API

openapi: 3.0.0
info:
  description: Api Documentation
  version: '1.0'
  title: Api Documentation Accounts expense-controller-v3 API
  termsOfService: urn:tos
  contact: {}
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://service.chromeriver.com
tags:
- name: expense-controller-v3
  description: Retrieve expense reports by filter(s)
paths:
  /v3/expense-reports:
    get:
      tags:
      - expense-controller-v3
      summary: Get list of reports by filter(s)
      description: This web service allows an external application to get a list of expense reports using different criteria
      operationId: getExpenseReportsUsingGET_1
      parameters:
      - name: approverEmailAddress
        in: query
        description: Unique email of the approver making a request
        required: false
        allowEmptyValue: false
        example: emailAddress@gmail.com
        schema:
          type: string
      - name: approverUniqueId
        in: query
        description: Unique ID of the approver making a request
        required: false
        allowEmptyValue: false
        example: personUniqueId
        schema:
          type: string
      - name: approverUserName
        in: query
        description: Unique user-name of the approver making a request
        required: false
        allowEmptyValue: false
        example: userName
        schema:
          type: string
      - name: chain-id
        in: header
        description: Used for tracking the flow of the request
        required: false
        schema:
          type: string
      - name: createDate
        in: query
        description: Filter by reports created this date (yyyy-MM-dd)
        required: false
        allowEmptyValue: false
        example: 2021-03-21
        schema:
          type: string
          format: date-time
      - name: createSource
        in: query
        description: How the report was created
        required: false
        allowEmptyValue: false
        example: AUTOMATIC
        schema:
          type: string
      - name: customer-code
        in: header
        description: Unique customer identifier provided by Chrome River
        required: true
        schema:
          type: string
      - name: exportDate
        in: query
        description: Filter by reports exported this date (yyyy-MM-dd)
        required: false
        allowEmptyValue: false
        example: 2021-03-21
        schema:
          type: string
          format: date-time
      - name: getPDFReport
        in: query
        description: Flag to indicate if PDF report should be included
        required: false
        allowEmptyValue: false
        example: false
        schema:
          type: boolean
          default: false
      - name: getPDFReportWithNotes
        in: query
        description: Flag to indicate if PDF report with notes should be included
        required: false
        allowEmptyValue: false
        example: false
        schema:
          type: boolean
          default: false
      - name: imageFirst
        in: query
        description: Flag to indicate if image should be retrieved first
        required: false
        allowEmptyValue: false
        example: false
        schema:
          type: boolean
          default: false
      - name: includeCollections
        in: query
        description: List of collections to include in the report
        required: false
        allowEmptyValue: false
        explode: true
        schema:
          type: array
          items:
            type: string
          enum:
          - HEADER_COMPLIANCE_ITEMS
          - HEADER_IMAGES
          - LINE_ITEMS
          - HEADER_NOTES
          - HEADER_UDAS
          - LINE_ITEM_MATTERS
          - LINE_ITEM_COMPLIANCE_ITEMS
          - LINE_ITEM_IMAGES
          - LINE_ITEM_CHILDREN
          - LINE_ITEM_NOTES
          - LINE_ITEM_UDAS
          - LINE_ITEM_TRIPS
          - LINE_ITEM_STEPS
          - HEADER_PAYMENT_ACCOUNT
      - name: limit
        in: query
        description: Maximum number of results to return. If no value is passed, it will be taken from the configurable property file, where this value is equal to 10 by default
        required: false
        schema:
          type: ref
      - name: offset
        in: query
        description: The (zero-based) offset of the first item returned in the collection. If no value is passed, it will be taken from the configurable property file, where this value is equal to 10 by default. This value is limited to 100 to ensure reasonable use of system resources.
        required: false
        schema:
          type: ref
      - name: ownerCountryAlpha2
        in: query
        description: Reports owner countryAlpha2
        required: false
        allowEmptyValue: false
        example: US
        schema:
          type: string
      - name: ownerEmailAddress
        in: query
        description: Unique email of the expense owner making a request
        required: false
        allowEmptyValue: false
        example: emailAddress@gmail.com
        schema:
          type: string
      - name: ownerUniqueId
        in: query
        description: Unique ID of the expense owner making a request
        required: false
        allowEmptyValue: false
        example: personUniqueId
        schema:
          type: string
      - name: ownerUserName
        in: query
        description: Unique user-name of the expense owner making a request
        required: false
        allowEmptyValue: false
        example: userName
        schema:
          type: string
      - name: reportStatus
        in: query
        description: Filter by report status
        required: false
        allowEmptyValue: false
        example: Returned
        schema:
          type: string
          enum:
          - Draft
          - Pending Approval
          - Approved
          - Returned
          - Exported
          - Paid
          - Partially Paid
          - Deleted
      - name: submitDate
        in: query
        description: Filter by reports submitted this date (yyyy-MM-dd)
        required: false
        allowEmptyValue: false
        example: 2021-03-21
        schema:
          type: string
          format: date-time
      - name: voucherInvoice
        in: query
        description: Voucher Invoice parameter
        required: false
        allowEmptyValue: false
        schema:
          type: string
      - name: x-api-key
        in: header
        description: API key for Authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json;charset=UTF-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ExpenseReportV3'
        '400':
          description: Customer Code is invalid.
        '401':
          description: Customer Code is not authorized. Cannot get list of expense reports.
        '403':
          description: Logged in user does not exist.
        '503':
          description: Service unavailable.
      deprecated: false
  /v3/expense-reports/{reportId}:
    get:
      tags:
      - expense-controller-v3
      summary: Get expense report details
      description: This web service allows an external application to get details of expense report by ReportID (including reports with deleted status)
      operationId: getExpenseReportUsingGET_3
      parameters:
      - name: chain-id
        in: header
        description: Used for tracking the flow of the request
        required: false
        schema:
          type: string
      - name: customer-code
        in: header
        description: Unique customer identifier provided by Chrome River
        required: true
        schema:
          type: string
      - name: getPDFReport
        in: query
        description: Flag to indicate if PDF report should be included
        required: false
        allowEmptyValue: false
        example: false
        schema:
          type: boolean
          default: false
      - name: getPDFReportWithNotes
        in: query
        description: Flag to indicate if PDF report with notes should be included
        required: false
        allowEmptyValue: false
        example: false
        schema:
          type: boolean
          default: false
      - name: imageFirst
        in: query
        description: Flag to indicate if image should be retrieved first
        required: false
        allowEmptyValue: false
        example: false
        schema:
          type: boolean
          default: false
      - name: reportId
        in: path
        description: Identifier for the expense report.
        required: true
        schema:
          type: string
      - name: voucherInvoice
        in: query
        description: Voucher Invoice parameter
        required: false
        allowEmptyValue: false
        schema:
          type: string
      - name: x-api-key
        in: header
        description: 'API key for Authentication '
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json;charset=UTF-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ExpenseReportV3'
        '400':
          description: Customer Code is invalid.
        '401':
          description: Customer Code is not authorized. Cannot get details of expense report.
        '403':
          description: Logged in user does not exist.
        '404':
          description: Report with provided reportId does not exist.
        '503':
          description: Service unavailable.
      deprecated: false
  /v3/expense-reports/{reportId}/line-items:
    get:
      tags:
      - expense-controller-v3
      summary: Get expense report line item details
      description: This web service allows an external application to get line item details of expense report by ReportID
      operationId: getLineItemsUsingGET
      parameters:
      - name: chain-id
        in: header
        description: Used for tracking the flow of the request
        required: false
        schema:
          type: string
      - name: createDate
        in: query
        description: Filter by line item created this date (yyyy-MM-dd)
        required: false
        allowEmptyValue: false
        example: 2021-04-21
        schema:
          type: string
          format: date-time
      - name: customer-code
        in: header
        description: Unique customer identifier provided by Chrome River
        required: true
        schema:
          type: string
      - name: downloadImages
        in: query
        description: Flag to indicate if images should be downloaded
        required: false
        allowEmptyValue: false
        schema:
          type: boolean
          default: true
      - name: exportDate
        in: query
        description: Filter by line item exported this date (yyyy-MM-dd)
        required: false
        allowEmptyValue: false
        example: 2021-04-21
        schema:
          type: string
          format: date-time
      - name: getMileageCoverPage
        in: query
        description: Voucher Invoice parameter
        required: false
        allowEmptyValue: false
        example: false
        schema:
          type: boolean
          default: false
      - name: getPDFReport
        in: query
        description: Flag to indicate if PDF report should be included
        required: false
        allowEmptyValue: false
        example: false
        schema:
          type: boolean
          default: false
      - name: getPDFReportWithNotes
        in: query
        description: Flag to indicate if PDF report with notes should be included
        required: false
        allowEmptyValue: false
        example: false
        schema:
          type: boolean
          default: false
      - name: imageFirst
        in: query
        description: Flag to indicate if image should be retrieved first
        required: false
        allowEmptyValue: false
        schema:
          type: boolean
          default: true
      - name: limit
        in: query
        description: Maximum number of results to return. If no value is passed, it will be taken from the configurable property file, where this value is equal to 10 by default
        required: false
        schema:
          type: ref
      - name: lineItemStatus
        in: query
        description: Filter by line item status
        required: false
        allowEmptyValue: false
        example: Returned
        schema:
          type: string
          enum:
          - Draft
          - Pending Approval
          - Approved
          - Returned
          - Exported
          - Paid
      - name: offset
        in: query
        description: The (zero-based) offset of the first item returned in the collection. If no value is passed, it will be taken from the configurable property file, where this value is equal to 10 by default. This value is limited to 100 to ensure reasonable use of system resources.
        required: false
        schema:
          type: ref
      - name: reportId
        in: path
        description: reportId
        required: true
        schema:
          type: string
      - name: submitDate
        in: query
        description: Filter by line item submitted this date (yyyy-MM-dd)
        required: false
        allowEmptyValue: false
        example: 2021-04-21
        schema:
          type: string
          format: date-time
      - name: x-api-key
        in: header
        description: 'API key for Authentication '
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json;charset=UTF-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ExpenseReportLineItemV3'
        '400':
          description: Customer Code is invalid.
        '401':
          description: Customer Code is not authorized. Cannot get details of line items.
        '503':
          description: Service unavailable.
      deprecated: false
components:
  schemas:
    Entity:
      type: object
      properties:
        code:
          type: string
          example: 100
          description: Entity code. Max 50 characters
        extraData1:
          type: string
          example: Main
          description: Extra data field. Max 1000 characters
        extraData2:
          type: string
          example: Office
          description: Extra data field. Max 1000 characters
        extraData3:
          type: string
          example: 1000
          description: Extra data field. Max 1000 characters
        extraData4:
          type: string
          example: 900
          description: Extra data field. Max 1000 characters
        extraData5:
          type: string
          example: '0000'
          description: Extra data field. Max 1000 characters
        name:
          type: string
          example: Los Angeles
          description: Name of entity. Max 100 characters
      title: Entity
    PaymentAccount:
      type: object
      properties:
        accountNumberLast4:
          type: string
          example: 9829
          description: Last 4 digits of payment account
        nickName:
          type: string
          example: John's AMEX
          description: Nickname for payment account
      title: PaymentAccount
    MapTripPoint:
      type: object
      properties:
        address:
          type: string
          example: 500 North Wilshire Blvd.
          description: Address. Max 400 characters
        amount:
          type: number
          example: 115.53
          description: Amount spent at trip point
        calculatedMiles:
          type: number
          format: double
          example: 15
          description: Calculated miles distance
        category:
          type: string
          example: Business- Travel
          description: Category of trip. Max 255 characters
        deductionAmount:
          type: number
          example: 15
          description: Deduction amount
        deductionDistance:
          type: number
          format: double
          example: 15
          description: Deduction distance
        distanceUnit:
          type: string
          example: miles
          description: Distance unit of trip calculation
        latitude:
          type: number
          format: double
          example: 30.29048912
          description: Latitude of trip point
        longitude:
          type: number
          format: double
          example: 93.2894802
          description: Longitude of trip point
        miles:
          type: number
          format: double
          example: 15
          description: Miles distance
        personalTrip:
          type: boolean
          example: false
          description: Indicates if this is a personal trip
        roundTrip:
          type: boolean
          example: false
          description: Indicates if this is a round trip
        tripStep:
          type: integer
          format: int32
          example: 1
          description: Which step in trip is this point
          minimum: -128
          maximum: 127
      title: MapTripPoint
    Person:
      type: object
      properties:
        firstName:
          type: string
          example: Smith
          description: Person's last name. Max 100 characters
        lastName:
          type: string
          example: Jacob
          description: Person's first name. Max 100 characters
        personEntities:
          type: array
          description: List of person entities associated with person
          items:
            $ref: '#/components/schemas/PersonEntities'
        personUniqueId:
          type: string
          example: jsmith
          description: Unique identifier for person. Max 100 characters
        primaryEmailAddress:
          type: string
          example: jacob.smith@cpa.org
          description: Person's primary email address. Max 100 characters
        reportsToUniqueId:
          type: string
          example: lkemp
          description: Unique identifier for manager person reports to
        title:
          type: string
          example: Associate Accountant
          description: Person's title. Max 255 characters
        uniquePersonId:
          type: string
      title: Person
    CurrentApprover:
      type: object
      properties:
        assignedDate:
          type: string
          format: date-time
          description: Date line item was assigned to approver
        emailAddress:
          type: string
          example: larry.kemp@crane.com
          description: Email address of current approver. Max 100 characters
        firstName:
          type: string
          example: Larry
          description: First name of current approver. Max 50 characters
        lastName:
          type: string
          example: Kemp
          description: Last name of current approver. Max 50 characters
        personUniqueId:
          type: string
          example: lkemp
          description: Person unique ID of current approver. Max 100 characters
        title:
          type: string
          example: Sr. Manager
          description: Title of current approver. Max 255 characters
      title: CurrentApprover
    PaLineItemType:
      type: object
      properties:
        externalRef:
          type: string
          example: 4320
          description: Reference to an external system's expense types. Max 50 characters
        id:
          type: integer
          format: int32
          example: 1398
          description: Internal ID of preapproval line item
        name:
          type: string
          example: Airfare
          description: Expense type of preapproval line item. Max 50 characters
        type:
          type: string
          example: LineItem
          enum:
          - LineItem
          - Header
      title: PaLineItemType
    ExpenseReportLineItemPersonGuest:
      type: object
      properties:
        amount:
          type: number
          example: 11.98
          description: Amount of expense spent by/for guest
        company:
          type: string
          example: CFA Consultants
          description: Company of guest. Max 100 characters
        firstName:
          type: string
          example: Jennifer
          description: First name of guest. Max 100 characters
        guestType:
          type: string
          example: InternalGuest
          description: Type of guest
          enum:
          - InternalGuest
          - ExternalGuest
          - HealthCareProvider
          - TemporaryHealthCareProvider
          - CRMGuest
        lastName:
          type: string
          example: Garth
          description: Last name of guest. Max 100 characters
        percentage:
          type: number
          example: 10
          description: Percentage of expense spent by/for guest
        title:
          type: string
          example: Legal Consultant
          description: Title of guest. Max 255 characters
      title: ExpenseReportLineItemPersonGuest
    Mileage:
      type: object
      properties:
        carPlanModifierGroup:
          type: string
          example: Passengers_CA
          description: Car plan modifier group. Max 20 characters
        carPlanName:
          type: string
          example: US Personal Car
          description: Name of car plan. Max 50 characters
        carPlanTierName:
          type: string
          example: < 1000 KM
          description: Name of car plan tier. Max 50 characters
        mapImageURL:
          type: string
        rate:
          type: number
          example: 50
          description: Rate of mileage
        trips:
          type: array
          description: List of trip points
          items:
            $ref: '#/components/schemas/MapTripPoint'
      title: Mileage
    ExpenseReportLineItemV3:
      type: object
      properties:
        allocations:
          type: array
          description: List of allocations selected for line item
          items:
            $ref: '#/components/schemas/LineItemAllocation'
        amountApproved:
          type: number
          example: 0
          description: Amount approved due to expense owner
        amountCustomer:
          type: number
          example: 0
          description: AmountSpent * customer's exchange rate
        amountSpent:
          type: number
          example: 119.81
          description: Amount spent of line item
        amountSpentConverted:
          type: number
          example: 119.81
          description: Amount spent of line item converted to customer currency code
        amountSpentPersonal:
          type: number
          example: 0
          description: Amount of line item due to personal expenses
        businessPurpose:
          type: string
          example: Conference
          description: Business purpose of expense. Max 2500 characters
        childLineItemIds:
          type: array
          description: List of line item IDs for child expenses. Used for hotel items.
          items:
            type: string
        children:
          type: array
          description: List of child expenses. Used for hotel items.
          items:
            $ref: '#/components/schemas/ExpenseReportLineItemV3'
        comments:
          type: array
          description: List of comments attached to line item
          items:
            $ref: '#/components/schemas/Comment'
        complianceItems:
          type: array
          description: List of compliance issues associated with the line item
          items:
            $ref: '#/components/schemas/ComplianceItem'
        createDate:
          type: string
          format: date-time
          example: 2022-01-03 05:53:39:000
          description: Date expense line item was created on report
        currencyCustomer:
          type: string
          example: USD
          description: Customer's default ISO-4217 currency code
        currencySpent:
          type: string
          example: USD
          description: ' ISO-4217 Currency code spent'
        currencySpentApproved:
          type: string
          example: USD
          description: Currency code approved
        currencySpentConverted:
          type: string
        currencySpentPersonal:
          type: string
          example: USD
          description: Currency of personal expenses (ISO-4217)
        currentApprover:
          type: array
          description: List of current approvers where line item is pending
          items:
            $ref: '#/components/schemas/CurrentApprover'
        description:
          type: string
          example: Flight to St. Louis
          description: Description of expense. Max 2500 characters
        expenseItemType:
          type: string
          example: Breakfast
          description: Expense category of line item. Max 50 characters
        expenseItemTypeDisplayName:
          type: string
          example: Meal - Breakfast
          description: Display name of expense category of line item. Max 50 characters
        expenseItemTypeIcon:
          type: string
          example: coffee.png
          description: File name of icon that represents the item type of this line item
        expenseTransactions:
          $ref: '#/components/schemas/ExpenseTransaction'
        exportDate:
          type: string
          format: date-time
          example: 2022-01-04 05:53:39:000
          description: Date expense line item was exported
        exportStatus:
          type: string
          example: Exported
          description: Export status of line item
          enum:
          - In Export
          - Waiting for Export
          - Exported
          - Paid
          - Partially Paid
        feed:
          $ref: '#/components/schemas/FeedDetail'
        firmPaid:
          type: boolean
        guests:
          type: array
          description: List of guests for line item
          items:
            $ref: '#/components/schemas/ExpenseReportLineItemPersonGuest'
        hasReceipt:
          type: boolean
          example: true
          description: Is a receipt attached
        hasTaxReceipt:
          type: boolean
          example: true
          description: Is a tax receipt attached
        imagesUrl:
          type: string
          example: file:///receipts/receipt2.pdf
          description: Images url attached to line item
        lineItemId:
          type: string
          example: b0dd069a-ce1a-45bf-b9dd-48cac24735ff
          description: Internal ID of expense report line item. 36 characters
        lineItemStatus:
          type: string
          example: Pending Approval
          description: NULL for parent line items (parent == true)
          enum:
          - Draft
          - Pending Approval
          - Approved For Payment
          - Returned
          - Exported
          - Paid
          - Partially Paid
        lineNumber:
          type: integer
          format: int32
          example: 1
          description: Used for primary or parent expenses.
        lineNumber2:
          type: integer
          format: int32
          example: 1.1
          description: This column is used exclusively for hotel (child) expenses.
        merchant:
          type: string
          description: Name of merchant/vendor of line item
        mileageDetails:
          $ref: '#/components/schemas/Mileage'
        paLineItemType:
          $ref: '#/components/schemas/PaLineItemType'
        parent:
          type: boolean
        parentId:
          type: string
        perDiemLineItem:
          $ref: '#/components/schemas/PerDiemLineItem'
        personal:
          type: boolean
        previousApprover:
          type: array
          description: List of previous approvers of line item
          items:
            $ref: '#/components/schemas/PreviousApprover'
        transactionDate:
          type: string
          format: date-time
          example: 2022-01-03 05:53:39:000
          description: Date of transaction
        udas:
          type: array
          description: List of line item user defined attributes
          items:
            $ref: '#/components/schemas/UserDefinedAttribute'
        updateDate:
          type: string
          format: date-time
          example: 2022-01-03 05:53:39:000
          description: Date expense line item was last updated on report
        vatAmount:
          type: number
          example: 5.99
          description: Amount of VAT tax
        vatAmount2:
          type: number
          example: 5.99
          description: Amount of 2nd VAT tax
        vatAmount3:
          type: number
          example: 5.99
          description: Amount of 3rd VAT tax
        vatAmountApplied:
          type: number
          example: 5.99
          description: VAT amount applied to expense
        vatAmountApplied2:
          type: number
          example: 5.99
          description: VAT amount applied to expense
        vatAmountApplied3:
          type: number
          example: 5.99
          description: VAT amount applied to expense
        vatAmountAppliedRemainder:
          type: number
          example: 5.99
          description: Remainder of VAT amount applied
        vatAmountAppliedRemainder2:
          type: number
          example: 5.99
          description: Remainder of VAT amount applied
        vatAmountAppliedRemainder3:
          type: number
          example: 5.99
          description: Remainder of VAT amount applied
        vatAmountEntered:
          type: number
          example: 5.99
          description: VAT amount as entered by user
        vatAmountEntered2:
          type: number
          example: 5.99
          description: VAT amount as entered by user
        vatAmountEntered3:
          type: number
          example: 5.99
          description: VAT amount as entered by user
        vatLocation:
          type: string
          example: Canada
          description: Location of VAT taxation. Max 50 characters
        vatTaxPercentage:
          type: number
          example: 5
          description: Rate of VAT tax
        vatTaxPercentage2:
          type: number
          example: 5
          description: Rate of 2nd VAT tax
        vatTaxPercentage3:
          type: number
          example: 5
          description: Rate of 3rd VAT tax
        vatTaxPercentageReclaim:
          type: number
          example: 100
          description: Rate of VAT refund
        vatTaxPercentageReclaim2:
          type: number
          example: 100
          description: Rate of VAT refund for 2nd VAT tax code
        vatTaxPercentageReclaim3:
          type: number
          example: 100
          description: Rate of VAT refund for 3rd VAT tax code
        voucherInvoice:
          type: string
          example: '0000006010110241'
          description: Voucher invoice number associated with the line item. Max 20 characters
      title: ExpenseReportLineItemV3
    ExpenseReportLineItem:
      type: object
      properties:
        allocations:
          type: array
          description: List of allocations selected for line item
          items:
            $ref: '#/components/schemas/LineItemAllocation'
        amount:
          type: number
          example: 119.81
          description: Amount of line item
        amountApproved:
          type: number
          example: 119.81
          description: Approved amount due to expense owner
        amountCustomer:
          type: number
          example: 0
          description: AmountSpent * customer's exchange rate
        amountSpent:
          type: number
          example: 119.81
          description: Amount spent of line item
        approvalStatus:
          type: string
          example: Pending Approval
          description: NULL for parent line items (parent == true)
          enum:
          - Draft
          - Pending Approval
          - Approved For Payment
          - Returned
          - Exported
          - Paid
          - Partially Paid
        businessPurpose:
          type: string
          example: Conference
          description: Business purpose of expense. Max 2500 character

# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/emburse/refs/heads/main/openapi/emburse-expense-controller-v3-api-openapi.yml