openapi: 3.1.0
info:
  title: Expensify Integration Server Integrations API
  description: 'Best-effort OpenAPI for the Expensify Integration Server, documented at https://integrations.expensify.com/Integration-Server/doc/. The API exposes a single POST endpoint that takes a requestJobDescription JSON payload selecting a job type (file, reconciliation, download, create, get, update). Credentials (partnerUserID + partnerUserSecret) are passed in every payload. Rate limits: 5 requests / 10s and 20 requests / 60s.'
  version: 1.0.0
  contact:
    name: API Evangelist
    email: kin@apievangelist.com
  license:
    name: Proprietary
servers:
- url: https://integrations.expensify.com/Integration-Server
  description: Expensify Integration Server
tags:
- name: Integrations
paths:
  /ExpensifyIntegrations:
    post:
      summary: Submit an integration job
      description: All Expensify Integration Server operations are dispatched through this single endpoint. The job type is selected by the type field on requestJobDescription.
      operationId: submitJob
      tags:
      - Integrations
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - requestJobDescription
              properties:
                requestJobDescription:
                  description: JSON string describing the job
                  oneOf:
                  - $ref: '#/components/schemas/FileJob'
                  - $ref: '#/components/schemas/ReconciliationJob'
                  - $ref: '#/components/schemas/DownloadJob'
                  - $ref: '#/components/schemas/CreateJob'
                  - $ref: '#/components/schemas/GetJob'
                  - $ref: '#/components/schemas/UpdateJob'
                template:
                  type: string
                  description: ExpensiCode template (for type=file)
      responses:
        '200':
          description: Job response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '429':
          description: Rate limit exceeded
components:
  schemas:
    Credentials:
      type: object
      required:
      - partnerUserID
      - partnerUserSecret
      properties:
        partnerUserID:
          type: string
        partnerUserSecret:
          type: string
    UpdateJob:
      type: object
      required:
      - type
      - credentials
      - inputSettings
      properties:
        type:
          type: string
          enum:
          - update
        credentials:
          $ref: '#/components/schemas/Credentials'
        inputSettings:
          type: object
          properties:
            type:
              type: string
              enum:
              - policy
              - employees
              - reportStatus
              - tagApprovers
            policyID:
              type: string
            categories:
              type: array
              items:
                type: object
                additionalProperties: true
            tags:
              type: array
              items:
                type: object
                additionalProperties: true
            reportFields:
              type: array
              items:
                type: object
                additionalProperties: true
            employees:
              type: array
              items:
                type: object
                additionalProperties: true
            reportIDList:
              type: array
              items:
                type: string
            reportState:
              type: string
    OnReceive:
      type: object
      properties:
        immediateResponse:
          type: array
          items:
            type: string
            enum:
            - returnRandomFileName
    JobResponse:
      type: object
      properties:
        responseCode:
          type: integer
          description: HTTP-style status code
        responseMessage:
          type: string
        fileName:
          type: string
        reportID:
          type: string
        policyID:
          type: string
        policyInfoList:
          type: array
          items:
            type: object
            additionalProperties: true
    FileJob:
      type: object
      required:
      - type
      - credentials
      - onReceive
      - inputSettings
      properties:
        type:
          type: string
          enum:
          - file
        credentials:
          $ref: '#/components/schemas/Credentials'
        onReceive:
          $ref: '#/components/schemas/OnReceive'
        inputSettings:
          type: object
          properties:
            type:
              type: string
              enum:
              - combinedReportData
            filters:
              type: object
              properties:
                startDate:
                  type: string
                  format: date
                endDate:
                  type: string
                  format: date
                approvedAfter:
                  type: string
                  format: date
                markedAsExported:
                  type: string
            reportState:
              type: string
            limit:
              type: integer
        outputSettings:
          type: object
          properties:
            fileExtension:
              type: string
              enum:
              - csv
              - xlsx
              - pdf
              - json
              - xml
            fileBasename:
              type: string
    GetJob:
      type: object
      required:
      - type
      - credentials
      - inputSettings
      properties:
        type:
          type: string
          enum:
          - get
        credentials:
          $ref: '#/components/schemas/Credentials'
        inputSettings:
          type: object
          properties:
            type:
              type: string
              enum:
              - policy
              - policyList
              - domainCardList
            policyIDList:
              type: array
              items:
                type: string
            fields:
              type: array
              items:
                type: string
            adminOnly:
              type: boolean
            userEmail:
              type: string
    CreateJob:
      type: object
      required:
      - type
      - credentials
      - inputSettings
      properties:
        type:
          type: string
          enum:
          - create
        credentials:
          $ref: '#/components/schemas/Credentials'
        inputSettings:
          type: object
          properties:
            type:
              type: string
              enum:
              - report
              - expenses
              - policy
              - expenseRules
            policyID:
              type: string
            report:
              type: object
              additionalProperties: true
            employeeEmail:
              type: string
            expenses:
              type: array
              items:
                type: object
                additionalProperties: true
            policy:
              type: object
              additionalProperties: true
    ReconciliationJob:
      type: object
      required:
      - type
      - credentials
      - inputSettings
      properties:
        type:
          type: string
          enum:
          - reconciliation
        credentials:
          $ref: '#/components/schemas/Credentials'
        inputSettings:
          type: object
          properties:
            type:
              type: string
              enum:
              - reconciliation
            startDate:
              type: string
              format: date
            endDate:
              type: string
              format: date
            cardID:
              type: string
            domain:
              type: string
    DownloadJob:
      type: object
      required:
      - type
      - credentials
      - fileName
      - fileSystem
      properties:
        type:
          type: string
          enum:
          - download
        credentials:
          $ref: '#/components/schemas/Credentials'
        fileName:
          type: string
        fileSystem:
          type: string
          enum:
          - integrationServer