Audit policy endpoints

Retrieve audit details

Use the following endpoints to retrieve detailed information on audits for a policy:

GET /policy/v1/policies/{policyId}/audits
GET /policy/v1/policies/{policyId}/audits/{auditId}

This example retrieves information about all audits on policy pc:101:

Command

GET /policy/v1/policies/pc:101/audits

Response

"attributes": {
  "actualAuditMethod": {
    "code": "Voluntary",
    "name": "Voluntary"
  },
  "auditMethod": {
    "code": "Voluntary",
    "name": "Voluntary"
  },
  "auditPeriodEndDate": "2021-11-01T07:01:00.000Z",
  "auditPeriodStartDate": "2021-10-11T07:01:00.000Z",
  "auditScheduleType": {
    "code": "PremiumReport",
    "name": "Premium Report"
  },
  "dueDate": "2021-11-16T08:01:00.000Z",
  "id": "pc:101",
  "initDate": "2021-10-27T07:01:00.000Z",
  "job": {
    "displayName": "0002370929",
    "id": "pc:SiCsb2XDZXigd2aGUldeT",
    "type": "Job",
    "uri": "/job/v1/jobs/pc:901"
  },
  "status": "In Progress"
},
...

Create an audit

Use this endpoint to create a new audit on a policy:

POST /policy/v1/policies/{policyId}/audits

The following fields are required in the request:

Name	Type	Description
`auditMethod`	`AuditMethod` TypeKey	How the audit is conducted. In the base configuration, this can be one of the following: `Estimate` `Phone` `Physical` `Voluntary`
`auditScheduleType`	`AuditScheduleType` TypeKey	The type of audit. In the base configuration this is either `PremiumReport` or `FinalAudit`. (For the General Liability LOB, only `FinalAudit` is available in the base configuration.) If an audit of type `FinalAudit` exists on a policy with a state of scheduled, in progress, or complete, another audit of type `FinalAudit` cannot be created for the same policy term.
`dueDate`	datetime	The date the audit is due. This value can default to a specific amount of time beyond the policy end date, based on your configuration. See Configuration for more information.
`initDate`	datetime	The date the audit process starts.
`auditPeriodEndDate`	datetime	Required when `auditScheduleType` is `PremiumReport`. Cannot overlap with dates of an existing premium report on the policy, and must fall within the coverage dates of the policy period. For `auditScheduleType` `FinalAudit`, this field is read only. The value defaults to the policy period end or cancellation date.
`auditPeriodStartDate`	datetime	Required when `auditScheduleType` is `PremiumReport`. Cannot overlap with dates of an existing premium report on the policy, and must fall within the coverage dates of the policy period. For `auditScheduleType` `FinalAudit`, this field is read only. The value defaults to the policy period start date.

The following example creates a premium report audit on policy pc:101.

Command

POST /policy/v1/policies/pc:101/audits

Request

{
    "data": {
        "attributes": {
            "auditMethod": {
                "code": "Voluntary"
            },
            "auditScheduleType": {
                "code": "PremiumReport"
            },
            "dueDate": "2025-03-14",
            "initDate": "2024-12-21",
            "auditPeriodEndDate": "2025-07-02",
            "auditPeriodStartDate": "2025-06-03"
        }
    }
}

Update audit details

You can update the details of an audit with the following endpoint:

PATCH /policy/v1/policies/{policyId}/audits/{auditId}

The attributes that can be updated differ based on whether the audit job has started. The following table lists attributes that can be updated only when the job is in a certain state. Attributes not listed can be updated before or after the audit job has started.

Attribute	Not updatable, must be set on creation	Updatable only before start	Updatable only after start
`auditMethod`		X
`actualAuditMethod`			X
`auditScheduleType`	X
`auditPeriodEndDate`	X (Premium report only)
`auditPeriodStartDate`	X (Premium report only)
`auditFee`			X (Final audit only)
`receivedDate`			X
`paymentReceived`			X (Premium report only)
`instructions`			X (Final audit only)

This example changes the due date (which can be updated before or after audit start) for audit pc:800 on policy pc:101 to August 15, 2024:

Command

POST /policy/v1/policies/pc:101/audits/pc:800

Request

{
    "data": {
        "attributes": {
            "dueDate": "2024-08-15"
        }
    }
}

Start an audit

Audits start automatically on their initDate through a batch process. However, you can start the audit job prior to that date with the following POST command:

POST /policy/v1/policies/{policyId}/audits/{auditId}/start

This example starts audit pc:800 on policy pc:101. This command does not take a request body.

Command

POST /policy/v1/policies/pc:101/audits/pc:800/start

Response

{
    "data": {
        "attributes": {
            "actualAuditMethod": {
                "code": "Estimated",
                "name": "Estimated"
            },
            "auditMethod": {
                "code": "Estimated",
                "name": "Estimated"
            },
            "auditPeriodEndDate": "2025-07-02T07:00:00.000Z",
            "auditPeriodStartDate": "2025-06-03T07:00:00.000Z",
            "auditScheduleType": {
                "code": "PremiumReport",
                "name": "Premium Report"
            },
            "dueDate": "2025-03-14T07:00:00.000Z",
            "id": "pc:800",
            "initDate": "2024-01-17T22:39:36.392Z",
            "job": {
                "displayName": "0000053333",
                "id": "pc:750",
                "type": "Job",
                "uri": "/job/v1/jobs/pc:750"
            },
            "status": "In Progress",
            "waived": false
        },
}

Reverse an audit

It’s possible that an audit can be completed, but then need to be redone. For example, if another job that changes the policy (such as a cancellation or policy change) completes after the audit job has completed, the audit might need to be reversed so the changes can be accounted for. For final audits a reversal is done automatically when the policy change or cancellation takes place.

You can also manually reverse an audit, under the following conditions:

Audit must be a premium report. Because final audits happen automatically, only premium report audits can be manually reversed.
Final audit for the policy must not be complete. If a final audit for the policy is complete, premium report audits can no longer be reversed.

See Application Guide for more information on reversing audits.

Use the following endpoint to reverse an audit.

POST /policy/v1/policies/{policyId}/audits/{auditId}/reverse

This endpoint does not take a request body.

This example reverses audit pc:850 on policy pc:101.

Command

POST /policy/v1/policies/pc:101/audits/pc:850/reverse

Response

{
    "data": {
        "attributes": {
            "actualAuditMethod": {
                "code": "Voluntary",
                "name": "Voluntary"
            },
            "auditMethod": {
                "code": "Voluntary",
                "name": "Voluntary"
            },
            "auditPeriodEndDate": "2024-09-01T07:01:00.000Z",
            "auditPeriodStartDate": "2024-08-01T07:01:00.000Z",
            "auditScheduleType": {
                "code": "PremiumReport",
                "name": "Premium Report"
            },
            "dueDate": "2024-09-16T07:01:00.000Z",
            "id": "pc:850",
            "initDate": "2024-01-23T23:56:41.475Z",
            "job": {
                "displayName": "0000703318",
                "id": "pc:750",
                "type": "Job",
                "uri": "/job/v1/jobs/pc:750"
            },
            "receivedDate": "2024-01-23T08:00:00.000Z",
            "reversalDate": "2024-01-24T08:00:00.000Z",
            "status": "Reversed",
            "totalCost": {
                "amount": "30950.00",
                "currency": "usd"
            },
            "transactionAmount": {
                "amount": "0.00",
                "currency": "usd"
            },
            "waived": false
        },

Revise an audit

If an audit needs to be updated after it’s been completed, you can revise the audit. Only final audits can be revised.

See Application Guide for more information on revising audits.

POST /policy/v1/policies/{policyId}/audits/{auditId}/revise

The following command places audit pc:850 on policy pc:101 in a Revised state. The command does not take a request body.

Command

POST /policy/v1/policies/pc:101/audits/pc:850/revise

Response

{
    "data": {
        "attributes": {
            "actualAuditMethod": {
                "code": "Physical",
                "name": "Physical"
            },
            "auditMethod": {
                "code": "Physical",
                "name": "Physical"
            },
            "auditPeriodEndDate": "2024-10-11T07:01:00.000Z",
            "auditPeriodStartDate": "2023-10-11T07:01:00.000Z",
            "auditScheduleType": {
                "code": "FinalAudit",
                "name": "Final Audit"
            },
            "dueDate": "2024-01-19T08:01:00.000Z",
            "id": "pc:850",
            "initDate": "2024-01-22T21:16:07.683Z",
            "job": {
                "displayName": "0000333796",
                "id": "pc:901",
                "type": "Job",
                "uri": "/job/v1/jobs/pc:901"
            },
            "receivedDate": "2024-01-19T08:00:00.000Z",
            "revisingAudit": {
                "displayName": "PolicyAudit pc:855",
                "id": "pc:855",
                "type": "PolicyAudit",
                "uri": "/policy/v1/policies/pc:101/audits/pc:855"
            },
            "status": "Revised",
            "totalCost": {
                "amount": "33339.00",
                "currency": "usd"
            },
            "transactionAmount": {
                "amount": "7577.00",
                "currency": "usd"
            },
            "waived": false
        },

There are a few things to take note of in the response.

Status

No audit information, such as dates or audit method, has been revised on this audit. There is no request body, so nowhere to revise the information. The reason for this behavior is that PolicyCenter maintains an audit history. Instead of revising the audit (in this case pc:850), the audit has been given a status of Revised and a duplicate - or revising - audit has been created.

"status": "Revised"

Revising audit

To avoid losing audit history, audit pc:850 is not actually revised. Instead, revising the audit creates and starts a new audit job. Information for identifying the new audit is in the revisingAudit object, while information on the newly started job is in the job object. In this example the new audit is pc:855, and the audit job for audit pc:855 is pc:901:

"revisingAudit": {
  "displayName": "PolicyAudit pc:855",
  "id": "pc:855",
  "type": "PolicyAudit",
  "uri": "/policy/v1/policies/pc:101/audits/pc:pc855"
},
…
"job": {
  "displayName": "0000333796",
  "id": "pc:901",
  "type": "Job",
  "uri": "/job/v1/jobs/pc:901"
},

If you run a GET command on the revisingAudit uri, you’ll see the information for the new audit. Because the job started automatically, this new audit has a status of In Progress, as shown here:

Command

GET /policy/v1/policies/pc:101/audits/pc:855

Response

{
    "data": {
        "attributes": {
            "actualAuditMethod": {
                "code": "Physical",
                "name": "Physical"
            },
            "auditMethod": {
                "code": "Physical",
                "name": "Physical"
            },
            "auditPeriodEndDate": "2024-10-11T07:01:00.000Z",
            "auditPeriodStartDate": "2023-10-11T07:01:00.000Z",
            "auditScheduleType": {
                "code": "FinalAudit",
                "name": "Final Audit"
            },
            "dueDate": "2024-01-22T21:23:32.232Z",
            "id": "pc:855",
            "initDate": "2024-01-22T21:23:32.232Z",
            "job": {
                "displayName": "0000444563",
                "id": "pc:901",
                "type": "Job",
                "uri": "/job/v1/jobs/pc:901"
            },
            "receivedDate": "2024-01-19T08:00:00.000Z",
            "revisionType": {
                "code": "Revision",
                "name": "Revision"
            },
            "status": "In Progress",
            "waived": false
        },

To change the information in the revising audit, use the PATCH command described above in Update audit details.

Waive an audit

You cannot delete a scheduled audit. Instead, if an audit has been scheduled but is no longer needed, you can waive the audit. You cannot waive an audit that has started. (However, you can waive the audit job on an audit that has started. See Waive an audit job for more information.)

POST /policy/v1/policies/{policyId}/audits/{auditId}/waive

This endpoint does not take a request body.

An audit that has been waived cannot be started or updated.