Emburse expense-controller-v1 API

openapi: 3.0.0
info:
  description: Api Documentation
  version: '1.0'
  title: Api Documentation Accounts expense-controller-v1 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-v1
  description: Retrieve expense report information and create draft expense reports
paths:
  /v1/expense-reports:
    get:
      tags:
      - expense-controller-v1
      summary: Get list of reports summary by expense owner
      description: This web service allows an external application to fetch a list of report summaries by owner. This excludes deleted reports of the owner
      operationId: getExpenseReportsUsingGET
      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: expenseOwnerId
        in: query
        description: Unique ID for the owner of the expense report. Either expenseOwnerId or (header) logged-in-user-id is required.
        required: false
        allowEmptyValue: false
        schema:
          type: string
      - name: logged-in-user-id
        in: header
        description: logged-in-user-id
        required: 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:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ExpenseReport'
        '400':
          description: Customer Code is invalid
        '401':
          description: Customer Code is not authorized.
        '403':
          description: Logged in user does not exist.
        '503':
          description: Service unavailable.
      deprecated: false
    post:
      tags:
      - expense-controller-v1
      summary: Create a draft expense report
      description: This web service allows an external application to create a draft expense report.
      operationId: createExpenseReportUsingPOST
      parameters:
      - name: chain-id
        in: header
        description: Reference used to track the flow of the request
        required: false
        schema:
          type: string
      - name: creator-user-id
        in: header
        description: Unique ID of expense creator
        required: false
        schema:
          type: string
      - name: customer-code
        in: header
        description: Unique customer identifier provided by Chrome River
        required: true
        schema:
          type: string
      - name: logged-in-user-id
        in: header
        description: Unique ID of expense owner
        required: true
        schema:
          type: string
      - name: x-api-key
        in: header
        description: 'API key for Authentication '
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExpenseReportHeaderCreateModel'
        description: Expense report to create
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Customer Code is invalid.
        '401':
          description: Customer Code is not authorized. Cannot create expense report.
        '402':
          description: Expense draft report cannot be created.
        '503':
          description: Service unavailable.
      deprecated: false
  /v1/expense-reports/{reportId}:
    get:
      tags:
      - expense-controller-v1
      summary: Get details of report
      description: This web service allows an external application to fetch details of a report.
      operationId: getExpenseReportUsingGET_2
      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: expenseOwnerId
        in: query
        description: Unique ID for the owner of the expense report.
        required: true
        allowEmptyValue: false
        schema:
          type: string
      - name: reportId
        in: path
        description: Identifier for the expense report.
        required: true
        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:
              schema:
                $ref: '#/components/schemas/ExpenseReport'
        '400':
          description: Customer Code is invalid.
        '401':
          description: Customer Code is not authorized.
        '403':
          description: Expense owner does not exist.
        '503':
          description: Service unavailable.
      deprecated: false
  /v1/expense-reports/{reportId}/line-items:
    delete:
      tags:
      - expense-controller-v1
      summary: Delete an expense report line item
      description: This web service allows an external application to delete the specified expense report line item.
      operationId: deleteExpenseReportLineItemUsingDELETE
      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: externalTransactionId
        in: query
        description: External transaction ID for transaction
        required: true
        allowEmptyValue: false
        schema:
          type: string
      - name: logged-in-user-id
        in: header
        description: Unique ID for the user logged in making request
        required: true
        schema:
          type: string
      - name: reportId
        in: path
        description: Report ID for report
        required: true
        schema:
          type: string
      - name: x-api-key
        in: header
        description: 'API key for Authentication '
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content. Item successfully deleted
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Cannot delete line item for expense report in this status
        '401':
          description: Customer Code is not authorized.  Cannot submit expense report.
        '403':
          description: Logged in user is not authorized to delete item or Logged in user does not exist.
        '404':
          description: Expense report line item does not exist for this report
        '503':
          description: Service unavailable.
      deprecated: false
  /v1/expense-reports/{reportId}/notes:
    post:
      tags:
      - expense-controller-v1
      summary: Add a note to an expense report
      description: This web service allows an external application to add a note to an expense report.
      operationId: createExpenseHeaderNoteUsingPOST
      parameters:
      - name: chain-id
        in: header
        description: Reference used to track 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: logged-in-user-id
        in: header
        description: Unique ID of the user logged in making request
        required: false
        schema:
          type: string
      - name: reportId
        in: path
        description: reportId
        required: true
        schema:
          type: string
      - name: x-api-key
        in: header
        description: 'API key for Authentication '
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExpenseHeaderNote'
        description: Expense report Note object to be added
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Customer Code is invalid.
        '401':
          description: Customer Code is not authorized. Cannot create expense report.
        '402':
          description: Expense draft report cannot be created.
        '503':
          description: Service unavailable.
      deprecated: false
  /v1/expense-reports/{reportId}/tracking:
    get:
      tags:
      - expense-controller-v1
      summary: Get expense report tracking details
      description: Returns routing and approval tracking details for the specified expense report.
      operationId: getReportForTrackingUsingGET
      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: reportId
        in: path
        description: Identifier for the expense report.
        required: true
        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:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ExpenseRoutingTrackingItem'
        '400':
          description: Customer Code is invalid.
        '401':
          description: Customer Code is not authorized.
        '403':
          description: User is not authorized to use this endpoint.
        '404':
          description: Expense report does not exist.
        '503':
          description: Service unavailable.
      deprecated: false
  /v1/open-expense-reports:
    get:
      tags:
      - expense-controller-v1
      summary: Get list of open expense reports
      description: This web service allows an external application to fetch open expense reports.
      operationId: getOpenExpenseReportsUsingGET
      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: x-api-key
        in: header
        description: 'API key for Authentication '
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OpenExpenseReport'
        '400':
          description: Customer Code is invalid
        '401':
          description: Customer Code is not authorized.
        '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
    ExpenseReportHeaderCreateModel:
      type: object
      required:
      - currencyCode
      - reportName
      properties:
        currencyCode:
          type: string
          example: USD
          description: Employee's PayMeInCurrency. ISO-4217
        reportName:
          type: string
          example: Trip to New Orleans 6/6-6/9
          description: Name of expense report. Max 45 characters
        transactionGroupId:
          type: integer
          format: int32
          example: 1
          description: Field used to associate an Expense Transactions Group with the report.
      title: ExpenseReportHeaderCreateModel
    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
    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
    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 characters
        children:
          type: array
          description: List of child expenses. Used for hotel items.
          items:
            $ref: '#/components/schemas/ExpenseReportLineItem'
        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
        currencyCodeCustomer:
          type: string
          example: USD
          description: Customer's default ISO-4217 currency code
        currencySpent:
          type: string
          example: USD
          description: ' ISO-4217 Currency code spent'
        currentApprovers:
          type: array
          description: List of approvers where line item is currently pending
          items:
            $ref: '#/components/schemas/Person'
        description:
          type: string
          example: Flight to St. Louis
          description: Description of expense. Max 2500 characters
        expenseItemType:
          type: string
          example: Airfare
          description: Expense category of line item. Max 50 characters
        exportStatus:
          type: string
          example: Exported
          description: Export status of line item
          enum:
          - In Export
          - Waiting for Export
          - Exported
          - Paid
          - Partially Paid
        feedCode:
          type: string
          example: CreditCardAmex
          description: Name of feed for expense transaction
        feedName:
          type: string
          example: Amex Corporate Card
          description: Name of feed for expense transaction
        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
        id:
          type: string
          example: b0dd069a-ce1a-45bf-b9dd-48cac24735ff
          description: Internal ID of expense report line item. 36 characters
        images:
          type: array
          description: Filenames of images attached to this line item
          items:
            type: string
        isCreditCard:
          type: boolean
          example: true
          description: Returns true if feed of expense transaction is a credit card feed
        paLineItemType:
          $ref: '#/components/schemas/PaLineItemType'
        parent:
          type: boolean
        perDiemLineItem:
          $ref: '#/components/schemas/PerDiemLineItem'
        personal:
          type: boolean
        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
        vatTaxCode:
          type: string
          example: GST
          description: VAT tax code. Max 10 characters
        vatTaxCode2:
          type: string
          example: HST
          description: VAT tax code 2. Max 10 characters
        vatTaxCode3:
          type: string
          example: PST
          description: VAT tax code 3. Max 10 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
      title: ExpenseReportLineItem
    ExpenseReport:
      type: object
      properties:
        budgetDetails:
          type: array
          description: Details of budget encumbrance/liquidation amounts associated with the preapproval attached to the report. Only relevant for customers using encumbrance/liquidation.
          items:
            $ref: '#/components/schemas/BudgetDetail'
        comments:
          type: array
          description: List of comments written on the expense report
          items:
            $ref: '#/components/schemas/Comment'
        complianceItems:
          type: array
          description: List of compliance item issues associated with the expense report
          items:
            $ref: '#/components/schemas/ComplianceItem'
        createDate:
          type: string
          format: date-time
          example: 2022-01-12 03:34:32:000
          description: Date expense report was created
        currencyCode:
          type: string
          example: USD
          description: Employee's PayMeInCurrency
        expenseReportUrl:
          type: string
          example: https://app.chromeriver.com/expense_reports_app/DEV034334052?customerCode=CF7H
          description: URL of expense report
        hasComplianceItems:
          type: boolean
          example: false
          description: Used in expense-report-approval summaries to notify if header, line item, or children items have compliance items
        images:
          type: array
          description: Filenames of images attached to expense report header
          items:
            type: string
        lineItems:
          type: array
          description: List of expense report line items
          items:
            $ref: '#/components/schemas/ExpenseReportLineItem'
        numberOfExpenseLineItems:
          type: integer
          format: int32
          example: 1
          description: Number of expense items in report
        preApprovalReportId:
          type: string
          example: 010038294829
          description: 12 character ID of preapproval attached to expense report
        receiptUrl:
          type: string
          example: https://chromeriver.com/v2/expense-report-receipts/010034331701?customerCode=ABCD
          description: URL of receipt attached to report
        reportId:
          type: string
          example: 010083927384
          description: 12 character ID of expense report
        reportName:
          type: string
          example: Trip to St. Louis 9/19-9/20
          description: Name of expense report. Max 45 characters
        reportOwner:
          $ref: '#/components/schemas/Person'
        reportStatus:
          type: string
          example: Submitted
          description: Status of expense report
          enum:
          - New
          - Draft
          - Submitted
          - Deleted
          - Returned
        reportTotalAmount:
          type: number
          example: 119.81
          description: Total of expenses in report
        reportTotalAmountApproved:
          type: number
          example: 119.81
          description: Total of approved expenses in report
        reportTotalFirmPaidAmount:
          type: number
          example: 119.81
          description: Total of firm paid expenses in report
        reportTotalPayMeAmount:
          type: number
          example: 119.81
          description: Total of amount due to expense owner
        submitDate:
          type: string
          format: date-time
          example: 2022-01-12 05:34:32:000
          description: Date expense report was submitted
        transactionGroupReferenceNumber:
          type: string
          example: IBQRNA1
          description: Expense transaction group reference number associated with the expense report. Max 255 characters
        udas:
          type: array
          description: Returned on GET requests. POST/PATCH/PUT requests with this field will result in a BAD_REQUEST
          items:
            $ref: '#/components/schemas/UserDefinedAttribute'
        updateDate:
          type: string
          format: date-time
          example: 2022-01-12 05:34:32:000
          description: Date expense report was last updated
      title: ExpenseReport
    PerDiemLineItem:
      type: object
      properties:
        additionalDeductionAmount:
          type: number
          example: 0
          description: Any additional amounts that need to be deducted not covered by the itemized line items
        address:
          type: string
          example: 5700 Olympic Blvd
          description: Address for expense. Max 400 characters
        allowableAmount:
          type: number
        alocholAmount:
          type: number
        amountPerDiem:
          type: number
          example: 150
          description: Amount of per diem expense
        baseRate:
          type: number
        breakfastAmountIMR:
          type: number
          example: 11
          description: Individual meal rate- breakfast
        breakfastDeductionAmount:
          type: number
          example: 0
          description: Amount of breakfast deduction
        city:
          type: string
          example: Los Angeles
          description: City of expense. Max 100 characters
        country:
          type: string
          example: United States
          description: Country of expense. Max 50 characters
        county:
          type: string
          example: Los Angeles County
          description: County of expense. Max 100 characters
        currencyCode:
          type: string
          example: USD
          description: Currency code of per diem line item. ISO-4217
        dinnerAmountIMR:
          type: number
          example: 22
          description: Individual meal rate- dinner
        dinnerDeductionAmount:
          type: number
          example: 0
          description: Amount of dinner deduction
        endDate:
          type: string
          format: date-time
          description: End date of per diem expense
        foodAmount:
          type: number
        foodOverage:
          type: number
        incidentalDeductionAmount:
          type: number
          example: 0
          description: The dollar amount of any incidental per diem allowance
        isArriveNextDay:
          type: boolean
          example: false
          description: Indicates whether traveller will arrive the following day
        isArrivePreviousDay:
          type: boolean
          example: false
          description: Indicates if person arrived previous day
        isBreakfastDeducted:
          type: boolean
          example: false
          description: Indicates if breakfast deduction is taken
        isDinnerDeducted:
          type: boolean
          example: false
          description: Indicates if dinner deduction is taken
        isDiscardedDay:
          type: boolean
        isFullTravelDay:
          type: boolean
          example: false
          description: Indicates whether travel is full day
        isLodgingDeducted:
          type: boolean
          example: false
          description: Indicates if lodging is deducted
        isLunchDeducted:
          type: boolean
          example: false
          description: Indicates if lunch deduction is taken
        isOvernightStay:
          type: boolean
          example: false
          description: Indicates if trip had an overnight stay
        isTravelDayDeducted:
          type: boolean
          description: If the travel day deduction is taken, this field will be true
        latitude:
          type: number
          format: double
          example: 193.29283
          description: Latitude of start position
        lodgingDeductionAmount:
          type: number
          example: 0
          description: Amount of lodging deduction
        longitude:
          type: number
          format: double
          example: 30

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