Emburse Invoice API External Controller API

openapi: 3.2.0
info:
  description: API Documentation
  version: v1
  title: Documentation Invoice API External Controller API
  termsOfService: https://www.chromeriver.com/company/security
  contact:
    name: Chrome River Technologies
    url: https://www.chromeriver.com/contact
    email: info@chromeriver.com
  license: {}
servers:
- url: https://service.chromeriver.com
tags:
- name: invoice-api-external-controller
  description: Operations in Invoice Api
paths:
  /v1/invoice-api/invoices:
    put:
      tags:
      - invoice-api-external-controller
      summary: Returns invoices by InvoiceFilter
      description: 'Date filtering expects RFC3339 / ISO-8601 timestamps (UTC recommended).

        Preferred examples:

        - 2022-12-01T00:00:00Z

        - 2022-12-01T00:00:00+00:00

        Legacy format currently accepted for backward compatibility (discouraged):

        - 2022-12-01T00:00:00+0000'
      operationId: getInvoicesUsingPUT
      parameters:
      - name: chain-id
        in: header
        description: Reference used to track the flow of the request
        required: true
        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
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceFilter'
        description: requestFilter
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Invoice'
      deprecated: false
  /v1/invoice-api/invoices/images/pdf:
    get:
      tags:
      - invoice-api-external-controller
      summary: Returns images/invoice-report in pdf file format
      operationId: getImagesInPdfUsingGET
      parameters:
      - name: chain-id
        in: header
        description: Reference used to track the flow of the request
        required: true
        schema:
          type: string
      - name: customer-code
        in: header
        description: Unique customer identifier provided by Chrome River
        required: true
        schema:
          type: string
      - name: getImage
        in: query
        description: Flag to fetch images attached to the invoice.
        required: false
        allowEmptyValue: false
        schema:
          type: boolean
          default: true
      - name: getPDFReport
        in: query
        description: Flag to fetch and attach invoice pdf report.
        required: false
        allowEmptyValue: false
        schema:
          type: boolean
          default: true
      - name: imageFirst
        in: query
        description: Flag to put images first and invoice pdf report at the end of the pdf file, vice versa.
        required: false
        allowEmptyValue: false
        schema:
          type: boolean
          default: true
      - name: invoiceId
        in: query
        description: Invoice Id to get images.
        required: true
        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
      deprecated: false
  /v1/invoice-api/invoices/payments:
    put:
      tags:
      - invoice-api-external-controller
      summary: Get invoice payment
      operationId: getInvoicePaymentsUsingPUT
      parameters:
      - name: chain-id
        in: header
        description: Reference used to track the flow of the request
        required: true
        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
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoicePaymentFilter'
        description: invoicePaymentFilter
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/InvoicePaymentExternal'
        '401':
          description: Customer Code or api key is not authorized.
        '503':
          description: Service unavailable.
      deprecated: false
  /v1/invoice-api/invoices/sdi/xml:
    post:
      tags:
      - invoice-api-external-controller
      summary: Post SDI invoice xml
      operationId: postInvoicePaymentStatusUsingPOST
      parameters:
      - name: chain-id
        in: header
        description: Reference used to track the flow of the request
        required: true
        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
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  description: file
                  type: string
                  format: binary
              required:
              - file
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/InvoiceSDIResponse'
        '201':
          description: Invoice created with warnings
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/InvoiceSDIResponse'
        '401':
          description: Customer Code or api key is not authorized.
        '503':
          description: Service unavailable.
      deprecated: false
  /v1/invoice-api/invoices/{invoiceId}/approve:
    post:
      tags:
      - invoice-api-external-controller
      summary: Approve Specified Invoice
      operationId: approveInvoiceUsingPOST
      parameters:
      - name: approverPersonUniqueId
        in: query
        description: Unique identifier of a person
        required: true
        allowEmptyValue: false
        schema:
          type: string
      - name: chain-id
        in: header
        description: Reference used to track the flow of the request
        required: true
        schema:
          type: string
      - name: customer-code
        in: header
        description: Unique customer identifier provided by Chrome River
        required: true
        schema:
          type: string
      - name: invoiceId
        in: path
        description: Invoice Id to approve
        required: true
        schema:
          type: string
      - name: x-api-key
        in: header
        description: API key for Authentication
        required: true
        schema:
          type: string
      requestBody:
        $ref: '#/components/requestBodies/InvoiceSubmitOptionsExternal'
      responses:
        '200':
          description: OK
        '400':
          description: 'bad-request: invoiceId not found

            bad-request: approverUniqueId not found

            bad-request: additionalPersonUniqueId not found'
        '410':
          description: Invoice has been deleted or no longer assigned for approval.
      deprecated: false
  /v1/invoice-api/invoices/{invoiceId}/assign:
    post:
      tags:
      - invoice-api-external-controller
      summary: Assign Specified Invoice To Person Or Entity
      operationId: assignInvoiceUsingPOST
      parameters:
      - name: approverPersonUniqueId
        in: query
        description: Unique identifier of a person
        required: true
        allowEmptyValue: false
        schema:
          type: string
      - name: chain-id
        in: header
        description: Reference used to track the flow of the request
        required: true
        schema:
          type: string
      - name: customer-code
        in: header
        description: Unique customer identifier provided by Chrome River
        required: true
        schema:
          type: string
      - name: invoiceId
        in: path
        description: Invoice Id to assign
        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/InvoiceAssignOptionsExternal'
        description: ' '
        required: true
      responses:
        '200':
          description: OK
        '400':
          description: 'bad-request: invoiceId not found

            bad-request: approverUniqueId not found

            bad-request: additionalPersonUniqueId not found

            bad-request: Move to Person or Entity details must be present'
        '410':
          description: Invoice has been deleted or no longer assigned for approval.
      deprecated: false
  /v1/invoice-api/invoices/{invoiceId}/ocr/images:
    get:
      tags:
      - invoice-api-external-controller
      summary: Get images uploaded for OCR
      operationId: getInvoiceOcrImagesReportUsingGET
      parameters:
      - name: chain-id
        in: header
        description: Reference used to track the flow of the request
        required: true
        schema:
          type: string
      - name: customer-code
        in: header
        description: Unique customer identifier provided by Chrome River
        required: true
        schema:
          type: string
      - name: invoiceId
        in: path
        description: Invoice Id to retrieve
        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:
            '*/*':
              schema:
                type: string
                format: byte
        '204':
          description: "Valid request, but no content returned \n \n Either Invoice does not exist or Invoice does not have OCR images"
          content:
            '*/*':
              schema:
                type: string
                format: byte
        '401':
          description: Customer Code or api key is not authorized.
      deprecated: false
  /v1/invoice-api/invoices/{invoiceId}/payment:
    post:
      tags:
      - invoice-api-external-controller
      summary: Post paid invoice data
      operationId: postInvoicePaymentStatusExternalUsingPOST
      parameters:
      - name: chain-id
        in: header
        description: Reference used to track the flow of the request
        required: true
        schema:
          type: string
      - name: checkDupePayments
        in: query
        description: Flag that will enable a check for duplicate payments. Add dupe check fields in the payload. If flag is not present, it will default to false
        required: false
        allowEmptyValue: false
        example: false
        schema:
          type: boolean
          default: false
      - name: customer-code
        in: header
        description: Unique customer identifier provided by Chrome River
        required: true
        schema:
          type: string
      - name: invoiceId
        in: path
        description: Invoice Id to update status
        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/InvoicePaymentCustomer'
        description: invoicePaymentPayload
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/InvoicePaymentOutput'
        '422':
          description: "Unprocessable Entity when a duplicate payment is passed, without checkDupePayments set to true  \n\n There are duplicate payments with the same values in fields: amount,invoiceID"
      deprecated: false
  /v1/invoice-api/invoices/{invoiceId}/return:
    post:
      tags:
      - invoice-api-external-controller
      summary: Return Specified Invoice
      operationId: returnInvoiceUsingPOST
      parameters:
      - name: approverPersonUniqueId
        in: query
        description: Unique identifier of a person
        required: true
        allowEmptyValue: false
        schema:
          type: string
      - name: chain-id
        in: header
        description: Reference used to track the flow of the request
        required: true
        schema:
          type: string
      - name: customer-code
        in: header
        description: Unique customer identifier provided by Chrome River
        required: true
        schema:
          type: string
      - name: invoiceId
        in: path
        description: Invoice Id to return
        required: true
        schema:
          type: string
      - name: x-api-key
        in: header
        description: API key for Authentication
        required: true
        schema:
          type: string
      requestBody:
        $ref: '#/components/requestBodies/InvoiceSubmitOptionsExternal'
      responses:
        '200':
          description: OK
        '400':
          description: 'bad-request: invoiceId not found

            bad-request: approverUniqueId not found

            bad-request: additionalPersonUniqueId not found'
        '410':
          description: Invoice has been deleted or no longer assigned for approval.
      deprecated: false
components:
  requestBodies:
    InvoiceSubmitOptionsExternal:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InvoiceSubmitOptionsExternal'
      description: ' '
      required: true
  schemas:
    InvoicePaymentOutput:
      type: object
      required:
      - amount
      - amountDiscount
      - currencyCode
      - invoiceId
      - paidDate
      properties:
        amount:
          type: number
          example: 1000
          description: Payment Amount for the Invoice
        amountDiscount:
          type: number
          example: 1000
          description: Payment Amount Discount for the Invoice
        bankNumber:
          type: string
          example: 25
          description: Bank Account Number. 36 character limit
        checkMailedDate:
          type: string
          format: date-time
          description: 'Check Payment Completion Date, Accepted date format: "yyyy-MM-dd''T''HH:mm:ss.SSSZ"'
        checkNumber:
          type: string
          example: 47029
          description: Check Number. 36 character limit
        currencyCode:
          type: string
          example: USD
          description: Currency in which Paid Invoice is created. These codes are standard three character values (e.g., USD, GBP, JPY, HKD, etc).
        invoiceId:
          type: string
          example: test
          description: Invoice Number of Paid Invoice. 36 characters limit
        paidDate:
          type: string
          format: date-time
          description: 'Invoice Payment Completion Date, Accepted date format: "yyyy-MM-dd''T''HH:mm:ss.SSSZ"'
        paymentMethod:
          type: string
          example: ACH
          description: PaymentMethod, Examples value are "ACH", "CHECK", "CC"
          enum:
          - ACH
          - CHECK
          - CC
      title: InvoicePaymentOutput
    InvoiceSubmitOptionsExternal:
      type: object
      required:
      - approvalMethod
      - invoiceId
      - routingType
      - submitSource
      properties:
        additionalPersonUniqueId:
          type: string
          description: Person Unique ID for an Additional Reviewer
        approvalMethod:
          type: string
          example: EMAI
          description: 'Types of Approval Methods: Email(EMAI), Dashboard(DASH), Mobile(MOBL), AutoApprove(AUTO), Mercury(MERC), None(NONE)'
          enum:
          - EMAI
          - DASH
          - MOBL
          - AUTO
          - MERC
          - NONE
        invoiceId:
          type: string
          example: test
          description: Invoice Number - 36 characters limit
        notes:
          type: string
          example: Example Comment For My Invoice
          description: Comment that will be added to InvoiceHeader upon successful request
        routingType:
          type: string
          example: ENTY
          description: 'Types of Routing: Entity(ENTY), Normal(ROUT), Owner(OWNR), Person(PERS), Other(RETA), Creator(RETC), Recall(RECL)'
          enum:
          - ENTY
          - ROUT
          - OWNR
          - PERS
          - RETA
          - RETC
          - RECL
        submitSource:
          type: string
          example: INVS
          description: 'Types of Submit Source: Invoice Submit (INVS), Approval Submit (APPS), Invoice Management Submit(IMGT), Bulk Submit (BLKS), NONE(NONE)'
          enum:
          - INVS
          - APPS
          - IMGT
          - BLKS
          - NONE
      title: InvoiceSubmitOptionsExternal
    InvoicePaymentExternal:
      type: object
      required:
      - amount
      - currencyCode
      - invoiceId
      - paidDate
      properties:
        achPaymentCompleteDate:
          type: string
          format: date-time
          description: 'ACH Payment Completion Date, Accepted date format: "yyyy-MM-dd''T''HH:mm:ss.SSSZ"'
        achPaymentStatus:
          type: string
          example: COMPLETED
          description: ACH Payment Status. 25 character limit
        amount:
          type: number
          example: 1000
          description: Payment Amount
        amountDiscount:
          type: number
          example: 1000
          description: Discount Amount for the Invoice
        bankNumber:
          type: string
          example: 25
          description: Bank Account Number. 36 character limit
        batchNumber:
          type: string
          description: Batch Number. 36 character limit
        checkMailedDate:
          type: string
          format: date-time
          description: 'Check Payment Completion Date, Accepted date format: "yyyy-MM-dd''T''HH:mm:ss.SSSZ"'
        checkNumber:
          type: string
          example: 47029
          description: Check Number. 36 character limit
        createSource:
          type: string
          example: FEED
          description: Creation Source, Examples value are "EP", "FEED"
          enum:
          - EP
          - FEED
        currencyCode:
          type: string
          example: USD
          description: Currency in which Paid Invoice is created. These codes are standard three character values (e.g., USD, GBP, JPY, HKD, etc).
        extReferenceId:
          type: string
          description: ID that maps to Batch PID. 36 characters limit
        invoiceId:
          type: string
          example: test
          description: Invoice Number of Paid Invoice. 36 characters limit
        lastFourCardDigits:
          type: string
          example: 1234
          description: Last four digits of credit card number. 4 character limit
        paidDate:
          type: string
          format: date-time
          description: 'Invoice Payment Completion Date, Accepted date format: "yyyy-MM-dd''T''HH:mm:ss.SSSZ"'
        paymentMethod:
          type: string
          example: ACH
          description: PaymentMethod, Examples value are "ACH", "CHECK", "CC"
          enum:
          - ACH
          - CHECK
          - CC
        status:
          type: string
          example: PAID
          description: Invoice payment status, Examples value are "PAID", "PART"
          enum:
          - PAID
          - PART
          - NONE
        transactionNumber:
          type: string
          description: Transaction Number. 36 character limit
      title: InvoicePaymentExternal
    InvoicePaymentFilter:
      type: object
      properties:
        invoiceId:
          type: string
          example: test
          description: Filter Invoice Number of Paid Invoice. 36 characters limit
        paidDateFrom:
          type: string
          format: date-time
          description: 'Filter Invoice Payment Completion Date From Bottom, Accepted date format: "yyyy-MM-dd''T''HH:mm:ss.SSSZ"'
        paidDateTo:
          type: string
          format: date-time
          description: 'Filter Invoice Payment Completion Date To Top, Accepted date format: "yyyy-MM-dd''T''HH:mm:ss.SSSZ"'
      title: InvoicePaymentFilter
    InvoiceError:
      type: object
      properties:
        chain-id:
          type: string
        code:
          type: string
        detail:
          type: string
        id:
          type: string
        message:
          type: string
        meta:
          type: object
        session-id:
          type: string
        status:
          type: string
        title:
          type: string
      title: InvoiceError
    InvoiceSDIResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/InvoiceHeaderSDI'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceError'
      title: InvoiceSDIResponse
    InvoicePaymentCustomer:
      type: object
      required:
      - amount
      - currencyCode
      - invoiceId
      - paidDate
      properties:
        amount:
          type: number
          example: 1000
          description: Payment Amount for the Invoice
        amountDiscount:
          type: number
          example: 1000
          description: Discount Amount for the Invoice
        bankNumber:
          type: string
          example: 25
          description: Bank Account Number. 36 character limit
        checkMailedDate:
          type: string
          format: date-time
          description: 'Check Payment Completion Date, Accepted date format: "yyyy-MM-dd''T''HH:mm:ss.SSSZ"'
        checkNumber:
          type: string
          example: 47029
          description: Check Number. 36 character limit
        currencyCode:
          type: string
          example: USD
          description: Currency in which Paid Invoice is created. These codes are standard three character values (e.g., USD, GBP, JPY, HKD, etc).
        dupeChecks:
          type: array
          example:
          - InvoiceID
          - AmountSpent
          description: Fields to use for duplicate check. Will only be used when checkDupePayments is set to True
          items:
            type: string
            enum:
            - AmountSpent
            - CurrencyCode
            - PaidDate
            - CheckNumber
            - BankNumber
            - InvoiceID
        invoiceId:
          type: string
          example: test
          description: Invoice Number of Paid Invoice. 36 characters limit
        paidDate:
          type: string
          format: date-time
          description: 'Invoice Payment Completion Date, Accepted date format: "yyyy-MM-dd''T''HH:mm:ss.SSSZ"'
        paymentMethod:
          type: string
          example: ACH
          description: PaymentMethod, Examples value are "ACH", "CHECK", "CC"
          enum:
          - ACH
          - CHECK
          - CC
      title: InvoicePaymentCustomer
    InvoiceFilter:
      type: object
      required:
      - fromDate
      - toDate
      properties:
        fromDate:
          type: string
          example: 2025-12-01 00:01:00+00:00
          description: Initial dequeued date for filtering (inclusive). ISO-8601/RFC3339 timestamp. UTC recommended.
        toDate:
          type: string
          example: 2025-12-02 00:00:00+00:00
          description: Final dequeued date for filtering (inclusive). ISO-8601/RFC3339 timestamp. UTC recommended.
      title: InvoiceFilter
    Invoice:
      type: object
      required:
      - invoiceId
      - invoiceNumber
      properties:
        addressUniqueId:
          type: string
          description: Address unique Id
        invoiceDate:
          type: string
          format: date-time
          description: Invoice Date
        invoiceId:
          type: string
          example: test
          description: Invoice Id
        invoiceNumber:
          type: string
          example: test
          description: Invoice Number - 36 characters limit
        vendorUniqueId:
          type: string
          description: Vendor unique Id
      title: Invoice
    InvoiceHeaderSDI:
      type: object
      properties:
        amountSpent:
          type: number
        currencyCodeSpent:
          type: string
        headerStatus:
          type: string
        invoiceDate:
          type: string
          format: date-time
        invoiceId:
          type: string
        invoiceNumber:
          type: string
      title: InvoiceHeaderSDI
    InvoiceAssignOptionsExternal:
      type: object
      required:
      - approvalMethod
      - entityCode
      - entityTypeCode
      - invoiceId
      - roleName
      - routingType
      - submitSource
      properties:
        additionalPersonUniqueId:
          type: string
          description: Person Unique ID for an Additional Reviewer
        approvalMethod:
          type: string
          example: EMAI
          description: 'Types of Approval Methods: Email(EMAI), Dashboard(DASH), Mobile(MOBL), AutoApprove(AUTO), Mercury(MERC), None(NONE)'
          enum:
          - EMAI
          - DASH
          - MOBL
          - AUTO
          - MERC
          - NONE
        entityCode:
          type: string
          example: 100
          description: The entity code for the person-entity relationship. Max 50 characters
        entityTypeCode:
          type: string
          example: DEPT
          description: The entity type code for the person-entity relationship. Max 50 characters
        invoiceId:
          type: string
          example: test
          description: Invoice Number - 36 characters limit
        notes:
          type: string
          example: Example Comment For My Invoice
          description: Comment that will be added to InvoiceHeader upon successful request
        roleName:
          type: string
          example: APReview
          description: The name of the role for the person-entity relationship. Max 50 characters
        routingType:
          type: string
          example: ENTY
          description: 'Types of Routing: Entity(ENTY), Normal(ROUT), Owner(OWNR), Person(PERS), Other(RETA), Creator(RETC), Recall(RECL)'
          enum:
          - ENTY
          - ROUT
          - OWNR
          - PERS
          - RETA
          - RETC
          - RECL
        submitSource:
          type: string
          example: INVS
          description: 'Types of Submit Source: Invoice Submit (INVS), Approval Submit (APPS), Invoice Management Submit(IMGT), Bulk Submit (BLKS), NONE(NONE)'
          enum:
          - INVS
          - APPS
          - IMGT
          - BLKS
          - NONE
      title: InvoiceAssignOptionsExternal