openapi: 3.0.3
info:
  title: Abacus Authentication Expenses API
  version: 1.0.0
  description: The Abacus API (now part of Emburse Spend) provides programmatic access to expense management functionality, including member management and expense operations. Available to partners and enterprise customers using OAuth 2.0 authentication. The API enables third-party integrations with the Abacus expense platform for automating expense workflows, member provisioning, and data synchronization.
  contact:
    name: Abacus Support
    url: https://support.abacus.com/hc/en-us
  x-generated-from: documentation
servers:
- url: https://api.abacus.com
  description: Production server
security:
- OAuth2: []
tags:
- name: Expenses
  description: Expense report management and operations
paths:
  /expenses:
    get:
      tags:
      - Expenses
      summary: Abacus List Expenses
      description: Retrieve a list of expense reports for the organization.
      operationId: listExpenses
      parameters:
      - name: page
        in: query
        description: Page number for pagination
        required: false
        schema:
          type: integer
          default: 1
        example: 1
      - name: per_page
        in: query
        description: Number of results per page
        required: false
        schema:
          type: integer
          default: 25
          maximum: 100
        example: 25
      - name: status
        in: query
        description: Filter by expense status
        required: false
        schema:
          type: string
          enum:
          - pending
          - approved
          - rejected
          - reimbursed
        example: pending
      - name: member_id
        in: query
        description: Filter expenses by member ID
        required: false
        schema:
          type: string
        example: '500123'
      - name: from_date
        in: query
        description: Filter expenses from this date (ISO 8601)
        required: false
        schema:
          type: string
          format: date
        example: '2025-01-01'
      - name: to_date
        in: query
        description: Filter expenses to this date (ISO 8601)
        required: false
        schema:
          type: string
          format: date
        example: '2025-03-31'
      responses:
        '200':
          description: List of expenses retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpenseListResponse'
              examples:
                ListExpenses200Example:
                  summary: Default listExpenses 200 response
                  x-microcks-default: true
                  value:
                    expenses:
                    - id: exp-500123
                      member_id: '500123'
                      amount: 45.5
                      currency: USD
                      category: meals
                      description: Team lunch
                      date: '2025-03-15'
                      status: pending
                    total: 1
                    page: 1
                    per_page: 25
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /expenses/{expense_id}:
    get:
      tags:
      - Expenses
      summary: Abacus Get Expense
      description: Retrieve details for a specific expense report.
      operationId: getExpense
      parameters:
      - $ref: '#/components/parameters/ExpenseId'
      responses:
        '200':
          description: Expense details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Expense'
              examples:
                GetExpense200Example:
                  summary: Default getExpense 200 response
                  x-microcks-default: true
                  value:
                    id: exp-500123
                    member_id: '500123'
                    amount: 45.5
                    currency: USD
                    category: meals
                    description: Team lunch
                    date: '2025-03-15'
                    status: pending
                    receipt_url: https://portal.example.com/path/abc123
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    ExpenseListResponse:
      type: object
      description: Paginated list of expenses
      properties:
        expenses:
          type: array
          items:
            $ref: '#/components/schemas/Expense'
        total:
          type: integer
          description: Total number of expenses
          example: 250
        page:
          type: integer
          description: Current page number
          example: 1
        per_page:
          type: integer
          description: Number of results per page
          example: 25
    Error:
      type: object
      description: Error response
      properties:
        error:
          type: string
          description: Error code
          example: invalid_request
        message:
          type: string
          description: Human-readable error message
          example: The request is missing required parameters
    Expense:
      type: object
      description: An expense report submitted by a member
      properties:
        id:
          type: string
          description: Unique expense identifier
          example: exp-500123
        member_id:
          type: string
          description: ID of the member who submitted the expense
          example: '500123'
        amount:
          type: number
          description: Expense amount
          example: 45.5
        currency:
          type: string
          description: Currency code (ISO 4217)
          example: USD
        category:
          type: string
          description: Expense category
          enum:
          - meals
          - travel
          - lodging
          - office_supplies
          - software
          - other
          example: meals
        description:
          type: string
          description: Description of the expense
          example: Team lunch
        date:
          type: string
          format: date
          description: Date of the expense
          example: '2025-03-15'
        status:
          type: string
          description: Current status of the expense
          enum:
          - pending
          - approved
          - rejected
          - reimbursed
          example: pending
        receipt_url:
          type: string
          format: uri
          description: URL to the uploaded receipt
          example: https://api.abacus.com/receipts/abc123
        created_at:
          type: string
          format: date-time
          description: Timestamp when the expense was created
          example: '2025-03-15T14:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the expense was last updated
          example: '2025-03-16T10:00:00Z'
  responses:
    UnauthorizedError:
      description: Authentication required or failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: unauthorized
            message: Invalid or missing access token
    NotFoundError:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: not_found
            message: The requested resource was not found
    ForbiddenError:
      description: Insufficient permissions for this operation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: forbidden
            message: You do not have permission to perform this action
  parameters:
    ExpenseId:
      name: expense_id
      in: path
      required: true
      description: Unique identifier for the expense
      schema:
        type: string
      example: exp-500123
  securitySchemes:
    OAuth2:
      type: oauth2
      description: OAuth 2.0 client credentials flow for API authentication
      flows:
        clientCredentials:
          tokenUrl: https://api.abacus.com/oauth/token
          scopes:
            members:read: Read member information
            members:write: Create and update members
            expenses:read: Read expense reports