Basware Organizations API

openapi: 3.2.0
info:
  title: Basware APIs for Purchase-to-Pay and Master Data import…
  description: The Basware APIs documented here are for Purchase-to-Pay use cases and for importing Master Data to Basware services.
  version: v1
servers:
- url: ''
security:
- Bearer: []
- oauth2authentication: []
tags:
- name: Organizations
paths:
  /v1/organizations:
    post:
      tags:
      - Organizations
      summary: Creates new organization element(s), fully overwrites previous record if exists.
      description: 'Notes:

        1. Organization element type ''Company'' requires fields ''homeCurrency'' and ''countryCode'' to have values.

        2. Organization element type ''Group'' does not support adding organization identifiers.'
      parameters:
      - name: Content-Type
        in: header
        description: Specifies the media type of the resource. Value application/json is supported.
        schema:
          type: string
        example: application/json
      requestBody:
        description: ''
        content:
          application/json-patch+json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/OrganizationEntity'
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/OrganizationEntity'
          text/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/OrganizationEntity'
          application/*+json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/OrganizationEntity'
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrganizationEntity'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrganizationEntity'
            text/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrganizationEntity'
        '400':
          description: Bad request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            text/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
        '403':
          description: Forbidden
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            text/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
        '500':
          description: Unexpected error
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            text/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
      operationId: postV1Organizations
      x-operation-id-source: derived
    get:
      tags:
      - Organizations
      summary: Returns existing organization elements
      parameters:
      - name: level
        in: query
        description: Sets how many levels of the organization to include. If no parentExternalCode is given, it starts from the top and goes down to the specified level.
        schema:
          type: string
      - name: parentExternalCode
        in: query
        description: Returns child organizations linked to the specified parentExternalCode. When level is also provided, it includes all child organizations up to the given level.
        schema:
          type: string
      - name: pageSize
        in: query
        description: A limit for the number of items to be returned for one request. Limit can range between 1 and 300 items.
        schema:
          type: integer
          format: int32
          default: 300
      - name: lastUpdated
        in: query
        description: Date Filter. Returns items that have been updated after specified date. The lastUpdated filter is ignored when used together with level or parentExternalCode. Use it alone for the filter to apply.
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrganizationEntity'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrganizationEntity'
            text/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrganizationEntity'
        '400':
          description: Bad request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            text/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
        '403':
          description: Forbidden
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            text/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
        '500':
          description: Unexpected error
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            text/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
      operationId: getV1Organizations
      x-operation-id-source: derived
    delete:
      tags:
      - Organizations
      summary: Can be used for removing existing organization elements in draft state…
      description: 'Notes:

        1. Only unpublished, draft state organization elements can be removed (those having ''published'' = ''false'').

        2. Removing an organization element will also remove it''s child organization elements.'
      requestBody:
        description: ''
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/DeleteOrganisationRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteOrganisationRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/DeleteOrganisationRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/DeleteOrganisationRequest'
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/DeleteOrganisationResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteOrganisationResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/DeleteOrganisationResponse'
        '202':
          description: RequestAccepted
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/DeleteOrganisationResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteOrganisationResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/DeleteOrganisationResponse'
        '400':
          description: BadRequest
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            text/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
        '401':
          description: Unauthorized
        '500':
          description: Unexpected error
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            text/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
      operationId: deleteV1Organizations
      x-operation-id-source: derived
  /v1/organizations/{externalCode}:
    get:
      tags:
      - Organizations
      summary: Returns a single organization element by externalCode -identifier
      parameters:
      - name: externalCode
        in: path
        description: ''
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/OrganizationEntity'
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationEntity'
            text/json:
              schema:
                $ref: '#/components/schemas/OrganizationEntity'
      operationId: getV1OrganizationsByExternalCode
      x-operation-id-source: derived
components:
  schemas:
    OrganizationEntity:
      required:
      - countryCode
      - externalCode
      - homeCurrency
      - organizationCode
      - organizationName
      - orgTreeLocation
      - type
      type: object
      properties:
        externalCode:
          maxLength: 100
          minLength: 1
          pattern: ^[^;:=]*$
          type: string
          description: 'External identifier for the organization element. Used to identify right organization element when the organization element is updated. Needs to be unique within the API. Cannot contain characters : ; =.'
          example: 4847-31231212-212121-1212
        organizationCode:
          maxLength: 25
          minLength: 1
          type: string
          description: Organization code. Must be unique within the tenant. Value cannot be modified after publishing.
          example: '200'
        organizationName:
          maxLength: 100
          minLength: 1
          type: string
          description: Organization name.
          example: Acme corporation
        type:
          enum:
          - Company
          - Group
          - Unit
          type: string
          description: 'Specifies organization element type: ''Group'' is a collection point of other organization elements. ''Company'' is normally used to represent a legal company. ''OrganizationUnit'' is a general element which is usually representing business unit or cost center in system.'
          example: Company
        homeCurrency:
          maxLength: 3
          minLength: 3
          type: string
          description: Specifies home currency for the organization element. Mandatory when 'type' = 'Company'.
          example: EUR
        countryCode:
          maxLength: 2
          minLength: 0
          type: string
          description: Specifies home country for the organization element. Mandatory when 'type' = 'Company'. Value cannot be modified after publishing. Country code is specified in ISO 3166-1 alpha-2 format.
          example: FI
        published:
          type: boolean
          description: 'Determines whether the organization element is a draft (for previewing in Basware Admin) or whether it is published to be available in Basware systems. Organization elements can no longer be removed after publishing. True = published to all systems, False = Draft. Default value: false.'
          example: true
        activeFrom:
          type:
          - string
          - 'null'
          description: Specifies validity start date for the organization element.
          format: date-time
          example: '2022-01-01'
        activeTo:
          type:
          - string
          - 'null'
          description: Specifies validity end date for the organization element.
          format: date-time
          example: '2026-12-12'
        description:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Available for additional information or a description regarding the company.
          example: ''
        sourceSystem:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Specifies the source system from where the organization element is imported.
          example: SAP_1
        lastUpdated:
          type: string
          description: Timestamp when the record was last updated. This value is set automatically by API when a new/changed record is received.
          format: date-time
        orgTreeLocation:
          $ref: '#/components/schemas/OrganizationTreeLocation'
        businessIdentifiers:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Identifiers'
          description: 'Company business identifiers. See "Usage scenario 6: Import companies on Basware API developer site for explanation of available identifier type values. Note: Identifiers are not allowed on ''group'' type organization elements.'
      additionalProperties: false
    ErrorEntity:
      type: object
      properties:
        externalCode:
          type:
          - string
          - 'null'
          description: External code of record on which error occurred (when available).
          example: 4847-31231212-212121-1212
        type:
          enum:
          - BUSINESS
          - VALIDATION
          - TECHNICAL
          - SECURITY
          type: string
          description: Error type.
          example: ''
        code:
          enum:
          - EXTERNAL_CODE_MISMATCH
          - SCHEMA_VALIDATION_ERROR
          - CONFLICT_IN_POST
          - DATA_ORIGIN_VALIDATION_ERROR
          - ACCESS_TOKEN_VALIDATION_ERROR
          - CREDENTIAL_VALIDATION_ERROR
          - PARAMETER_VALIDATION_ERROR
          - UNEXPECTED_ERROR
          - METHOD_NOT_ALLOWED
          - ENTITY_NOT_FOUND
          - DATA_VALIDATION_FAILED
          - SNS_PUBLISH_ERROR
          - SQS_PUBLISH_ERROR
          type: string
          description: Error code.
          example: ''
        message:
          type:
          - string
          - 'null'
          description: Specific error message.
          example: ''
        info:
          type:
          - string
          - 'null'
          description: Information about type of the error.
          example: ''
      additionalProperties: false
    DeleteOrganisationResponse:
      type: object
      properties:
        taskStatus:
          enum:
          - Success
          - Failed
          type: string
        deletedRecordCount:
          type:
          - integer
          - 'null'
          format: int32
        deletedRecordExternalCodes:
          type:
          - array
          - 'null'
          items:
            type: string
        message:
          type:
          - string
          - 'null'
      additionalProperties: false
    Identifiers:
      required:
      - description
      - externalCode
      - id
      - schemeId
      type: object
      properties:
        externalCode:
          maxLength: 100
          minLength: 1
          type: string
          description: External identifier for the Business identifier. Needs to be unique within business identifiers.
          example: 4847-31231212-212121-1212
        id:
          maxLength: 100
          minLength: 0
          type: string
          description: Specifies identifier value for the selected identifier type. The identifier type is determined by field 'schemeId'.
          example: FI190101452
        schemeId:
          minLength: 1
          type: string
          description: 'Specifies identifier type. The identifier value is determined by field ''id''. Available values:

            "DUNS", "EMAIL-RFC2822", "GLN", "IBAN", "ISO6523-ACTORID-UPIS", "UNKNOWN", "FI:Y-TUNNUS", "FI:VAT", "FI:OVT", "SE:ORGNR", "SE:VAT", "GLN", "NO:ORGNR", "NO:VAT", "DK:CVR", "DK:P", "DK:DIGST", "GLN", "FR:SIRENE", "FR:SIRET", "FR:VAT", "GLN", "DE:ORGNR", "DE:HRN", "DE:VAT", "DE:LWID", "GLN", "BE:EN", "BE:VAT", "GLN", "NL:KVK", "NL:VAT", "IBAN", "IT:FISCALE", "IT:IPA", "IT:IVA", "PT:NIF", "ES:CIF", "ES:NIF", "PL:KRS", "PL:REGON", "PL:VAT", "EE:ORGNR", "EE:VAT", "IE:ORGNR", "IE:VAT", "GLN", "GB:ORGNR", "GB:VAT", "XI:VAT", "GB:UTR", "GLN", "AT:ORGNR", "AT:VAT", "AT:GOV", "AT:CID", "CH:ORGNR", "CH:VAT", "HU:VAT", "RO:VAT", "GR:VAT", "GR:GEMI", "LI:VAT", "LU:VAT", "LT:LEC", "LT:VAT", "LV:VAT", "CZ:ORGNR", "CZ:VAT", "IS:KTNR", "IS:VAT", "BG:VAT", "HR:VAT", "SK:ORGNR", "SK:VAT", "CY:VAT", "US:TIN", "CA:BN", "CA:GST", "MX:VAT", "IN:GSTIN", "CN:BRN", "MY:GST", "AU:ABN", "AU:ACN", "AU:TFN", "NZ:BN"'
          example: FI:VAT
        description:
          maxLength: 500
          minLength: 0
          type: string
          description: Describes the business identifier. Auto-filled by API based on identifier scheme id, but can be set manually for 'UNKNOWN' type identifiers to provide information what kind of identifier is used.
          example: Finnish Value Added Tax identifier.
        category:
          enum:
          - Legal
          - NonLegal
          type:
          - string
          - 'null'
          description: Specifies identifier category. Legal identifiers can no longer be changed after the company is published.
        inherited:
          type: boolean
          description: Specifies whether the identifier has been inherited from a parent company. Legal identifiers for Units are automatically inherited from parent Company.
          example: false
      additionalProperties: false
      description: Identifiers
    ResponseEntityList:
      type: object
      properties:
        requestId:
          type:
          - string
          - 'null'
          description: ID of the request on which error occurred (generated by Basware API).
          example: fbc082a2-65a4-469c-b230-d84a252f18fc
        hasErrors:
          type: boolean
          description: Specifies whether the request has errors.
        errors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ErrorEntity'
      additionalProperties: false
      description: Errors returned here are returned synchronously from Basware API middle layer. Additional errors coming from target system(s) may be returned through errorFeedbacks API.
    OrganizationTreeLocation:
      required:
      - parentExternalCode
      type: object
      properties:
        pathToRoot:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Lists all parent externalCodes on the way to root organization element (set automatically by API).
        parentExternalCode:
          minLength: 1
          type: string
          description: 'External code of the parent company. Note: Parent company cannot be changed after the company is published (published = true).'
          example: ROOT
        parentCompanyCode:
          type:
          - string
          - 'null'
          description: Company code of the parent company. This value is set automatically by API.
          example: ROOT
        level:
          type: integer
          description: Specifies how many levels from root node the organization element resides from. This value is set automatically by API based on number of parents on the way to the root node.
          format: int32
          example: 1
        childCount:
          type: integer
          description: Count of child organization elements (immediate children) of this organization element. This value is set automatically by API.
          format: int32
          example: 0
        sortPosition:
          type: integer
          description: Specifies the sorting position for organization elements under the same parent element. Used for placement of the company within the organization tree in UI.
          format: int32
          example: 3
      additionalProperties: false
      description: Speficies the organization element's position within the organization tree.
    DeleteOrganisationRequest:
      type: object
      properties:
        externalCode:
          type:
          - string
          - 'null'
      additionalProperties: false
  securitySchemes:
    Bearer:
      type: http
      description: Please insert basic authentication credentials into fields
      scheme: basic
    oauth2authentication:
      type: oauth2
      description: Oauth2 client credentials flow.
      flows:
        clientCredentials:
          tokenUrl: https://api.basware.com/v1/tokens
          scopes:
            accountingDocuments.read: GET accountingDocuments
            accountingDocuments.write: POST/PATCH accountingDocuments
            accountingDocuments.delete: DELETE accountingDocuments
            accounts.read: GET accounts
            accounts.write: POST/PATCH accounts
            accounts.delete: DELETE accounts
            advancedPermissions.read: GET advancedPermissions
            advancedPermissions.write: POST/PATCH advancedPermissions
            advancedPermissions.delete: DELETE advancedPermissions
            advancedValidations.read: GET advancedValidations
            advancedValidations.write: POST/PATCH advancedValidations
            advancedValidations.delete: DELETE advancedValidations
            applicationGroups.read: GET applicationGroups
            applicationGroups.write: POST/PATCH applicationGroups
            companies.read: GET companies
            companies.write: POST/PATCH companies
            contracts.delete: DELETE contracts
            contracts.read: GET contracts
            contracts.write: POST/PATCH contracts
            costCenters.read: GET costCenters
            costCenters.write: POST/PATCH costCenters
            costCenters.delete: DELETE costCenters
            errorFeedbacks.read: GET errorFeedbacks
            errorFeedbacks.write: POST/PATCH errorFeedbacks
            errorFeedbacks.delete: DELETE errorFeedbacks
            exchangeRates.read: GET exchangeRates
            exchangeRates.write: POST/PATCH exchangeRates
            exchangeRates.delete: DELETE exchangeRates
            exportedContracts.read: GET exportedContracts
            exportedContracts.write: POST/PATCH exportedContracts
            exportedContracts.delete: DELETE exportedContracts
            exportedContractSpends.read: GET exportedContractSpends
            exportedContractSpends.write: POST/PATCH exportedContractSpends
            exportedContractSpends.delete: DELETE exportedContractSpends
            exportedPurchaseOrders.read: GET exportedPurchaseOrders
            exportedPurchaseOrders.write: POST/PATCH exportedPurchaseOrders
            exportedPurchaseOrders.delete: DELETE exportedPurchaseOrders
            exportedPurchaseRequisitions.read: GET exportedPurchaseRequisitions
            exportedPurchaseRequisitions.write: POST/PATCH exportedPurchaseRequisitions
            exportedPurchaseRequisitions.delete: DELETE exportedPurchaseRequisitions
            lists.read: GET lists
            lists.write: POST/PATCH lists
            lists.delete: DELETE lists
            matchingOrders.read: GET matchingOrders
            matchingOrders.write: POST/PATCH matchingOrders
            matchingOrders.delete: DELETE matchingOrders
            matchingOrderLines.read: GET matchingOrderLines
            matchingOrderLines.write: POST/PATCH matchingOrderLines
            matchingOrderLines.delete: DELETE matchingOrderLines
            paymentTerms.read: GET paymentTerms
            paymentTerms.write: POST/PATCH paymentTerms
            paymentTerms.delete: DELETE paymentTerms
            projects.read: GET projects
            projects.write: POST/PATCH projects
            projects.delete: DELETE projects
            purchaseOrders.read: GET purchaseOrders
            purchaseOrders.write: POST/PATCH purchaseOrders
            purchaseOrders.delete: DELETE purchaseOrders
            purchaseRequisitions.read: GET purchaseRequisitions
            purchaseRequisitions.write: POST/PATCH purchaseRequisitions
            purchaseRequisitions.delete: DELETE purchaseRequisitions
            purchaseGoodsReceipts.read: GET purchaseGoodsReceipts
            purchaseGoodsReceipts.write: POST/PATCH purchaseGoodsReceipts
            purchaseGoodsReceipts.delete: DELETE purchaseGoodsReceipts
            requestStatus.read: GET requestStatus
            requestStatus.write: POST/PATCH requestStatus
            subscriptions.read: GET subscriptions
            subscriptions.write: POST/PATCH subscriptions
            subscriptions.delete: DELETE subscriptions
            tasks.read: GET tasks
            taskStatus.read: GET taskStatus
            taxCodes.read: GET taxCodes
            taxCodes.write: POST/PATCH taxCodes
            taxCodes.delete: DELETE taxCodes
            users.read: GET users
            users.write: POST/PATCH users
            users.delete: DELETE users
            vendors.read: GET vendors
            vendors.write: POST/PATCH vendors
            vendors.delete: DELETE vendors