Acessing Audit Data

What is the Audit Log?

The Audit Log provides a detailed record of changes made to your payroll data. Every time an entity is created, updated, or deleted, an audit entry captures who made the change, what changed, and when it happened.

Use the Audit Log to:

Compliance — maintain a tamper-proof history of payroll changes for regulatory and internal audits.
Change tracking — see exactly what was modified on a worker, bank account, payroll run, etc.
Debugging — trace unexpected data back to the action that caused it.

Querying Audit Entries

Audit entries are accessed via the auditEntries GraphQL query. Results are paginated and sorted by timestamp (ascending) by default.

query {
  auditEntries(
    page: 0
    size: 100
    filterBy: { ... }
    orderBy: { field: AUDIT_TIMESTAMP, sort: DESCENDING }
  ) {
    totalPages
    nodes {
      id
      auditTimestamp
      entityId
      entityType
      action
      event
      entity
      actor {
        ... on AuditUser {
          displayName
          userEmail
        }
        ... on AuditApiClient {
          displayName
          apiClient
        }
        ... on AuditSystem {
          displayName
        }
      }
      employer {
        id
        legalName
      }
      worker {
        id
      }
      httpRequest {
        traceId
        requestId
        ipAddress
      }
    }
  }
}

You can also query audit entries scoped to a specific entity by using the auditEntries field on any auditable entity (e.g., a Worker or Employer).

Pagination

The auditEntries query uses page-based pagination. Pass page and size to control which page of results you receive.

Parameter	Type	Default	Description
`page`	`Int`	`0`	Zero-based page index.
`size`	`Int`	`500`	Number of entries per page (max 500).

The response includes totalPages so you know how many pages are available.

Paginating through all results

# First page
query {
  auditEntries(page: 0, size: 100) {
    totalPages
    nodes { id auditTimestamp entityType action event }
  }
}

# Next page
query {
  auditEntries(page: 1, size: 100) {
    totalPages
    nodes { id auditTimestamp entityType action event }
  }
}

Keep incrementing page until you reach totalPages - 1.

Filters

Use the filterBy argument to narrow results. The following filters are available:

Filter	Type	Description
`entityType`	`String`	Filter by entity type (e.g., `"WorkerContract"`).
`workerId`	`String`	Filter entries related to a specific worker.
`auditTimestamp`	`BoundedDateTimeIntervalInput`	Filter by date range using `start` and `end`.

Date Range Filter

The auditTimestamp filter accepts a bounded date-time interval:

filterBy: {
  auditTimestamp: {
    start: "2025-01-01T00:00:00Z"
    end: "2025-01-31T23:59:59Z"
  }
}

Both start and end are inclusive.

Sorting

Results are sorted by AUDIT_TIMESTAMP in ascending order by default. You can change the direction:

orderBy: { field: AUDIT_TIMESTAMP, sort: DESCENDING }

Available Fields

Each audit entry contains:

Field	Type	Description
`id`	`ID`	Unique identifier for the audit entry.
`auditTimestamp`	`DateTime`	UTC timestamp of when the change occurred.
`entityId`	`ID`	Identifier of the entity that was changed.
`entityType`	`String`	Type of the entity (e.g., `"WorkerContract"`, `"EmployerBankAccount"`).
`action`	`String`	High-level action category (e.g., `CREATE`, `UPDATE`, `DELETE`).
`event`	`String`	Human-readable description of the change.
`entity`	`String`	JSON representation of the entity's state after the change.
`actor`	`AuditActor`	Who performed the action (see Actor Types).
`employer`	`Employer`	The employer associated with this entry.
`worker`	`Worker`	The worker associated with this entry (if applicable).

Audit Coverage

The following entities and actions are tracked in the Audit Log.

Money Movement

Entity	Actions
Employer bank account	Create, Update, Delete
Worker bank account	Create, Update, Delete
Employer money movement policy	Create, Update
Pay distribution	Create, Update

Profile

Entity	Actions
Employer taxes setup	Create, Update, Delete
Worker taxes setup	Create, Update, Delete, Override
Worker address	Create, Update, Terminate
Worker contract	Create, Update, Delete
Worker work location	Add, Update, Remove
Employer address	Create, Update, Delete
Worker name	Update

Payroll

Entity	Actions
Payroll run	Run, Confirm, Cancel, Delete, Update
Worker payroll run	Create
Payroll run workers list	Include, Exclude
Worker payroll element	Update
Worker pay distribution	Update
Partner payroll settings	Create, Update, Delete

Accounting

Entity	Actions
Partner accounting settings	Create, Update, Delete

Examples

Query changes in a date range

query {
  auditEntries(
    filterBy: {
      auditTimestamp: {
        start: "2025-01-01T00:00:00Z"
        end: "2025-01-31T23:59:59Z"
      }
    }
    orderBy: { field: AUDIT_TIMESTAMP, sort: DESCENDING }
  ) {
    totalPages
    nodes {
      id
      auditTimestamp
      entityType
      action
      event
      actor {
        ... on AuditUser { displayName userEmail }
        ... on AuditApiClient { displayName apiClient }
        ... on AuditSystem { displayName }
      }
    }
  }
}

Query changes for a specific worker

query {
  auditEntries(
    filterBy: {
      workerId: "worker-uuid-here"
    }
    orderBy: { field: AUDIT_TIMESTAMP, sort: DESCENDING }
  ) {
    totalPages
    nodes {
      id
      auditTimestamp
      entityType
      action
      event
      entity
    }
  }
}

Query changes by entity type

query {
  auditEntries(
    filterBy: {
      entityType: "WorkerContract"
      auditTimestamp: {
        start: "2025-06-01T00:00:00Z"
        end: "2025-06-30T23:59:59Z"
      }
    }
    orderBy: { field: AUDIT_TIMESTAMP, sort: DESCENDING }
  ) {
    totalPages
    nodes {
      id
      auditTimestamp
      action
      event
      entity
      worker { id }
      employer { id legalName }
    }
  }
}

Query with actor details and pagination

query {
  auditEntries(
    page: 0
    size: 50
    filterBy: {
      auditTimestamp: {
        start: "2025-03-01T00:00:00Z"
        end: "2025-03-31T23:59:59Z"
      }
    }
    orderBy: { field: AUDIT_TIMESTAMP, sort: DESCENDING }
  ) {
    totalPages
    nodes {
      id
      auditTimestamp
      entityType
      action
      event
      actor {
        ... on AuditUser {
          displayName
          userEmail
        }
        ... on AuditApiClient {
          displayName
          apiClient
        }
        ... on AuditSystem {
          displayName
        }
      }
      httpRequest {
        traceId
        requestId
        ipAddress
      }
    }
  }
}

Understanding Changes

The entity field contains a JSON snapshot of the entity after the change was applied. The Audit Log captures the current state at the time of the action — it does not store a diff or the previous state.

To understand what changed, compare the entity snapshots of consecutive audit entries for the same entityId.

The event field provides a human-readable summary of the change, which is useful for displaying in a UI without parsing the JSON.