(2024.2) Equipment API Calls

1 Read Call
- 1.1 Controlling Results Count
- 1.2 Response Data
  - 1.2.1 Results
- 1.3 Lists
  - 1.3.1 Searchable
  - 1.3.2 List Types
2 Write Call
- 2.1 Available Fields
  - 2.1.1 Request Example
    - 2.1.1.1 Call:
    - 2.1.1.2 Headers:
    - 2.1.1.3 Body:
  - 2.1.2 Results
- 2.2 Equipment VLANs
  - 2.2.1 Available Fields
  - 2.2.2 Request Example
    - 2.2.2.1 Call:
    - 2.2.2.2 Headers:
    - 2.2.2.3 Body:
  - 2.2.3 Results
- 2.3 Equipment Remarks
  - 2.3.1 Available Fields
  - 2.3.2 Request Example
    - 2.3.2.1 Call:
    - 2.3.2.2 Headers:
    - 2.3.2.3 Body:
  - 2.3.3 Results
- 2.4 Equipment Charges
  - 2.4.1 Available Fields
  - 2.4.2 Request Example
    - 2.4.2.1 Call:
    - 2.4.2.2 Headers:
    - 2.4.2.3 Body:
  - 2.4.3 Results
- 2.5 Equipment GLA
  - 2.5.1 Available Fields
  - 2.5.2 Request Example
    - 2.5.2.1 Call:
    - 2.5.2.2 Headers:
    - 2.5.2.3 Body:
  - 2.5.3 Results
- 2.6 Equipment Contacts
  - 2.6.1 Available Fields
  - 2.6.2 Request Example
    - 2.6.2.1 Call:
    - 2.6.2.2 Headers:
    - 2.6.2.3 Body:
  - 2.6.3 Results
- 2.7 Equipment UDFs
  - 2.7.1 Available Fields
  - 2.7.2 Request Example
    - 2.7.2.1 Call:
    - 2.7.2.2 Headers:
    - 2.7.2.3 Body:
  - 2.7.3 Results
3 Locating Equipment Data

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

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

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

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

Parameter	Replace With
LISTTYPE	The type of List to be retrieved. Types can be found below.

List Types

Type	Description	Extra Parameters*	Searchable	Results

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

Available Fields

Field	Required	Data Type	Options	Default	Notes

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:

Headers:

Key	Value

Key	Value
Content-Type	application/json
Pcr-Html-Encoded	TRUE

Body:

Key	Value

Key	Value
status	Active
eqp_catalog	1
billable	0
consumed	0
use_dhcp	0
private	0

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.

Available Fields

Field	Required	Data Type	Options	Default	Notes

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:

Headers:

Key	Value

Key	Value
Content-Type	application/json
Pcr-Html-Encoded	TRUE

Body:

Key	Value

Key	Value
status	Active
eqp_catalog	1
billable	0
consumed	0
use_dhcp	0
private	0
equipment_recid	908
vlan	1

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.

Available Fields

Field	Required	Data Type	Options	Default	Notes

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:

Headers:

Key	Value

Key	Value
Content-Type	application/json
Pcr-Html-Encoded	TRUE

Body:

Key	Value

Key	Value
status	Active
eqp_catalog	1
billable	0
consumed	0
use_dhcp	0
private	0
equipment_recid	456231
remarks	This 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.

Available Fields

Field	Required	Data Type	Options	Default	Notes

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_date	no	String	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_date	no	String	MCR ARC		YYYY-MM-DD format. Other formats may give unexpected results. Used for Monthly Recurring Charges and Alternate Recurring Charges
recurring_date	no	String	ARC		YYYY-MM-DD format. Other formats may give unexpected results. Used for Alternate Recurring Charges
transaction_date	no	String	NRC		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.
effective	no	String	today, backdate	today	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:

Headers:

Key	Value

Key	Value
Content-Type	application/json
Pcr-Html-Encoded	TRUE

Body:

Key	Value

Key	Value
status	Active
eqp_catalog	1
billable	0
consumed	0
use_dhcp	0
private	0
equipment_recid	58337
charge_recid	1

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).

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

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

Field	Required	Data Type	Options	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:

Headers:

Key	Value

Key	Value
Content-Type	application/json
Pcr-Html-Encoded	TRUE

Body:

Key	Value

Key	Value
status	Active
eqp_catalog	1
billable	0
consumed	0
use_dhcp	0
private	0
equipment_recid	2345
gla	1
gla_percent	100
gla_type	Default

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.

Available Fields

Field	Required	Data Type	Options	Default	Notes

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:

Headers:

Key	Value

Key	Value
Content-Type	application/json
Pcr-Html-Encoded	TRUE

Body:

Key	Value

Key	Value
status	Active
eqp_catalog	1
billable	0
consumed	0
use_dhcp	0
private	0
equipment_recid	2345
contact	1

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.

Available Fields

Field	Required	Data Type	Options	Default	Notes

Field

Required

Data Type

Options

Default

Notes

equipment_recid

Yes

Integer

RECID column from EQUIPMENT table.

udf_UDF-RECID

Yes*

Integer

UDF-RECID is the RECID of the UDF to assign the value to. Example: udf_684=value

See Note Below

udf_UDF-IDENTIFIER

Yes*

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:

Headers:

Key	Value

Key	Value
Content-Type	application/json
Pcr-Html-Encoded	TRUE

Body:

Key	Value

Key	Value
status	Active
eqp_catalog	1
billable	0
consumed	0
use_dhcp	0
private	0
equipment_recid	765
udf_UDF-RECID	1

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.

Main > Cable
Main > Services
Main > Inventory
Main > Catalog
- Specifically: Services, Equipment, Charges and G/L Accounts (GLA)