Document toolboxDocument toolbox

(2024.1) Equipment API Endpoint



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

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