Bulk policy archive retrieval

You can perform archiving actions on policies in bulk, retrieving multiple policies at once and maintaining a record of those retrievals.

Note:

See Data Archiving for information on retrieving archived policies from previous versions of PolicyCenter.

Bulk retrieve archived policies

You can retrieve multiple policies from archive at once. To do this, call the following endpoint, passing it an array of policy numbers you want to retrieve.

POST /policy/v1/bulk-policy-archive-retrievals

For example:

Command

POST /policy/v1/bulk-policy-archive-retrievals

Request

{
  "data": {
    "attributes": {
        "policyNumbers": ["7890123456","P012345678"],
        "policyTermRetrievalFilter": "AllTerms",
        "title": "Bulk Retrieval 1"
    }
  }
}

The following fields are required in the request body:

  • policyNumbers: An array of policy numbers to retrieve.

  • title: Any string that helps you identify the bulk retrieval. The title does not have to be unique, but it can be helpful to give some context as to the purpose or contents of the retrieval.

  • policyTermRetrievalFilter: In the base configuration, allowed values are AllTerms, TermsInLastNumOfYears, TermsWithinPeriod. If you set this value to TermsInLastNumOfYears, you must also provide a value for yearsOfTermsRetrieved. If you set this value to TermsWithinPeriod, you must also provide values for toDateTermsRetrieved and fromDateTermsRetrieved.

If any of the policies cannot be retrieved the entire process fails and none of the policies in the bulk process are retrieved.

Note:

PolicyCenter does not retrieve the policies immediately. Policies are retrieved when the Restore Policy Term work queue runs. Typically, this process runs at scheduled times throughout the day. Users with certain administrative privileges can run the RestorePolicyTerm process manually from the UI in the Server Tools Work Queue Info screen.

Bulk archive retrieval status

You can use Cloud API endpoints to determine the status of a bulk retrieval.

To retrieve a list of all bulk retrieval records, use the following command:

Command

GET /policy/v1/bulk-policy-archive-retrievals

Response

{
    "data": [
        {
            "attributes": {
                "createdDate": "2023-06-12T21:53:25.621Z",
                "id": "pc:789",
                "title": "Bulk Retrieval 1"
            },
     …
    }
}

Append fields=*all to see the status of all policies within each retrieval batch:

Command

GET /policy/v1/bulk-policy-archive-retrievals?fields=*all

Response

{
    "data": [
        {
            "attributes": {
                "createdDate": "2023-06-12T21:53:25.621Z",
                "id": "pc:789",
                "policyTermRetrievalStatuses": [
                    {
                        "policyNumber": "P012345678",
                        "status": "Archived",
                        "uri": "/policy/v1/policies/pc:110?asOfDate=2023-05-08T07:01:00.000Z"
                    },
                    {
                        "policyNumber": "7890123456",
                        "status": "Retrieved",
                        "uri": "/policy/v1/policies/pc:122?asOfDate=2021-03-09T08:01:00.000Z"
                    }
                ],
                "policyTermsInArchive": 1,
                "policyTermsRetrieved": 1,
                "policyTermsRetrieving": 0,
                "title": "Bulk Retrieval 1"
            },
        …

You can check on the status of an individual bulk retrieval by including the id of the retrieval. For example:

Command

GET /policy/v1/bulk-policy-archive-retrievals/pc:789

Response

{
    "data": {
        "attributes": {
            "createdDate": "2023-06-12T21:53:25.621Z",
            "id": "pc:789",
            "policyTermsInArchive": 0,
            "policyTermsRetrieved": 2,
            "policyTermsRetrieving": 0,
            "title": "Bulk Retrieval 1"
        },
…
}

The response includes the following fields:

  • policyTermsInArchive: The number of policy terms in the bulk retrieval that have not yet been retrieved.

  • policyTermsRetrieved: The number of policy terms in the bulk retrieval that have been retrieved.

  • policyTermsRetrieving: The number of policy terms in the bulk retrieval that are being processed for retrieval.

Bulk archive record deletion

After a bulk policy archive retrieval has completed and you no longer need a record of that retrieval, you can delete the record.

DELETE /policy/v1/bulk-policy-archive-retrievals/{retrieval-id}

This command does not delete any of the policies associated with the retrieval, it deletes only the record of the bulk retrieval.