Device42 Customers API

openapi: 3.2.0
info:
  title: Device42 Customers 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: Customers
paths:
  /api/1.0/customers/:
    get:
      operationId: getCustomers
      description: Get all customers
      summary: Get all
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/include_cols'
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                properties:
                  Customers:
                    type: array
                    items:
                      $ref: '#/components/schemas/Customers'
        '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: postCustomers
      summary: Create/update
      description: Create/update customers
      tags:
      - Customers
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                id:
                  description: Customer id
                  type: integer
                name:
                  description: Customer name
                  type: string
                contact_info:
                  description: Text field for contact information
                  type: string
                notes:
                  description: Any additional notes
                  type: string
                type:
                  type: string
                  enum:
                  - customer
                  - department
                new_name:
                  description: New name for an existing customer 'name'.<br>If the customer 'name' does not exist, this creates a new customer.
                  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
                manager:
                  description: Name of manager
                  type: string
                customer_ids:
                  description: Comma separated list of customer ids which are part of this customer
                  type: string
                user_ids:
                  description: Comma separated list of end user ids which are part of this customer
                  type: string
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                properties:
                  msg:
                    example:
                    - Customer added or updated.
                    - 4
                    - Skynet
                    - 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'
  /api/1.0/customers/{id}/:
    delete:
      operationId: deleteCustomers
      summary: Delete
      description: This API is used to delete the customer with the customer id supplied as the required argument
      tags:
      - Customers
      parameters:
      - name: id
        in: path
        description: IP Address id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                properties:
                  deleted:
                    example: 'true'
                  id:
                    example: '1'
        '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/customers/contacts/:
    post:
      operationId: post_Update_Customer_Contacts
      summary: Create/update customer contacts
      tags:
      - Customers
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                contact_id:
                  description: Customer contact id
                  type: string
                name:
                  description: Customer contact name. <b>Required if contact_id not provided</b>
                  type: string
                type:
                  description: Contact type. <b>Required if contact_id not provided</b>.
                  type: string
                customer:
                  description: Customer name. Must already exist. <b>Required if contact_id not provided</b>
                  type: string
                email:
                  description: Text field.
                  type: string
                phone:
                  description: Text field.
                  type: string
                address:
                  description: Text field
                  type: string
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                properties:
                  msg:
                    example:
                    - customer contact record added/updated successfully
                    - 5
                    - mickeymouse
                    - true
                    - true
                  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/customers/contacts/{id}/:
    delete:
      operationId: deleteCustomerContact
      summary: Delete customer contacts
      description: This API is used to delete the customer contact with the customer contact id supplied as the required argument
      tags:
      - Customers
      parameters:
      - name: id
        in: path
        description: Customer Contact id
        required: true
        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/custom_fields/customer/:
    put:
      operationId: put_CustomFields_2
      summary: Custom fields
      tags:
      - Customers
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                name:
                  description: Name of the customer
                  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:
              - name
              - 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
                    - 4
                    - Skynet
                  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:
    include_cols:
      name: include_cols
      in: query
      description: 'do not return all columns just the ones specified. For example, ?include_cols=name, device_id, rack will only result in name, device_id, and rack included in the output. The following column names can be part of include_cols: name, device_id, rack, name, device_id, serial_no, asset_no, uuid, notes, in_service, service_level, type, id, last_updated, tags, customer_id, customer, hw_model, hw_size, manufacturer, hw_depth, rack, start_at, rack_id, orientation, row, room, building, reversed, blade_host_name, blade_host_id, slot_number, virtual_host_name, location, device_sub_type, os, osarch, osver, osverno, custom_fields, device_purchase_line_items, device_external_links, ip_addresses, mac_addresses, cpucount, cpucore, cpuspeed, ram, hddcount, hddsize, hddraid, hddraid_type, hdd_details, pdu_mapping_url, modules, vms, devices, aliases, xpos, ucs_manager, preferred_alias, file_attachment_details'
      schema:
        type: string
  schemas:
    Customers:
      properties:
        Contacts:
          type: array
          items:
            properties:
              address:
                example: 123 main st
              email:
                example: rick@d42.com
              name:
                example: Random Guy
              phone:
                example: 555-555-5555
              type:
                example: Technical
        Custom Fields:
          type: array
          items:
            properties:
              key:
                example: custID
              notes:
                example: ''
              value:
                example: '42'
              value2:
                example: ''
        contact_info:
          example: 555 Technical Lane, Cool City.
        devices_url:
          example: /api/api/1.0/devices/customer_id/1/
        groups:
          example: Prod_East:no, Corp:yes
        id:
          example: 1
        name:
          example: ABC, Inc.
        notes:
          example: some notes here
        subnets_url:
          example: /api/api/1.0/subnets/customer_id/1/
  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.