Use audit log with API

Audit log offers a record of important events in your Greenhouse Recruiting environment from the previous 30 days. You can access audit log with Greenhouse API. 

Access audit log

Configure an API key

To access audit log with API, you need a Harvest API key that has permission to audit log data. Create a new Harvest API key, or manage permissions on an existing Harvest API key.

To configure a Harvest API key, click the Configure icon on your navigation bar, then select Dev Center > API Credential Management.

Click Create new API key, or hover over an existing key to click the Edit icon.

Under Manage permissions, check to include Audit log.

Click Save.

Copy your Harvest API key to a secure location for use in the next step.

Authenticate

Next, use your API key to make a request to POST https://harvest.greenhouse.io/auth/jwt_access_token. Use Basic auth with your Harvest API key as the header. Use HTTPS for your request or you'll receive an error. 

HTTP request 

curl -X POST 'https://harvest.greenhouse.io/auth/jwt_access_token'
-H "Content-Type: application/json"
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

In the response, you'll receive an access token, as well as its expiration date. The access token offers temporary access to authenticate your requests to audit log API. 

{
   "access_token": "MeyJhbGci.eyJhdWQiO",
   "expires": 2024-02-03T16:38:46.985Z
}

With your valid access token, you can make an audit log request.

Make an audit log request

Make a request to audit log using the endpoint GET https://auditlog.us.greenhouse.io/events/. Use an authorization header bearing your temporary access token. Use HTTPS for your request or you'll receive an error. 

HTTP request 

curl -X GET 'https://auditlog.us.greenhouse.io/events/'
-H "Content-Type: application/json"
-H "Authorization: Bearer MeyJhbGci.eyJhdWQiO"

You'll receive a payload containing audit log results for the previous 30 days for your organization. 

{
"hits": 2,
"results": [
{
     "request": {
        "id": "1234zID",
        "type": "custom_fields#update"
     },
     "performer": {
        "meta": {
            "name": "Allison Jamie",
            "username": "allison.j@omniva-corp.com"
     },
         "id": 12345,
         "ip_address": "192.168.0.1",
         "type": "user"
     },
     "organization_id": 123,
     "event": {
          "meta": null,
          "target_type": "Custom Option Created",
          "type": "action"
     },
      "event_time": "2023-06-02T16:06:19.217Z"
},
{
      "request": {
          "id": "1234zID",
          "type": "custom_fields#update"
     },
     "performer": {
         "id": "12345",
         "meta": "Not found",
            "name": "Allison Jamie",
            "username": "allison.j@omniva-corp.com"
     },
         "id": 12345,
         "ip_address": "192.168.0.1",
         "type": "user"
     },
      "organization_id": 123,
         "meta": {
           "custom_field_id": 15436,
           "name": "Certification",
           "active": true,
           "id": 28881005002,
           "priority": 5
     },
        "target_type": "CustomFieldOption",
        "target_id": 15436,
        "type": "data_change_create"
     },
        "event_time": "2023-06-02T16:06:19.137Z"
}
]
}

Use pagination with your query if you have many audit log results and need to retrieve the next page.

A single event in Greenhouse Recruiting, like "Single Sign-On Changed," may return multiple audit log results. Link an event and its subsequent changes with the request_ids query parameter to dig further into an event. Linked results will include event details, or before and after values, in the event_meta attributes. Learn more about the payload structure.

Query parameters

You can use and combine optional query parameters to further refine your requests:

Query parameters
paging	Use this parameter for paginating audit log results. When set to true, audit log returns a PIT (point in time) header that can be used to retrieve the next page of audit log results.
before_time	Use this parameter to retrieve audit log results before a certain point in time, represented in ISO-8601 format like 2024-02-03T16:38:46.985Z. This parameter can be combined with after_time for a date range.
after_time	Use this parameter to retrieve audit log results after a certain point in time, represented in ISO-8601 format like 2024-02-03T16:38:46.985Z. This parameter can be combined with before_time for a date range.
date	Use this parameter to retrieve audit log results from a specific date, like 2024-02-03.
magic_time	Use the magic time parameter to retrieve audit log results from a trailing range in time. This parameter takes a value in last{#x} where # is a number and x is seconds, minutes, hours, days, or weeks, like last7days or last15minutes.
performer_ids	Use this parameter to retrieve audit log results matching one or more performer IDs, which are Greenhouse Recruiting user IDs. Separate multiple IDs by a comma.
performer_types	Use this parameter to retrieve audit log results matching one or more performer types: user, api_key, or greenhouse_internal. Separate multiple performer types by a comma.
performer_ip_addresses	Use this parameter to retrieve audit log results matching one or more performer IP addresses. Separate multiple IP addressess by a comma.
event_types	Use this parameter to retrieve audit log results matching one or more event types: data_change_update, data_change_create, data_change_destroy, harvest_access, or action. Separate multiple event types by a comma.
event_target_ids	Use this parameter to retrieve audit log results matching one or more event target IDs, which reflect the element that was created, edited or accessed. Separate multiple event target IDs by a comma.
event_target_types	Use this parameter to retrieve audit log results matching one or more event target types. Check out the audit log glossary for a list of expected events. Separate multiple event target types by a comma.
request_ids	Use this parameter to retrieve audit log results matching one or more request IDs. A single event in audit log may return multiple results. An event and its resulting changes can be linked by request ID. Separate multiple request IDs by a comma.
request_types	Use this parameter to retrieve audit log results matching one or more request types. Separate multiple request types by a comma.

Check out example queries and learn more about what to expect in your audit log data.