Audit job endpoints

Waive an audit job

If an audit has started but is no longer needed, you can waive the audit by using the following endpoint:

POST /jobs/{jobId}/waive

Note: If you want to waive a job that has not been started, use the waive endpoint on the policy. See Waive an audit for more information.

This endpoint does not take a request body.

Withdraw an audit job

Withdrawing an audit job is similar to waiving, but withdraw is done only on audits that have been revised. (See Revise an audit for more information.) If an audit has been revised and then later it’s determined the revision is not necessary, the job can be withdrawn.

Use the following endpoint to withdraw an audit job:

POST /jobs/{jobId}/withdraw

This endpoint does not take a request body.

Quote an audit job

To quote an audit job, use the following endpoint:

POST /jobs/{jobId}/quote

Before you quote an audit job, there might be information you need to add to the job based on the validation requirements implemented by the LOB. In the base configuration for Workers’ Comp and General Liability you must include an audited amount. In Workers’ Comp you must also include a received date. If you run the quote endpoint without updating the required validation information, you’ll receive errors similar to the following:

{
    "status": 400,
    "errorCode": "gw.api.rest.exceptions.BadInputException",
    "userMessage": "Entity validation errors block 'quote' action",
    "details": [
        {
            "message": "All audited amounts must be filled in to calculate premiums.",
            "properties": {
                "type": "WorkersCompLine",
                "url": "/job/v1/jobs/pc:901/lines/WorkersCompLine",
                "severity": "error"
            }
        },
        {
            "message": "Received date must be specified.",
            "properties": {
                "type": "WorkersCompLine",
                "url": "/job/v1/jobs/pc:901/lines/WorkersCompLine",
                "severity": "error"
            }
        }
    ]
}

This example demonstrates updating the required validation information for Workers’ Comp in the base configuration. It walks through finding the covered employees for audit job pc:901, updating the audited amount and received date, and quoting the job.

Retrieve covered employees

The audited amount is the payroll amount reported by the customer. The employees covered by the audited amount could be in multiple jurisdictions. To update this value through the API, you need to find the covered employee associated with the audit job and update the fields that represent the various jurisdictions.

Command

GET /jobs/pc:901/lines/WorkersCompLine/covered-employees

Response

{
    "count": 1,
    "data": [
        {
            "attributes": {
                "addedDate": "2024-02-01T08:01:00.000Z",
                "id": "401",
                "ifAnyExposure": false,
                "location": {
                    "displayName": "1: 2306 Market St., San Francisco, CA",
                    "id": "401",
                    "type": "PolicyLocation",
                    "uri": "/job/v1/jobs/pc:901/locations/401"
                },
                "removedDate": "2025-02-01T08:01:00.000Z",
                "specialCov": {
                    "code": "stat",
                    "name": "State Act"
                },
                "splits": {
                    "1": {
                        "basisAmount": 35,
                        "endDate": "2025-02-01T08:01:00.000Z",
                        "numEmployees": 50,
                        "startDate": "2024-02-01T08:01:00.000Z"
                    }
                }
            },

Notice the splits property. If there were multiple jurisdictions on this audit, there would be multiple objects under the splits property. In this case there is only one, so this next step updates the audited amount for that split for covered employee 401.

Update audited amount

Command

PATCH /jobs/pc:901/lines/WorkersCompLine/covered-employees/401

Request

{
    "data": {
        "attributes": {
            "splits": {
                "1": {
                    "auditedAmount": 4000
                }
            }
        }
    }
}

Response

...
"id": "401",
...
"splits": {
  "1": {
    "auditedAmount": 40,
    "basisAmount": 35,
    "endDate": "2025-02-01T08:01:00.000Z",
    "numEmployees": 50,
    "startDate": "2024-02-01T08:01:00.000Z"
  }
...

Update received date

Next, update the date that the payment was received. The received date is the date payment was received from the customer. You set the received date on the audit policy. This update is done on the audit policy, not the job.

Command

PATCH /policies/pc:101/audits/pc:855

Request

{
    "data": {
        "attributes": {
            "receivedDate": "2024-05-15"
        }
    }
}

Quote the job

Now it’s time to quote the audit job. After the job is quoted you can no longer update it. To update the job, you must return it to draft state. (See Quoting the submission for more information.) This endpoint does not take a request body.

Command

POST /jobs/pc:901/quote

Response

{
  "data": {
    "attributes": {
      ...
      "id": "pc:901",
      ...
      "jobStatus": {
        "code": "Quoted",
        "name": "Quoted"
      },
      "jobType": {
        "code": "Audit",
        "name": "Audit"
      },
    ...
},

As you can see in the response, the job has now been quoted.

Complete an audit job

Audit jobs are not bound or issued. Instead, when the audit is over, the job must be marked as complete. You can set an audit job to complete with the following endpoint:

POST /jobs/{jobId}/complete

This endpoint does not take a request body.

Command

POST /jobs/pc:901/complete

Response

...
  "id": "pc:901",
  ...
  "jobStatus": {
    "code": "AuditComplete",
    "name": "Completed"
  },
  "jobType": {
    "code": "Audit",
    "name": "Audit"
  },
  ...