For developers
Policy Center REST API
Policy Center Solution (PCS) REST API Overview
Starting point and URLs collection
REST API base URL: https://<domain>/p/api/services / restful/<version>
Example: https://demo.igpolicy.net/p/api/services/restful/3.1REST API objects URLs collection: https:// <domain> / p/api /services/restful/ <version> / <object_type> / <guid>
- <domain> Policy Center client domain name (often something like company.igpolicy.net)
- <version> is a current version of Policy Center product, e.g. 3.1;
- <object_type> is an Policy Center retention object type, e.g. recordclass;
- <guid> is an unique object identifier within Policy Center;
Table of contents
- Global parameters
- Differences between "reference" objects and "full" objects
- Services
- DataOwner
- DataSource
- Citations
- Rule
- Changes
- Mappings
Global Parameters
The following parameters are available for every API:
- fetch - can take true/ false values (default is false), indicates show only object reference or shows full list of object fields with values in output accordingly;
- start - can take any positive integer value, indicates the position from what objects will be displayed in output;
- pagesize - can take value from 1 to 100 (default is 20), indicates the amount of objects in result output;
- responseFormat - API response format can be either XML or JSON
- withEmpty – Note: this parameter can be used only when &responseFormat=json. By default empty metadata fields will not be included into API response. But if this parameter is set to 1 or ‘true’ – empty fields will not be stripped out from API response (Example https://pcs-api-hpe.igpolicy.net/p/api/services/restful/3.1/recordclass/94fe26b7-b584-ca35-cdb1-6198a965c282?responseFormat=json&withEmpty=true)
Differences between "reference" objects and "full" objects
Many APIs return a "reference" object instead of returning a "full" object. References are the same type as a regular object, but the only piece of data filled out is the "ref" attribute in XML.
For instance: <citation ref="https://demo.igpolicy.net/p/api/services/restful/3.1/legalsource/311be25e-6029-879e-5c8b-4e0959d39e8d">
You can use the ref URL to get full information about the object.
Responses
Object read requests will return an XML or JSON document representing that object. In an XML response, all object fields will be included in the object output, even empty fields. With a JSON response, only non-empty fields will be included in the response, unless the “withEmpty” parameter is set.
If there is an error retrieving an object, the return element “Status” will indicate this with value "Error," and “Message” element will describe the error(s). Warnings can effectively be ignored, but the presence of errors indicates that the requested operation has failed.
Services
RecordClass
A group of related records that are used and arranged in accordance with a filing system. These records are normally kept together because they relate to a particular subject or function, result from the same activity, have a particular form, or have some relationship arising from their creation, receipt, use, or disposition. They can be evaluated as a unit for retention scheduling purposes.
REST URLs Collection
Operation | HTTP Method | Encoding | URL |
List | GET | XML | https://demo.igpolicy.net/p/api/services/restful/3.1/recordclass |
Read | GET | XML | https://demo.igpolicy.net/p/api/services/restful/3.1/recordclass/<guid> |
Parameters:
Name | Description | Required |
mappings |
To return all object mappings, you should set mappings=true. The API will return all object mapping references, unless fetch=true is set, in which case you will get object mapping data instead of just references. All mappings will be sorted by mapped object type. |
|
guid | RecordClass object id |
Examples:
REST URL: https://demo.igpolicy.net/p/api/services/restful/3.1/recordclass
RESPONSE:
REST URL: https://demo.igpolicy.net/p/api/services/restful/3.1/recordclass/fbf31bf3-fd6c-aabd-4030-fede030e9b2b
RESPONSE:
REST URL: https://demo.igpolicy.net.com/p/api/services/restful/3.1/recordclass?start=20&pagesize=2&fetch=false
RESPONSE:
REST URL: https://demo.igpolicy.net/p/api/services/restful/3.1/recordclass?fetch=true&mappings=true&start=5&pagesize=1
RESPONSE:
DataOwner
REST URLs Collection
Operation | HTTP Method | Encoding | URL |
List | GET | XML | https://demo.igpolicy.net/p/api/services/restful/3.1/dataowner |
Read | GET | XML | https://demo.igpolicy.net/p/api/services/restful/3.1/dataowner/<guid> |
Parameters:
Name | Description | Required |
guid | DataOwner object id |
Examples:
REST URL: https://demo.igpolicy.net/p/api/services/restful/3.1/dataowner
RESPONSE:
REST URL: https://demo.igpolicy.net/p/api/services/restful/3.1/dataowner/cfcf2086-6419-0c7c-90d5-3a75cb058017
RESPONSE:
DataSource
REST URLs Collection
Operation | HTTP Method | Encoding | URL |
List | GET | XML | https://demo.igpolicy.net/p/api/services/restful/3.1/datasource |
Read | GET | XML | https://demo.igpolicy.net/p/api/services/restful/3.1/datasource/<guid> |
Parameters:
Name | Description | Required |
guid | DataSource object id |
Examples:
REST URL: https://demo.igpolicy.net/p/api/services/restful/3.1/datasource
RESPONSE:
REST URL: https://demo.igpolicy.net/p/api/services/restful/3.1/datasource/e66bd933-68f6-da32-57c8-a6041f9a51ae
RESPONSE:
Citations
A record within the Citation Library that represents a legal or business obligation to retain a record. There are several types of citations.
- GRS Citation: Digital copies of citations delivered from the GRS database. Only a limited number of fields can be edited on a GRS citation.
- Local Citation: Citations created locally within PCS and not part of a GRS subscription.
REST URLs Collection
Operation | HTTP Method | Encoding | URL |
List | GET | XML | https://demo.igpolicy.net/p/api/services/restful/3.1/citation |
Read | GET | XML | https://demo.igpolicy.net/p/api/services/restful/3.1/citation/<guid> |
Parameters:
Name | Description | Required |
guid | Citation object id |
Examples:
REST URL: https://demo.igpolicy.net/p/api/services/restful/3.1/legalsource
RESPONSE:
REST URL: https://demo.igpolicy.net/p/api/services/restful/3.1/citation/ed273e79-55d2-cd3d-ba2b-9c26feaf1582
RESPONSE:
REST URL: https://demo.igpolicy.net.com/p/api/services/restful/3.1/ citation ?start=17&pagesize=3&fetch=false
RESPONSE:
Rule
REST URLs Collection
Operation | HTTP Method | Encoding | URL |
List | GET | XML | https://demo.igpolicy.net/p/api/services/restful/3.1/rule |
Read | GET | XML | https://demo.igpolicy.net/p/api/services/restful/3.1/rule/<guid> |
Parameters:
Name | Description | Required |
mappings | To get information about all object mappings you should include mappi ngs=true argument into your request string. So all object mappings will be included as a reference to mapped object. All mappings will be also sorted by mapped object type. | |
guid | Rule object id | |
Examples:
REST URL: https://demo.igpolicy.net/p/api/services/restful/3.1/rule
RESPONSE:
REST URL: https://demo.igpolicy.net/p/api/services/restful/3.1/rule/fb64420e-848d-2957-6bc4-9f1a216ca4e6
RESPONSE:
REST URL: https://demo.igpolicy.net/p/api/services/restful/3.1/rule?start=1&pagesize=2&fetch=true
RESPONSE:
REST URL: https://demo.igpolicy.net/p/api/services/restful/3.1/rule/fbdc0ff5-ad7f-419b-a23d-5703653e62b3?mappings=true
RESPONSE:
Changes
The changes API is intended to provide information about changes made between published versions of the API snapshot set in Policy Center.
Parameters:
Name | Description | Required |
type |
String determines the type of change you want the API to return. Possible values are update, delete, create, and replace. Update shows modified items, delete shows items that were deleted, create shows items created, and replace shows items where a rule tied to a specific jurisdiction and mapped to a record class is replaced by a mapping to a new rule in the same jurisdiction |
NO |
SnapshotTimeStamp | Unix timestamp. API will use this parameter only to compare with currently published snapshot. If sent SnapshotTimeStamp is equal to currently published SnapshotTimeStamp API will return ZERO changes. Otherwise—and it doesn’t matter how much snapshots have been published since SnapshotTimeStamp—API will return only list of most recent changes (changes which has happen during last API snapshot publishing). | YES |
Example Request:
https://demo.igpolicy.net/p/api/services/restful/3.1/changes
Example Response:
Example Request:
https://demo.igpolicy.net/p/api/services/restful/3.1/changes? fetch=true
Example Response:
Example Request:
https://demo.igpolicy.net/p/api/services/restful/3.1/changes?type=replace
Example Response:
Mappings
The mappings API is intended to provide information about mapping objects—that is, the object that ties together a record class and a retention rule in Policy Center.
Mappings between Record Class and Rule have additional tag
example:
AA-01-001 | - Record Class code |
12345678 | - Mapping code (Box code) |
AA-01-001-12345678 | - Classification Code |
REST URLs Collection
Operation | HTTP Method | Encoding | URL |
List | GET | XML | https://demo.igpolicy.net/p/api/services/restful/3.1/<mapping_type> |
Read | GET | XML | https://demo.igpolicy.net/p/api/services/restful/3.1/<mapping_type> /<guid> |
Parameters:
Name | Description | Required |
guid | Mapping object id | |
mapping_type | Mapping object type, e.g. “maprctorule” | |
Example Request:
https://demo.igpolicy.net/p/api/services/restful/3.1/maprctorule
Example Response:
Example Request:
Example Response:
Example Request for mapping between Record Class and Source :
Example Response: