Device42 Purchasing API

openapi: 3.2.0
info:
  title: Device42 Purchasing API
  version: '2.0'
  description: 'API Overview


    RESTful APIs are supported in Device42 as one of the primary methods of entering, editing and retrieving data.'
  contact:
    name: Device42
    email: support@device42.com
servers:
- url: https://<host>
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Purchasing
paths:
  /api/1.0/purchases/:
    get:
      operationId: getPurchases
      description: Get method retrieves all purchases
      summary: Get all
      tags:
      - Purchasing
      parameters:
      - $ref: '#/components/parameters/purchase_id'
      - $ref: '#/components/parameters/order_no'
      - name: vendor
        description: Vendor name
        in: query
        schema:
          type: string
      - $ref: '#/components/parameters/cost_center'
      - name: building
        description: Associated building
        in: query
        schema:
          type: string
      - $ref: '#/components/parameters/completed'
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Purchases'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: postPurchases
      summary: Create/update
      description: 'Create/update purchases. Required parameters:


        order_no OR purchase_id'
      tags:
      - Purchasing
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                order_no:
                  description: order number / name for the purchase. Can be new or existing.
                  type: string
                purchase_id:
                  description: Can be used instead of order_no to update existing purchase
                  type: string
                line_type:
                  description: required for any new line being added for both device or contract.
                  type: string
                line_no:
                  description: 'required for existing line items, use existing line # to change existing line item.'
                  type: string
                vendor:
                  description: The cloud vendor
                  type: string
                cost:
                  type: string
                po_date:
                  type: string
                cost_center:
                  type: string
                building:
                  description: Associated building
                  type: string
                completed:
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                notes:
                  description: Any additional notes
                  type: string
                line_name:
                  type: string
                line_quantity:
                  description: 'can be calculated automatically from # of objects associated'
                  type: string
                line_cost:
                  description: cost for single object / item.
                  type: string
                line_cost_center:
                  type: string
                line_customer:
                  type: string
                line_item_type:
                  description: Default is device.
                  type: string
                  enum:
                  - device
                  - asset
                  - device_os
                  - rack
                  - shipping
                  - tax
                  - other
                line_asset_ids:
                  description: Comma separated asset_id. Only applicable if line_item_type is asset.
                  type: string
                line_start_date:
                  description: Date in YYYY-MM-DD format
                  type: string
                line_end_date:
                  description: Date in YYYY-MM-DD format
                  type: string
                line_frequency:
                  type: string
                  enum:
                  - one time
                  - monthly
                  - quarterly
                  - bi-annually
                  - annually
                line_renew_date:
                  description: Date in YYYY-MM-DD format
                  type: string
                line_cancel_policy:
                  type: string
                line_contract_type:
                  type: string
                line_service_type:
                  description: new service type will be created, if it doesn’t exist (added in v9.0.2)
                  type: string
                line_contract_id:
                  description: (added in v9.0.2)
                  type: string
                line_notes:
                  type: string
                line_completed:
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                line_devices:
                  description: Comma separated device names. Only applicable if line_item_type is device. Will create new devices if device with name specific here does not exist.
                  type: string
                line_device_serial_nos:
                  description: Comma separated serial numbers. Only applicable if line_item_type is device. Will only work on existing serial numbers.
                  type: string
                line_device_asset_nos:
                  description: Comma separated asset numbers. Only applicable if line_item_type is device. Will only work on existing asset numbers.
                  type: string
                line_circuits:
                  description: circuit ID name
                  type: string
                line_circuit_ids:
                  description: D42 ID for the circuit(s)
                  type: string
                line_building_ids:
                  description: D42 ID for the building(s)
                  type: string
                line_certificate_ids:
                  description: D42 ID for the certificate(s)
                  type: string
                line_software_ids:
                  description: D42 ID for the software
                  type: string
                line_room_ids:
                  description: D42 ID for the room(s)
                  type: string
                line_rack_ids:
                  description: D42 ID for the rack(s)
                  type: string
                line_part_ids:
                  description: D42 ID for the part(s)
                  type: string
                line_device_os_ids:
                  description: D42 ID for the Device OS
                  type: string
                line_devices_remove:
                  description: Comma separated device names to clear from a purchase line. Use <b> * </b> to clear all devices from a purchase line. Use with line_no or line_name.
                  type: string
                groups:
                  description: If multitenancy is on, admin groups that have access to this object are specified here, e.g. Prod_East:no,Corp:yes specifies that the admin groups for this object are Prod_East with view only permission and Corp with change permission. If this parameter is present with no value, all groups are deleted.
                  type: string
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                properties:
                  msg:
                    example:
                    - purchase updated successfully
                    - 11
                    - thisisatest
                  code:
                    example: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/1.0/purchases/{id}/:
    delete:
      operationId: deletePurchases
      summary: Delete
      description: This API is used to delete the purchase order with the purchase order id supplied as the required argument
      tags:
      - Purchasing
      parameters:
      - name: id
        in: path
        required: true
        description: purchase id
        schema:
          type: integer
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                properties:
                  deleted:
                    example: 'true'
                  id:
                    example: '114'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/1.0/purchases/{purchase-id}/attachments/:
    get:
      operationId: getAllPurchaseAttachments
      summary: Get attachments by purchase ID
      description: 'Retrieve all file attachments for a specific purchase using purchase id.

        Returns a zip file of all the attachments associated with the purchase with the specified ID in URL.

        Note that this implementation of Swagger does not support file download - use another mechanism such as CURL.


        cURL example:

        curl -X GET \

        URL/api/1.0/purchases/3/attachments \

        -H ''Authorization: Basic YWRtaW46YWRtIW5kNDI='''
      tags:
      - Purchasing
      parameters:
      - name: purchase-id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                properties:
                  file_download:
                    example: attachments_archive.6646-2020-01-24.zip
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/1.0/custom_fields/purchase/:
    put:
      operationId: putCustom_FieldPurchases
      description: Create/update custom fields for purchases
      summary: Custom fields
      tags:
      - Purchasing
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                order_no:
                  description: order number / name for the purchase. Can be new or existing.
                  type: string
                key:
                  description: Can be new or existing. This is the custom field name.
                  type: string
                type:
                  description: this is the custom field type. If left blank, default is text. Date should be formatted as YYYY-MM-DD
                  type: string
                  enum:
                  - text
                  - number
                  - date
                  - related_field
                  - boolean
                  - url
                  - picklist
                  - json
                  - markup
                mandatory:
                  description: Is custom field mandatory? yes/no
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                filterable:
                  description: Is custom field filterable? yes/no
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                log_for_api:
                  description: Log custom field? yes/no
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                related_field_name:
                  description: Required if type = related_field. The existing field to relate this custom field to. Below are details for some of the fields that have been renamed or require further clarification. appcomp (for application components), businessapp (for Business Service), circuit (for Telco Circuit), cloudinfrastructure (for Cloud Account),  hardware (for device hardware model), netport (for Switch Port), organisation (for Vendor), pdu (for Power Unit), pdu_model (for Power Unit Model), purchase (for Purchase Order), software (for Software Component), vlan (for Subnet)
                  type: string
                  enum:
                  - appcomp
                  - building
                  - businessapp
                  - certificate
                  - circuit
                  - cloudinfrastructure
                  - costcenter
                  - customer
                  - device
                  - dns_zone
                  - endusers
                  - hardware
                  - ip_address
                  - netport
                  - organisation
                  - os
                  - pdu
                  - pdu_model
                  - powercircuit
                  - purchase
                  - rack
                  - room
                  - servicecategory
                  - software_category
                  - software
                  - vlan
                add_to_picklist:
                  description: Comma separated values to add to picklist. If type is picklist and custom field is new, this is a required field. Duplicates will be ignored.
                  type: string
                remove_from_picklist:
                  description: Comma separated values to be removed from picklist. Duplicates will be ignored. Values that are in use will Not be deleted, unless <b>delete_in_use</b> parameter is provided and set to <b>yes</b>
                  type: string
                delete_in_use:
                  description: pass in <b>yes</b> if you want to delete Picklist value that is in use. Used in conjunction with <b>remove_from_picklist</b>.
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                related_field_value_by_id:
                  description: Select yes if you want to set the related field value by ID.
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                value:
                  description: This will set the value of the custom field for the specific object.
                  type: string
                clear_value:
                  description: yes to clear existing value for that field
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                notes:
                  description: Any additional notes
                  type: string
                clear_notes:
                  description: Yes to clear any existing notes
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                bulk_fields:
                  description: comma separated key value pairs, with key and value separated by colon. e.g.key1:value1, key2:value2
                  type: string
                multi_select:
                  description: Applies only to Picklist fields. Is custom field multi select? yes/no
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
              required:
              - order_no
              - key
        required: true
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                properties:
                  msg:
                    example:
                    - custom key pair values added or updated
                    - 623
                    - PO1234
                    - true
                    - false
                  code:
                    example: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  responses:
    Forbidden:
      description: Forbidden (The resource requested is hidden)
      content:
        application/json:
          example:
            errors:
            - code: 403
              reason: Forbidden
              title: Forbidden
              detail: The resource requested is hidden
    BadRequest:
      description: Bad Request (A validation exception has occurred.)
      content:
        application/json:
          example:
            errors:
            - code: 400
              reason: BAD_REQUEST
              title: The error response code title.
              detail: Details of the error response.
    Unauthorized:
      description: Unauthorized (Invalid credentials.)
      content:
        application/json:
          example:
            errors:
            - code: 401
              reason: Unauthorized
              title: Unauthorized
              detail: Invalid credentials.
    InternalServerError:
      description: Internal Server Error (A required parameter is missing or there is an issue with the server. Check the returned 'msg' field from the call.)
      content:
        application/json:
          example:
            errors:
            - code: 500
              reason: Internal Server Error
              title: Internal Server Error
              detail: A required parameter is missing or there is an issue with the server. Check the returned 'msg' field from the call.
    NotFound:
      description: Not Found (The specified resource could not be found)
      content:
        application/json:
          example:
            errors:
            - code: 404
              reason: Not Found
              title: Not Found
              detail: The specified resource could not be found.
    ServiceUnavailable:
      description: Service Unavailable (Please check if your Device42 instance is working normally.)
      content:
        application/json:
          example:
            errors:
            - code: 503
              reason: Service Unavailable
              title: Service Unavailable
              detail: Please check if your Device42 instance is working normally.
  parameters:
    purchase_id:
      name: purchase_id
      in: query
      description: Device42 Purchase ID
      schema:
        type: string
    completed:
      name: completed
      in: query
      description: Line Item is completed
      schema:
        type: string
    cost_center:
      name: cost_center
      in: query
      description: Cost Center
      schema:
        type: string
    order_no:
      name: order_no
      in: query
      description: Order number
      schema:
        type: string
  schemas:
    Purchases:
      type: object
      properties:
        purchases:
          type: array
          items:
            properties:
              purchase_id:
                example: '1'
              po_date:
                example: 'null'
              vendor:
                example: Amazon
              building:
                example: West Haven Office
              order_no:
                example: '9000000001'
              line_items:
                example: []
              notes:
                example: 'null'
              line_items_one_time_cost:
                example: '0'
              customer:
                example: Device42
              cost:
                example: '100.00'
              groups:
                example: ''
              completed:
                example: 'no'
              custom_fields:
                example: []
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication using a Device42 user's username and password.
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token obtained from POST /tauth/1.0/token/ using an API Client's key/secret as Basic auth credentials.