TM Forum financialAccount API

openapi: 3.2.0
info:
  title: Account Management Financial Account API
  description: This is Swagger UI environment generated for the TMF Account Management specification
  version: 4.0.0
servers:
- url: https://serverRoot/tmf-api/accountManagement/v4/
tags:
- name: financialAccount
paths:
  /financialAccount:
    get:
      operationId: listFinancialAccount
      summary: List or find FinancialAccount objects
      description: This operation list or find FinancialAccount entities
      tags:
      - financialAccount
      parameters:
      - name: fields
        description: Comma-separated properties to be provided in response
        required: false
        in: query
        schema:
          type: string
      - name: offset
        description: Requested index for start of resources to be provided in response
        required: false
        in: query
        schema:
          type: integer
      - name: limit
        description: Requested number of resources to be provided in response
        required: false
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: Success
          headers:
            X-Result-Count:
              description: Actual number of items returned in the response body
              schema:
                type: integer
            X-Total-Count:
              description: Total number of items matching criteria
              schema:
                type: integer
          content:
            application/json;charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FinancialAccount'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: createFinancialAccount
      summary: Creates a FinancialAccount
      description: This operation creates a FinancialAccount entity.
      tags:
      - financialAccount
      responses:
        '201':
          description: Created
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/FinancialAccount'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/FinancialAccount_Create'
        description: The FinancialAccount to be created
        required: true
  /financialAccount/{id}:
    get:
      operationId: retrieveFinancialAccount
      summary: Retrieves a FinancialAccount by ID
      description: This operation retrieves a FinancialAccount entity. Attribute selection is enabled for all first level attributes.
      tags:
      - financialAccount
      parameters:
      - name: id
        description: Identifier of the FinancialAccount
        required: true
        in: path
        schema:
          type: string
      - name: fields
        description: Comma-separated properties to provide in response
        required: false
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/FinancialAccount'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      operationId: patchFinancialAccount
      summary: Updates partially a FinancialAccount
      description: This operation updates partially a FinancialAccount entity.
      tags:
      - financialAccount
      parameters:
      - name: id
        description: Identifier of the FinancialAccount
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: Updated
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/FinancialAccount'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/FinancialAccount_Update'
        description: The FinancialAccount to be updated
        required: true
    delete:
      operationId: deleteFinancialAccount
      summary: Deletes a FinancialAccount
      description: This operation deletes a FinancialAccount entity.
      tags:
      - financialAccount
      parameters:
      - name: id
        description: Identifier of the FinancialAccount
        required: true
        in: path
        schema:
          type: string
      responses:
        '204':
          description: Deleted
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      description: Used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx)
      type: object
      required:
      - code
      - reason
      properties:
        code:
          type: string
          description: Application relevant detail, defined in the API or a common list.
        reason:
          type: string
          description: Explanation of the reason for the error which can be shown to a client user.
        message:
          type: string
          description: More details and corrective actions related to the error which can be shown to a client user.
        status:
          type: string
          description: HTTP Error code extension
        referenceError:
          type: string
          format: uri
          description: URI of documentation describing the error.
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class.
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name.
    FinancialAccount_Update:
      type: object
      description: 'An account of money owed by a party to another entity in exchange for goods or services that have been delivered or used. A financial (account receivable account/account payable) aggregates the amounts of one or more party accounts (billing or settlement) owned by a given party. It is a specialization of entity Account.

        Skipped properties: id,href,lastModified'
      required:
      - name
      properties:
        accountType:
          type: string
          description: 'A categorization of an account, such as individual, joint, and so forth, whose instances share some of the same characteristics. Note: for flexibility we use a String here but an implementation may use an enumeration with a limited list of valid values.'
        description:
          type: string
          description: Detailed description of the party account
        name:
          type: string
          description: Name of the account
        state:
          type: string
          description: 'Contains the lifecycle state such as: Active, Closed, Suspended and so on.'
        accountBalance:
          type: array
          items:
            $ref: '#/components/schemas/AccountBalance'
        accountRelationship:
          type: array
          items:
            $ref: '#/components/schemas/AccountRelationship'
        contact:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
        creditLimit:
          $ref: '#/components/schemas/Money'
          description: The maximum amount of money that may be charged on an account
        relatedParty:
          type: array
          items:
            $ref: '#/components/schemas/RelatedParty'
        taxExemption:
          type: array
          items:
            $ref: '#/components/schemas/AccountTaxExemption'
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    ContactMedium:
      type: object
      description: Indicates the contact medium that could be used to contact the party.
      properties:
        mediumType:
          type: string
          description: 'Type of the contact medium, such as: email address, telephone number, postal address'
        preferred:
          type: boolean
          description: If true, indicates that is the preferred contact medium
        characteristic:
          $ref: '#/components/schemas/MediumCharacteristic'
          description: Any additional characteristic(s) of this contact medium
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: The time period that the contact medium is valid for
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    AccountTaxExemption:
      type: object
      description: Proof of freedom from taxes imposed by a taxing jurisdiction
      required:
      - issuingJurisdiction
      - validFor
      properties:
        certificateNumber:
          type: string
          description: Identifier of a document that shows proof of exemption from taxes for the taxing jurisdiction
        issuingJurisdiction:
          type: string
          description: Name of the taxing jurisdiction for which taxes are exempt
        reason:
          type: string
          description: Reason of the tax exemption
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: Period for which the exemption is valid
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    MediumCharacteristic:
      type: object
      description: Describes the contact medium characteristics that could be used to contact a party (an individual or an organization)
      properties:
        city:
          type: string
          description: The city
        contactType:
          type: string
          description: 'The type of contact, for example: phone number such as mobile, fixed home, fixed office. postal address such as shipping instalation…'
        country:
          type: string
          description: The country
        emailAddress:
          type: string
          description: Full email address in standard format
        faxNumber:
          type: string
          description: The fax number of the contact
        phoneNumber:
          type: string
          description: The primary phone number of the contact
        postCode:
          type: string
          description: Postcode
        socialNetworkId:
          type: string
          description: Identifier as a member of a social network
        stateOrProvince:
          type: string
          description: State or province
        street1:
          type: string
          description: Describes the street
        street2:
          type: string
          description: Complementary street description
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    FinancialAccount_Create:
      type: object
      description: 'An account of money owed by a party to another entity in exchange for goods or services that have been delivered or used. A financial (account receivable account/account payable) aggregates the amounts of one or more party accounts (billing or settlement) owned by a given party. It is a specialization of entity Account.

        Skipped properties: id,href'
      required:
      - name
      properties:
        accountType:
          type: string
          description: 'A categorization of an account, such as individual, joint, and so forth, whose instances share some of the same characteristics. Note: for flexibility we use a String here but an implementation may use an enumeration with a limited list of valid values.'
        description:
          type: string
          description: Detailed description of the party account
        lastModified:
          type: string
          format: date-time
          description: Date of last modification of the account
        name:
          type: string
          description: Name of the account
        state:
          type: string
          description: 'Contains the lifecycle state such as: Active, Closed, Suspended and so on.'
        accountBalance:
          type: array
          items:
            $ref: '#/components/schemas/AccountBalance'
        accountRelationship:
          type: array
          items:
            $ref: '#/components/schemas/AccountRelationship'
        contact:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
        creditLimit:
          $ref: '#/components/schemas/Money'
          description: The maximum amount of money that may be charged on an account
        relatedParty:
          type: array
          items:
            $ref: '#/components/schemas/RelatedParty'
        taxExemption:
          type: array
          items:
            $ref: '#/components/schemas/AccountTaxExemption'
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    FinancialAccount:
      type: object
      description: An account of money owed by a party to another entity in exchange for goods or services that have been delivered or used. A financial (account receivable account/account payable) aggregates the amounts of one or more party accounts (billing or settlement) owned by a given party. It is a specialization of entity Account.
      required:
      - name
      properties:
        id:
          type: string
          description: Unique identifier of the account
        href:
          type: string
          description: Unique reference of the account
        accountType:
          type: string
          description: 'A categorization of an account, such as individual, joint, and so forth, whose instances share some of the same characteristics. Note: for flexibility we use a String here but an implementation may use an enumeration with a limited list of valid values.'
        description:
          type: string
          description: Detailed description of the party account
        lastModified:
          type: string
          format: date-time
          description: Date of last modification of the account
        name:
          type: string
          description: Name of the account
        state:
          type: string
          description: 'Contains the lifecycle state such as: Active, Closed, Suspended and so on.'
        accountBalance:
          type: array
          items:
            $ref: '#/components/schemas/AccountBalance'
        accountRelationship:
          type: array
          items:
            $ref: '#/components/schemas/AccountRelationship'
        contact:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
        creditLimit:
          $ref: '#/components/schemas/Money'
          description: The maximum amount of money that may be charged on an account
        relatedParty:
          type: array
          items:
            $ref: '#/components/schemas/RelatedParty'
        taxExemption:
          type: array
          items:
            $ref: '#/components/schemas/AccountTaxExemption'
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    Money:
      type: object
      description: A base / value business entity used to represent money
      properties:
        unit:
          type: string
          description: Currency (ISO4217 norm uses 3 letters to define the currency)
        value:
          type: number
          format: float
          description: A positive floating point number
    AccountBalance:
      type: object
      description: Balances linked to the account
      required:
      - amount
      - balanceType
      - validFor
      properties:
        balanceType:
          type: string
          description: 'Type of the balance : deposit balance, disputed balance, loyalty balance, receivable balance...'
        amount:
          $ref: '#/components/schemas/Money'
          description: Balance amount
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: Balance validity period
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    AccountRef:
      type: object
      description: Account reference. A account may be a party account or a financial account.
      properties:
        id:
          type: string
          description: Unique identifier of the account
        href:
          type: string
          description: Reference of the account
        description:
          type: string
          description: Detailed description of the account
        name:
          type: string
          description: Name of the account
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
      required:
      - id
    Contact:
      type: object
      description: An individual or an organization used as a contact point for a given account and accessed via some contact medium.
      required:
      - contactType
      - validFor
      properties:
        contactName:
          type: string
          description: A displayable name for that contact
        contactType:
          type: string
          description: Type of contact (primary, secondary...)
        partyRoleType:
          type: string
          description: Identifies what kind of party role type is linked to the contact (a account manager...)
        contactMedium:
          type: array
          items:
            $ref: '#/components/schemas/ContactMedium'
        relatedParty:
          $ref: '#/components/schemas/RelatedParty'
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: Validity period of that contact
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    TimePeriod:
      type: object
      description: A period of time, either as a deadline (endDateTime only) a startDateTime only, or both
      properties:
        endDateTime:
          type: string
          format: date-time
          description: End of the time period, using IETC-RFC-3339 format
        startDateTime:
          type: string
          format: date-time
          description: Start of the time period, using IETC-RFC-3339 format. If you define a start, you must also define an end
    AccountRelationship:
      type: object
      description: Significant connection between accounts. For instance an aggregating account for a list of shop branches each having its own billing account.
      required:
      - relationshipType
      - validFor
      properties:
        relationshipType:
          type: string
          description: Type of relationship
        account:
          $ref: '#/components/schemas/AccountRef'
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: Validity period of that relationship
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    RelatedParty:
      type: object
      description: Related Entity reference. A related party defines party or party role linked to a specific entity.
      required:
      - '@referredType'
      - id
      - name
      properties:
        id:
          type: string
          description: Unique identifier of a related entity.
        href:
          type: string
          description: Reference of the related entity.
        name:
          type: string
          description: Name of the related entity.
        role:
          type: string
          description: Role played by the related party
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.