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 API credentials

To access audit log with API, you need Harvest v3 OAuth credentials with permission to audit log data. Create new credentials, or manage permissions on existing Harvest v3 credentials.

To configure Harvest v3 credentials, click the Configure icon on your navigation bar, then click Dev Center on the left.

Click API Credential Management.

Click Create new API credentials, or hover over existing Harvest v3 credentials to click the Edit icon.

Make the following selections:

• API type: Choose Harvest v3 (OAuth).
• Partner: Select the name of the integration that requested the credentials. If the integration isn't listed, select unlisted vendor. If you're creating a custom integration, select custom.
• Description: Give the credentials a descriptive name.

Click Save, then click View and store credentials to generate the client key and client secret.

Copy the client key and client secret to a secure location for use in the next step, then click I have stored the client credentials.

Under Manage scopes, check to include Audit log (plus any other permissions your integration needs). If an integration requested these credentials, confirm the exact permissions it requires before assigning them; providing permission to your data is similar to assigning a user access to that data in-app. Learn more at Manage Harvest API key permissions.

Authenticate

Next, use your client key and client secret to make a request to POST https://auth.greenhouse.io/token. Use Basic auth with your client key and client secret, and set grant_type to client_credentials. Use HTTPS for your request or you'll receive an error.

HTTP request

curl -X POST 'https://auth.greenhouse.io/token' \
  -u '{client_id}:{client_secret}' \
  -d 'grant_type=client_credentials'

In the response, you'll receive an access token, its type, and its expiration date. Use the access token as a bearer token to authenticate your requests to audit log API.

{
   "token_type": "Bearer",
   "access_token": "eyJhbGciOiJSUzI1NiJ9...",
   "expires_at": "2026-09-25T16:38:46Z"
}

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:

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