.Services API Calls v2019.4

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 RECID's of 'Services' and 'Charges':

SELECT * FROM SERVICES_CHARGES;

Controlling Results Count

By default 20, items will be returned at a time.

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

Parameter	Default	Description
LIMIT	20	Number of listings to show.
PAGE	1	Page number to show.

Response Data

Name	Datatype	Searchable	Notes
BILLABLE	Yes/No	Yes	To indicate whether the service item is or is not billable
STATUS_DATE	string	Yes	Shows the date when the service was set to its current status
SERVICE_HOST	string	Yes	The Service Host associated with the service
SERVICE_ID	string	Yes	Service Id (phone_number, etc.)
SERVICE_ID_FMT	string	Yes	Formatted Service Id
CATALOG	string	Yes	Service Catalog name
OWNER	string	Yes	Name of the service owner – either a person or org hierarchy
LOCATIONS_PATH	string	Yes	The hierarchical path to the location of the service; use LOCATIONS when searching
SLA_CATALOG_PATH	string	Yes	The hierarchical path to the SLA of the service; use SLA when searching
SERVICES_STATUS	string	Yes	The current status of the service
SERVICES_UDF	list	No	List of all the User Defined Fields and the selected values for this service
SERVICES_CHARGES	list	No	Charges listed for this service
SERVICES_CONTACTS	list	No	Contacts associated with the service
SERVICES_EQUIPMENT	list	No	Pieces of equipment to be used/listed for this service
SERVICES_EXPENSE_GLA	list	No	Expense G/L Accounts to be used for billing of this service
SERVICES_REMARKS	list	No	List of all remarks/comments for this service

Results

Lists

When inserting or updating Service 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/services.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/services.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 Results
DEPTHIER	Retrieve available Department Hierarchies		Coming Soon	Department Hierarchy Results
EXPENSE_TYPE	Retrieve available Expense Types		no	Expense Types Results
GLAS	Retrieve available GLAs		no	GLAs Results
LOCATIONS	Retrieve available Locations		yes	Locations Results
CHARGE_CATALOG	Retrieve available Charge Catalogs		yes	Charge Catalog Results
SERVICE_CATALOG	Retrieve available Service Catalogs		yes	Service Catalog Results
SERVICE_HOSTS	Retrieve available Service Hosts		no	Service Hosts Results
UDFS	Retrieve available User Defined Fields (UDF)	SERV_CATALOG_RECID (required)	no	UDFs Results
SLAS	Retrieve available SLAs		no	SLAs Results
POOLS	Retrieve available Service Pools		no	Service Pools Results
SERVICE_CLASSES	Retrieve available Service Classes		no	Service Classes Results
SERVICE_HOST_PARTITIONS	Retrieve available Service Host Partitions		no	Service Host Partitions Results
AUTH_CODE_TYPE	Retrieve available Auth Code Types		no	Auth Code Types Results
BANDWIDTH	Retrieve available Bandwidths		no	Bandwidth Results
RATING_GROUP	Retrieve available Rating Groups		no	Rating Groups Results
SERVICE_STATUS	Retrieve available Service Statuses		no	Service Status Results

*Extra Parameters can be appended to the URL in standard Query String fashion.

Write Call

Available Fields

Field	Required	Data Type	Options	Default	Notes
recid	no*	Integer			Identifier of the record. *See Note Below
status	yes	Integer	Services API Calls		The status of the service.
serv_catalog	yes	Integer	Services API Calls		Recid of the Service Catalog item. When updating the Catalog, the process will maintain the Service Type and the Service ID Format. The Catalog may only be updated for a Service if it's status is Available.
service_id	yes	String			Service ID of this service. Before inserting a new record, the system confirms there is no existing matching formatted version. If a match is found, the call will update the appropriate record.
service_id_fmt	no*	String			Formatted version of the Service ID. *See Note Below
owner	no*	Integer	Services API Calls		Record ID of either the Contact or the Department owner.
owner_type	no*	String	"contact" or "department"		Type of owner
location	no	Integer	Services API Calls		Recid of location for service.
service_host	no	Integer	Services API Calls		Recid of Service Host for service.
sla	no	Integer	Services API Calls		Recid of SLA for service.
reference	no	String			Reference for service
billable	no	Integer	1 = yes; 0 = no		Designate if the Service is Billable
billing_group	no	Integer	Services API Calls		Recid of billing group for service.
essential	no	Integer	1 = yes; 0 = no		Designate if this is an essential Service.
status_date	yes	String			Date status was set for Service. Format “YYYY/MM/DD”.
assoc_service	no	Integer	Services API Calls		Recid of Associated Service.
equipment	no	String	Services API Calls		Recid(s) of equipment to add to Service. If multiple Equipment are to be assigned, separate Recids with commas. Example: 56,875.
contact	no	String	Services API Calls		Recid(s) of Contacts to add to Service. If multiple contacts are to be assigned, separate recids with commas. Example: 1234,7894.
remarks	no	String			Remarks to add to the Service.
pool	no	String	Services API Calls		Recids of Service pool(s) to add to the Service. If multiple contacts are to be assigned, separate recids with commas. Example: 548,785.
gla	no	Integer	Services API Calls		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 required and the same count of percentages need to be provided also. Total of all percentages must equal exactly 100.
gla_type	no*	String	Services API Calls		List Value(s) of Expense Type(s). *Required if GLA is specified.
service_type	yes	String	"phone", "data", "authcode", "backbone"		Type of Service. This value determines specific fields and requirements listed below.
directory	yes	Integer	1 = yes; 0 = no		IF service_type = "phone". Designates if this Service is to be listed in the directory.
report_911	yes	Integer	1 = yes; 0 = no		IF service_type = "phone". Designates if this Service is to be listed in emergency 911 feed.
multiple_locations	no	Integer	1 = yes; 0 = no		IF service_type = "phone". Designates if this Service has multiple locations.
bandwidth	no	Integer	Services API Calls		IF service_type = "data" OR "backbone". Recid of bandwidth record.
auth_code_type	no	Integer	Services API Calls		IF service_type = "authcode". Recid of authcode type.
service_class	no	Integer	Services API Calls		IF service_type = "authcode". Recid of Service Class for authcode.
rating_group	no	Integer	Services API Calls		Recid of Rating Group for the Service. Config USE_RATING_GROUP must be set to TRUE to use this field

Note: When updating a record, either the "recid" or "service_id_fmt" is required.

Call:

POST DOMAIN/KEY/services.json

Headers:

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

Body:

Key	Value
status	Available
serv_catalog	1
service_id	5558675309
status_date	2019/03/18
service_type	Phone
directory	1
report_911	1

Results

If the request is successful, the Service RECID will be returned as follows:

Service Pools

Services can be assigned to one or more Pools.

Below is the proper format for making a separate request. Note "type=POOLS" to indicate that this is to add a Service to one or more Pools.

POST http://DOMAIN/api/API_KEY/services.OUTPUT?type=POOLS&field1=value1 ...

Available Fields

Field	Required	Data Type	Options	Default	Notes
service_recid	yes	Integer			Recid of service
pools	yes	String			One or more Recids of Pools. If multiple, separate with commas. Example: 23,43

Call:

POST DOMAIN/KEY/services.json

Headers:

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

Body:

Key	Value
service_recid	1
pools	1

Results

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

Service Remarks

Remarks can be added to services.

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

POST http://DOMAIN/api/API_KEY/services.OUTPUT?type=REMARK&field1=value1 ...

Available Fields

Field	Required	Data Type	Options	Default	Notes
service_recid	yes	Integer			Recid of service
remarks	yes	String			The remark to add to the service

Call:

POST DOMAIN/KEY/services.json

Headers:

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

Body:

Key	Value
service_recid	1
remarks	Test Remark

Results

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

Service Charges

Charges can be easily added to a Service. If multiple Charges need to be added to Service, 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 a Service Charge record.

POST http://DOMAIN/api/API_KEY/services.OUTPUT?type=CHARGES&field1=value1 ...

Available Fields

Field	Required	Data Type	Options	Default	Notes
recid	no	Integer			*Conditionally Required if attempting to UPDATE a Service Charge
service_recid	yes	Integer			The RECID of the Service that the charge is for
charge_recid	yes	Integer	Services API Calls		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. *Required if charge does not have an amount on it.
quantity	no	Integer		1	The quantity of charge to be used.
prorate	no	Integer	1 or 0	0	Should the charge be prorated when activated
gla	no	Integer	Services API Calls		Recid of GLA to assign to Service Charge
location	no	Integer	Services API Calls		Location that this Charge applies to for the service
stop_date	no	String			The Date the Recurring Charge should stop on. YYYY-MM-DD format.
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

Call:

POST DOMAIN/KEY/services.json

Headers:

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

Body:

Key	Value
service_recid	1
charge_recid	1

Results

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

Service GLA

GLAs can be easily added to a Service. If multiple GLAs need to be added to the service, 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 a Service GLA record(s).

POST http://DOMAIN/api/API_KEY/services.OUTPUT?type=GLA&field1=value1 ...

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

POST http://DOMAIN/api/API_KEY/services.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	Notes
service_recid	yes	Integer		The RECID of the Service that the GLA is for
gla	yes	String	Services API Calls	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	Services API Calls	The type(s) of GLA(s).

Call:

POST DOMAIN/KEY/services.json

Headers:

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

Body:

Key	Value
service_recid	1
gla	1
gla_percent	100
gla_type	Default

Results

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

Service Contacts

Contacts can be easily added to a Service. If multiple contacts 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 a Service.

POST http://DOMAIN/api/API_KEY/services.OUTPUT?type=CONTACTS&field1=value1 ...

Available Fields

Field	Required	Data Type	Options	Default	Notes
service_recid	yes	Integer			The RECID of the Service that the Contact is for
contact	yes	String	Services API Calls		Record ID(s) of the contact(s).

Call:

POST DOMAIN/KEY/services.json

Headers:

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

Body:

Key	Value
service_recid	1
contact	1

Results

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

Service UDFs

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

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

POST http://DOMAIN/api/API_KEY/services.OUTPUT?type=UDFS&field1=value1 ...

Available Fields

Field	Required	Data Type	Notes
service_recid	Yes	Integer	The RECID of the Service that the UDF is for
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.

Call:

POST DOMAIN/KEY/services.json

Headers:

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

Body:

Key	Value
service_recid	1
udf_UDF-RECID1	1
udf_UDF-RECID2	Test
udf_UDF-RECID3	2019/12/31

Results

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

Service Locations

Locations can be added to Services.

Below is the proper format for making a separate request. Note "type=LOCATIONS" to indicate that this is to add Locations to a Service.

POST http://DOMAIN/api/API_KEY/services.OUTPUT?type=LOCATIONS&field1=value1 ...

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

POST http://DOMAIN/api/API_KEY/services.OUTPUT?type=LOCATIONS&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	Notes
service_recid	yes	Integer		Recid of Service
location	yes	Integer	Services API Calls	Recid(s) of the Location(s) to assign to the Service.
report_911	yes	Integer	1 = yes; 0 = no	Designate if Location should show on emergency 911 feed
location_status	yes	Integer	1 = yes; 0 = no	Status of Location

Call:

POST DOMAIN/KEY/services.json

Headers:

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

Body:

Key	Value
service_recid	1
location	1
report_911	1
location_status	1

Results

If the request is successful, the Recid of the Service Location record(s) will be returned in the same order as provided:

Service Equipment

Equipment can be added to a Service.

Below is the proper format for making a separate request. Note "type=EQUIPMENT" to indicate that this is to add Equipment to a Service.

POST http://DOMAIN/api/API_KEY/services.OUTPUT?type=EQUIPMENT&field1=value1 ...

If multiple Equipment are to be assigned, structure your request as follows:

POST http://DOMAIN/api/API_KEY/services.OUTPUT?type=EQUIPMENT&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
service_recid	yes	Integer			Recid of Service
equipment	yes	String	Services API Calls		Recid(s) of Equipment to assign to the Service

Call:

POST DOMAIN/KEY/services.json

Headers:

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

Body:

Key	Value
service_recid	1
equipment	1

Results

If the request is successful, the Recid of the Service Equipment record(s) will be returned in the order provided:

Locating Service Data

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