Home
Guides

List Payroll Calendar

Suggest Edits

The List Payroll Calendar endpoint allows you to retrieve all payroll calendars associated with your organization for a specific cycle (month/year). This guide walks you through how to use this endpoint.

Prerequisites

Before you make the endpoint call, you will need:

  • API access: Ensure you have access to the Remote API.
  • Authentication: An OAuth2 token for authentication.
  • Environment setup: Either use the production URL https://gateway.remote.com or Remote sandbox https://gateway.remote-sandbox.com. We recommend using sandbox before querying live data.

Understanding the Endpoint

This endpoint retrieves payroll calendar information for a specific cycle. This cycle determines the time period (e.g. November 2024) for which payroll calendars will be listed.

List Payroll Calendar has two scopes:

  • https://gateway.remote.com/employment.manage that lets you create, read, update, and delete employments.
  • https://gateway.remote.com/employment.read that only allows reading the employment data.

To better understand this endpoint, let's say you are managing payroll for your company and you need to review all payroll calendars for November 2024 to ensure payroll events and schedules align with your processing deadlines. Here's how you will structure your endpoint call:

Request Structure

The request structure for this endpoint looks like the following:

GET https://gateway.remote-sandbox.com/v1/payroll-calendars/2024-11

In this call,

  • Your base URL is https://gateway.remote-sandbox.com. Change it to remote.com when you are ready for production.
  • The required cycle for processing is 2024-11.
  • Do not forget to include a valid OAuth2 token in the authorization header.

These are the required parameters to make a successful endpoint call. You can also add optional query parameters such as page and page_size.

GET https://gateway.remote-sandbox.com/v1/payroll-calendars/2024-11?page=1&page_size=10

Response

A successful request returns a 200 OK status with the requested list of payroll calendars.

{
"current_page": 1,
"payroll_calendars": [
    {
    "country": {"code": "CAN"},
          "owned_by_remote": true,
          "cycle_frequency": "bi-monthly"
          "cycles": [
	          {
	            "start_date": "YYYY-MM-DD",
	            "end_date": "YYYY-MM-DD",
	            "input_cutoff_date": "YYYY-MM-DD",
	            "employee_inclusion_cutoff_date": "YYYY-MM-DD",
              "payment_date": "YYYY-MM-DD"
            }
            ...
          ]
    },
    ...
],
"total_count": 1,
"total_pages": 10
}

Here's what each parameter indicates:

  • current_page: the current page of all the total_pages.
  • payroll_calendars:
    • code: code of a supported country on Remote.
    • owned_by_remote: a flag that indicates whether the payroll is owned by remote or not.
    • cycle_frequency: the frequency at which the payroll calendar is run.
    • cycles: refer to the frequency of payroll run in the month passed in the request.
    • start_date: the start date of this payroll cycle.
    • end_date: the end date of this payroll cycle.
    • input_cutoff_date: the last date to accept data for the payroll.
    • employee_inclusion_cutoff_date: the date that marks which employees to include in the payroll run. Employees added after this date will not be included.
    • payment_date: the scheduled date on which payments are disbursed.
  • total_count: the total number of records
  • total_pages: the total number of pages to go through

Troubleshooting

  • 401 Unauthorized: This error occurs when the API call has a missing or invalid OAuth2 token. To fix this, verify that you have a valid token and that it is included in the authorization header.
  • 404 Not Found: This error occurs if there are no payroll calendars found for the provided cycle. If you are sure this shouldn't be the case, double-check that you provided the correct cycle.
  • 422 Unprocessable Entity: This error occurs when the request body has incorrect request parameters, which in this case means incorrect cycle format, or invalid page and page size. To fix this error, try fixing the cycle format to YYYY-MM and verify whether page and page_size are integers.

Updated 23 days ago