Document toolboxDocument toolbox

.Services API Calls v2021.2

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

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

Parameter

Default

Description

limit

20

The 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 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

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.

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 v2021.2


The status of the service.

serv_catalog

yes

Integer

.Services API Calls v2021.2


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. The service_id field can be formatted or unformatted. The service_id cannot be updated. *See Note Below.

owner

no*

Integer

.Services API Calls v2021.2


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 v2021.2


Recid of location for service.

service_host

no

Integer

.Services API Calls v2021.2


Recid of Service Host for service.

sla

no

Integer

.Services API Calls v2021.2


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 v2021.2


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 v2021.2


Recid of Associated Service.

equipment

no

String

.Services API Calls v2021.2


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 v2021.2


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 v2021.2


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 v2021.2


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 v2021.2


List Value(s) of Expense Type(s). *Required if GLA is specified.

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 v2021.2


IF service_type = "data" OR "backbone". Recid of bandwidth record.

auth_code_type

no

Integer

.Services API Calls v2021.2


IF service_type = "authcode". Recid of authcode type.

service_class

no

Integer

.Services API Calls v2021.2


IF service_type = "authcode". Recid of Service Class for authcode.

rating_groupnoInteger.Services API Calls v2021.2

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, the "recid" or "service_id" is Required. If both are passed they must match the same record.

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_id5558675309
status_date2019/03/18
directory1
report_9111

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 column from SERVICES table.

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.

Available Fields

Field

Required

Data Type

Options

Default

Notes

service_recid

yes

Integer



RECID column from SERVICES table.

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

typeREMARKS

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.


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

RECID for charges reads as "SERV1234" but when using that RECID for the API you only need the numbers, so "1234" from the example.

service_recid

yes

Integer



RECID column from SERVICES table.

charge_recid

no*

Integer

Services API Calls


RECID column from CHRG_CATALOG table. *Conditionally Required if attempting to add a new Service Charge

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.

typeyesStringCHARGES

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 v2021.2


RECID of GLA to assign to Service Charge

location

no

Integer

.Services API Calls v2021.2


Location that this Charge applies to for the service

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

MRC

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

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.

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

Default

Notes

service_recid

yes

Integer



RECID column from SERVICES table.

gla

yes

String

.Services API Calls v2021.2


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 v2021.2


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_percent100
gla_typeDefault

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



RECID column from SERVICES table.

contact

yes

String

.Services API Calls v2021.2


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

Options

Default

Notes

service_recid

Yes

Integer



RECID column from SERVICES table.

udf_UDF-RECIDYes*Integer

UDF-RECID is the RECID of the UDF to assign the value to. RECID column from USER_DEFINED_FIELDS_VALS table. 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.

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-RECID2Test
udf_UDF-RECID32019/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

Default

Notes

service_recid

yes

Integer



RECID column from SERVICES table.

location

yes

Integer

.Services API Calls v2021.2


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_9111
location_status1

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 pieces of Equipment are going 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 column from SERVICES table.

equipment

yes

String

.Services API Calls v2021.2


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.


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