Basware PurchaseRequisitions API

openapi: 3.2.0
info:
  title: Basware OAUTH2 authentication APIs AccountingDocuments Purchase Requisitions API
  description: "**Using OAUTH2.0 authentication:**\n\nGet API access token from api.basware.com/tokens\n1. Using client id and client secret, which you can obtain from Basware. \n2. Specify which APIs can be accessed by using the token e.g. Read only access to vendors API only (these are called scopes). Available scopes are listed at <https://developer.basware.com/api/p2p/manual#AccessRights>. \n3. Each token has an expiration time, until which it can be used to call APIs.\n\nWhen using OAUTH2 authentication, you need to pass the OAUTH2 authentication token when calling Basware API endpoints. Available Basware API operations are documented at <https://api.basware.com/swagger>. \n\nSee the Basware API developer site at <https://developer.basware.com/api/p2p/manual#Authentication> for more details on API authentication."
  version: 1.0.0
  x-logo:
    url: https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png
servers:
- url: https://api.basware.com
  description: Base URL declared by the provider in apis.yml (roadmap#122).
tags:
- name: PurchaseRequisitions
paths:
  /v1/purchaseRequisitions:
    get:
      tags:
      - PurchaseRequisitions
      summary: Returns purchase requisitions posted to Basware API.
      description: 'Note: Updating data for existing requisitions is not supported. Posting updates will result in errors in errorFeedbacks -interface and data will not be updated in Alusta Purchase. The data will still be accepted and updated in Basware API. Because of this updates to existing purchase requisition records will result in inconsistent data between GET operations to Basware API and Alusta Purchase.'
      parameters:
      - name: pageSize
        in: query
        description: A limit for the number of items to be returned for one request. Limit can range between 1 and 100 items.
        schema:
          type: integer
          format: int32
          default: 100
      - name: companyCode
        in: query
        description: Company filter. Returns items for specific company.
        schema:
          type: string
          default: ''
      - name: lastUpdated
        in: query
        description: Date Filter. Returns items that have been updated after specified date.
        schema:
          type: string
          format: date-time
      - name: x-amz-meta-continuationtoken
        in: header
        description: Used to get next page of results when item count indicated by 'pageSize' is exceeded. A token is returned in header (not body) parameter 'X-amz-meta-continuationToken' of the response whenever there are more records to fetch. Post the received value here in a new HEADER parameter on the next GET request to receive the next page of results. When getting the next page of results, you must include the same query parameters that were used when getting the first page.
        schema:
          type: string
        example: 1c121d65-110b-4027-b306-e7525d4e716f
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/PurchaseRequisitionResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseRequisitionResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/PurchaseRequisitionResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not found. Request was successful and no records were found.
        '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'
    post:
      tags:
      - PurchaseRequisitions
      summary: Creates new purchase requisition(s). P2P Purchase does not allow updates to purchase requisitions after import.
      description: " Notes: \n 1. Any referenced vendors, users, etc. need to exist in P2P when the purchase requisition is imported. \n 2. Updating data for existing requisitions is not supported. Posting updates will result in errors in errorFeedbacks -interface and data will not be updated in Alusta Purchase. The data will still be accepted and updated in Basware API. Because of this updates to existing purchase requisition records will result in inconsistent data between GET operations to Basware API and Alusta Purchase.\n \nPlease see section \"[Usage scenario 4: Import and export procurement data](https://developer.basware.com/api/p2p/manual#usage4)\" for details on implementing this API. Check out also the [example JSONs using a minimal feasible set of fields](https://developer.basware.com/api/p2p/templates) from the developer site."
      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:
        content:
          application/json-patch+json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/PurchaseRequisitionEntity'
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/PurchaseRequisitionEntity'
          text/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/PurchaseRequisitionEntity'
          application/*+json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/PurchaseRequisitionEntity'
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PurchaseRequisitionEntity'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PurchaseRequisitionEntity'
            text/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PurchaseRequisitionEntity'
        '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'
        '401':
          description: Unauthorized
        '409':
          description: Conflict
          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'
    delete:
      tags:
      - PurchaseRequisitions
      summary: Deletes data from Basware API. For manual one-time operations.
      description: "For manual one-time operations only, such as a manual clean-up to remove test data generated during API integration development. Only removes records from API layer. \nDeletion in target systems needs to be done separately using the data deletion mechanisms available in each of the target system in addition to deleting the data in Basware API."
      requestBody:
        description: "Contains the body of the request.\n            Either externalCode or lastUpdated -field is required. If both values are provided, externalCode will have the priority."
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/DeleteRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/DeleteRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/DeleteRequest'
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
        '202':
          description: RequestAccepted
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
        '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'
  /v1/purchaseRequisitions/{externalCode}:
    get:
      tags:
      - PurchaseRequisitions
      summary: Returns single purchase requisition by externalCode -identifier.
      description: 'Note: Updating data for existing requisitions is not supported. Posting updates will result in errors in errorFeedbacks -interface and data will not be updated in Alusta Purchase. The data will still be accepted and updated in Basware API. Because of this updates to existing purchase requisition records will result in inconsistent data between GET operations to Basware API and Alusta Purchase.'
      parameters:
      - name: externalCode
        in: path
        description: ExternalCode of the entity to be fetched
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/PurchaseRequisitionEntity'
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseRequisitionEntity'
            text/json:
              schema:
                $ref: '#/components/schemas/PurchaseRequisitionEntity'
        '401':
          description: Unauthorized
        '404':
          description: Not found. Request was successful and no records were found.
        '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'
components:
  schemas:
    DeliveryAddress:
      required:
      - name
      type: object
      properties:
        name:
          maxLength: 250
          minLength: 1
          type: string
          description: Specifies the address’ name for the goods delivery.
          example: Maple street office
        pObox:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: PO box
          example: ''
        streetName:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Street name.
          example: Maple street
        additionalStreetName:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Additional street name.
          example: ''
        blockName:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Block name.
          example: ''
        buildingName:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Building name.
          example: ''
        buildingNumber:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Building number.
          example: '68'
        department:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Department.
          example: ''
        floor:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Floor.
          example: ''
        room:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Room.
          example: ''
        postalZone:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Postal zone.
          example: '02600'
        city:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: City.
          example: Toronto
        region:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Region.
          example: ''
        district:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: District.
          example: ''
        countryCode:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Country code.
          example: CA
        countryName:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Country name.
          example: Canada
        description:
          maxLength: 1000
          minLength: 0
          type:
          - string
          - 'null'
          description: Description.
          example: ''
        globalLocationNumber:
          maxLength: 13
          minLength: 0
          type:
          - string
          - 'null'
          description: Global location number.
          example: ''
        countrySubEntity:
          maxLength: 50
          minLength: 0
          type:
          - string
          - 'null'
          example: TX
        countrySubEntityDescription:
          maxLength: 50
          minLength: 0
          type:
          - string
          - 'null'
          example: Texas
        addressId:
          maxLength: 2000
          minLength: 0
          type:
          - string
          - 'null'
          description: Identifier for the address.
          example: '1000467'
        addressSchemeId:
          maxLength: 2000
          minLength: 0
          type:
          - string
          - 'null'
          description: Can be used to specify a code that represents the agency or organization responsible for the addressID numbering.
          example: BuyerAccountId
      additionalProperties: false
      description: 'Specifies delivery address for the purchase requisition. If no address specified, uses the default delivery address of organization (configured in P2P).

        Delivery address on header level applies to entire purchase reuisition. If addresses are also provided on requisition lines, these will apply only to the corresponding lines.'
    RequisitionCodingRow:
      required:
      - externalCode
      type: object
      properties:
        externalCode:
          maxLength: 36
          minLength: 1
          type: string
          description: The coding row number in the external system.
          example: 1547e437-1231-ad32-dff2-132985aae212
        accountCode:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: Defines code for the account. If empty, defaults based on item's purchasing category.
          example: '10017'
        accountName:
          maxLength: 2000
          minLength: 0
          type:
          - string
          - 'null'
          description: Defines name for the account. If empty, defaults based on the item's purchasing category.
          example: IT equipment costs
        costCenterCode:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: Cost center code. If empty, the requisition owner's default cost center is used.
          example: '23800'
        costCenterName:
          maxLength: 2000
          minLength: 0
          type:
          - string
          - 'null'
          description: Cost center name.
          example: Lift engine research
        projectCode:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: Project code.
          example: ''
        projectName:
          maxLength: 255
          minLength: 0
          type:
          - string
          - 'null'
          description: Project name.
          example: ''
        fixedAssetCode:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: Fixed asset code.
          example: ''
        fixedAssetName:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Fixed asset name.
          example: ''
        fixedAssetSubCode:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: Fixed asset sub code.
          example: ''
        fixedAssetSubName:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Fixed asset sub name.
          example: ''
        internalOrderCode:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: Internal order code.
          example: ''
        internalOrderName:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Internal order name.
          example: ''
        profitCenterCode:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: Profit center code.
          example: ''
        profitCenterName:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Profit center name.
          example: ''
        businessUnitCode:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: Business unit code.
          example: ''
        businessUnitName:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Business unit name.
          example: ''
        projectSubCode:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: Project sub code.
          example: ''
        projectSubName:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Project sub name.
          example: ''
        employeeCode:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: Employee code. If empty, defaults to requisition owner's employee code.
          example: '815722'
        employeeName:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Employee name. If empty, defaults to requisition owner's name.
          example: Jim Green
        vehicleName:
          maxLength: 255
          minLength: 0
          type:
          - string
          - 'null'
          description: Vehicle name.
          example: ''
        vehicleNumber:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: Vehicle number.
          example: ''
        salesOrderCode:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: Sales order code.
          example: ''
        salesOrderName:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Sales order name.
          example: ''
        salesOrderSubCode:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: Sales order sub code.
          example: ''
        salesOrderSubName:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Sales order sub name.
          example: ''
        customerCode:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: Customer code.
          example: ''
        customerName:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Customer name.
          example: ''
        accAssignmentCategoryCode:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: Account assignment category code. If empty, defaults based on the item's purchasing category.
          example: ''
        accAssignmentCategoryName:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Account assignment category name. If empty, defaults based on the item's purchasing category.
          example: ''
        budgetCode:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: Defines a code for the budget.
          example: B36782
        budgetName:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Defines name for the budget.
          example: IT equipment 2020
        serviceCode:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: Service code.
          example: ''
        serviceName:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Service name.
          example: ''
        businessAreaCode:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: Business area code.
          example: ''
        businessAreaName:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Business area name.
          example: ''
        workOrderCode:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: Work order code.
          example: ''
        workOrderName:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Work order name.
          example: ''
        workOrderSubCode:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: Work order sub code.
          example: ''
        workOrderSubName:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Work order sub name.
          example: ''
        distributionCode:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: Distribution code.
          example: ''
        distributionMode:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Distribution mode.
          example: ''
        dimCode1:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: DimCode1-10 are often used for additional, customer-specific, coding dimensions. Specifies the dimension code.
          example: '236710'
        dimCode2:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: DimCode2
          example: ''
        dimCode3:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: DimCode3
          example: ''
        dimCode4:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: DimCode4
          example: ''
        dimCode5:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: DimCode5
          example: ''
        dimCode6:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: DimCode6
          example: ''
        dimCode7:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: DimCode7
          example: ''
        dimCode8:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: DimCode8
          example: ''
        dimCode9:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: DimCode9
          example: ''
        dimCode10:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: DimCode10
          example: ''
        dimName1:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: DimName1-10 is used for additional, customer-specific, coding dimensions. Specifies the dimension name.
          example: Maple street office
        dimName2:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: DimName2
          example: ''
        dimName3:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: DimName3
          example: ''
        dimName4:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: DimName4
          example: ''
        dimName5:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: DimName5
          example: ''
        dimName6:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: DimName6
          example: ''
        dimName7:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: DimName7
          example: ''
        dimName8:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: DimName8
          example: ''
        dimName9:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: DimName9
          example: ''
        dimName10:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: DimName10
          example: ''
        num1:
          type:
          - number
          - 'null'
          description: Num1-5 are custom fields in the business document.
          format: double
        num2:
          type:
          - number
          - 'null'
          description: Num2
          format: double
        num3:
          type:
          - number
          - 'null'
          description: Num3
          format: double
        num4:
          type:
          - number
          - 'null'
          description: Num4
          format: double
        num5:
          type:
          - number
          - 'null'
          description: Num5
          format: double
        text1:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Text1-5 are custom fields in the business document.
          example: ''
        text2:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Text2
          example: ''
        text3:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Text3
          example: ''
        text4:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Text4
          example: ''
        text5:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Text5
          example: ''
        date1:
          type:
          - string
          - 'null'
          description: Date1-5 are custom fields in the business document.
          format: date-time
        date2:
          type:
          - string
          - 'null'
          description: Date2
          format: date-time
        date3:
          type:
          - string
          - 'null'
          description: Date3
          format: date-time
        date4:
          type:
          - string
          - 'null'
          description: Date4
          format: date-time
        date5:
          type:
          - string
          - 'null'
          description: Date5
          format: date-time
      additionalProperties: false
    DeleteRequest:
      type: object
      properties:
        lastUpdated:
          type:
          - string
          - 'null'
          description: 'To delete records updated after specific time, use lastUpdated -field. This will delete all items that have been updated after the specified date. In response, user will get the taskStatus api link where the task status can be checked. Note: ''0001-01-01'' can be used to delete all records.'
          format: date-time
        externalCode:
          maxLength: 36
          minLength: 0
          type:
          - string
          - 'null'
          description: Single item can be deleted using externalCode and final status is returned immediately.
      additionalProperties: false
    PurchaseRequisitionResponse:
      required:
      - purchaseRequisitions
      type: object
      properties:
        purchaseRequisitions:
          type: array
          ite

# --- truncated at 32 KB (62 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/basware/refs/heads/main/openapi/basware-purchaserequisitions-api-openapi.yml