openapi: 3.1.0
info:
  title: Arthur Financials API
  version: 2.0.0
  description: Arthur Financials API - the financials surface of the Arthur API v2, the UK property management
    platform from Arthur Online (an Aareon company). Derived operation-for-operation from the provider's
    public Postman Documenter collection at https://developer.arthuronline.co.uk/. Every request is scoped
    to an Arthur entity via the mandatory X-EntityID header and authorised with an OAuth 2.0 Authorization
    Code access token.
  contact:
    name: Arthur Online API Support
    url: https://support.arthuronline.co.uk/
  termsOfService: https://www.arthuronline.co.uk/terms-and-conditions/
  x-derived-from: collections/arthur-online.postman_collection.json
  x-derived-by: API Evangelist enrichment pipeline
  x-derived-date: '2026-07-26'
servers:
- url: https://api.arthuronline.co.uk/v2
  description: Arthur API v2 production
security:
- arthurOAuth: []
tags:
- name: Recurrings
- name: Transactions
- name: Contractor Invoices
paths:
  /recurrings/{recurringId}:
    get:
      operationId: viewRecurring
      summary: View Recurring
      tags:
      - Recurrings
      parameters:
      - name: recurringId
        in: path
        required: true
        description: Arthur recurringId.
        schema:
          type: string
      - $ref: '#/components/parameters/EntityId'
      responses:
        '200':
          description: The request was completed successfully without errors.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                  data:
                    type: array
                    items:
                      type: object
                  pagination:
                    $ref: '#/components/schemas/Pagination'
              example:
                status: 200
                data:
                  id: 1481960
                  tenancy_id: 966665
                  property_id: 36378
                  unit_id: 80046
                  transaction_type: Direct Rent
                  description: Rent
                  description_format_id: 1
                  at_remittance: false
                  fee_type: fixed
                  amount: '1000.00'
                  currency: GBP
                  vat_code_id: 4
                  frequency_id: 1
                  start_date: '2025-01-31'
                  next_collection_date: null
                  end_type: tenancy-end
                  end_date: '2025-01-29T00:00:00'
                  created_by:
                    id: 100569
                    full_name: Max Mil
                  active: false
                  created: '2025-01-29T12:49:28'
                  modified: '2025-01-29T12:59:49'
                pagination:
                  page: 1
                  current: 20
                  count: 291
                  pageCount: 15
                  limit: 20
                  queryScope: null
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /transactions:
    get:
      operationId: listTransactions
      summary: List Transactions
      tags:
      - Transactions
      parameters:
      - $ref: '#/components/parameters/EntityId'
      - name: statement
        in: query
        required: false
        schema:
          type: string
        description: "Filters the transactions by statement. The available options are tenant , tenant-deposit\
          \ , property-owner , \n property-owner-consolidated , contractor , tenancy-closing-statement\
          \ , late-rents , contingency-statement , invoices"
      - name: allocated_from
        in: query
        required: false
        schema:
          type: string
        description: Filter by transaction allocated from ID
      - name: status
        in: query
        required: false
        schema:
          type: string
        description: The status of the transaction. The available options are paid , unpaid , partpaid
          , outstanding , overdue , or voided . Use this parameter to filter transactions based on their
          payment status.
      - name: transaction_type
        in: query
        required: false
        schema:
          type: string
        description: Filter by the ID of the transaction type or by its alias name (Obtained from the
          v2/transaction_types endpoint)
      - name: date_from
        in: query
        required: false
        schema:
          type: string
        description: Filters the transactions by the created date, starting from the specified date. Use
          the format yyyy-mm-dd to input the date.
      - name: date_to
        in: query
        required: false
        schema:
          type: string
        description: Filters the transactions by the created date, up to the specified date. Use the format
          yyyy-mm-dd to input the date.
      - name: modifiedFrom
        in: query
        required: false
        schema:
          type: string
        description: Filters the transactions by the modified date, starting from the specified date.
          Use the format yyyy-mm-dd to input the date.
      - name: modifiedTo
        in: query
        required: false
        schema:
          type: string
        description: Filters the transactions by the modified date, up to the specified date. Use the
          format yyyy-mm-dd to input the date.
      - name: transaction_date_from
        in: query
        required: false
        schema:
          type: string
        description: Filters the transactions by the date, starting from the specified date. Use the format
          yyyy-mm-dd to input the date.
      - name: transaction_date_to
        in: query
        required: false
        schema:
          type: string
        description: Filters the transactions by the date, up to the specified date. Use the format yyyy-mm-dd
          to input the date.
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Sort'
      - $ref: '#/components/parameters/Direction'
      description: 'This retrieves a list of transactions.


        See available filters below to customize the list of transactions returned.'
      responses:
        '200':
          description: The request was completed successfully without errors.
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /transactions/{transaction_id}:
    get:
      operationId: viewTransaction
      summary: View Transaction
      tags:
      - Transactions
      parameters:
      - name: transaction_id
        in: path
        required: true
        description: Arthur transaction id.
        schema:
          type: integer
      - $ref: '#/components/parameters/EntityId'
      description: 'This API endpoint retrieves the details of a single transaction, identified by its
        unique transaction_id .


        Use this endpoint to view the specific details of a transaction.'
      responses:
        '200':
          description: The request was completed successfully without errors.
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /transactions/{transaction_id}/payoff:
    put:
      operationId: payoffTransaction
      summary: Payoff Transaction
      tags:
      - Transactions
      parameters:
      - name: transaction_id
        in: path
        required: true
        description: Arthur transaction id.
        schema:
          type: integer
      - $ref: '#/components/parameters/EntityId'
      - $ref: '#/components/parameters/Strict'
      description: "This API endpoint allows the user to payoff a transaction with a payment. The transaction\
        \ is identified by its unique transaction_id and the payment details are included in the optional\
        \ request body.\n\nIf no request body is included, the endpoint will pay off the full charge.\n\
        \nSupported Fields \n The following fields are supported for the request body\n\nField \n Data\
        \ Type \n Description \n\ndescription \n string \n A description of the payoff receipt. \n\npayment_method_id\
        \ \n integer \n The ID of the payment method used to pay off the transaction. \n\namount \n float\
        \ \n The amount paid towards the transaction."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                description:
                  type: string
                  description: A description of the payoff receipt.
                payment_method_id:
                  type: integer
                  description: The ID of the payment method used to pay off the transaction.
                amount:
                  type: number
                  description: The amount paid towards the transaction.
      responses:
        '200':
          description: The request was completed successfully without errors.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                  data:
                    type: object
              example:
                status: 200
                data:
                  id: 22386790
                  recurring_id: null
                  parent_id: 22350765
                  ref: TR13434
                  transaction_type: Tenancy Receipt
                  payment_type: payment
                  description: Paid - Rent, (Arthur), TE1158, Arthur (26th Feb 2023 - 25th Mar 2023)
                  property_id: 106845
                  unit_id: 287886
                  tenancy_id: 484937
                  payee_group_id: 10
                  invoice_ref: ''
                  payee_tenant_id: 588463
                  amount: '600.00'
                  amount_charged: '0.00'
                  amount_paid: '600.00'
                  amount_outstanding: '0.00'
                  amount_net: '600.00'
                  amount_vat: '0.00'
                  vat_code_id: 0
                  source: arthur
                  created_by:
                    id: 1817080
                    full_name: API Documentation
                  payee_name: ''
                  payee_person_id: null
                  payee_entity_id: null
                  date: '2023-02-27'
                  due_date: null
                  charged_to_date: null
                  expected_payment_date: null
                  allocated_from: null
                  is_overdue: false
                  is_outstanding: false
                  modified: '2023-02-27T13:32:23'
                  created: '2023-02-27T13:32:23'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /invoices:
    get:
      operationId: listInvoices
      summary: List Invoices
      tags:
      - Contractor Invoices
      parameters:
      - $ref: '#/components/parameters/EntityId'
      - name: workorder_id
        in: query
        required: false
        schema:
          type: string
        description: Filter by the connected workorder ID
      - name: status
        in: query
        required: false
        schema:
          type: string
        description: Filter by invoice status (paid, unpaid, pending, cancelled)
      - name: amount
        in: query
        required: false
        schema:
          type: string
        description: Filter by invoice amount
      - name: amount_outstanding
        in: query
        required: false
        schema:
          type: string
        description: Filter by invoice amount outstanding
      - name: amount_vat
        in: query
        required: false
        schema:
          type: string
        description: Filter by VAT amount
      - name: vat_percentage
        in: query
        required: false
        schema:
          type: string
        description: Filter by the percentage of VAT
      - name: paid_date
        in: query
        required: false
        schema:
          type: string
        description: Filters the contractor invoices by the paid date. Use the format yyyy-mm-dd to input
          the date
      - name: submitted
        in: query
        required: false
        schema:
          type: string
        description: To show only submitted invoices, set submitted flag to true
      - name: completed_date
        in: query
        required: false
        schema:
          type: string
        description: Filters the contractor invoices by the completed date. Use the format yyyy-mm-dd
          to input the date
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Sort'
      - $ref: '#/components/parameters/Direction'
      description: This retrieves a list of invoices.
      responses:
        '200':
          description: The request was completed successfully without errors.
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /invoices/{invoice_id}:
    get:
      operationId: viewInvoices
      summary: View Invoices
      tags:
      - Contractor Invoices
      parameters:
      - name: invoice_id
        in: path
        required: true
        description: Arthur invoice id.
        schema:
          type: integer
      - $ref: '#/components/parameters/EntityId'
      description: 'This API endpoint retrieves the details of a single invoice, identified by its unique 
        invoice_id .


        Use this endpoint to view the specific details of an invoice.'
      responses:
        '200':
          description: The request was completed successfully without errors.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                  data:
                    type: object
              example:
                status: 200
                data:
                  id: 123
                  workorder_id: 123
                  ref: W0/000
                  status: unpaid
                  location: Property address
                  amount: '1476.00'
                  amount_paid: '0.00'
                  amount_outstanding: '1476.00'
                  amount_vat: '246.00'
                  vat_percentage: '20.00'
                  paid_date: null
                  submitted: true
                  submitted_date: '2020-04-07T13:51:11+01:00'
                  completed_date: null
                  invoice_items:
                  - id: 123
                    name: Item name
                    description: Item description
                    amount: '1230.00'
                    quantity: 1
                  created_by:
                    id: 123
                    full_name: Zoltan Chivay
                  workorder:
                    id: 123
                    ref: WO000
                    title: Workorder title
                  contractor:
                    id: 123
                    full_name: Zoltan Chivay
                    status: live
                  created: '2020-08-07T15:50:39+01:00'
                  modified: '2020-09-04T15:23:55+01:00'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    arthurOAuth:
      type: oauth2
      description: OAuth 2.0 Authorization Code flow. Access tokens are valid for 14 days; refresh tokens
        for 21 days. Register an application in Arthur Settings > OAuth Applications to obtain a client_id
        and client_secret.
      flows:
        authorizationCode:
          authorizationUrl: https://auth.arthuronline.co.uk/oauth/authorize
          tokenUrl: https://auth.arthuronline.co.uk/oauth/token
          refreshUrl: https://auth.arthuronline.co.uk/oauth/token
          scopes: {}
  parameters:
    EntityId:
      name: X-EntityID
      in: header
      required: true
      description: The Arthur entity (account) the request is scoped to. Mandatory on every API call.
      schema:
        type: string
    Page:
      name: page
      in: query
      required: false
      description: Page number, between 1 and the total number of pages.
      schema:
        type: integer
        minimum: 1
    Limit:
      name: limit
      in: query
      required: false
      description: Items per page, between 1 and 100.
      schema:
        type: integer
        minimum: 1
        maximum: 100
    Sort:
      name: sort
      in: query
      required: false
      description: Field to sort the collection by.
      schema:
        type: string
    Direction:
      name: direction
      in: query
      required: false
      description: Sort direction.
      schema:
        type: string
        enum:
        - ASC
        - DESC
    Strict:
      name: strict
      in: query
      required: false
      description: When true, abort the request instead of auto-creating an unknown Simple type. POST
        and PUT only.
      schema:
        type: boolean
  schemas:
    Pagination:
      type: object
      description: Pagination block returned on every list response.
      properties:
        page:
          type: integer
        current:
          type: integer
        count:
          type: integer
        pageCount:
          type: integer
        limit:
          type: integer
    Error:
      type: object
      description: Arthur error envelope.
      properties:
        status:
          type: integer
        error:
          type: string
          description: Machine-readable error code, e.g. expired_token.
        message:
          type: string
  responses:
    BadRequest:
      description: The request was invalid or malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing, invalid or expired access token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: expired_token
            message: This token has expired.
    NotFound:
      description: The request was sent to a location that does not exist in the API.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'