openapi: 3.1.0
info:
  title: Example (EG) APIs
  description: |
    **Example** provides function as a service.
  version: 1.0.0.0
  contact:
    name: StepChange
    x-name-full: >
      Foundation for Credit Counselling, 123 Albion Street, Leeds, LS2 8ER trading as StepChange Debt Charity and StepChange Debt Charity Scotland. 

      A registered charity no.1016630 and SC046263. It is a limited company registered in England and Wales (company no:2757055). 

      Authorised and regulated by the Financial Conduct Authority (Firm Registration Number 729047)
    x-name-location: 123 Albion Street · Leeds · LS2 8ER · United Kingdom
    x-combined-contact: https://www.stepchange.org/
    x-todo: This is an example that can be used as a template
    url: https://www.stepchange.org/s
    email: contactus@stepchange.org
  license:
    name: Proprietary License
    url: https://www.stepchange.org/
externalDocs:
  description: Application User Guide
  url: /v1/example/doc/html/user-guide/index.html
servers:
- url: /v1/example
paths:
  /readiness:
    get:
      summary: Returns a simple status response about the operational state of (readiness)
      security:
      - openId:
        - read:example_client
        - read:example_document
        - read:example_admin
      operationId: getReadiness
      tags:
      - Integration
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  point:
                    $ref: 'https://api.cowdrey.net/domain/schemas.yaml#/components/schemas/dateTime'
              examples:
                ok:
                  value:
                    point: 20241118T150800
        '400':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/BadRequest'
        '401':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/UnauthorizedError'
        '404':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/NotFound'
  /currency:
    get:
      summary: List of all defined currencies
      security:
      - openId:
        - read:example_client
        - read:example_admin
      operationId: getAllCurrencies
      parameters:
      - $ref: 'https://api.cowdrey.net/domain/paramters.yaml#/components/parameters/pageSize'
      - $ref: 'https://api.cowdrey.net/domain/paramters.yaml#/components/parameters/pageNumber'
      tags:
      - Currencies
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    currencyId:
                      $ref: 'https://api.cowdrey.net/domain/schemas.yaml#/components/schemas/currencyId'
                    name:
                      $ref: 'https://api.cowdrey.net/domain/schemas.yaml#/components/schemas/currencyName'
                    symbol:
                      $ref: 'https://api.cowdrey.net/domain/schemas.yaml#/components/schemas/currencySymbol'
                    isoCode:
                      $ref: 'https://api.cowdrey.net/domain/schemas.yaml#/components/schemas/currencyIsoCode'
                    rate:
                      description: currency conversion rate from default currency to this currency
                      type: number
                      format: currency
              examples:
                sample:
                  value:
                  - currencyId: 578a82ad-a7ce-4f9c-ba5f-fbe27c1886f5
                    name: Euro
                    symbol: €
                    isoCode: EUR
                    rate: 1.2
                  - currencyId: 007fa4b5-9776-4e99-a116-095398b5d47a
                    name: Sterling
                    symbol: £
                    isoCode: GBP
                    rate: 1
                  - currencyId: 300e2d59-e873-4ecc-a3ad-58e44e3f3c03
                    name: United States dollar
                    symbol: $
                    isoCode: USD
                    rate: 1.17
        '400':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/BadRequest'
        '401':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/UnauthorizedError'
        '404':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/NotFound'
  /currency/default:
    get:
      summary: Get default monetary currency
      security:
      - openId:
        - read:example_client
        - read:example_admin
      operationId: getDefaultCurrency
      tags:
      - Currencies
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  currencyId:
                    $ref: 'https://api.cowdrey.net/domain/schemas.yaml#/components/schemas/currencyId'
                  name:
                    $ref: 'https://api.cowdrey.net/domain/schemas.yaml#/components/schemas/currencyName'
                  symbol:
                    $ref: 'https://api.cowdrey.net/domain/schemas.yaml#/components/schemas/currencySymbol'
                  isoCode:
                    $ref: 'https://api.cowdrey.net/domain/schemas.yaml#/components/schemas/currencyIsoCode'
              examples:
                sample:
                  value:
                    currencyId: 007fa4b5-9776-4e99-a116-095398b5d47a
                    name: Sterling
                    symbol: £
                    isoCode: GBP
        '400':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/BadRequest'
        '401':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/UnauthorizedError'
        '404':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/NotFound'
  '/currency{currencyId}':
    patch:
      summary: update currency conversion rate
      security:
      - openId:
        - write:example_admin
      operationId: updateCurrencyRate
      parameters:
      - $ref: 'https://api.cowdrey.net/domain/paramters.yaml#/components/parameters/currencyId'
      tags:
      - Currencies
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - rate
              properties:
                rate:
                  type: number
                  format: currency
                  minimum: 0
            examples:
              sample:
                value:
                  rate: 0.85
      responses:
        '204':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/NoContent'
        '400':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/BadRequest'
        '401':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/UnauthorizedError'
        '404':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/NotFound'
    post:
      summary: Change default currency
      security:
      - openId:
        - write:example_admin
      operationId: updateCurrencyDefault
      parameters:
      - $ref: 'https://api.cowdrey.net/domain/paramters.yaml#/components/parameters/currencyId'
      tags:
      - Currencies
      responses:
        '204':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/NoContent'
        '400':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/BadRequest'
        '401':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/UnauthorizedError'
        '404':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/NotFound'
  /clients:
    get:
      summary: Export clients in bulk
      security:
      - openId:
        - read:example_admin
      operationId: getMultipleclients
      tags:
      - Clients
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: 'https://api.cowdrey.net/domain/schemas.yaml#/components/schemas/clientBulk'
        '400':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/BadRequest'
        '401':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/UnauthorizedError'
        '404':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/NotFound'
    post:
      summary: Import clients in bulk
      security:
      - openId:
        - write:example_admin
      operationId: addMultipleclients
      tags:
      - Clients
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              description: |
                multiple single client definitions inside JSON array,
                *note*: existing clients (with same identifier) will be replaced
              minItems: 1
              items:
                $ref: 'https://api.cowdrey.net/domain/schemas.yaml#/components/schemas/clientBulk'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: internal client identifiers returned in the same order as supplied
                type: array
                items:
                  $ref: 'https://api.cowdrey.net/domain/schemas.yaml#/components/schemas/clientId'
              examples:
                sample:
                  value:
                  - 07bc9f28-cc27-4f3a-958b-dd8fd1034c2c
        '400':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/BadRequest'
        '401':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/UnauthorizedError'
        '404':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/NotFound'
  /client:
    get:
      summary: List of all known clients
      security:
      - openId:
        - read:example_client
      operationId: getAllclients
      parameters:
      - $ref: 'https://api.cowdrey.net/domain/paramters.yaml#/components/parameters/pageSize'
      - $ref: 'https://api.cowdrey.net/domain/paramters.yaml#/components/parameters/pageNumber'
      tags:
      - Clients
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: 'https://api.cowdrey.net/domain/schemas.yaml#/components/schemas/clientId'
              examples:
                sample:
                  value:
                  - 07bc9f28-cc27-4f3a-958b-dd8fd1034c2c
                  - 0de00152-657a-43c8-92ba-245428a23d74
                  - 582ad17e-d1cc-41f9-8277-09b2f7112d58
                  - 7060d226-d483-43c6-8432-4ed4de0fcd27
                  - bdf1c15a-c91f-472f-bde6-2b3ff212b051
                  - ffb9e869-a240-4a99-9f46-109802fb44e6
                  - 532dc221-d753-4799-815c-d7b9d36c59bc
                  - 43939c0a-fade-44d5-9eb3-4e50f9698d13
                  - 2e8c5466-4d0c-4193-91e0-605a45770833
                  - e883b5ce-fca6-474d-873a-7b7cdaef097e
        '400':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/BadRequest'
        '401':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/UnauthorizedError'
        '404':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/NotFound'
    post:
      summary: Add single client
      security:
      - openId:
        - write:example_client
      operationId: addSingleclient
      tags:
      - Clients
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: 'https://api.cowdrey.net/domain/schemas.yaml#/components/schemas/clientNew'
            examples:
              single:
                value:
                  reference: gbr-lds-daro1
                  title: Mr.
                  forename: Darren
                  surname: Aro
                  dateOfBirth: '19931109'
                  activated: '20250418'
                  deactivated: '20260430'
                  currency: GBP
                  location:
                    country: GBR
                    region: West Yorkshire
                    town: Leeds
                    street: Albion Street
                    premisesNameNumber: '123'
                    postalCode: LS2 8ER
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  clientId:
                    $ref: 'https://api.cowdrey.net/domain/schemas.yaml#/components/schemas/clientId'
              example:
                clientId: 86e420f1-137b-4e34-9ff7-18bd12743a10
        '400':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/BadRequest'
        '401':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/UnauthorizedError'
        '404':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/NotFound'
  '/client/{clientId}':
    patch:
      summary: Update aspects of single client
      security:
      - openId:
        - write:example_client
      operationId: updateSingleclient
      parameters:
      - $ref: 'https://api.cowdrey.net/domain/paramters.yaml#/components/parameters/clientId'
      tags:
      - Clients
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: 'https://api.cowdrey.net/domain/schemas.yaml#/components/schemas/clientUpdate
            examples:
              single:
                value:
                  deactivated: '20260430'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  clientId:
                    $ref: 'https://api.cowdrey.net/domain/schemas.yaml#/components/schemas/clientId'
              example:
                clientId: 86e420f1-137b-4e34-9ff7-18bd12743a10
        '400':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/BadRequest'
        '401':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/UnauthorizedError'
        '404':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/NotFound'
    put:
      summary: Replace single client
      security:
      - openId:
        - write:example_client
      operationId: replaceSingleclient
      parameters:
      - $ref: 'https://api.cowdrey.net/domain/paramters.yaml#/components/parameters/clientId'
      tags:
      - Clients
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: 'https://api.cowdrey.net/domain/schemas.yaml#/components/schemas/clientReplace
            examples:
              single:
                value:
                  clientId: 86e420f1-137b-4e34-9ff7-18bd12743a10
                  reference: gbr-lds-daro1
                  title: Mr.
                  forename: Darren
                  surname: Aro
                  dateOfBirth: '19931109'
                  activated: '20250418'
                  location:
                    country: GBR
                    region: West Yorkshire
                    town: Leeds
                    street: Albion Street
                    premisesNameNumber: '123'
                    postalCode: LS2 8ER
                  delete: false
      responses:
        '204':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/NoContent'
        '400':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/BadRequest'
        '401':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/UnauthorizedError'
        '404':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/NotFound'
    delete:
      summary: Delete specified client
      security:
      - openId:
        - write:example_client
      operationId: deleteSingleclient
      tags:
      - Clients
      parameters:
      - $ref: 'https://api.cowdrey.net/domain/paramters.yaml#/components/parameters/clientId'
      responses:
        '204':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/NoContent'
        '400':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/BadRequest'
        '401':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/UnauthorizedError'
        '404':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/NotFound'
    get:
      summary: Get specified client
      security:
      - openId:
        - read:example_client
      operationId: getSingleclient
      tags:
      - Clients
      parameters:
      - $ref: 'https://api.cowdrey.net/domain/paramters.yaml#/components/parameters/clientId'
      - $ref: 'https://api.cowdrey.net/domain/paramters.yaml#/components/parameters/dateTime'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: 'https://api.cowdrey.net/domain/schemas.yaml#/components/schemas/client'
              examples:
                single:
                  value:
                    clientId: 86e420f1-137b-4e34-9ff7-18bd12743a10
                    reference: gbr-lds-daro1
                    activated: '20250418'
                    currency: GBP
                    location:
                      country: GBR
                      region: West Yorkshire
                      town: Leeds
                      street: Albion Street
                      premisesNameNumber: '123'
                      postalCode: LS2 8ER
                    delete: false
        '400':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/BadRequest'
        '401':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/UnauthorizedError'
        '404':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/NotFound'
  /document:
    post:
      summary: >
        Add content to the document store, *note*: all documents are considered to be historical
      security:
      - openId:
        - write:example_document
      operationId: addDocument
      tags:
      - Documents
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                document:
                  description: document filename that is being uploaded
                  type: string
                form-content:
                  type: string
                  format: binary
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - documentId
                - hash
                - size
                - mimeType
                properties:
                  documentId:
                    $ref: 'https://api.cowdrey.net/domain/schemas.yaml#/components/schemas/documentId'
                  hash:
                    type: string
                    description: MD5 Hash of uploaded file
                  size:
                    type: number
                    format: integer
                    description: size in bytes of uploaded file
                    minimum: 0
                  mimeType:
                    $ref: 'https://api.cowdrey.net/domain/schemas.yaml#/components/schemas/ianaMimeType'
              examples:
                sample:
                  value:
                    documentId: d94641c3-4507-4589-882e-3d31621b3a0e
                    hash: c96970e2220bf6385edc6b56d9682e4a
                    size: 4286
                    mimeType: image/vnd.microsoft.icon
        '400':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/BadRequest'
        '401':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/UnauthorizedError'
        '413':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/TooLarge'
    get:
      summary: List of all known documents
      security:
      - openId:
        - read:example_document
      operationId: getAllDocuments
      parameters:
      - $ref: 'https://api.cowdrey.net/domain/paramters.yaml#/components/parameters/pageSize'
      - $ref: 'https://api.cowdrey.net/domain/paramters.yaml#/components/parameters/pageNumber'
      tags:
      - Documents
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: 'https://api.cowdrey.net/domain/schemas.yaml#/components/schemas/documentId'
              examples:
                sample:
                  value:
                  - 5520aca1-4727-431a-aa9c-23f2e54b8a41
                  - df4600ba-c46f-428a-855d-eb84caf9b59c
        '400':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/BadRequest'
        '401':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/UnauthorizedError'
        '404':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/NotFound'
  '/document/{documentId}':
    get:
      summary: |
        Fetch specified content from the document store
      security:
      - openId:
        - read:example_document
      operationId: getDocument
      parameters:
      - $ref: 'https://api.cowdrey.net/domain/paramters.yaml#/components/parameters/documentId'
      - $ref: 'https://api.cowdrey.net/domain/paramters.yaml#/components/parameters/dateTime'
      tags:
      - Documents
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                type: string
                format: binary
        '400':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/BadRequest'
        '401':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/UnauthorizedError'
        '404':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/NotFound'
    put:
      summary: Update specified content within the document store
      security:
      - openId:
        - write:example_document
      operationId: replaceDocument
      parameters:
      - $ref: 'https://api.cowdrey.net/domain/paramters.yaml#/components/parameters/documentId'
      tags:
      - Documents
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                document:
                  description: document filename that is being uploaded
                  type: string
                form-content:
                  type: string
                  format: binary
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - documentId
                - hash
                - size
                - mimeType
                properties:
                  documentId:
                    $ref: 'https://api.cowdrey.net/domain/schemas.yaml#/components/schemas/documentId'
                  hash:
                    type: string
                    description: MD5 Hash of uploaded file
                  size:
                    type: number
                    format: integer
                    description: size in bytes of uploaded file
                    minimum: 0
                  mimeType:
                    $ref: 'https://api.cowdrey.net/domain/schemas.yaml#/components/schemas/ianaMimeType'
              examples:
                sample:
                  value:
                    documentId: d94641c3-4507-4589-882e-3d31621b3a0e
                    hash: c96970e2220bf6385edc6b56d9682e4a
                    size: 5145
                    mimeType: image/vnd.microsoft.icon
        '400':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/BadRequest'
        '401':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/UnauthorizedError'
        '413':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/TooLarge'
    delete:
      summary: |
        Remove specified content from the document store
      security:
      - openId:
        - write:example_document
      parameters:
      - $ref: 'https://api.cowdrey.net/domain/paramters.yaml#/components/parameters/documentId'
      operationId: deleteDocument
      tags:
      - Documents
      responses:
        '204':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/NoContent'
        '400':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/BadRequest'
        '401':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/UnauthorizedError'
        '404':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/NotFound'
  '/document/timeline/{documentId}':
    get:
      summary: timeline points for specified document
      security:
      - openId:
        - read:example_document
      operationId: getDocumentTimeline
      parameters:
      - $ref: 'https://api.cowdrey.net/domain/paramters.yaml#/components/parameters/documentId'
      tags:
      - Documents
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  properties:
                    point:
                      $ref: 'https://api.cowdrey.net/domain/schemas.yaml#/components/schemas/dateTime'
              examples:
                sample:
                  value:
                  - 20250102T000000
                  - 20250118T000000
                  - 20250202T000000
                  - 20250309T000000
                  - 20260401T000000
        '400':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/BadRequest'
        '401':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/UnauthorizedError'
        '404':
          $ref: 'https://api.cowdrey.net/domain/responses.yaml#/components/responses/NotFound'
components:
  requestBodies:
    client:
      $ref: 'https://api.cowdrey.net/domain/schemas.yaml#/components/schemas/clientNew'
    clientNew:
      $ref: 'https://api.cowdrey.net/domain/schemas.yaml#/components/schemas/clientNew'
    updatedclient:
      $ref: 'https://api.cowdrey.net/domain/schemas.yaml#/components/schemas/clientUpdate'
    clientBulk:
      $ref: 'https://api.cowdrey.net/domain/schemas.yaml#/components/schemas/clientBulk'
  securitySchemes:
    basicAuth:
      $ref: 'https://api.cowdrey.net/domain/securitySchemes.yaml#/components/securitySchemes/basicAuth'
    openId:
      $ref: 'https://api.cowdrey.net/domain/securitySchemes.yaml#/components/securitySchemes/openId'
    jwt:
      $ref: 'https://api.cowdrey.net/domain/securitySchemes.yaml#/components/securitySchemes/jwt'
    oauth2:
      $ref: 'https://api.cowdrey.net/domain/securitySchemes.yaml#/components/securitySchemes/oauth2'
security:
- openId:
  - read:example_admin
  - read:example_client
  - read:example_document
  - write:example_admin
  - write:example_client
  - write:example_document
