API docs by Redocly

Affinity Client Web API (4.0)

Download OpenAPI specification:

Welcome

Thank you for choosing the Affinity Client Web API. We've designed it to efficiently handle large-volume data exchange between external systems and the Affinity system.

About the API

Our API allows you to integrate with the Affinity system with the purpose of retrieving, creating or updating Affinity records. These records can be masterfiles, such as employees, departments and positions, or transactions such as timesheets and leave.

Key features

  • Resource-oriented design. Utilises predictable, RESTful endpoint URLs with standard operations (GET, PUT, DELETE).
  • JSON format. All requests and responses are in JSON, with clear schema definitions and sample payloads provided.
  • Bearer token authentication. Secured via HTTPS using bearer tokens passed in the Authorization header.
  • Error-handling. Standard HTTP response codes are used, with detailed error messages provided in the response body.
  • Flexible create/update. PUT can be used to create or update objects in most cases.

Options

  • Asynchronous processing. The API supports both synchronous and asynchronous operations, with endpoints available to poll for the status of asynchronous requests. This is achieved through the wait_for_completion request parameter. If you choose to wait for completion, the API response will only occur after the create/update operation is complete.
  • Validation options. The API allows for validation-only requests to check data integrity before actual submission.
  • Bulk operations. The API facilitates bulk create/update operations with an option to continue processing subsequent records even if some fail validation.

Documentation

This documentation will help you to get the most out of the API both technically, and in terms of best practice around inbound data. Key features:

  • Straightforward navigation using the side menu.
  • Uses the OpenAPI Specification.
  • Resource and operations map for quick reference.
  • Descriptions of all available resources, operations, and request parameters.
  • Data field descriptions, plus sample values and if they are required.
  • Extra information to help you understand the API in a broader Affinity context.
  • Descriptive errors and responses.

We update this documentation whenever new versions of the API are released (and older versions are deprecated) and new resources are available. We also make improvements for clarity and context on a regular basis.

Versions

Release history

The current API version (v4) was released in May 2024. This release introduced new standard objects.

Updates

From time to time, we may add new properties to responses. Your application must be able to cope with extra properties by ignoring them.

Getting started

The API endpoint

All requests must be made using HTTPS against this URL: https://api.testaffinitylogon.com/.

Authentication

Our API uses bearer authentication over HTTPS. We provide you with a bearer token which you then use to verify that you are an authorised user. You do this by passing the bearer token in the HTTP header with every request. A request includes the basic authentication header with the Authorization field followed by the word 'Bearer' (indicating the type of authentication), followed by the encoded user credentials:

Authorization: Bearer token-goes-here

When authentication fails, error code 401 (Unauthorised) is returned, and the body includes this message:

Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription.

Content-Type

The API currently only supports JSON-encoded data in requests and responses. You should provide either the Content-Type and Accept headers with the value application/json (or both) to identify both the request and response formats. For example:

Content-Type: application/json

Available resources and operations

In the context of the Affinity Client Web API, a typical PUT operation is used to update a specific resource such as an employee record, a timesheet, or tax declaration by replacing the current state of that resource with a new one provided in the request body. PUT can also be used to create records in most cases.

Resource categories

  • Employees. Manage biographical and payroll details, leave balances, organisational assignments, superannuation, tax declarations, and significant dates.
  • Timesheets. Create, update, retrieve, and delete timesheet records for individual or multiple employees.
  • Pay points. Access and manage pay groups and their associated accounting dates.
  • Payroll costs. Retrieve payroll costing information by timesheet, employee, or pay point.

Map of resources and operations

Click the links to jump straight to the docs.

Employees (Multiple)

Employees (Single)

Pay Points

Payroll Costs

Timesheets

Extras

Request data types

GUID fields

We use RFC 4122 GUIDs, represented as a string with the structure xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx where each x is a hexidecimal character. GUIDs are not case sensitive.

Dates and date-times

We use ISO8601 dates/times. Dates must be formatted as YYYY-MM-DD. Times must be formatted as HH:MM. Dates/times are assumed to be in local time and must be formatted as YYYY-MM-DDTHH:MM:SS."

Data quality and frequency

Blanks, duplicated data, and whole masterfile records

Sending blanks and data that has already been sent will slow things down, so please avoid this. The Affinity system only requires a single record containing the identifier, the field that changed, and optionally the effective date of that change — not the entire record.

Bulk updates

Sending multiple updates in a single request is more efficient than sending separate individual requests. Where possible, please batch updates into one request.

Frequency of sends

To optimise processing, consider the nature of the data and align sends with your application and payroll needs. We reserve the right to limit connections in line with our fair use policy.

Effective date

For effective-date-enabled data, each transaction can contain an effective date. If no effective date is supplied, the Affinity system will assume the effective date is today's date.

Fair use policy

We are committed to providing fair and consistent access to our API for all clients — regardless of size, scale, or complexity. To maintain system stability and performance, we apply rate limits to certain types of API transactions.

Transaction limits and reasonable use

Our fair use policy is grounded in the principle of reasonable use. The transaction limits below are designed to support typical daily operational needs. If your integration requires higher volumes, please contact us to discuss a tailored arrangement. These safeguards help:

  • Maintain consistent platform performance.
  • Prevent accidental overuse or system abuse.
  • Ensure equitable access for all clients.

Unless otherwise agreed, the following limits apply:

  • Timesheets: Up to 5,000 transactions per hour.
  • Masterfiles and lookups: Up to 2,000 transactions per hour.

These limits may be enforced at the API level. Requests exceeding the defined thresholds if rejected must be retried later.

Monitoring and notifications

We actively monitor usage to ensure compliance with this policy. If your system consistently attempts to exceed the defined limits, we will notify your technical contact and provide guidance on how to adjust your integration.

Periodic review and updates

We review our fair use policy regularly to ensure it continues to meet the needs of our clients and aligns to industry standards. As such, we may update this policy from time to time.

API requests

Get the details of any specific API request.

Our API is designed to be either synchronous or asyncronous. If you start an asyncronous request, you can use this to poll for the details and to find out the results.

Authorizations:
Bearer
path Parameters
apiRequestId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "path": "string",
  • "started_at_utc": "string",
  • "completed_at_utc": "string",
  • "total_records": 0,
  • "records_imported_successfully": 0,
  • "records_that_failed_to_import": 0,
  • "import_results": [
    ]
}

Audit logs

Get the audit logs for a particular employee.

Get all the audit logs for a particular employee, since a particular timestamp.

Authorizations:
Bearer
path Parameters
idType
required
string
Enum: "Guid" "Number"
employeeId
required
string
sinceTimestamp
required
string <date-time>

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Multiple employees

Retrieve combined information for multiple employees.

Returns a range of personal and payroll information about one or more employees. You can opt to include or exclude terminated employees and refine using several parameters including pay point.

Authorizations:
Bearer
query Parameters
idType
string
Enum: "Guid" "Number"
employeeIds
Array of strings
payPoints
Array of integers <int32> [ items <int32 > ]
effectiveDate
string <date>

The effective date of the data. 'Effective date' is the date when a value comes into effect in a record. For example, a pay rate increase. If no effective date is supplied then the data in the record as at the current period-end date will be returned.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create or update combined information for multiple employees.

Updates existing personal and payroll details for one or more employees or creates new entries.

Authorizations:
Bearer
Request Body schema: application/json
required
Array of objects (EmployeeCombinedIn)
wait_for_completion
boolean or null
Default: true

Determines whether to wait for the request to completely import. If set to true (the default if not specified), the request will wait for the entire import to complete before returning a response. If set to false, the request will immediately return a 204 response and the import will continue in the background. The status of the import can be monitored using the ApiRequest endpoint.

validate_only
boolean or null
Default: false

Determines whether to only validate the request without importing any data. If set to true, the request will validate the data and return any validation errors without importing any data. If set to false (the default if not specified), the request will both validate the data, and import it if validation succeeded.

continue_on_validation_failure
boolean or null
Default: false

Determines whether to continue processing subsequent records if validation fails. If set to false (the default if not specified), the first validation failure will cause the entire request to fail and no records will be imported. If set to true, any records that fail validation will be skipped and the remaining records will be imported.

Responses

Request samples

Content type
application/json
{
  • "data": [
    ],
  • "wait_for_completion": true,
  • "validate_only": false,
  • "continue_on_validation_failure": false
}

Response samples

Content type
application/json
{
  • "api_request_id": "string",
  • "data": [
    ]
}

Retrieve biographical information for multiple employees.

Returns a range of personal information about one or more employees, including names and contact information, and start and termination dates. You can opt to include or exclude terminated employees and refine using several parameters including pay point.

Authorizations:
Bearer
query Parameters
idType
string
Enum: "Guid" "Number"
employeeIds
Array of strings
payPoints
Array of integers <int32> [ items <int32 > ]
includeTerminatedFrom
string <date>

Include terminated employees from this date onwards

effectiveDate
string <date>

The effective date of the data. 'Effective date' is the date when a value comes into effect in a record. For example, a pay rate increase. If no effective date is supplied then the data in the record as at the current period-end date will be returned.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create or update biographical information for multiple employees.

Updates personal details for one or more employees (including names and contact details) or creates new entries.

Authorizations:
Bearer
Request Body schema: application/json
required
Array of objects (EmployeeBiographicalIn)
wait_for_completion
boolean or null
Default: true

Determines whether to wait for the request to completely import. If set to true (the default if not specified), the request will wait for the entire import to complete before returning a response. If set to false, the request will immediately return a 204 response and the import will continue in the background. The status of the import can be monitored using the ApiRequest endpoint.

validate_only
boolean or null
Default: false

Determines whether to only validate the request without importing any data. If set to true, the request will validate the data and return any validation errors without importing any data. If set to false (the default if not specified), the request will both validate the data, and import it if validation succeeded.

continue_on_validation_failure
boolean or null
Default: false

Determines whether to continue processing subsequent records if validation fails. If set to false (the default if not specified), the first validation failure will cause the entire request to fail and no records will be imported. If set to true, any records that fail validation will be skipped and the remaining records will be imported.

Responses

Request samples

Content type
application/json
{
  • "data": [
    ],
  • "wait_for_completion": true,
  • "validate_only": false,
  • "continue_on_validation_failure": false
}

Response samples

Content type
application/json
{
  • "api_request_id": "string",
  • "data": [
    ]
}

Retrieve bank account details for multiple employees.

Returns the details of employee balance accounts (their primary bank accounts) and up to five additional accounts (per employee) as an array.

Authorizations:
Bearer
query Parameters
idType
string
Enum: "Guid" "Number"
employeeIds
Array of strings
payPoints
Array of integers <int32> [ items <int32 > ]
effectiveDate
string <date>

The effective date of the data. 'Effective date' is the date when a value comes into effect in a record. For example, a pay rate increase. If no effective date is supplied then the data in the record as at the current period-end date will be returned.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create or update bank details for multiple employees.

Updates employee balance bank accounts details (their primary bank accounts) and up to five additional accounts (per employee), or creates new entries.

Authorizations:
Bearer
Request Body schema: application/json
required
Array of objects (EmployeeBankAccountsIn)
wait_for_completion
boolean or null
Default: true

Determines whether to wait for the request to completely import. If set to true (the default if not specified), the request will wait for the entire import to complete before returning a response. If set to false, the request will immediately return a 204 response and the import will continue in the background. The status of the import can be monitored using the ApiRequest endpoint.

validate_only
boolean or null
Default: false

Determines whether to only validate the request without importing any data. If set to true, the request will validate the data and return any validation errors without importing any data. If set to false (the default if not specified), the request will both validate the data, and import it if validation succeeded.

continue_on_validation_failure
boolean or null
Default: false

Determines whether to continue processing subsequent records if validation fails. If set to false (the default if not specified), the first validation failure will cause the entire request to fail and no records will be imported. If set to true, any records that fail validation will be skipped and the remaining records will be imported.

Responses

Request samples

Content type
application/json
{
  • "data": [
    ],
  • "wait_for_completion": true,
  • "validate_only": false,
  • "continue_on_validation_failure": false
}

Response samples

Content type
application/json
{
  • "api_request_id": "string",
  • "data": [
    ]
}

Retrieve emergency contact details for multiple employees.

Returns the details of employee emergency contacts.

Authorizations:
Bearer
query Parameters
idType
string
Enum: "Guid" "Number"
employeeIds
Array of strings
payPoints
Array of integers <int32> [ items <int32 > ]
effectiveDate
string <date>

The effective date of the data. 'Effective date' is the date when a value comes into effect in a record. For example, a pay rate increase. If no effective date is supplied then the data in the record as at the current period-end date will be returned.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create or update emergency contact details for multiple employees.

Updates employee emergency contact details or creates new entries.

Authorizations:
Bearer
Request Body schema: application/json
required
Array of objects (EmployeeEmergencyContactIn)
wait_for_completion
boolean or null
Default: true

Determines whether to wait for the request to completely import. If set to true (the default if not specified), the request will wait for the entire import to complete before returning a response. If set to false, the request will immediately return a 204 response and the import will continue in the background. The status of the import can be monitored using the ApiRequest endpoint.

validate_only
boolean or null
Default: false

Determines whether to only validate the request without importing any data. If set to true, the request will validate the data and return any validation errors without importing any data. If set to false (the default if not specified), the request will both validate the data, and import it if validation succeeded.

continue_on_validation_failure
boolean or null
Default: false

Determines whether to continue processing subsequent records if validation fails. If set to false (the default if not specified), the first validation failure will cause the entire request to fail and no records will be imported. If set to true, any records that fail validation will be skipped and the remaining records will be imported.

Responses

Request samples

Content type
application/json
{
  • "data": [
    ],
  • "wait_for_completion": true,
  • "validate_only": false,
  • "continue_on_validation_failure": false
}

Response samples

Content type
application/json
{
  • "api_request_id": "string",
  • "data": [
    ]
}

Retrieve leave balances for one or more employees.

Returns a range of leave accrual and entitlement balances for all standard leave types that hold a balance (annual leave, sick leave, long service leave) along with customised leave (Leave C, D and E in Affinity).

Authorizations:
Bearer
query Parameters
idType
string
Enum: "Guid" "Number"
employeeIds
Array of strings
payPoints
Array of integers <int32> [ items <int32 > ]
effectiveDate
string <date>

The effective date of the data. 'Effective date' is the date when a value comes into effect in a record. For example, a pay rate increase. If no effective date is supplied then the data in the record as at the current period-end date will be returned.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update leave balances for one or more employees.

Updates a range of leave accrual and entitlement balances for all standard leave types that hold a balance (annual leave, sick leave, long service leave) along with customised leave (Leave C, D and E in Affinity).

Authorizations:
Bearer
Request Body schema: application/json
required
Array of objects (EmployeeLeaveBalancesIn)
wait_for_completion
boolean or null
Default: true

Determines whether to wait for the request to completely import. If set to true (the default if not specified), the request will wait for the entire import to complete before returning a response. If set to false, the request will immediately return a 204 response and the import will continue in the background. The status of the import can be monitored using the ApiRequest endpoint.

validate_only
boolean or null
Default: false

Determines whether to only validate the request without importing any data. If set to true, the request will validate the data and return any validation errors without importing any data. If set to false (the default if not specified), the request will both validate the data, and import it if validation succeeded.

continue_on_validation_failure
boolean or null
Default: false

Determines whether to continue processing subsequent records if validation fails. If set to false (the default if not specified), the first validation failure will cause the entire request to fail and no records will be imported. If set to true, any records that fail validation will be skipped and the remaining records will be imported.

Responses

Request samples

Content type
application/json
{
  • "data": [
    ],
  • "wait_for_completion": true,
  • "validate_only": false,
  • "continue_on_validation_failure": false
}

Response samples

Content type
application/json
{
  • "api_request_id": "string",
  • "data": [
    ]
}

Retrieve organisational details for multiple employees.

Returns a range of organisational details for one or more employees.

Authorizations:
Bearer
query Parameters
idType
string
Enum: "Guid" "Number"
employeeIds
Array of strings
payPoints
Array of integers <int32> [ items <int32 > ]
effectiveDate
string <date>

The effective date of the data. 'Effective date' is the date when a value comes into effect in a record. For example, a pay rate increase. If no effective date is supplied then the data in the record as at the current period-end date will be returned.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create or update organisational details for multiple employees.

Updates existing organisational details for one or more employees or creates new entries.

Authorizations:
Bearer
Request Body schema: application/json
required
Array of objects (EmployeeOrganisationalIn)
wait_for_completion
boolean or null
Default: true

Determines whether to wait for the request to completely import. If set to true (the default if not specified), the request will wait for the entire import to complete before returning a response. If set to false, the request will immediately return a 204 response and the import will continue in the background. The status of the import can be monitored using the ApiRequest endpoint.

validate_only
boolean or null
Default: false

Determines whether to only validate the request without importing any data. If set to true, the request will validate the data and return any validation errors without importing any data. If set to false (the default if not specified), the request will both validate the data, and import it if validation succeeded.

continue_on_validation_failure
boolean or null
Default: false

Determines whether to continue processing subsequent records if validation fails. If set to false (the default if not specified), the first validation failure will cause the entire request to fail and no records will be imported. If set to true, any records that fail validation will be skipped and the remaining records will be imported.

Responses

Request samples

Content type
application/json
{
  • "data": [
    ],
  • "wait_for_completion": true,
  • "validate_only": false,
  • "continue_on_validation_failure": false
}

Response samples

Content type
application/json
{
  • "api_request_id": "string",
  • "data": [
    ]
}

Retrieve pay components for multiple employees.

Returns a range of pay components for one or more employees. employee_guid, pay_element and date_effective field values must be unique in order to retrieve multiple pay components per employee.

Authorizations:
Bearer
query Parameters
idType
string
Enum: "Guid" "Number"
employeeIds
Array of strings
payPoints
Array of integers <int32> [ items <int32 > ]
effectiveDate
string <date>

The effective date of the data. 'Effective date' is the date when a value comes into effect in a record. For example, a pay rate increase. If no effective date is supplied then the data in the record as at the current period-end date will be returned.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create or update pay components for multiple employees.

Updates existing pay components for one or more employees or creates new entries. employee_guid, pay_element and date_effective field values must be unique in order to create or update multiple pay components per employee.

Authorizations:
Bearer
Request Body schema: application/json
required
Array of objects (EmployeePayComponentIn)
wait_for_completion
boolean or null
Default: true

Determines whether to wait for the request to completely import. If set to true (the default if not specified), the request will wait for the entire import to complete before returning a response. If set to false, the request will immediately return a 204 response and the import will continue in the background. The status of the import can be monitored using the ApiRequest endpoint.

validate_only
boolean or null
Default: false

Determines whether to only validate the request without importing any data. If set to true, the request will validate the data and return any validation errors without importing any data. If set to false (the default if not specified), the request will both validate the data, and import it if validation succeeded.

continue_on_validation_failure
boolean or null
Default: false

Determines whether to continue processing subsequent records if validation fails. If set to false (the default if not specified), the first validation failure will cause the entire request to fail and no records will be imported. If set to true, any records that fail validation will be skipped and the remaining records will be imported.

Responses

Request samples

Content type
application/json
{
  • "data": [
    ],
  • "wait_for_completion": true,
  • "validate_only": false,
  • "continue_on_validation_failure": false
}

Response samples

Content type
application/json
{
  • "api_request_id": "string",
  • "data": [
    ]
}

Retrieve pay details for multiple employees.

Returns a range of pay details for one or more employees.

Authorizations:
Bearer
query Parameters
idType
string
Enum: "Guid" "Number"
employeeIds
Array of strings
payPoints
Array of integers <int32> [ items <int32 > ]
effectiveDate
string <date>

The effective date of the data. 'Effective date' is the date when a value comes into effect in a record. For example, a pay rate increase. If no effective date is supplied then the data in the record as at the current period-end date will be returned.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create or update pay details for multiple employees.

Updates existing pay details for one or more employees or creates new entries.

Authorizations:
Bearer
Request Body schema: application/json
required
Array of objects (EmployeePayDetailIn)
wait_for_completion
boolean or null
Default: true

Determines whether to wait for the request to completely import. If set to true (the default if not specified), the request will wait for the entire import to complete before returning a response. If set to false, the request will immediately return a 204 response and the import will continue in the background. The status of the import can be monitored using the ApiRequest endpoint.

validate_only
boolean or null
Default: false

Determines whether to only validate the request without importing any data. If set to true, the request will validate the data and return any validation errors without importing any data. If set to false (the default if not specified), the request will both validate the data, and import it if validation succeeded.

continue_on_validation_failure
boolean or null
Default: false

Determines whether to continue processing subsequent records if validation fails. If set to false (the default if not specified), the first validation failure will cause the entire request to fail and no records will be imported. If set to true, any records that fail validation will be skipped and the remaining records will be imported.

Responses

Request samples

Content type
application/json
{
  • "data": [
    ],
  • "wait_for_completion": true,
  • "validate_only": false,
  • "continue_on_validation_failure": false
}

Response samples

Content type
application/json
{
  • "api_request_id": "string",
  • "data": [
    ]
}

Retrieve superannuation details for multiple employees.

Returns a range of superannuation information for one or more employees.

Authorizations:
Bearer
query Parameters
idType
string
Enum: "Guid" "Number"
employeeIds
Array of strings
payPoints
Array of integers <int32> [ items <int32 > ]
effectiveDate
string <date>

The effective date of the data. 'Effective date' is the date when a value comes into effect in a record. For example, a pay rate increase. If no effective date is supplied then the data in the record as at the current period-end date will be returned.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create or update superannuation details for multiple employees.

Updates existing superannuation details for one or more employees or creates new entries. Optionally creates a SUPRxx (employer Super contribution) deduction code as part of the operation.

ABNs/USIs

  • Creating a new self-managed fund. If no matching ABN is found in the Super fund masterfile when supplied for an SMSF, a Super fund masterfile will be created using a system-generated fund identifier (FUND_ID) in the format SMSnnn, and the record saved to the SUPERMF table with that FUND_ID.
  • Creating a new standard fund. If no matching ABN and USI is found in the Super fund masterfile when supplied for a standard fund, a Super fund masterfile will be created using a system-generated fund identifier (FUND_ID) in the format SMnnnn, and the record saved to the SUPERMF table with that FUND_ID.
  • Updating an existing fund. If a standard Super fund masterfile with a matching ABN and USI exists (or an SMSF with a matching ABN exists), updates to fund name and other details like phone, contact name and address will be applied.

SUPERDEFAULTCODES

If the SUPERDEFAULTCODES code group is enabled in your Affinity system, the default Super pay elements contained in that code group (usually SUPR01, SUPE01, ZUPE01) will automatically link to new and updated Super fund masterfiles, and appear in a list in the fund masterfile screen. This link makes things easier for payroll teams because whenever they assign a Super fund masterfile to an employee masterfile, the default pay elements linked to that fund will be available in the employee masterfile when creating the relevant Super deductions. Note that only the SUPR employer contribution is automatically added to the employee masterfile. Any additional Super-related pay elements must be added manually to employee masterfiles in Affinity.

createEmpad

When createEmpad = true, the employer Super deduction (SUPRxx) record is automatically created in the employee masterfile. For SUPRxx pay elements, this only works if just one default SUPRxx pay element (such as SUPR01) is assigned to all employees. For example, if there are multiple employer Super deduction codes that could apply to a Super fund masterfile, then a manual entry in the employee masterfile is required. The API uses the following fields to create or deactivate an employee's SUPRxx deduction record in the employee masterfile:

"employee_guid": "string",
"status": "Active",
"amount": 0,
"amount_type": "Percentage",
"super_type": "Employer contribution"
"fund_name": "string",
"member_number": "string",
"date_effective": "2025-07-11"

Significant dates

When an employee's Super details change, a significant dates record is automatically created. This is visible in the employee masterfile (Contacts/Dates tab).

Authorizations:
Bearer
query Parameters
create_empad
boolean
Default: false

True = Automatically creates a corresponding SUPRxx (employer Super contribution) deduction record in the employee masterfile. Relevant if only one default SUPRxx pay element is assigned to all employees. False = Does not create a corresponding SUPRxx (employer Super contribution) deduction record in the employee masterfile.

Request Body schema: application/json

A list of employee superannuation details to be created or updated in the system.

required
Array of objects (EmployeeSuperannuationIn)
wait_for_completion
boolean or null
Default: true

Determines whether to wait for the request to completely import. If set to true (the default if not specified), the request will wait for the entire import to complete before returning a response. If set to false, the request will immediately return a 204 response and the import will continue in the background. The status of the import can be monitored using the ApiRequest endpoint.

validate_only
boolean or null
Default: false

Determines whether to only validate the request without importing any data. If set to true, the request will validate the data and return any validation errors without importing any data. If set to false (the default if not specified), the request will both validate the data, and import it if validation succeeded.

continue_on_validation_failure
boolean or null
Default: false

Determines whether to continue processing subsequent records if validation fails. If set to false (the default if not specified), the first validation failure will cause the entire request to fail and no records will be imported. If set to true, any records that fail validation will be skipped and the remaining records will be imported.

Responses

Request samples

Content type
application/json
{
  • "data": [
    ],
  • "wait_for_completion": true,
  • "validate_only": false,
  • "continue_on_validation_failure": false
}

Response samples

Content type
application/json
{
  • "api_request_id": "string",
  • "data": [
    ]
}

Retrieve all tax declaration records for multiple employees.

Retrieves all existing tax declaration records for one or more employees based on three optional parameters (idType, employeeIds, payPoints). Note that idType can be either employee_guid or employee_no. Use payPoints to retrieve records for employees associated with a specific pay point. Also note that in the Affinity system, the declaration date is the effective date.

Authorizations:
Bearer
query Parameters
idType
string
Enum: "Guid" "Number"
employeeIds
Array of strings
payPoints
Array of integers <int32> [ items <int32 > ]

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create or update multiple tax declaration records for multiple employees.

Updates one or more tax declaration records for one or more employees based on tax_declaration_id or creates new records. Note that in the Affinity system, the declaration date is the effective date.

Authorizations:
Bearer
Request Body schema: application/json
required
Array of objects (EmployeeTaxDeclarationIn)
wait_for_completion
boolean or null
Default: true

Determines whether to wait for the request to completely import. If set to true (the default if not specified), the request will wait for the entire import to complete before returning a response. If set to false, the request will immediately return a 204 response and the import will continue in the background. The status of the import can be monitored using the ApiRequest endpoint.

validate_only
boolean or null
Default: false

Determines whether to only validate the request without importing any data. If set to true, the request will validate the data and return any validation errors without importing any data. If set to false (the default if not specified), the request will both validate the data, and import it if validation succeeded.

continue_on_validation_failure
boolean or null
Default: false

Determines whether to continue processing subsequent records if validation fails. If set to false (the default if not specified), the first validation failure will cause the entire request to fail and no records will be imported. If set to true, any records that fail validation will be skipped and the remaining records will be imported.

Responses

Request samples

Content type
application/json
{
  • "data": [
    ],
  • "wait_for_completion": true,
  • "validate_only": false,
  • "continue_on_validation_failure": false
}

Response samples

Content type
application/json
{
  • "api_request_id": "string",
  • "data": [
    ]
}

Pay points

Return all pay points (pay groups).

Returns an array of all pay points. Each entry in the array is a separate pay point object. If there are no more pay points, the resulting array will be empty.

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve accounting dates for a specified pay point.

Returns an array of accounting dates for a specified pay point. The array is from six months ago to 18 months ahead. Here is some context around accounting dates. Automatic resets of YTD and MTD totals are critical to payroll reporting. Some organisations use calendar months for month-end financial reporting and others use specific dates. For instance, while March officially ends on the 31st, a company might choose 28th March as its accounting month-end, coinciding with the last Sunday of the month, and apply similar criteria to other months. The Affinity system requires that each reporting period is a standard length. This enables the system to identify an organisation’s forthcoming month-end date in order to initiate the appropriate resets during the first payroll cycle after the designated month-end date, thus allowing for consistent month-over-month comparisons. For example, a payroll processed on 27th March would contribute to March's MTD totals. However, a payroll processed on 3rd April, following the company's specific month-end date, would reset the MTD figures, marking the beginning of a new financial month.

Authorizations:
Bearer
path Parameters
payPointNo
required
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "pay_point_no": 1,
  • "month_to_date_based_on": "Calendar month",
  • "accounting_months": [
    ]
}

Create or update accounting month-end dates for a single pay point.

Creates additional month-end dates or updates existing month-end dates for a single pay point. Here is some context around accounting dates. Automatic resets of YTD and MTD totals are critical to payroll reporting. Some organisations use calendar months for month-end financial reporting and others use specific dates. For instance, while March officially ends on the 31st, a company might choose 28th March as its accounting month-end, coinciding with the last Sunday of the month, and apply similar criteria to other months. The Affinity system requires that each reporting period is a standard length. This enables the system to identify an organisation’s forthcoming month-end date in order to initiate the appropriate resets during the first payroll cycle after the designated month-end date, thus allowing for consistent month-over-month comparisons. For example, a payroll processed on 27th March would contribute to March's MTD totals. However, a payroll processed on 3rd April, following the company's specific month-end date, would reset the MTD figures, marking the beginning of a new financial month.

Authorizations:
Bearer
path Parameters
payPointNo
required
integer <int32>
Request Body schema:
required
object
wait_for_completion
boolean or null
Default: true

Determines whether to wait for the request to completely import. If set to true (the default if not specified), the request will wait for the entire import to complete before returning a response. If set to false, the request will immediately return a 204 response and the import will continue in the background. The status of the import can be monitored using the ApiRequest endpoint.

validate_only
boolean or null
Default: false

Determines whether to only validate the request without importing any data. If set to true, the request will validate the data and return any validation errors without importing any data. If set to false (the default if not specified), the request will both validate the data, and import it if validation succeeded.

Responses

Request samples

Content type
{
  • "data": {
    },
  • "wait_for_completion": true,
  • "validate_only": false
}

Response samples

Content type
application/json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "property1": null,
  • "property2": null
}

Payroll costs

Retrieve payroll-costing information per timesheet.

Returns payroll-costing data based on timesheet transactions that have been processed in pay runs. Data from standard timesheet cost elements is returned (cost centres, projects, tasks etc.), along with any custom cost elements that the organisation uses.

Authorizations:
Bearer
path Parameters
payrollCostIdType
required
string
Enum: "TimesheetGuid" "IntegrationId" "ExternalReference"
payrollCostId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve payroll-costing information by timesheet for a selected employee.

Returns payroll-costing data based on timesheet transactions that have been processed in a specified pay period for a single employee. Data from standard timesheet cost elements is returned (cost centres, projects, tasks etc.), along with any custom cost elements that the organisation uses.

Authorizations:
Bearer
path Parameters
employeeIdType
required
string
Enum: "EmployeeGuid" "EmployeeNumber"
employeeId
required
string
periodEndDate
required
string <date>

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve payroll-costing information by timesheet for all employees for a given pay point and pay period.

Returns payroll-costing data based on timesheet transactions that have been processed in a specified pay point and pay period. Data from standard timesheet cost elements is returned (cost centres, projects, tasks etc.), along with any custom cost elements that the organisation uses.

Authorizations:
Bearer
path Parameters
payPoint
required
integer <int32>
periodEndDate
required
string <date>

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve payroll-costing information by timesheet for all employees in all payruns after a given payroll processing date/time.

Returns payroll-costing data based on timesheet transactions that have been processed in a specified pay point and pay period. Data from standard timesheet cost elements is returned (cost centres, projects, tasks etc.), along with any custom cost elements that the organisation uses.

Authorizations:
Bearer
path Parameters
payrunProcessedAt
required
string <date-time>

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Single employee

Retrieve biographical information for a single employee.

Returns a range of personal information about a single employee including name and contact information, and start and termination dates.

Authorizations:
Bearer
path Parameters
idType
required
string
Enum: "Guid" "Number"
employeeId
required
string
query Parameters
effectiveDate
string <date>

The effective date of the data. 'Effective date' is the date when a value comes into effect in a record. For example, a pay rate increase. If no effective date is supplied then the data in the record as at the current period-end date will be returned.

Responses

Response samples

Content type
application/json
{
  • "employee_guid": "string",
  • "employee_no": 0,
  • "pay_point_no": 0,
  • "first_names": "string",
  • "surname": "string",
  • "common_name": "string",
  • "title": "strin",
  • "preferred_name": "string",
  • "residential_address": {
    },
  • "nationality": "string",
  • "gender": "Not specified",
  • "birth_date": "2019-08-24",
  • "personal_email": "string",
  • "work_email": "string",
  • "mobile_phone": "string",
  • "home_phone": "string",
  • "work_phone": "string",
  • "pay_location": "string",
  • "start_date": "2019-08-24",
  • "termination_date": "2019-08-24",
  • "employee_position": "string",
  • "manager_employee_no": 0,
  • "termination_type": "Abandonment of Employment",
  • "card_id": "string",
  • "tax_number": "string",
  • "tax_code": "str",
  • "rdo_scheme": "string",
  • "payroll_tax_scheme": "string",
  • "flexifield_1": "string",
  • "flexifield_2": "string",
  • "flexifield_3": "string",
  • "flexifield_4": "string",
  • "flexifield_5": "string",
  • "flexifield_6": "string",
  • "flexifield_7": "string",
  • "flexifield_8": "string",
  • "flexifield_9": "string",
  • "flexifield_10": "string",
  • "flexifield_11": "string",
  • "flexifield_12": "string",
  • "flexifield_13": "string",
  • "flexifield_14": "string",
  • "flexifield_15": "string",
  • "flexifield_16": "string",
  • "flexifield_17": "string",
  • "flexifield_18": "string",
  • "flexifield_19": "string",
  • "flexifield_20": "string",
  • "flexifield_21": "string",
  • "flexifield_22": "string",
  • "flexifield_23": "string",
  • "flexifield_24": "string",
  • "flexifield_25": "string",
  • "flexifield_26": "string",
  • "flexifield_27": "string",
  • "flexifield_28": "string",
  • "flexifield_29": "string",
  • "flexifield_30": "string",
  • "flexifield_31": "string",
  • "flexifield_32": "string",
  • "flexifield_33": "string",
  • "flexifield_34": "string",
  • "flexifield_35": "string",
  • "flexifield_36": "string",
  • "record_version": 0
}

Create or update biographical information for one employee.

Updates an employee's personal information (including name and contact details) or creates new entries.

Authorizations:
Bearer
path Parameters
idType
required
string
Enum: "Guid" "Number"
employeeId
required
string
Request Body schema: application/json
required
object
wait_for_completion
boolean or null
Default: true

Determines whether to wait for the request to completely import. If set to true (the default if not specified), the request will wait for the entire import to complete before returning a response. If set to false, the request will immediately return a 204 response and the import will continue in the background. The status of the import can be monitored using the ApiRequest endpoint.

validate_only
boolean or null
Default: false

Determines whether to only validate the request without importing any data. If set to true, the request will validate the data and return any validation errors without importing any data. If set to false (the default if not specified), the request will both validate the data, and import it if validation succeeded.

Responses

Request samples

Content type
application/json
{
  • "data": {
    },
  • "wait_for_completion": true,
  • "validate_only": false
}

Response samples

Content type
application/json
{
  • "api_request_id": "string",
  • "data": {
    }
}

Retrieve bank account details for one employee.

Returns an employee's balance bank account details (their primary bank account) and up to five additional accounts as an array.

Authorizations:
Bearer
path Parameters
idType
required
string
Enum: "Guid" "Number"
employeeId
required
string
query Parameters
effectiveDate
string <date>

The effective date of the data. 'Effective date' is the date when a value comes into effect in a record. For example, a pay rate increase. If no effective date is supplied then the data in the record as at the current period-end date will be returned.

Responses

Response samples

Content type
application/json
{
  • "employee_guid": "string",
  • "employee_no": 0,
  • "balance_account": {
    },
  • "additional_accounts": [
    ],
  • "record_version": 0
}

Create or update bank account details for one employee.

Updates an employee's existing balance account details (their primary bank account) and up to five additional accounts, or creates new entries.

Authorizations:
Bearer
path Parameters
idType
required
string
Enum: "Guid" "Number"
employeeId
required
string
Request Body schema: application/json
required
object
wait_for_completion
boolean or null
Default: true

Determines whether to wait for the request to completely import. If set to true (the default if not specified), the request will wait for the entire import to complete before returning a response. If set to false, the request will immediately return a 204 response and the import will continue in the background. The status of the import can be monitored using the ApiRequest endpoint.

validate_only
boolean or null
Default: false

Determines whether to only validate the request without importing any data. If set to true, the request will validate the data and return any validation errors without importing any data. If set to false (the default if not specified), the request will both validate the data, and import it if validation succeeded.

Responses

Request samples

Content type
application/json
{
  • "data": {
    },
  • "wait_for_completion": true,
  • "validate_only": false
}

Response samples

Content type
application/json
{
  • "api_request_id": "string",
  • "data": {
    }
}

Retrieve emergency contact information for a single employee.

Returns emergency contact information for a single employee.

Authorizations:
Bearer
path Parameters
idType
required
string
Enum: "Guid" "Number"
employeeId
required
string
query Parameters
effectiveDate
string <date>

The effective date of the data. 'Effective date' is the date when a value comes into effect in a record. For example, a pay rate increase. If no effective date is supplied then the data in the record as at the current period-end date will be returned.

Responses

Response samples

Content type
application/json
{
  • "employee_guid": "string",
  • "employee_no": 0,
  • "emergency_contact_name": "string",
  • "relationship_to_employee": "string",
  • "address": {
    },
  • "mobile_phone": "string",
  • "home_phone": "string",
  • "work_phone": "string",
  • "record_version": 0
}

Create or update emergency contact information for one employee.

Updates emergency contact information for a single employee.

Authorizations:
Bearer
path Parameters
idType
required
string
Enum: "Guid" "Number"
employeeId
required
string
Request Body schema: application/json
required
object
wait_for_completion
boolean or null
Default: true

Determines whether to wait for the request to completely import. If set to true (the default if not specified), the request will wait for the entire import to complete before returning a response. If set to false, the request will immediately return a 204 response and the import will continue in the background. The status of the import can be monitored using the ApiRequest endpoint.

validate_only
boolean or null
Default: false

Determines whether to only validate the request without importing any data. If set to true, the request will validate the data and return any validation errors without importing any data. If set to false (the default if not specified), the request will both validate the data, and import it if validation succeeded.

Responses

Request samples

Content type
application/json
{
  • "data": {
    },
  • "wait_for_completion": true,
  • "validate_only": false
}

Response samples

Content type
application/json
{
  • "api_request_id": "string",
  • "data": {
    }
}

Retrieve leave balances for a single employee.

Returns a range of leave accrual and entitlement balances for all standard leave types that hold a balance (annual leave, sick leave, long service leave) along with customised leave (Leave C, D and E in Affinity).

Authorizations:
Bearer
path Parameters
idType
required
string
Enum: "Guid" "Number"
employeeId
required
string
query Parameters
effectiveDate
string <date>

The effective date of the data. 'Effective date' is the date when a value comes into effect in a record. For example, a pay rate increase. If no effective date is supplied then the data in the record as at the current period-end date will be returned.

Responses

Response samples

Content type
application/json
{
  • "employee_guid": "string",
  • "employee_no": 0,
  • "annual_leave": {
    },
  • "sick_leave": {
    },
  • "long_service_leave": {
    },
  • "leave_c": {
    },
  • "leave_d": {
    },
  • "leave_e": {
    },
  • "record_version": 0
}

Update leave balances for a single employee.

Updates a range of leave accrual and entitlement balances for all standard leave types that hold a balance (annual leave, sick leave, long service leave) along with customised leave (Leave C, D and E in Affinity).

Authorizations:
Bearer
path Parameters
idType
required
string
Enum: "Guid" "Number"
employeeId
required
string
Request Body schema: application/json
required
object
wait_for_completion
boolean or null
Default: true

Determines whether to wait for the request to completely import. If set to true (the default if not specified), the request will wait for the entire import to complete before returning a response. If set to false, the request will immediately return a 204 response and the import will continue in the background. The status of the import can be monitored using the ApiRequest endpoint.

validate_only
boolean or null
Default: false

Determines whether to only validate the request without importing any data. If set to true, the request will validate the data and return any validation errors without importing any data. If set to false (the default if not specified), the request will both validate the data, and import it if validation succeeded.

Responses

Request samples

Content type
application/json
{
  • "data": {
    },
  • "wait_for_completion": true,
  • "validate_only": false
}

Response samples

Content type
application/json
{
  • "api_request_id": "string",
  • "data": {
    }
}

Retrieve pay components for one employee.

Returns pay components for a single employee. When the employee_guid, pay_element and date_effective field values are unique, it's possible to retrieve multiple pay components for an employee.

Authorizations:
Bearer
path Parameters
idType
required
string
Enum: "Guid" "Number"
employeeId
required
string
query Parameters
effectiveDate
string <date>

The effective date of the data. 'Effective date' is the date when a value comes into effect in a record. For example, a pay rate increase. If no effective date is supplied then the data in the record as at the current period-end date will be returned.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve pay details for one employee.

Returns pay details for a single employee.

Authorizations:
Bearer
path Parameters
idType
required
string
Enum: "Guid" "Number"
employeeId
required
string
query Parameters
effectiveDate
string <date>

The effective date of the data. 'Effective date' is the date when a value comes into effect in a record. For example, a pay rate increase. If no effective date is supplied then the data in the record as at the current period-end date will be returned.

Responses

Response samples

Content type
application/json
{
  • "employee_guid": "string",
  • "employee_no": 0,
  • "pay_point_no": 0,
  • "pay_type": "Salaried",
  • "annual_salary": 0.1,
  • "rate_1": 0.1,
  • "rate_2": 0.1,
  • "rate_3": 0.1,
  • "rate_4": 0.1,
  • "rate_5": 0.1,
  • "rate_6": 0.1,
  • "rate_7": 0.1,
  • "rate_8": 0.1,
  • "rate_9": 0.1,
  • "rate_service_date": "2019-08-24",
  • "rate_table_id": "string",
  • "rate_table_step": "string",
  • "service_start_date": "2019-08-24",
  • "total_remuneration": 0.1,
  • "suspend_from": "2019-08-24",
  • "suspend_until": "2019-08-24",
  • "worker_type": "Part-time, temporary (0)",
  • "award_id": "string",
  • "ta_award_id": "string",
  • "std_hours_per_day": 0.1,
  • "std_hours_per_week": 0.1,
  • "record_version": 0
}

Create or update pay details for one employee.

Updates existing pay details for a single employee or creates new entries.

Authorizations:
Bearer
path Parameters
idType
required
string
Enum: "Guid" "Number"
employeeId
required
string
Request Body schema: application/json
required
object
wait_for_completion
boolean or null
Default: true

Determines whether to wait for the request to completely import. If set to true (the default if not specified), the request will wait for the entire import to complete before returning a response. If set to false, the request will immediately return a 204 response and the import will continue in the background. The status of the import can be monitored using the ApiRequest endpoint.

validate_only
boolean or null
Default: false

Determines whether to only validate the request without importing any data. If set to true, the request will validate the data and return any validation errors without importing any data. If set to false (the default if not specified), the request will both validate the data, and import it if validation succeeded.

Responses

Request samples

Content type
application/json
{
  • "data": {
    },
  • "wait_for_completion": true,
  • "validate_only": false
}

Response samples

Content type
application/json
{
  • "api_request_id": "string",
  • "data": {
    }
}

Retrieve organisational details for one employee.

Returns organisational details for a single employee.

Authorizations:
Bearer
path Parameters
idType
required
string
Enum: "Guid" "Number"
employeeId
required
string
query Parameters
effectiveDate
string <date>

The effective date of the data. 'Effective date' is the date when a value comes into effect in a record. For example, a pay rate increase. If no effective date is supplied then the data in the record as at the current period-end date will be returned.

Responses

Response samples

Content type
application/json
{
  • "employee_guid": "string",
  • "employee_no": 0,
  • "employee_position": "string",
  • "fte": 0.1,
  • "branch": "string",
  • "department": "string",
  • "division": "string",
  • "group": "string",
  • "pay_location": "string",
  • "ess_group": "string",
  • "cost_centres": [
    ],
  • "contractor_abn": "string",
  • "record_version": 0
}

Create or update organisational details for one employee.

Updates existing organisational details for a single employee or creates new entries.

Authorizations:
Bearer
path Parameters
idType
required
string
Enum: "Guid" "Number"
employeeId
required
string
Request Body schema: application/json
required
object
wait_for_completion
boolean or null
Default: true

Determines whether to wait for the request to completely import. If set to true (the default if not specified), the request will wait for the entire import to complete before returning a response. If set to false, the request will immediately return a 204 response and the import will continue in the background. The status of the import can be monitored using the ApiRequest endpoint.

validate_only
boolean or null
Default: false

Determines whether to only validate the request without importing any data. If set to true, the request will validate the data and return any validation errors without importing any data. If set to false (the default if not specified), the request will both validate the data, and import it if validation succeeded.

Responses

Request samples

Content type
application/json
{
  • "data": {
    },
  • "wait_for_completion": true,
  • "validate_only": false
}

Response samples

Content type
application/json
{
  • "api_request_id": "string",
  • "data": {
    }
}

Retrieve superannuation details for one employee.

Returns superannuation details for a single employee. Note that the data requirements for self-managed Super funds (SMSFs) differ from other types of funds. These are explained in the individual field descriptions.

Authorizations:
Bearer
path Parameters
idType
required
string
Enum: "Guid" "Number"
employeeId
required
string
query Parameters
effectiveDate
string <date>

The effective date of the data. 'Effective date' is the date when a value comes into effect in a record. For example, a pay rate increase. If no effective date is supplied then the data in the record as at the current period-end date will be returned.

Responses

Response samples

Content type
application/json
{
  • "employee_guid": "string",
  • "employee_no": 0,
  • "status": "Active",
  • "amount": 0.1,
  • "amount_type": "Percentage",
  • "super_type": "Employer contribution",
  • "fund_name": "string",
  • "fund_abn": "string",
  • "fund_usi": "string",
  • "fund_spin": "string",
  • "member_number": "string",
  • "fund_contact_name": "string",
  • "fund_address": {
    },
  • "fund_email": "string",
  • "fund_phone": "string",
  • "fund_account_name": "string",
  • "fund_bank_account": "string",
  • "fund_esa": "string",
  • "record_version": 0
}

Create or update superannuation details for one employee.

Updates existing superannuation information for a single employee or creates new entries.

ABNs/USIs

  • Creating a new self-managed fund. If no matching ABN is found in the Super fund masterfile when supplied for an SMSF, a Super fund masterfile will be created using a system-generated fund identifier (FUND_ID) in the format SMSnnn, and the record saved to the SUPERMF table with that FUND_ID.
  • Creating a new standard fund. If no matching ABN and USI is found in the Super fund masterfile when supplied for a standard fund, a Super fund masterfile will be created using a system-generated fund identifier (FUND_ID) in the format SMnnnn, and the record saved to the SUPERMF table with that FUND_ID.
  • Updating an existing fund. If a standard Super fund masterfile with a matching ABN and USI exists (or an SMSF with a matching ABN exists), updates to fund name and other details like phone, contact name and address will be applied.

SUPERDEFAULTCODES

If the SUPERDEFAULTCODES code group is enabled in your Affinity system, the default Super pay elements contained in that code group (usually SUPR01, SUPE01, ZUPE01) will automatically link to new and updated Super fund masterfiles, and appear in a list in the fund masterfile screen. This link makes things easier for payroll teams because whenever they assign a Super fund masterfile to an employee masterfile, the default pay elements linked to that fund will be available in the employee masterfile when creating the relevant Super deductions. Note that only the SUPR employer contribution is automatically added to the employee masterfile. Any additional Super-related pay elements must be added manually to employee masterfiles in Affinity.

Significant dates

When an employee’s Super details change, a significant dates record is automatically created. This is visible in the employee masterfile (Contacts/Dates tab).

Authorizations:
Bearer
path Parameters
idType
required
string
Enum: "Guid" "Number"
employeeId
required
string
Request Body schema: application/json
required
object
wait_for_completion
boolean or null
Default: true

Determines whether to wait for the request to completely import. If set to true (the default if not specified), the request will wait for the entire import to complete before returning a response. If set to false, the request will immediately return a 204 response and the import will continue in the background. The status of the import can be monitored using the ApiRequest endpoint.

validate_only
boolean or null
Default: false

Determines whether to only validate the request without importing any data. If set to true, the request will validate the data and return any validation errors without importing any data. If set to false (the default if not specified), the request will both validate the data, and import it if validation succeeded.

Responses

Request samples

Content type
application/json
{
  • "data": {
    },
  • "wait_for_completion": true,
  • "validate_only": false
}

Response samples

Content type
application/json
{
  • "api_request_id": "string",
  • "data": {
    }
}

Retrieve one tax declaration detail record for one employee.

Returns one tax declaration record for one employee based on tax_declaration_id. Note that in the Affinity system, the declaration date is the effective date.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "tax_declaration_id": "string",
  • "employee_guid": "string",
  • "employee_no": 0,
  • "declaration_date": "2019-08-24",
  • "tax_number": "string",
  • "reason_no_number": "string",
  • "primary_email": "string",
  • "prior_surname": "string",
  • "basis_of_payment": "Full-time",
  • "australian_resident": true,
  • "working_holiday_maker": true,
  • "claim_tax_free_threshold": true,
  • "claim_pensioners_offset": true,
  • "claim_zone_offset": true,
  • "visa_country": "st",
  • "has_stlr": true,
  • "seasonal_worker": true,
  • "information_correct": true,
  • "tax_treatment_code": "string",
  • "record_version": 0
}

Create or update one tax declaration record for one employee.

Updates one tax declaration record for one employee based on tax_declaration_id or creates a new record. Note that in the Affinity system, the declaration date is the effective date.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Request Body schema: application/json
required
object
wait_for_completion
boolean or null
Default: true

Determines whether to wait for the request to completely import. If set to true (the default if not specified), the request will wait for the entire import to complete before returning a response. If set to false, the request will immediately return a 204 response and the import will continue in the background. The status of the import can be monitored using the ApiRequest endpoint.

validate_only
boolean or null
Default: false

Determines whether to only validate the request without importing any data. If set to true, the request will validate the data and return any validation errors without importing any data. If set to false (the default if not specified), the request will both validate the data, and import it if validation succeeded.

Responses

Request samples

Content type
application/json
{
  • "data": {
    },
  • "wait_for_completion": true,
  • "validate_only": false
}

Response samples

Content type
application/json
{
  • "api_request_id": "string",
  • "data": {
    }
}

Delete one tax declaration record for one employee.

Deletes one tax declaration record for one employee based on tax_declaration_id. Note that in the Affinity system, the declaration date is the effective date.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "record_key": "string",
  • "message": "string"
}

Retrieve all tax declaration records for one employee.

Retrieves all existing tax declaration records for one employee based on optional parameters. Note that idType can be either employee_guid or employee_no. Also note that in the Affinity system, the declaration date is the effective date.

Authorizations:
Bearer
path Parameters
idType
required
string
Enum: "Guid" "Number"
employeeId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create or update one tax declaration record for one employee.

Updates one tax declaration record for one employee for a specific declarationDate or creates a new record. Note that idType can be either employee_guid or employee_no. Also note that in the Affinity system, the declaration date is the effective date.

Authorizations:
Bearer
path Parameters
idType
required
string
Enum: "Guid" "Number"
employeeId
required
string
declarationDate
required
string <date>
Request Body schema:
required
object
wait_for_completion
boolean or null
Default: true

Determines whether to wait for the request to completely import. If set to true (the default if not specified), the request will wait for the entire import to complete before returning a response. If set to false, the request will immediately return a 204 response and the import will continue in the background. The status of the import can be monitored using the ApiRequest endpoint.

validate_only
boolean or null
Default: false

Determines whether to only validate the request without importing any data. If set to true, the request will validate the data and return any validation errors without importing any data. If set to false (the default if not specified), the request will both validate the data, and import it if validation succeeded.

Responses

Request samples

Content type
{
  • "data": {
    },
  • "wait_for_completion": true,
  • "validate_only": false
}

Response samples

Content type
application/json
{
  • "api_request_id": "string",
  • "data": {
    }
}

Retrieve significant dates for one employee.

Returns essential information about significant dates relating to a single employee. A ‘significant date’ in the Affinity context is like a diary entry. The Diary is a module in Affinity that allows for date-related tasks, reminders and events to be stored against employee records. Dates can be for information only, or they can be queried and reported on, providing the organisation with more insights. For example, if probationary period expiry dates are recorded as a significant date, this information can be queried and reported on then sent to the relevant recipients via Affinity’s myPA tool.

Authorizations:
Bearer
path Parameters
idType
required
string
Enum: "Guid" "Number"
employeeId
required
string
query Parameters
dateFrom
string <date>

Returns records from a specified diary_entry_date onwards. For example, dateFrom=2025-01-01 will only return records from 1 January 2025 onwards.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create or update significant dates for one employee.

Creates or updates significant dates for a single employee. A ‘significant date’ in the Affinity context is like a diary entry. The Diary is a module in Affinity that allows for date-related tasks, reminders and events to be stored against employee records. Dates can be for information only, or they can be queried and reported on, providing the organisation with more insights. For example, if probationary period expiry dates are recorded as a significant date, this information can be queried and reported on then sent to the relevant recipients via Affinity’s myPA tool.

Authorizations:
Bearer
Request Body schema:
required
object
wait_for_completion
boolean or null
Default: true

Determines whether to wait for the request to completely import. If set to true (the default if not specified), the request will wait for the entire import to complete before returning a response. If set to false, the request will immediately return a 204 response and the import will continue in the background. The status of the import can be monitored using the ApiRequest endpoint.

validate_only
boolean or null
Default: false

Determines whether to only validate the request without importing any data. If set to true, the request will validate the data and return any validation errors without importing any data. If set to false (the default if not specified), the request will both validate the data, and import it if validation succeeded.

Responses

Request samples

Content type
{
  • "data": {
    },
  • "wait_for_completion": true,
  • "validate_only": false
}

Response samples

Content type
application/json
{
  • "api_request_id": "string",
  • "data": {
    }
}

Timesheets

Retrieve a single timesheet.

Returns a single timesheet, including start and finish times, units, unit rates, pay elements, and costing allocations.

Authorizations:
Bearer
path Parameters
idType
required
string
Enum: "Guid" "ExternalReference"
timesheetId
required
string

Responses

Response samples

Content type
application/json
{
  • "api_request_id": "string",
  • "data": {
    }
}

Create or update information in a single timesheet.

Updates an individual timesheet or creates a new timesheet by timesheetId.

Authorizations:
Bearer
path Parameters
idType
required
string
Enum: "Guid" "ExternalReference"
timesheetId
required
string
Request Body schema: application/json
required
object
wait_for_completion
boolean or null
Default: true

Determines whether to wait for the request to completely import. If set to true (the default if not specified), the request will wait for the entire import to complete before returning a response. If set to false, the request will immediately return a 204 response and the import will continue in the background. The status of the import can be monitored using the ApiRequest endpoint.

validate_only
boolean or null
Default: false

Determines whether to only validate the request without importing any data. If set to true, the request will validate the data and return any validation errors without importing any data. If set to false (the default if not specified), the request will both validate the data, and import it if validation succeeded.

Responses

Request samples

Content type
application/json
{
  • "data": {
    },
  • "wait_for_completion": true,
  • "validate_only": false
}

Response samples

Content type
application/json
{
  • "api_request_id": "string",
  • "data": {
    }
}

Delete a single timesheet.

Deletes a single timesheet by external reference.

Authorizations:
Bearer
path Parameters
idType
required
string
Enum: "Guid" "ExternalReference"
timesheetId
required
string

Responses

Response samples

Content type
application/json
{
  • "api_request_id": "string",
  • "data": {
    }
}

Retrieve timesheets for one pay point and one timesheet date.

Returns timesheets for exactly one pay point and date combo, including start and finish times, units, unit rates, pay elements, and costing allocations.

Authorizations:
Bearer
query Parameters
payPoint
integer <int32>
timesheetDate
string <date>

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create or update information in multiple timesheets.

Updates multiple timesheets or creates new timesheets.

Authorizations:
Bearer
Request Body schema: application/json
required
Array of objects (TimesheetIn)
wait_for_completion
boolean or null
Default: true

Determines whether to wait for the request to completely import. If set to true (the default if not specified), the request will wait for the entire import to complete before returning a response. If set to false, the request will immediately return a 204 response and the import will continue in the background. The status of the import can be monitored using the ApiRequest endpoint.

validate_only
boolean or null
Default: false

Determines whether to only validate the request without importing any data. If set to true, the request will validate the data and return any validation errors without importing any data. If set to false (the default if not specified), the request will both validate the data, and import it if validation succeeded.

continue_on_validation_failure
boolean or null
Default: false

Determines whether to continue processing subsequent records if validation fails. If set to false (the default if not specified), the first validation failure will cause the entire request to fail and no records will be imported. If set to true, any records that fail validation will be skipped and the remaining records will be imported.

Responses

Request samples

Content type
application/json
{
  • "data": [
    ],
  • "wait_for_completion": true,
  • "validate_only": false,
  • "continue_on_validation_failure": false
}

Response samples

Content type
application/json
{
  • "api_request_id": "string",
  • "data": [
    ]
}