openapi: 3.1.0
info:
  title: Arthur Entities API
  version: 2.0.0
  description: Arthur Entities API - the entities 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: Entities
paths:
  /entities:
    get:
      operationId: listEntities
      summary: List Entities
      tags:
      - Entities
      parameters:
      - $ref: '#/components/parameters/EntityId'
      - name: service
        in: query
        required: false
        schema:
          type: string
        description: Filter by type of service
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Sort'
      - $ref: '#/components/parameters/Direction'
      description: This endpoint retrieves a list of entities.
      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: 1
                  title: ''
                  name: Company
                  address: Address name, Address line 1, Address line 2, City, County, POSTCODE, Country
                  address_line_1: Address line 1
                  address_line_2: Address line 2
                  city: City
                  county: County
                  country: United Kingdom
                  postcode: POSTCODE
                  website: Company website
                  phone_home: '123'
                  phone_work: '123'
                  phone_mobile: '123'
                  email: companyEmail@gmail.com
                  registration_status: active
                  company: Company name
                  vat_no: 1
                  contacts:
                  - id: 2
                    name: Company Owner
                    main_contact: true
                    phone_home: '132'
                    phone_work: '132'
                    phone_mobile: '132'
                    email: contactemail@gmail.com
                    registration_status: active
                  tags: []
                  modified: '2020-06-26T14:09:12+01:00'
                  created: '2020-06-26T13:01:15+01:00'
                - id: 4
                  title: ''
                  name: Company
                  address: Address name, Address line 1, Address line 2, City, County, POSTCODE, Country
                  address_line_1: Address line 1
                  address_line_2: Address line 2
                  city: City
                  county: County
                  country: United Kingdom
                  postcode: POSTCODE
                  website: Company website
                  phone_home: '123'
                  phone_work: '123'
                  phone_mobile: '123'
                  email: companyEmail@gmail.com
                  registration_status: active
                  company: Company name
                  vat_no: 1
                  contacts:
                  - id: 5
                    name: Company Owner
                    main_contact: true
                    phone_home: '132'
                    phone_work: '132'
                    phone_mobile: '132'
                    email: contactemail@gmail.com
                    registration_status: active
                  tags: []
                  modified: '2020-06-26T14:09:12+01:00'
                  created: '2020-06-26T13:01:15+01:00'
                pagination:
                  page: 1
                  current: 1
                  count: 2
                  pageCount: 1
                  limit: 20
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createEntity
      summary: Create Entity
      tags:
      - Entities
      parameters:
      - $ref: '#/components/parameters/EntityId'
      - $ref: '#/components/parameters/Strict'
      description: "Use this endpoint to create a new entity. The API will return the saved data and a\
        \ unique Entity ID.\n\nCurrently only supports creating landlords and agents \n\nSupported Fields\
        \ \n The following fields are supported for the request body\n\nField \n Example \n Type \n Required?\
        \ \n\ncompany \n company ltd \n String \n No \n\nemail \n company@email.com \n String \n Yes \n\
        \nfirst_name \n Brian \n String \n Yes \n\nlast_name \n Jackson \n String \n No \n\ntitle \n Mr\
        \ \n String \n No \n\nphone_work \n 12345 \n String \n No \n\nphone_home \n 12345 \n String \n\
        \ No \n\nmobile \n 12345 \n String \n No \n\ngroup \n Owner \n String \n Yes \n\nvat_no \n 1 \n\
        \ String \n No \n\nwebsite \n www.yourwebsite.com \n String \n No \n\ninvite_existing \n true\
        \ \n Boolean \n No \n\naddress_name \n Queens road \n String \n No \n\naddress_line_1 \n 42 Raven\
        \ drive \n String \n No \n\naddress_line_2 \n 3 Swan court \n String \n No \n\ncity \n London\
        \ \n String \n No \n\ncounty \n Greater London \n String \n No \n\ncountry \n United Kingdom \n\
        \ String \n No \n\npostcode \n NW14DG \n String \n No"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                company:
                  type: string
                  example: company ltd
                email:
                  type: string
                  example: company@email.com
                first_name:
                  type: string
                  example: Brian
                last_name:
                  type: string
                  example: Jackson
                title:
                  type: string
                  example: Mr
                phone_work:
                  type: string
                  example: '12345'
                phone_home:
                  type: string
                  example: '12345'
                mobile:
                  type: string
                  example: '12345'
                group:
                  type: string
                  example: Owner
                vat_no:
                  type: string
                  example: '1'
                website:
                  type: string
                  example: www.yourwebsite.com
                invite_existing:
                  type: boolean
                  example: true
                address_name:
                  type: string
                  example: Queens road
                address_line_1:
                  type: string
                  example: 42 Raven drive
                address_line_2:
                  type: string
                  example: 3 Swan court
                city:
                  type: string
                  example: London
                county:
                  type: string
                  example: Greater London
                country:
                  type: string
                  example: United Kingdom
                postcode:
                  type: string
                  example: NW14DG
              required:
              - email
              - first_name
              - group
            example:
              title: Mr
              first_name: Michael
              last_name: Brian
              company: My Company
              address_name: My Favourite One
              address_line_1: 31 Eagle Road
              address_line_2: 5 Raven Court
              city: London
              county: Greater London
              country: United Kingdom
              postcode: NW14SA
              website: www.arthuronline.co.uk
              phone_work: '123'
              phone_home: '1234'
              mobile: '12345'
              email: emailCompany@gmail.com
              vat_no: '1'
              group: Owner
      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: 1
                  title: Mr
                  name: My Company
                  address: My Favourite One, 31 Eagle Road, 5 Raven Court, London, Greater London, NW14SA,
                    United Kingdom
                  address_line_1: 31 Eagle Road
                  address_line_2: 5 Raven Court
                  city: London
                  county: Greater London
                  country: United Kingdom
                  postcode: NW14SA
                  website: companyWebsite@gmail.com
                  phone_home: '1234'
                  phone_work: '123'
                  phone_mobile: '12345'
                  email: emailCompany@gmail.com
                  registration_status: invited
                  company: My Company
                  vat_no: 0
                  contacts:
                  - id: 2
                    name: Michael O'Brian
                    main_contact: true
                    phone_home: '1234'
                    phone_work: '123'
                    phone_mobile: '12345'
                    email: emailCompany@gmail.com
                    registration_status: invited
                  tags: []
                  modified: '2020-06-30T10:55:22+01:00'
                  created: '2020-06-30T10:55:22+01:00'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /entities/{entity_id}:
    get:
      operationId: viewEntity
      summary: View Entity
      tags:
      - Entities
      parameters:
      - name: entity_id
        in: path
        required: true
        description: Arthur entity id.
        schema:
          type: integer
      - $ref: '#/components/parameters/EntityId'
      description: 'This API endpoint retrieves the details of a single entity, identified by its unique 
        entity_id .


        Use this endpoint to view the specific details of a entity.'
      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: 1
                  title: ''
                  name: Company
                  address: Address name, Address line 1, Address line 2, City, County, POSTCODE, United
                    Kingdom
                  address_line_1: Address line 1
                  address_line_2: Address line 2
                  city: City
                  county: County
                  country: United Kingdom
                  postcode: POSTCODE
                  website: Company website
                  phone_home: '123'
                  phone_work: '123'
                  phone_mobile: '123'
                  email: companyEmail@gmail.com
                  registration_status: active
                  company: Company name
                  vat_no: 1
                  contacts:
                  - id: 2
                    name: Company Owner
                    main_contact: true
                    phone_home: '132'
                    phone_work: '132'
                    phone_mobile: '132'
                    email: contactemail@gmail.com
                    registration_status: active
                  tags: []
                  modified: '2020-06-26T14:09:12+01:00'
                  created: '2020-06-26T13:01:15+01:00'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateEntity
      summary: Update Entity
      tags:
      - Entities
      parameters:
      - name: entity_id
        in: path
        required: true
        description: Arthur entity id.
        schema:
          type: integer
      - $ref: '#/components/parameters/EntityId'
      - $ref: '#/components/parameters/Strict'
      description: "This endpoint updates an existing entity using the same fields as the 'Add Entity'\
        \ endpoint. Any fields that are not provided will not be changed. The API will return the updated\
        \ data for the entity in the response.\n\nSupported Fields \n The following fields are supported\
        \ for the request body\n\nField \n Example \n Type \n Required? \n\ncompany \n company ltd \n\
        \ String \n No \n\nemail \n company@email.com \n String \n No \n\nfirst_name \n Brian \n String\
        \ \n No \n\nlast_name \n Jackson \n String \n No \n\ntitle \n Mr \n String \n No \n\nphone_work\
        \ \n 12345 \n String \n No \n\nphone_home \n 12345 \n String \n No \n\nmobile \n 12345 \n String\
        \ \n No \n\nvat_no \n 20 \n Integer \n No \n\nwebsite \n www.yourwebsite.com \n String \n No \n\
        \naddress_name \n Queens road \n String \n No \n\naddress_line_1 \n 42 Raven drive \n String \n\
        \ No \n\naddress_line_2 \n 3 Swan court \n String \n No \n\ncity \n London \n String \n No \n\n\
        county \n Greater London \n String \n No \n\ncountry \n United Kingdom \n String \n No \n\npostcode\
        \ \n NW14DG \n String \n No"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                company:
                  type: string
                  example: company ltd
                email:
                  type: string
                  example: company@email.com
                first_name:
                  type: string
                  example: Brian
                last_name:
                  type: string
                  example: Jackson
                title:
                  type: string
                  example: Mr
                phone_work:
                  type: string
                  example: '12345'
                phone_home:
                  type: string
                  example: '12345'
                mobile:
                  type: string
                  example: '12345'
                vat_no:
                  type: integer
                  example: 20
                website:
                  type: string
                  example: www.yourwebsite.com
                address_name:
                  type: string
                  example: Queens road
                address_line_1:
                  type: string
                  example: 42 Raven drive
                address_line_2:
                  type: string
                  example: 3 Swan court
                city:
                  type: string
                  example: London
                county:
                  type: string
                  example: Greater London
                country:
                  type: string
                  example: United Kingdom
                postcode:
                  type: string
                  example: NW14DG
            example:
              city: Kent
      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: 1
                  title: Mr
                  name: My Company
                  address: My Favourite One, 31 Eagle Road, 5 Raven Court, Kent, Greater London, NW14SA,
                    United Kingdom
                  address_line_1: 31 Eagle Road
                  address_line_2: 5 Raven Court
                  city: Kent
                  county: Greater London
                  country: United Kingdom
                  postcode: NW14SA
                  website: companyWebsite@gmail.com
                  phone_home: '1234'
                  phone_work: '123'
                  phone_mobile: '12345'
                  email: emailCompany@gmail.com
                  registration_status: invited
                  company: My Company
                  vat_no: 0
                  contacts:
                  - id: 2
                    name: Michael O'Brian
                    main_contact: true
                    phone_home: '1234'
                    phone_work: '123'
                    phone_mobile: '12345'
                    email: emailCompany@gmail.com
                    registration_status: invited
                  tags: []
                  modified: '2020-06-30T10:55:22+01:00'
                  created: '2020-06-30T10:55:22+01:00'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteEntity
      summary: Delete Entity
      tags:
      - Entities
      parameters:
      - name: entity_id
        in: path
        required: true
        description: Arthur entity id.
        schema:
          type: integer
      - $ref: '#/components/parameters/EntityId'
      description: This endpoint deletes an existing entity using the entity  id .
      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
                message: Owner deleted successfully.
        '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'