Introduction

Audit log offers a record of important events from the prior thirty days, providing insights to who accessed or edited information in Greenhouse Recruiting.

Use audit log to empower your teams to detect and minimize the impact of incidents when they occur, scrutinize configuration edits, and ensure sensitive data is only accessed by the people who truly need it. Learn more about what to expect with audit log.

Authentication

Audit log uses bearer authorization over HTTPS with a valid access token. You’ll need a Harvest API key to generate an access token, returned through the Harvest endpoint POST: Authenticate audit log. Use the access token as your bearer to authenticate audit log API requests.

The authenticate audit log object

The authenticate audit log object returns an access token that is valid for 24 hours, which can be used to authenticate your requests to the events object.

Attributes

POST: Authenticate audit log

HTTP request

curl -X POST 'https://harvest.greenhouse.io/auth/jwt_access_token'
-H "Content-Type: application/json"
-H "On-Behalf-Of: {greenhouse user ID}"
-H "Authorization: Basic MGQwMzFmE2MWwNjdlMjQ6"

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

HTTP request

POST https://harvest.greenhouse.io/auth/jwt_access_token

Rate limiting

Status: 200 OK
X-RateLimit-Limit: 50
X-RateLimit-Remaining: 49

Audit log API requests are limited to 50 per 10 seconds, as specified in the returned X-RateLimit-Limit header. Paginated requests are limited to 3 per 30 seconds. Check the X-RateLimit-Limit and X-RateLimit-Remaining headers to see how many more requests are permitted until throttling kicks in. Exceeding the limit will return an HTTP 429 response.

Pagination

Pagination on audit log API allows for retrieving the next page from your query results.

1. In the initial request:
   • Set the paging query parameter to true to receive a paging object with pit_id and next_search_after in the response
   • Use the Size header to specify the number of results you want to receive per page. The minimum value is 100, and the maximum value is 500
2. In subsequent requests:
   • Ensure that the query parameters remain consistent with the initial request
   • Set the Pit-Id header to the paging.pit_id value from the initial request
   • Set the Search-After header to the paging.next_search_after value from each response progressively
3. The last page of results will return null for the paging.next_search_after attribute, and an empty list of results

Audit log API requests are rate limited. Paginated requests are limited to 3 per 30 seconds, and overall requests are limited to 50 per 10 seconds. Exceeding the limit will result in throttling.

Validation

Any methods that take input will validate all parameters. Any parameter that fails validation will trigger an error response with status HTTP 422. The response body will be a JSON object that includes a message as well as a list of fields that failed validation.

General considerations

Unless otherwise specified, audit log API methods generally conform to the following standards:

• Properties without a value will use null instead of being undefined.
• “Snake case” is used for attributes and headers, like first_name.
• Timestamps are rendered in ISO-8601 format, like 2024-02-03T16:38:46.985Z.
• URLs to external resources are valid for thirty days.
• Resumes, cover letters, and other document attachments are hosted on Amazon Web Services and are provided via signed, temporary URLs. Due to the temporary nature of these resources, you should download the documents immediately after your request is made. You shouldn’t rely on these URLs to be available in future requests. In the event AWS is experiencing issues, document attachments won’t be available in audit log.

Errors

Audit Log Change Log

Events

The events object

The events object is the audit log’s collected record of important events in Greenhouse Recruiting from the previous thirty days. A single event may return multiple results. For instance, an event and its resulting changes will return individual results that can be linked by request.id.

Attributes

GET: Retrieve events

HTTP request

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

{
    "paging": {
        "pit_id": "cmFuZG9tX3ZhbHVl",
        "search_after": null,
        "size": "100",
        "next_search_after": "1685989175"
    },
    "hits": 2,
    "results": [
        {
            "request": {
                "id": "1234zID",
                "type": "email_settings#create_organization_email"
            },
            "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": "Global Email Added",
                "type": "action"
            },
            "event_time": "2023-06-02T16:06:19.217Z"
        },
        {
            "request": {
                "id": "1234zID",
                "type": "email_settings#create_organization_email"
            },
            "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": {
                    "id": [
                        null,
                        1234
                    ],
                    "value": [
                        null,
                        "johnny.c@omniva-corp.com"
                    ]
                },
                "target_type": "OrganizationEmail",
                "target_id": 1234,
                "type": "data_change_create"
            },
            "event_time": "2023-06-02T16:06:19.137Z"
        }
    ]
}

HTTP request

GET https://auditlog.us.greenhouse.io/events/

URL Parameters