Document toolboxDocument toolbox

Equipment API Calls

Owned by Jeremiah Sokolowski
Last updated: Jan 11, 2024 by David EngblomVersion comment
26 min read


Read Call

In an effort to make the PCR-360 API more flexible, PCR has made the decision to no longer create individual endpoints for all the different data types. Instead, PCR is encouraging Users to use the SQL endpoint with a structured SELECT statement to retrieve exactly the data you want. Please see the SQL endpoint documentation for more information.

Example SELECT query for retrieving Equipment and related records:

SELECT * FROM EQUIPMENT;

Request Type

Description

equipment.OUTPUT

Retrieve equipment that match your search.

Remember, OUTPUT is replaced by the desired data type you want returned. Making a Request

Controlling Results Count

By default, 20 items will be returned at a time. However, you can retrieve up to 50 items in a single API call by changing the ‘limit’ field. If you wish to retrieve more than 50 listings, you can do so by using the 'page' field and making more than one API call.

These parameters are added in addition to any fields from the specific data types.

Parameter

Default

Description

limit

20

Number of listings to show. Maximum is 50.

page

1

Page number to show. To view more than 50 listings, make successive API calls while incrementing this field.

Response Data

Name

Datatype

Searchable

Notes

BILLABLE

Yes/No

Yes

To indicate whether the Equipment item is or is not Billable.

EQUIPMENT_ID

string

Yes

Unique identifier of a piece of Equipment; this is required for data Equipment.

ASSET_TAG

string

Yes

Unique identifier of a piece of Equipment; this is required for Assets.

SERIAL_NUM

string

Yes

A unique identifier for one individual instance of a piece of Equipment; often supplied by the manufacturer.

PURCHASE_PRICE /
PURCHASE_PRICE_GREATER /
PURCHASE_PRICE_LESS

number

Yes

The price paid upon purchase of the Equipment. Searches can be exact match, greater than, or less than a specified value, respectively.

CONSUMED

Yes/No

Yes

Shows whether or not an item from inventory is now in use.

RECEIVED_DATE

string

Yes

Date the piece of Equipment was received.

BILLED_DATE

string

Yes

Date the piece of Equipment was billed.

CATALOG

string

Yes

Equipment part number.

OWNER

string

Yes

The Contact or Dept Hierarchy that owns this piece of Equipment.

DEPT_HIERARCHY_PATH

string

No

If OWNER is Dept Hierarchy, this will list the hierarchical path to the OWNER.

LOCATIONS_PATH

string

Yes

The full hierarchical path to the Location of the piece of Equipment; use LOCATIONS for search.

EQP_STATUS

string

Yes

Current status of the piece of Equipment. Use STATUS for search.

EQUIPMENT_UDF

list

No

List of all the User Defined Fields and the selected values for this piece of Equipment.

EQUIPMENT_CHARGES

list

No

Charges listed for the piece of Equipment.

EQUIPMENT_CONTACTS

list

No

Contacts associated with the piece of Equipment.

EQUIPMENT_EXPENSE_GLA

list

No

Expense G/L Accounts to be used for billing for the piece of Equipment.

EQUIPMENT_REMARKS

list

No

List of all remarks/comments for the piece of Equipment.

Results

Lists

When inserting or updating Equipment records, it is sometimes necessary to provide values that exist elsewhere in the system. The LIST method can help to retrieve available options for these values.

Below is how to make a LIST request:

   GET http://DOMAIN/api/API_KEY/equipment.OUTPUT?LIST=LISTTYPE


Searchable

If a LISTTYPE is designated as searchable in the table below, adding the "SEARCH" param will return values that contain the provided value.

   GET http://DOMAIN/api/API_KEY/equipment.OUTPUT?LIST=LISTTYPE&SEARCH=test

Parameter

Replace With

LISTTYPE

The type of List to be retrieved. Types can be found below.

List Types

Type

Description

Extra Parameters*

Searchable

Results

CONTACTS

Retrieve available Contacts

CTYPE - Type of contact. Example: "worker"

yes

Contacts

DEPTHIER

Retrieve available Departments


Coming Soon

Department Hierarchy

EQP_CATALOG

Retrieve available Equipment Catalogs


yes

Equipment Catalog

EXPENSE_TYPE

Retrieve available Expense Types


no

Expense Types

GLAS

Retrieve available GLAs


no

GLA

LOCATIONS

Retrieve available Locations


yes

Locations

UDFS

Retrieve available User Defined Fields (UDF)

eqp_catalog_recid - REQUIRED: The RECID of a valid Equipment Catalog. Example: "53"

no

UDF

CABLING_EQP_TYPE

Retrieve available Cabling Equipment Types


no

Cabling Equipment Types

EQP_CONDITION

Retrieve available Equipment Conditions


no

Equipment Conditions

EQP_STATUS

Retrieve available Equipment Statuses


no

Equipment Statuses

VLANS

Retrieve available VLANs


no

VLAN

Write Call

Using POST Calls

  • POST requests will ignore parameters supplied as a query string and need any additional parameters in the request Body.

  • To configure the number of Pages/Results returned by the API (this is most useful for the SQL Endpoint), you can send these as additional Parameter's in the Body.

    Parameter

    		Data Type

    Default

    Description

    limit

    		Interger

    20

    Number of listings to show.

    page

    		Interger

    1

    Page number to show.

  • API fields are not case sensitive, and will always be returned in the lower case format.

UDF parameters are all lower case when processed by PCR-360. Since Organizations can create their own UDF fields, the generic use of IDENTIFIER is used as a placeholder for actual UDF Identifiers.

Available Fields

Field

Required

Data Type

Options

Default

Notes

RECID

no*

Integer



Identifier of the record to be updated
*Conditionally Required for updating

status

yes

Integer

Value Lookups:


The status of the Equipment

eqp_catalog

yes

Integer

Value Lookups:


Recid of the Equipment Catalog item

location

no

Integer

Value Lookups:


Recid of Location

owner

no*

Integer

Value Lookups:


Record ID of either the Contact or the Department Owner
*Conditionally Required for updating

owner_type

no*

String

"contact" or "department"


Type of Owner.
*Conditionally Required only when setting an Owner

serial_number

no

String



Serial number of Equipment

serial_number_barcode

no

String



Serial number barcode of Equipment

equipment_id

no

String



ID of Equipment

asset_tag

no

String



Asset tag of the Equipment

billable

yes

Integer

1 = yes; 0 = no


Designate if the Equipment is Billable

consumed

yes

Integer

1 = yes; 0 = no


Designate if the Equipment is consumed

purchase_price

no

Decimal



Purchase price of the Equipment

received_date

no

String



Date Equipment was received

billed_date

no

String



Date Equipment was billed

card_number

no

String



Card number of Equipment

parent_equipment

no

Integer

Value Lookups:


Recid of parent Equipment, if applicable

cabling_equipment_type

no

Integer

Value Lookups:


Recid of Cabling Equipment type

ip4_gateway

no

String



IPv4 address of gateway for Equipment

ip6_gateway

no

String



IPv6 address of gateway for Equipment

lan_name

no

String



Name of LAN Equipment is attached to

mac

no

String



MAC address of Equipment

ip4

no

String



IPv4 address of Equipment

ip6

no

String



IPv6 address of Equipment

ip4_subnet

no

String



IPv4 address for subnet that Equipment is attached to

ip6_subnet

no

String



IPv6 address for subnet that Equipment is attached to

ip4_gateway_address

no

String



IPv4 address of gateway

ip6_gateway_address

no

String



IPv6 address of gateway

host_name

no

String



Host name of Equipment

condition

no

Integer

Value Lookups:


Recid of condition value for Equipment.

ordered_date

no

String



Date Equipment was ordered

units

no




Quantity on hand

warranty_end_date

no

String



Date that warranty ends on Equipment. warranty_end_date is automatically set when received_date is provided

use_dhcp

yes

Integer

1 = yes; 0 = no


Designate if the Equipment uses DHCP

private

yes

Integer

1 = yes; 0 = no


Designate if this Equipment is private

vlan

no

Mixed



Recid of VLAN this Equipment belongs to. Multiple Recids can be provided using commas. Example: 23,34

contact

no

Integer



Recid of the contact(s) to associate this Equipment with

remarks

no

String



Remarks for the Equipment

gla

no

Integer

Value Lookups:


Recid(s) of GLA record(s) to assign to this Service. If multiple GLAs are to be assigned, separate recids with commas. Example: 874,32.

gla_percent

no*

String


100

Percentage(s) of this Service that should apply to specified GLA(s). *If multiple GLAs are provided, then percent is Conditionally Required and the same count of percentages need to be provided also. Total of all percentages must equal exactly 100.

gla_type

no*

Integer

Value Lookups:


Recid(s) of Expense Type(s).
*Conditionally Required if GLA is specified

Request Example

Call:
POST DOMAIN/KEY/equipment.json
Headers:

Key

Value

Content-Type

application/json

Pcr-Html-Encoded

TRUE

Body:

Key

Value

status

Active

eqp_catalog

1

billable0
consumed0
use_dhcp0
private0

Results

If the request is successful, the equipment RECID will be returns as follows:

Equipment VLANs

Equipment can be assigned to one or more VLANs.

Below is the proper format for making a separate request. Note "TYPE=VLANS" to indicate that this is to add Equipment to VLANs.

POST http://DOMAIN/api/API_KEY/equipment.OUTPUT?TYPE=VLANS&field1=value1 ...


Available Fields

Field

Required

Data Type

Options

Default

Notes

equipment_recid

yes

Integer



RECID column from EQUIPMENT table.

vlan

yes

String



One or more Recids of VLANs. If multiple, separate with commas. Example: 23,43

Request Example

Call:
POST DOMAIN/KEY/equipment.json
Headers:

Key

Value

Content-Type

application/json

Pcr-Html-Encoded

TRUE

Body:

Key

Value

status

Active

eqp_catalog

1

billable0
consumed0
use_dhcp0
private0
equipment_recid

908

vlan1

Results

If the request is successful, the Recid(s) will be returned in the same order provided:

Equipment Remarks

Remarks can be added to Equipment.

Below is the proper format for making a separate request. Note "TYPE=REMARK" to indicate that this is to add a remark to Equipment.

POST http://DOMAIN/api/API_KEY/equipment.OUTPUT?TYPE=REMARK&field1=value1 ...


Available Fields

Field

Required

Data Type

Options

Default

Notes

equipment_recid

yes

Integer



RECID column from EQUIPMENT table.

remarks

yes

String



The remark to add to the Equipment

Request Example

Call:
POST DOMAIN/KEY/equipment.json
Headers:

Key

Value

Content-Type

application/json

Pcr-Html-Encoded

TRUE

Body:

Key

Value

status

Active

eqp_catalog

1

billable0
consumed0
use_dhcp0
private0
equipment_recid

456231

remarksThis is a Remark from the API

Results

If the request is successful, the Recid of the remark record will be returned as follows:

Equipment Charges

Charges can be easily added to Equipment. If multiple Charges need to be added to Equipment, then separate POST requests will need to be made.

Below is the proper format for making a separate request. Note "TYPE=CHARGES" to indicate that this is to create an Equipment Charge record.

POST http://DOMAIN/api/API_KEY/equipment.OUTPUT?TYPE=CHARGES&field1=value1 ...


Available Fields

Field

Required

Data Type

Options

Default

Notes

recid

no*

Integer



*Conditionally Required if attempting to UPDATE an Equipment Charge. RECID column from EQUIPMENT_CHARGES table.

equipment_recid

yes

Integer



The RECID of the Equipment that the Charge is for.

charge_recid

yes

Integer

Value Lookups:


RECID of the applicable Charge Catalog.

description

no

String



The details or Description of the Charge on the Equipment

amount

no*

Decimal



The amount to be charged. *Conditionally Required if charge does not have an amount on it.

quantity

no

Integer


1

Quantity of Charge to be used. Only allowed if Charge Catalog allows it.

prorate

no

Integer

1 or 0

0

Should the Charge be prorated when activated. Only allowed if BILL_MRC_CHANGE_FORCE_PRORATE config option is false

start_datenoString

MRC

ARC


The Start Date of a Charge. YYYY-MM-DD format. Other formats may give unexpected results.

Used for Monthly Recurring Charges and Alternate Recurring Charges.

stop_datenoString

MCR

ARC


YYYY-MM-DD format. Other formats may give unexpected results.

Used for Monthly Recurring Charges and Alternate Recurring Charges

recurring_datenoStringARC

YYYY-MM-DD format. Other formats may give unexpected results.

Used for Alternate Recurring Charges

transaction_datenoStringNRC

YYYY-MM-DD format. Other formats may give unexpected results.

Used for Non-Recurring Charges

override_amount

no

Decimal



If allowed by the selected Charge, overrides the default amount from the Charge.

override_gla

no

Integer

Value Lookups:


RECID of GLA to override default GLA with. The Override GLA Format should match the Billing Group Format of the Equipment.

effectivenoStringtoday, backdatetoday

Effective flag for the Charge being added/stopped. if set to any value other than listed, "today" will be assumed by the API

Alternate Recurring Charges (Quarterly, Semi-Annual and Annual), when updated will always use backdate as the Effective Date.

Charge Validations

The following checks are made by the API when adding a Charge:

  • Charge Catalog restrictions are not violated
  • Error if the amount is provided and the Catalog does not allow overrides
  • Error if quantity provided for non/quantity Catalogs, also checks for whole numbers/fractional and errors is a fraction
  • Verify Service is billable when adding a Charge
  • Verify there exists an expense GLA that matches the Charge Catalog Expense Type
  • Monthly Recurring Charges
    • start_date is required for new charge
    • error if stop_date is provided for billing complete charges
    • error if stop_date is earlier than start_date
  • Non-Recurring Charges
    • transaction_date is required for new charge
    • error if stop_date is provided
  • Alternate Recurring Charges (Annual, Semi-Anual, Quarterly)
    • start_date is required for new charge
    • recurring_date is required for new charge
    • error if stop_date is provided for billing complete charges

Request Example

Call:
POST DOMAIN/KEY/equipment.json
Headers:

Key

Value

Content-Type

application/json

Pcr-Html-Encoded

TRUE

Body:

Key

Value

status

Active

eqp_catalog

1

billable0
consumed0
use_dhcp0
private0
equipment_recid

58337

charge_recid1

Results

If the request is successful, the RECID of the new Equipment charge is returned as follows:

Equipment GLA

GLAs can be easily added to Equipment. If multiple Charges need to be added to Equipment, then separate each value with commas.

Below is the proper format for making a separate request. Note "TYPE=GLA" to indicate that this is to add an Equipment GLA record(s).

POST http://DOMAIN/api/API_KEY/equipment.OUTPUT?TYPE=GLA&field1=value1 ...


If multiple GLAs are to be set, structure your request as follows:

POST http://DOMAIN/api/API_KEY/equipment.OUTPUT?TYPE=GLA&field1=v1.1,v1.2&field2=v2.1,v2.2 ...


When creating your comma separated values, each place in the string corresponds to the same space in other field value strings.

Available Fields

Field

Required

Data Type

Options

Default

Notes

equipment_recid

yes

Integer



RECID column from EQUIPMENT table.

gla

yes

String

Value Lookups:


Record ID(s) of the applicable GLA(s).

gla_percent

yes

String



Percentages to apply to each GLA. All percentages must equal exactly 100.

gla_type

yes

String

Value Lookups:


The type(s) of GLA(s).

Request Example

Call:
POST DOMAIN/KEY/equipment.json
Headers:

Key

Value

Content-Type

application/json

Pcr-Html-Encoded

TRUE

Body:

Key

Value

status

Active

eqp_catalog

1

billable0
consumed0
use_dhcp0
private0
equipment_recid

2345

gla1
gla_percent100
gla_typeDefault

Results

If the request is successful, the RECID(s) of the new Equipment GLA records will be returned in same order provided:

Equipment Contacts

Contacts can be easily added to Equipment. If multiple charges need to be added to Equipment, then separate each value with commas.

Below is the proper format for making a separate request. Note "TYPE=CONTACTS" to indicate that this is to add contacts to Equipment.

POST http://DOMAIN/api/API_KEY/equipment.OUTPUT?TYPE=CONTACTS&field1=value1 ...


Available Fields

Field

Required

Data Type

Options

Default

Notes

equipment_recid

yes

Integer



RECID column from EQUIPMENT table.

contact

yes

String

Value Lookups:


Record ID(s) of the Contact(s).

Request Example

Call:
POST DOMAIN/KEY/equipment.json
Headers:

Key

Value

Content-Type

application/json

Pcr-Html-Encoded

TRUE

Body:

Key

Value

status

Active

eqp_catalog

1

billable0
consumed0
use_dhcp0
private0
equipment_recid

2345

contact1

Results

If the request is successful, the RECID(s) of the new Equipment contact records will be returned in the same order provided:

Equipment UDFs

User Defined Fields can be easily set for Equipment. To get a list of available UDFs for a piece of Equipment, visit Lists.

Below is the proper format for making a UDF request. Note "TYPE=UDFS" to indicate that this is to add UDFs to Equipment.

POST http://DOMAIN/api/API_KEY/equipment.OUTPUT?TYPE=UDFS&field1=value1 ...


Available Fields

Field

Required

Data Type

Options

Default

Notes

equipment_recid

Yes

Integer



RECID column from EQUIPMENT table.

udf_UDF-RECIDYes*Integer

UDF-RECID is the RECID of the UDF to assign the value to. Example: udf_684=value
  • See Note Below
udf_UDF-IDENTIFIERYes*Mixed

IDENTIFIER is the unique Identifier of the UDF to assign the value to. Example: udf_LEGACYNUM=value
  • See Note Below
  • udf_UDF-RECID and udf_UDF-IDENTIFIER are Conditionally Required. The use of one is Required, but not both.

Request Example

Call:
POST DOMAIN/KEY/equipment.json
Headers:

Key

Value

Content-Type

application/json

Pcr-Html-Encoded

TRUE

Body:

Key

Value

status

Active

eqp_catalog

1

billable0
consumed0
use_dhcp0
private0
equipment_recid

765

udf_UDF-RECID1

Results

If the request is successful, the RECID(s) of the new Equipment UDF records will be returned same order provided:

Locating Equipment Data

Within PCR-360, these menu options list a variety of Grids that can be used to help locate any of the required fields.

.Equipment API Calls v2019.1
.Equipment API Calls v2019.4
.Equipment API Calls v2019.5
.Equipment API Calls v2020.3
.Equipment API Calls v2020.4
.Equipment API Calls v2021.1
.Equipment API Calls v2021.2
.Equipment API Calls v2021.3
.Equipment API Calls v2022.1
.Equipment API Calls v2.1.4.7

Help Desk Portal - Email: help@pcr.com - Phone: 616.259.9242