Equipment API Calls
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 / | 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=LISTTYPESearchable
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=testParameter | 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 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 Default Description limit 20 Number of listings to show. page 1 Page number to show.Data Type Interger Interger
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 | ||
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 | |
owner_type | no* | String | "contact" or "department" | Type of 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). |
Request Example
Call:
POST DOMAIN/KEY/equipment.jsonHeaders:
Key | Value |
|---|---|
Content-Type | application/json |
Pcr-Html-Encoded | TRUE |
Body:
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.
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.jsonHeaders:
Key | Value |
|---|---|
Content-Type | application/json |
Pcr-Html-Encoded | TRUE |
Body:
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.
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.jsonHeaders:
Key | Value |
|---|---|
Content-Type | application/json |
Pcr-Html-Encoded | TRUE |
Body:
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.
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_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:
POST DOMAIN/KEY/equipment.jsonHeaders:
Key | Value |
|---|---|
Content-Type | application/json |
Pcr-Html-Encoded | TRUE |
Body:
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).
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.jsonHeaders:
Key | Value |
|---|---|
Content-Type | application/json |
Pcr-Html-Encoded | TRUE |
Body:
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.
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.jsonHeaders:
Key | Value |
|---|---|
Content-Type | application/json |
Pcr-Html-Encoded | TRUE |
Body:
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.
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-RECID | Yes* | Integer | UDF-RECID is the RECID of the UDF to assign the value to. Example: udf_684=value
| ||
| udf_UDF-IDENTIFIER | Yes* | Mixed | IDENTIFIER is the unique Identifier of the UDF to assign the value to. Example: udf_LEGACYNUM=value
|
- 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.jsonHeaders:
Key | Value |
|---|---|
Content-Type | application/json |
Pcr-Html-Encoded | TRUE |
Body:
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)