Products API

List products

List all products for an account:

GET /products

Response

Status: 200 OK
[
  {
    "name": "Adobe Reader",
    "created_at": "2016-03-14T03:10:50-06:00",
    "category": "software/browser_viewer_application",
    "sourceID": null,
    "updated_at": "2016-03-14T03:10:50-06:00",
    "service": {
      "name": "Personal Computing",
      "id": 22,
      "provider": {
        "name": "Widget Data Center, Internal IT",
        "id": 32
      }
    },
    "support_team": {
      "name": "End-User Support, Houston",
      "id": 9
    },
    "id": 33
  },
  {
    "name": "APC NetShelter SX 48U Rack",
    "created_at": "2016-03-14T03:10:50-06:00",
    "category": "rack_enclosure",
    "sourceID": null,
    "updated_at": "2016-03-14T03:10:50-06:00",
    "service": {
      "name": "Rack Space",
      "id": 26,
      "provider": {
        "name": "Widget Data Center, External IT",
        "id": 30
      }
    },
    "support_team": {
      "name": "Unix Servers",
      "id": 13
    },
    "id": 34,
    "disabled": true
  },
  "..."
]

The response contains these fields by default. Filtering and pagination are available to reduce/limit the collection of products.

States

The following states are available:

Collection Fields

By default the following fields will appear in collections of products:

id sourceID name category support_team service created_at updated_at

Obtain a different set of fields using the ?fields= parameter.

Sorting

By default a collection of products is sorted ascending by name.

The following fields are accepted by the ?sort= parameter:

id sourceID name category support_team service created_at updated_at

List products relevant for API user

List all products which support team is one of the teams that the API user is a member of:

GET /products/supported_by_my_teams

Response

The response is similar to the response in List products

Get a single product

GET /products/:id

Response

Status: 200 OK
{
  "picture_uri": "https://itrp-demo.s3.amazonaws.com/defaults/avatars/products/large/Adobe Reader.png",
  "name": "Adobe Reader",
  "model": null,
  "rule_set": "software",
  "financial_owner": null,
  "brand": "Adobe",
  "remarks": "No license required.",
  "created_at": "2016-03-14T03:10:50-06:00",
  "category": "software/browser_viewer_application",
  "sourceID": null,
  "updated_at": "2016-03-14T03:10:50-06:00",
  "supplier": null,
  "service": {
    "name": "Personal Computing",
    "id": 22,
    "provider": {
      "name": "Widget Data Center, Internal IT",
      "id": 32
    }
  },
  "support_team": {
    "name": "End-User Support, Houston",
    "id": 9
  },
  "rate": null,
  "useful_life": null,
  "id": 33,
  "source": null,
  "depreciation_method": "na_cost_is_zero",
  "ui_extension": null,
  "disabled": false
}

The response contains these fields.

Create a product

POST /products

When creating a new product these fields are available.

Response

Status: 201 Created
{
  "brand": "...",
  "...": "..."
}

The response contains all fields of the created product and is similar to the response in Get a single product

Update a product

PATCH /products/:id

When updating a product these fields are available.

Response

Status: 200 OK
{
  "brand": "...",
  "...": "..."
}

The response contains all fields of the updated product and is similar to the response in Get a single product

Fields

brand
Required string (max 128) — The Brand field is used to select a previously entered brand name or to enter a new one. The brand name is typically the name of the product’s manufacturer.
category
Required reference to Product Categories — The Category field is used to select the appropriate product category for the product.
created_at
Readonly datetime — The date and time at which the product was created.
depreciation_method
Optional enum — The Depreciation method field is used to specify whether or not configuration items that are based on the product are typically depreciated and if so, which depreciation method is normally applied. Valid values are:
  • na_cost_is_zero: N/A - Cost is Zero/Included in Other CI or Service
  • na_not_capitalized: N/A - Not Capitalized
  • na_leased: N/A - Leased
  • double_declining_balance: Double Declining Balance
  • reducing_balance: Reducing Balance (or Diminishing Value)
  • straight_line: Straight Line (or Prime Cost)
  • sum_of_the_years_digits: Sum of the Year’s Digits
disabled
Optional boolean, default: false — The Disabled box is checked when the product may no longer be used to register new configuration items.
financial_owner
Optional reference to Organization — The Financial owner field is used to select the internal organization which budget is normally used to obtain the product.
id
Readonly integer — The unique ID of the product.
model
Required string (max 128) — The Model field is used to enter the model of the product.
name
Required string (max 128) — The Name field is used to enter the name of the product. Fill out the Brand, Model and Category fields to automatically generate a name based on the values entered in these fields.
picture_uri
Readonly TODO — The hyperlink to the image file that was uploaded for the product.
rate
Optional float — The Rate field is used to specify the yearly rate that should normally be applied to calculate the depreciation of configuration items that are based on the product using the reducing balance (or diminishing value) method.
remarks
Optional text (max 64KB) — The Remarks field is used to enter any additional information about the product that might prove useful.
rule_set
Readonly enum — The Rule set field is automatically set to the rule set of the related product category. Valid values are:
  • logical_asset_with_financial_data: Logical Asset with Financial Data
  • logical_asset_without_financial_data: Logical Asset without Financial Data
  • physical_asset: Physical Asset
  • server: Server
  • software: Software
  • software_distribution_package: Software Distribution Package
service
Optional reference to Service — The Service field is used to select the Service which Service Instances would typically include the product.
source
Optional string (max 30) - See source
sourceID
Optional string (max 128) - See source
supplier
Optional reference to Organization — The Supplier field is used to select the Organization from which the product is typically obtained. If the product is developed internally, select the internal organization that develops it. Note that a lease company should be selected in this field if the product is normally leased.
support_team
Optional reference to Team — The Support team field is used to select the Team responsible for maintaining the product’s information in the configuration management database (CMDB).
ui_extension
Optional reference to UI Extension — The UI extension field is used to select the UI extension that is to be added to the configuration items that are based on the product.
updated_at
Readonly datetime — The date and time of the last update of the product. If the product has no updates it contains the created_at value.
useful_life
Optional integer — The Useful life field is used to enter the number of years within which configuration items that are based on the product are typically depreciated.