TM Forum partyAccount API

openapi: 3.2.0
info:
  title: Account Management Party 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: partyAccount
paths:
  /partyAccount:
    get:
      operationId: listPartyAccount
      summary: List or find PartyAccount objects
      description: This operation list or find PartyAccount entities
      tags:
      - partyAccount
      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/PartyAccount'
        '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: createPartyAccount
      summary: Creates a PartyAccount
      description: This operation creates a PartyAccount entity.
      tags:
      - partyAccount
      responses:
        '201':
          description: Created
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/PartyAccount'
        '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/PartyAccount_Create'
        description: The PartyAccount to be created
        required: true
  /partyAccount/{id}:
    get:
      operationId: retrievePartyAccount
      summary: Retrieves a PartyAccount by ID
      description: This operation retrieves a PartyAccount entity. Attribute selection is enabled for all first level attributes.
      tags:
      - partyAccount
      parameters:
      - name: id
        description: Identifier of the PartyAccount
        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/PartyAccount'
        '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: patchPartyAccount
      summary: Updates partially a PartyAccount
      description: This operation updates partially a PartyAccount entity.
      tags:
      - partyAccount
      parameters:
      - name: id
        description: Identifier of the PartyAccount
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: Updated
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/PartyAccount'
        '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/PartyAccount_Update'
        description: The PartyAccount to be updated
        required: true
    delete:
      operationId: deletePartyAccount
      summary: Deletes a PartyAccount
      description: This operation deletes a PartyAccount entity.
      tags:
      - partyAccount
      parameters:
      - name: id
        description: Identifier of the PartyAccount
        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.
    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
    BillStructure:
      type: object
      description: The structure of the bill for party accounts (billing or settlement).
      properties:
        cycleSpecification:
          $ref: '#/components/schemas/BillingCycleSpecificationRefOrValue'
        format:
          $ref: '#/components/schemas/BillFormatRefOrValue'
        presentationMedia:
          type: array
          items:
            $ref: '#/components/schemas/BillPresentationMediaRefOrValue'
        '@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
    BillFormatRefOrValue:
      type: object
      description: An attachment by value or by reference.
      required:
      - name
      - isRef
      properties:
        id:
          type: string
          description: Unique identifier of the bill format
        href:
          type: string
          description: Reference of the bill format
        description:
          type: string
          description: An explanatory text for this bill format
        isRef:
          default: true
          type: boolean
        name:
          type: string
          description: A short descriptive name
        '@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.
    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.
    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
    PartyAccount_Update:
      type: object
      description: 'Account used for billing or for settlement purposes concerning a given party (an organization or an individual). It is a specialization of entity Account.

        Skipped properties: id,href,accountBalance'
      required:
      - name
      - relatedParty
      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
        paymentStatus:
          type: string
          description: The condition of the account, such as due, paid, in arrears.
        state:
          type: string
          description: 'Contains the lifecycle state such as: Active, Closed, Suspended and so on.'
        accountRelationship:
          type: array
          items:
            $ref: '#/components/schemas/AccountRelationship'
        billStructure:
          $ref: '#/components/schemas/BillStructure'
        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
        defaultPaymentMethod:
          $ref: '#/components/schemas/PaymentMethodRef'
        financialAccount:
          $ref: '#/components/schemas/FinancialAccountRef'
        paymentPlan:
          type: array
          items:
            $ref: '#/components/schemas/PaymentPlan'
        relatedParty:
          type: array
          items:
            $ref: '#/components/schemas/RelatedParty'
          minItems: 1
        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
    PaymentMethodRef:
      type: object
      description: PaymentMethod reference. A payment method defines a specific mean of payment (e.g direct debit).
      properties:
        id:
          type: string
          description: Unique identifier of the payment mean
        href:
          type: string
          description: Reference of the payment mean
        name:
          type: string
          description: Name of the payment mean
        '@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
    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
    BillPresentationMediaRefOrValue:
      type: object
      description: An attachment by value or by reference.
      required:
      - name
      - isRef
      properties:
        id:
          type: string
          description: Unique identifier of the bill presentation media
        href:
          type: string
          description: Reference of the bill presentation media
        description:
          type: string
          description: An explanatory text describing this bill presentation media
        isRef:
          default: true
          type: boolean
        name:
          type: string
          description: A short descriptive name
        '@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.
    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
    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
    BillingCycleSpecificationRefOrValue:
      type: object
      description: An attachment by value or by reference.
      required:
      - name
      - isRef
      properties:
        id:
          type: string
          description: Unique identifier of the billing cycle specification
        href:
          type: string
          description: Reference of the billing cycle specification
        billingDateShift:
          type: integer
          description: An offset of a billing/settlement date. The offset is expressed as number of days with regard to the start of the billing/settlement period.
        billingPeriod:
          type: string
          description: 'A billing time period. It can be recurring, for example: week, month, quarter of year, year .'
        chargeDateOffset:
          type: integer
          description: An offset of a date through which charges previously received by the billing system will appear on the bill. The offset is expressed as number of days with regard to the start of the BillingPeriod.
        creditDateOffset:
          type: integer
          description: An offset of a date through which credits previously received by the billing system will appear on the bill. The offset is expressed as number of days with regard to the start of the BillingPeriod.
        dateShift:
          type: integer
          description: An offset of a billing/settlement date. The offset is expressed as number of days with regard to the start of the billing/settlement period.
        description:
          type: string
          description: An explanation regarding this billing cycle specification
        frequency:
          type: string
          description: Frequency of the billing cycle (monthly for instance)
        isRef:
          default: true
          type: boolean
        mailingDateOffset:
          type: integer
          description: An offset of a customer bill mailing date. The offset is expressed as number of days with regard to the start of the BillingPeriod.
        name:
          type: string
          description: A short descriptive name
        paymentDueDateOffset:
          type: integer
          description: An offset of a payment due date. The offset is expressed as number of days with regard to the start of the BillingPeriod.
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: The period for which the billing specification cycle 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
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
    PaymentPlan:
      type: object
      description: Defines a plan for payment (when a party wants to spread his payments)
      properties:
        numberOfPayments:
          type: integer
          description: Number of payments used to spread the global payment
        paymentFrequency:
          type: string
          description: Frequency of the payments, such as monthly and bimonthly
        planType:
          type: string
          description: Type of payment plan
        priority:
          type: integer
          description: Priority of the payment plan
        status:
          type: string
          description: Status of the payment plan (effective, ineffective)
        paymentMethod:
          $ref: '#/components/schemas/PaymentMethodRef'
        totalAmount:
          $ref: '#/components/schemas/Money'
          description: Amount paid
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: Validity period of the payment plan
        '@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
    FinancialAccountRef:
      type: object
      description: AccountReceivable reference. An account of money owed by a party to another entity in exchange for goods or services that have been delivered or used. An account receivable aggregates the amounts of one or more party accounts (billing or settlement) owned by a 

# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tm-forum/refs/heads/main/openapi/tm-forum-partyaccount-api-openapi.yml