Document toolboxDocument toolbox

(2024.1) Services 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 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

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

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

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

Field

Required

Data Type

Options

Default

Notes

recid

no*

Integer





Identifier of the record. *See Note Below

status

yes

Integer

(2024.1) Services API Calls



The status of the service.

serv_catalog

yes

Integer

(2024.1) Services API Calls



Recid of the Service Catalog item.

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

(2024.1) Services API Calls



Record ID of either the Contact or the Department owner. The API will validate if the Owner's GLA Format is compatible with the Service's Billing Group Format.

owner_type

no*

String

"contact" or "department"



Type of owner

location

no

Integer

(2024.1) Services API Calls



Recid of location for service.

service_host

no

Integer

(2024.1) Services API Calls



Recid of Service Host for service.

sla

no

Integer

(2024.1) 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

(2024.1) 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

(2024.1) Services API Calls



Recid of Associated Service.

equipment

no

String

(2024.1) 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

(2024.1) 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

(2024.1) 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

(2024.1) 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. The Override GLA Format should match the Billing Group Format of the Service,

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

(2024.1) Services API Calls



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

(2024.1) Services API Calls



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

auth_code_type

no

Integer

(2024.1) Services API Calls



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

service_class

no

Integer

(2024.1) Services API Calls



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

rating_group

no

Integer

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

Call:

Headers:

Key

Value

Key

Value

Content-Type

application/json

Pcr-Html-Encoded

TRUE

Body:

Key

Value

Key

Value

status

Available

serv_catalog

1

service_id

5558675309

status_date

2019/03/18

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.

Available Fields

Field

Required

Data Type

Options

Default

Notes

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:

Headers:

Key

Value

Key

Value

Content-Type

application/json

Pcr-Html-Encoded

TRUE

Body:

Key

Value

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

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:

Headers:

Key

Value

Key

Value

Content-Type

application/json

Pcr-Html-Encoded

TRUE

Body:

Key

Value

Key

Value

type

REMARKS

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.



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

type

yes

String

CHARGES





quantity

no

Integer



1

The 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

gla

no

Integer

(2024.1) Services API Calls



RECID of GLA to assign to Service Charge

location

no

Integer

(2024.1) Services API Calls



Location that this Charge applies to for the service

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

MRC

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

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

Call:

Headers:

Key

Value

Key

Value

Content-Type

application/json

Pcr-Html-Encoded

TRUE

Body:

Key

Value

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

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

service_recid

yes

Integer





RECID column from SERVICES table.

gla

yes

String

(2024.1) 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

(2024.1) Services API Calls



The type(s) of GLA(s).

When adding a new GLA to a Service, the API will validate that the Billing Group Format for the Service is compatible with the Format for the new GLA.

Call:

Headers:

Key

Value

Key

Value

Content-Type

application/json

Pcr-Html-Encoded

TRUE

Body:

Key

Value

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.

Available Fields

Field

Required

Data Type

Options

Default

Notes

Field

Required

Data Type

Options

Default

Notes

service_recid

yes

Integer





RECID column from SERVICES table.

contact

yes

String

(2024.1) Services API Calls



Record ID(s) of the contact(s).

Call:

Headers:

Key

Value

Key

Value

Content-Type

application/json

Pcr-Html-Encoded

TRUE

Body:

Key

Value

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.

Available Fields

Field

Required

Data Type

Options

Default

Notes

Field

Required

Data Type

Options

Default

Notes

service_recid

Yes

Integer





RECID column from SERVICES table.

udf_UDF-RECID

Yes*

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

Headers:

Key

Value

Key

Value

Content-Type

application/json

Pcr-Html-Encoded

TRUE

Body:

Key

Value

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.

If multiple locations 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

service_recid

yes

Integer





RECID column from SERVICES table.

location

yes

Integer

(2024.1) 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:

Headers:

Key

Value

Key

Value

Content-Type

application/json

Pcr-Html-Encoded

TRUE

Body:

Key

Value

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.

If multiple pieces of Equipment are going to be assigned, 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

service_recid

yes

Integer





RECID column from SERVICES table.

equipment

yes

String

(2024.1) Services API Calls



Recid(s) of Equipment to assign to the Service

Call:

Headers:

Key

Value

Key

Value

Content-Type

application/json

Pcr-Html-Encoded

TRUE

Body:

Key

Value

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.