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

Attribute	Definition
access_token	A JWT (JSON web token) that’s valid for 24 hours from the time of creation.
expires	The exact time the access token will expire in `ISO-8601` format, like `2024-02-03T16:38:46.985Z`.

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

Note: Use HTTPS for all requests. Requests made over HTTP will return an HTTP 401 response.

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.

Note: An HTTP 429 response will exclude the X-RateLimit-Limit and X-RateLimit-Remaining headers.

Pagination

Pagination on audit log API allows for retrieving the next page from your query results. Use the paging query parameter to receive a pit_id with your results. To retrieve the next page of results, the pit_id should be the value of your pit_id header, and the next_search_after should be the value of your search_after header. Your query parameters should remain consistent with your original query. Audit log results with only one page will return null results on the next page.

pit_id. The ID from a specific point in time (PIT) in a fixed time dataset, created automatically when you run a query.
search_after. Use this parameter to retrieve audit log after a specific page in the search results when running a query with the pit_id.
size. The size of the requested query. This parameter has a minimum value of 100 and a maximum value of 500.

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

Error Code	Meaning
401	Unauthorized – Your access token is invalid or has expired. Access tokens expire 24 hours after generation. Ensure you’re sharing a valid access token in the authorization header.
403	Forbidden – You do not have access to that record.
404	Not Found – Resource not found
422	Not processed – We’re not able to process your request. Validate your parameters.
429	Rate limit exceeded – You’re being throttled for exceeding our rate limit.
500	Server Error – We’re having a problem with our server. Give us a few minutes and try again, or check our status page.

Audit Log Change Log

Date	Description
Dec 12, 2023	Fix bug with missing GET events in nav menu
Nov 7, 2023	Removed On-Behalf-Of header from the events object sample payload
Nov 6, 2023	Updated Throttling section to Rate limiting and updated approach to rate limiting.
Oct 26, 2023	Updated Pagination to reflect new approach to returning `pit_ids`.
July 14, 2023	We added new query parameters to the Events endpoint, including `performer_ids`, `performer_types`, `performer_ip_addresses`, `event_types`, `event_target_ids`, `event_target_types`, `request_ids`, and `request_types`.

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

Attribute	Definition
organization_id	Your organization’s unique Greenhouse Recruiting ID
event_time	The exact time of the event, represented in `ISO-8601` format like `2024-02-03T16:38:46.985Z`
request.id	The ID of the request
request.type	The name of the action taken in Greenhouse Recruiting, or the request URL if from Harvest API
performer.id	The Greenhouse Recruiting user ID of the person who performed the change or the API key if performed via Greenhouse API
performer.type	One of the following values: `user`, `api_key`, or `greenhouse_internal`
performer.meta	The Greenhouse Recruiting email address of the person who performed the change or the exact type of API key that performed the change
performer.ip_address	The IP address of the person or integration that performed the change
event.type	One of the following values: `data_change_update`, `data_change_create`, `data_change_destroy`, `harvest_access`, or `action`
event.target_id	The ID of the element that was edited or accessed; this may be blank if the action does not target one particular ID
event.target_type	The resource name for data changes, Harvest access, or the event action type for other actions
event.meta	The before and after values from data change events, or other relevant data for the event such as the title of a report

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

Parameter	Definition
before_time (optional)	Use this parameter to retrieve audit log 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 (optional)	Use this parameter to retrieve audit log 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 (optional)	Use this parameter to retrieve audit log from a specific date, represented in `ISO-8601` format like `2024-02-03`.
magic_time (optional)	Use this 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 (optional)	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 (optional)	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 (optional)	Use this parameter to retrieve audit log results matching one or more performer IP addresses. Separate multiple IP addresses by a comma.
event_types (optional)	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 (optional)	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 (optional)	Use this parameter to retrieve audit log results matching one or more event target types. Separate multiple event target types by a comma.
request_ids (optional)	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 will return individual results that can be linked by request ID. Separate multiple request IDs by a comma.
request_types (optional)	Use this parameter to retrieve audit log results matching one or more request types. Separate multiple request types by a comma.
paging (optional)	Use this parameter for pagination. When set to `true`, we return a `pit_id` that can be used to paginate query results.